Technical Reference: Base Operating System and Extensions, Volume 2

setgroups Subroutine

Purpose

Sets the supplementary group ID of the current process.

Library

Standard C Library (libc.a)

Syntax

#include <grp.h>

int setgroups ( NumberGroups, GroupIDSet) int NumberGroups; gid_t *GroupIDSet;

Description

The setgroups subroutine sets the supplementary group ID of the process. The setgroups subroutine cannot set more than NGROUPS_MAX groups in the group set. (NGROUPS_MAX is a constant defined in the limits.h file.)

Note

The routine may coredump instead of returning EFAULT when an invalid pointer is passed in case of 64-bit application calling 32-bit kernel interface.

Parameters

GroupIDSet	Pointer to the array of group IDs to be established.
NumberGroups	Indicates the number of entries in the GroupIDSet parameter.

Return Values

Upon successful completion, the setgroups subroutine returns a value of 0. Otherwise, a value of -1 is returned and the errno global variable is set to indicate the error.

Error Codes

The setgroups subroutine fails if any of the following are true:

EFAULT	The NumberGroups and GroupIDSet parameters specify an array that is partially or completely outside of the process' allocated address space.
EINVAL	The NumberGroups parameter is greater than the NGROUPS_MAX value.
EPERM	A group ID in the GroupIDSet parameter is not presently in the supplementary group ID, and the invoker does not have root user authority.

Security

Auditing Events:

Event	Information
PROC_SetGroups	NumberGroups, GroupIDSet

Related Information

The getgid subroutine, getgroups subroutine, initgroups subroutine, setgid (setgid, setrgid, setegid, setregid, or setgidx Subroutine) subroutine.

List of Security and Auditing Subroutines and Subroutines Overview in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.