mirror of https://github.com/mkerrisk/man-pages
117 lines
3.8 KiB
Plaintext
117 lines
3.8 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "GETGROUPS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" getgroups
|
|
.SH NAME
|
|
getgroups \- get supplementary group IDs
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <unistd.h>
|
|
.br
|
|
.sp
|
|
int getgroups(int\fP \fIgidsetsize\fP\fB, gid_t\fP \fIgrouplist\fP\fB[]);
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fIgetgroups\fP() function shall fill in the array \fIgrouplist\fP
|
|
with the current supplementary group IDs of the calling
|
|
process. It is implementation-defined whether \fIgetgroups\fP() also
|
|
returns the effective group ID in the \fIgrouplist\fP
|
|
array.
|
|
.LP
|
|
The \fIgidsetsize\fP argument specifies the number of elements in
|
|
the array \fIgrouplist\fP. 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.
|
|
.LP
|
|
If \fIgidsetsize\fP is 0, \fIgetgroups\fP() shall return the number
|
|
of group IDs that it would otherwise return without
|
|
modifying the array pointed to by \fIgrouplist\fP.
|
|
.LP
|
|
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.
|
|
.SH RETURN VALUE
|
|
.LP
|
|
Upon successful completion, the number of supplementary group IDs
|
|
shall be returned. A return value of -1 indicates failure and
|
|
\fIerrno\fP shall be set to indicate the error.
|
|
.SH ERRORS
|
|
.LP
|
|
The \fIgetgroups\fP() function shall fail if:
|
|
.TP 7
|
|
.B EINVAL
|
|
The \fIgidsetsize\fP argument is non-zero and less than the number
|
|
of group IDs that would have been returned.
|
|
.sp
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.SS Getting the Supplementary Group IDs of the Calling Process
|
|
.LP
|
|
The following example places the current supplementary group IDs of
|
|
the calling process into the \fIgroup\fP array.
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB#include <sys/types.h>
|
|
#include <unistd.h>
|
|
\&...
|
|
gid_t *group;
|
|
int nogroups;
|
|
long ngroups_max;
|
|
.sp
|
|
|
|
ngroups_max = sysconf(_SC_NGROUPS_MAX) + 1;
|
|
group = (gid_t *)malloc(ngroups_max *sizeof(gid_t));
|
|
.sp
|
|
|
|
ngroups = getgroups(ngroups_max, group);
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
None.
|
|
.SH RATIONALE
|
|
.LP
|
|
The related function \fIsetgroups\fP() is a privileged operation and
|
|
therefore is not covered by this volume of
|
|
IEEE\ Std\ 1003.1-2001.
|
|
.LP
|
|
As implied by the definition of supplementary groups, the effective
|
|
group ID may appear in the array returned by
|
|
\fIgetgroups\fP() or it may be returned only by \fIgetegid\fP(). Duplication
|
|
may exist,
|
|
but the application needs to call \fIgetegid\fP() to be sure of getting
|
|
all of the
|
|
information. Various implementation variations and administrative
|
|
sequences cause the set of groups appearing in the result of
|
|
\fIgetgroups\fP() 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.)
|
|
.LP
|
|
Application writers should note that {NGROUPS_MAX} is not necessarily
|
|
a constant on all implementations.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIgetegid\fP() , \fIsetgid\fP() , the Base Definitions volume of
|
|
IEEE\ Std\ 1003.1-2001, \fI<sys/types.h>\fP, \fI<unistd.h>\fP
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- 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 .
|