[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions, Volume 2

setgroups Subroutine


Sets the supplementary group ID of the current process.


Standard C Library (libc.a)


#include <grp.h>

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


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.)

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.


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.


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.

[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]