getgroups(2) [osx man page]
GETGROUPS(2) BSD System Calls Manual GETGROUPS(2) NAME
getgroups -- get group access list SYNOPSIS
#include <unistd.h> int getgroups(int gidsetsize, gid_t grouplist[]); DESCRIPTION
getgroups() gets the current group access list of the current user process and stores it in the array grouplist[]. The parameter gidsetsize indicates the number of entries that may be placed in grouplist[]. getgroups() returns the actual number of groups returned in grouplist[]. However, no more than {NGROUPS_MAX} will be returned. If gidsetsize is 0, getgroups() returns the number of groups without modifying the grouplist[] array. Calling initgroups(3) to opt-in for supplementary groups will cause getgroups() to return a single entry, the GID that was passed to initgroups(3). To provide compatibility with applications that use getgroups() in environments where users may be in more than {NGROUPS_MAX} groups, a vari- ant of getgroups(), obtained when compiling with either the macros _DARWIN_UNLIMITED_GETGROUPS or _DARWIN_C_SOURCE defined, can be used that is not limited to {NGROUPS_MAX} groups. However, this variant only returns the user's default group access list and not the group list modi- fied by a call to setgroups(2) (either in the current process or an ancestor process). Use of setgroups(2) is highly discouraged, and there is no foolproof way to determine if it has been previously called. RETURN VALUES
A successful call returns the number of groups in the group set. Otherwise, a value of -1 is returned and the global integer variable errno is set to indicate the error. ERRORS
The possible errors for getgroups() are: [EFAULT] The argument grouplist specifies an invalid address. [EINVAL] The argument gidsetsize, although non-zero, is smaller than the number of groups in the group set. LEGACY SYNOPSIS
#include <sys/param.h> #include <sys/types.h> #include <unistd.h> The include files <sys/param.h> and <sys/types.h> are necessary. SEE ALSO
setgroups(2), initgroups(3), compat(5) HISTORY
The getgroups() function call appeared in 4.2BSD. 4.2 Berkeley Distribution October 28, 2011 4.2 Berkeley Distribution
Check Out this Related Man Page
GETGROUPS(3P) POSIX Programmer's Manual GETGROUPS(3P) PROLOG
This manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ (consult the correspond- ing Linux manual page for details of Linux behavior), or the interface may not be implemented on Linux. NAME
getgroups - get supplementary group IDs SYNOPSIS
#include <unistd.h> int getgroups(int gidsetsize, gid_t grouplist[]); DESCRIPTION
The getgroups() function shall fill in the array grouplist with the current supplementary group IDs of the calling process. It is implemen- tation-defined whether getgroups() also returns the effective group ID in the grouplist array. The gidsetsize argument specifies the number of elements in the array grouplist. The actual number of group IDs stored in the array shall be returned. The values of array entries with indices greater than or equal to the value returned are undefined. If gidsetsize is 0, getgroups() shall return the number of group IDs that it would otherwise return without modifying the array pointed to by grouplist. If the effective group ID of the process is returned with the supplementary group IDs, the value returned shall always be greater than or equal to one and less than or equal to the value of {NGROUPS_MAX}+1. RETURN VALUE
Upon successful completion, the number of supplementary group IDs shall be returned. A return value of -1 indicates failure and errno shall be set to indicate the error. ERRORS
The getgroups() function shall fail if: EINVAL The gidsetsize argument is non-zero and less than the number of group IDs that would have been returned. The following sections are informative. EXAMPLES
Getting the Supplementary Group IDs of the Calling Process The following example places the current supplementary group IDs of the calling process into the group array. #include <sys/types.h> #include <unistd.h> ... gid_t *group; int nogroups; long ngroups_max; ngroups_max = sysconf(_SC_NGROUPS_MAX) + 1; group = (gid_t *)malloc(ngroups_max *sizeof(gid_t)); ngroups = getgroups(ngroups_max, group); APPLICATION USAGE
None. RATIONALE
The related function setgroups() is a privileged operation and therefore is not covered by this volume of IEEE Std 1003.1-2001. As implied by the definition of supplementary groups, the effective group ID may appear in the array returned by getgroups() or it may be returned only by getegid(). Duplication may exist, but the application needs to call getegid() to be sure of getting all of the informa- tion. Various implementation variations and administrative sequences cause the set of groups appearing in the result of getgroups() to vary in order and as to whether the effective group ID is included, even when the set of groups is the same (in the mathematical sense of "set"). (The history of a process and its parents could affect the details of the result.) Application writers should note that {NGROUPS_MAX} is not necessarily a constant on all implementations. FUTURE DIRECTIONS
None. SEE ALSO
getegid(), setgid(), the Base Definitions volume of IEEE Std 1003.1-2001, <sys/types.h>, <unistd.h> COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition, Standard for Information Technol- ogy -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html . IEEE
/The Open Group 2003 GETGROUPS(3P)