1 files changed, 130 insertions, 0 deletions
diff --git a/man2/getgroups.2 b/man2/getgroups.2
new file mode 100644
index 000000000..f4f0ee13b
--- /dev/null
+++ b/man2/getgroups.2
@@ -0,0 +1,130 @@
+.\" Hey Emacs! This file is -*- nroff -*- source.
+.\"
+.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu)
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one.
+.\" 
+.\" Since the Linux kernel and libraries are constantly changing, this
+.\" manual page may be incorrect or out-of-date.  The author(s) assume no
+.\" responsibility for errors or omissions, or for damages resulting from
+.\" the use of the information contained herein.  The author(s) may not
+.\" have taken the same level of care in the production of this manual,
+.\" which is licensed free of charge, as they might when working
+.\" professionally.
+.\" 
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.\"
+.\" Modified Thu Oct 31 12:04:29 1996 by Eric S. Raymond <esr@thyrsus.com>
+.\" Modified, 27 May 2004, Michael Kerrisk <mtk16@ext.canterbury.ac.nz>
+.\"     Added notes on capability requirements
+.\"
+.TH GETGROUPS 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual"
+.SH NAME
+getgroups, setgroups \- get/set list of supplementary group IDs
+.SH SYNOPSIS
+.B #include <sys/types.h>
+.br
+.B #include <unistd.h>
+.sp
+.BI "int getgroups(int " size ", gid_t " list []);
+.sp
+.B #include <grp.h>
+.sp
+.BI "int setgroups(size_t " size ", const gid_t *" list );
+.SH DESCRIPTION
+.TP
+.B getgroups
+Up to
+.I size
+supplementary group IDs (of the calling process) are returned in
+.IR list .
+It is unspecified whether the effective group ID of the calling process
+is included in the returned list. (Thus, an application should also call
+.BR getegid (2)
+and add or remove the resulting value.)
+If
+.I size
+is zero,
+.I list
+is not modified, but the total number of supplementary group IDs for the
+process is returned.
+.TP
+.B setgroups
+Sets the supplementary group IDs for the process.
+Appropriate privileges (Linux: the
+.B CAP_SETGID
+capability) are required.
+.SH "RETURN VALUE"
+.TP
+.B getgroups
+On success, the number of supplementary group IDs is returned.
+On error, \-1 is returned, and
+.I errno
+is set appropriately.
+.TP
+.B setgroups
+On success, zero is returned.  On error, \-1 is returned, and
+.I errno
+is set appropriately.
+.SH ERRORS
+.TP
+.B EFAULT
+.I list
+has an invalid address.
+.TP
+.B EINVAL
+For
+.BR setgroups ,
+.I size
+is greater than
+.B NGROUPS
+(32 for Linux 2.0.32).
+For
+.BR getgroups ,
+.I size
+is less than the number of supplementary group IDs, but is not zero.
+.TP
+.B EPERM
+The calling process has insufficient privilege to call 
+.BR setgroups .
+.SH NOTES
+A process can have up to at least NGROUPS_MAX supplementary group IDs
+in addition to the effective group ID. The set of supplementary group IDs
+is inherited from the parent process and may be changed using
+.BR setgroups .
+The maximum number of supplementary group IDs can be found using
+.BR sysconf (3):
+.nf
+    long ngroups_max;
+    ngroups_max = sysconf(_SC_NGROUPS_MAX);
+.fi
+The maximal return value of
+.B getgroups
+cannot be larger than one more than the value obtained this way.
+.LP
+The prototype for
+.B setgroups
+is only available if
+.B _BSD_SOURCE
+is defined (either explicitly, or implicitly, by not defining
+_POSIX_SOURCE or compiling with the -ansi flag).
+.SH "CONFORMING TO"
+SVr4, SVID (issue 4 only; these calls were not present in SVr3),
+X/OPEN, 4.3BSD.  The
+.B getgroups
+function is in POSIX.1.  Since
+.B setgroups
+requires privilege, it is not covered by POSIX.1.
+.SH "SEE ALSO"
+.BR getgid (2),
+.BR setgid (2),
+.BR initgroups (3),
+.BR capabilities (7)