X-Git-Url: https://git.saurik.com/apple/xnu.git/blobdiff_plain/9bccf70c0258c7cac2dcb80011b2a964d884c552..4bd07ac2140668789aa3ee8ec4dde4a3e0a3bba5:/bsd/man/man2/getgroups.2

diff --git a/bsd/man/man2/getgroups.2 b/bsd/man/man2/getgroups.2
index ecc9c82ee..2ae5297fc 100644
--- a/bsd/man/man2/getgroups.2
+++ b/bsd/man/man2/getgroups.2
@@ -1,3 +1,26 @@
+.\"
+.\" Copyright (c) 2008-2011 Apple Inc.  All rights reserved.
+.\"
+.\" @APPLE_LICENSE_HEADER_START@
+.\" 
+.\" This file contains Original Code and/or Modifications of Original Code
+.\" as defined in and that are subject to the Apple Public Source License
+.\" Version 2.0 (the 'License'). You may not use this file except in
+.\" compliance with the License. Please obtain a copy of the License at
+.\" http://www.opensource.apple.com/apsl/ and read it before using this
+.\" file.
+.\" 
+.\" The Original Code and all software distributed under the License are
+.\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
+.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
+.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
+.\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
+.\" Please see the License for the specific language governing rights and
+.\" limitations under the License.
+.\" 
+.\" @APPLE_LICENSE_HEADER_END@
+.\"
+.\"
 .\"	$NetBSD: getgroups.2,v 1.8 1995/02/27 12:32:57 cgd Exp $
 .\"
 .\" Copyright (c) 1983, 1991, 1993
@@ -33,64 +56,105 @@
 .\"
 .\"     @(#)getgroups.2	8.2 (Berkeley) 4/16/94
 .\"
-.Dd April 16, 1994
+.Dd October 28, 2011
 .Dt GETGROUPS 2
 .Os BSD 4.2
 .Sh NAME
 .Nm getgroups
 .Nd get group access list
 .Sh SYNOPSIS
-.Fd #include <sys/param.h>
-.Fd #include <sys/types.h>
 .Fd #include <unistd.h>
 .Ft int
-.Fn getgroups "int gidsetlen" "gid_t *gidset"
+.Fo getgroups
+.Fa "int gidsetsize"
+.Fa "gid_t grouplist[]"
+.Fc
 .Sh DESCRIPTION
-.Fn Getgroups
+.Fn getgroups
 gets the current group access list of the current user process
 and stores it in the array 
-.Fa gidset .
+.Fa grouplist[] .
 The parameter
-.Fa gidsetlen
+.Fa gidsetsize
 indicates the number of entries that may be placed in 
-.Fa gidset .
-.Fn Getgroups
+.Fa grouplist[] .
+.Fn getgroups
 returns the actual number of groups returned in
-.Fa gidset .
-No more than
+.Fa grouplist[] .
+However, no more than
 .Dv {NGROUPS_MAX}
-will ever
-be returned.
-If
-.Fa gidsetlen
+will be returned. If
+.Fa gidsetsize
 is 0, 
 .Fn getgroups
 returns the number of groups without modifying the
-.Fa gidset
+.Fa grouplist[]
 array.
+.Pp
+Calling
+.Xr initgroups 3
+to opt-in for supplementary groups will cause
+.Fn getgroups
+to return a single entry, the GID that was passed to 
+.Xr initgroups 3 .
+.Pp
+To provide compatibility with applications that use
+.Fn getgroups
+in environments where users may be in more than
+.Dv {NGROUPS_MAX}
+groups, a variant of
+.Fn getgroups ,
+obtained when compiling with either the macros
+.Dv _DARWIN_UNLIMITED_GETGROUPS
+or
+.Dv _DARWIN_C_SOURCE
+defined, can be used that is not limited to
+.Dv {NGROUPS_MAX}
+groups.
+However, this variant only returns the user's default group access list and
+not the group list modified by a call to
+.Xr setgroups 2
+(either in the current process or an ancestor process).
+Use of
+.Xr setgroups 2
+is highly discouraged, and there is no foolproof way to determine if it has
+been previously called.
 .Sh RETURN VALUES
 A successful call returns the number of groups in the group set.
-A value of -1 indicates that an error occurred, and the error
-code is stored in the global variable
-.Va errno .
+Otherwise, a value of -1 is returned and the global integer variable
+.Va errno
+is set to indicate the error.
 .Sh ERRORS
 The possible errors for
 .Fn getgroups
 are:
 .Bl -tag -width Er
+.\" ==========
+.It Bq Er EFAULT
+The argument
+.Fa grouplist
+specifies an invalid address.
+.\" ==========
 .It Bq Er EINVAL
 The argument
-.Fa gidsetlen
+.Fa gidsetsize ,
+although non-zero,
 is smaller than the number of groups in the group set.
-.It Bq Er EFAULT
-The argument
-.Fa gidset
-specifies
-an invalid address.
 .El
+.Sh LEGACY SYNOPSIS
+.Fd #include <sys/param.h>
+.Fd #include <sys/types.h>
+.Fd #include <unistd.h>
+.Pp
+The include files
+.In sys/param.h
+and
+.In sys/types.h
+are necessary.
 .Sh SEE ALSO
 .Xr setgroups 2 ,
-.Xr initgroups 3
+.Xr initgroups 3 ,
+.Xr compat 5
 .Sh HISTORY
 The
 .Fn getgroups