getgroups(2)

getgroups, setgroups -- get or set supplementary group access list IDs

Synopsis

   #include <unistd.h>
   
   int getgroups(int gidsetsize, gid_t grouplist);
   

   int setgroups(int ngroups, const gid_t grouplist);

Description

getgroups gets the current supplemental group access list of the calling process and stores the result in the array of group IDs specified by grouplist. This array has gidsetsize entries and must be large enough to contain the entire list. This list cannot be greater than {NGROUPS_MAX}. If gidsetsize equals 0, getgroups will return the number of groups to which the calling process belongs without modifying the array pointed to by grouplist.

setgroups sets the supplementary group access list of the calling process from the array of group IDs specified by grouplist. The number of entries is specified by ngroups and can not be greater than {NGROUPS_MAX}. This function may be invoked only by a process with the P_SETUID privilege.

Return values

On success, getgroups returns the number of supplementary group IDs set for the calling process and setgroups returns 0. On failure, getgroups and setgroups return -1 and set errno to identify the error.

Errors

In the following conditions, getgroups fails and sets errno to:

EINVAL: The value of gidsetsize is non-zero and less than the number of supplementary group IDs set for the calling process.

In the following conditions, setgroups fails and sets errno to:

EINVAL: The value of ngroups is greater than {NGROUPS_MAX}.
EPERM: The calling process does not have the P_SETUID privilege.

In the following conditions, either call fails and sets errno to:

EFAULT: A referenced part of the array pointed to by grouplist is outside of the allocated address space of the process.

References

chown(2), getuid(2), groups(1), initgroups(3C), setuid(2)

Notices

Considerations for threads programming

These ID numbers are attributes of the containing process and are shared by sibling threads.