xnu-4903.270.47.tar.gz

[apple/xnu.git] / bsd / man / man2 / getgroups.2

diff --git a/bsd/man/man2/getgroups.2 b/bsd/man/man2/getgroups.2
index 160022ca3e53c8183745dd5fdbf2d947988b4794..2ae5297fcfefc31203f447324dd4a215ff0bc9b1 100644 (file)
--- 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,7 +56,7 @@
 .\"
 .\"     @(#)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
@@ -47,7 +70,7 @@
 .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 grouplist[] .
@@ -55,20 +78,47 @@ The parameter
 .Fa gidsetsize
 indicates the number of entries that may be placed in 
 .Fa grouplist[] .
-.Fn Getgroups
+.Fn getgroups
 returns the actual number of groups returned in
 .Fa grouplist[] .
-No more than
+However, no more than
 .Dv {NGROUPS_MAX}
-will ever
-be returned.
-If
+will be returned. If
 .Fa gidsetsize
 is 0, 
 .Fn getgroups
 returns the number of groups without modifying the
 .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.
 Otherwise, a value of -1 is returned and the global integer variable