xnu-3248.20.55.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 ecc9c82eec74d591f16e65ff12f731cd53f135b6..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
 .\"    $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
 .\"
 .\"
 .\"     @(#)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
 .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
 .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
 .Sh DESCRIPTION

-.Fn Getgroups
+.Fn getgroups

 gets the current group access list of the current user process
 and stores it in the array 
 gets the current group access list of the current user process
 and stores it in the array 

-.Fa gidset .
+.Fa grouplist[] .

 The parameter
 The parameter

-.Fa gidsetlen
+.Fa gidsetsize

 indicates the number of entries that may be placed in 
 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
 returns the actual number of groups returned in

-.Fa gidset .
-No more than
+.Fa grouplist[] .
+However, no more than

 .Dv {NGROUPS_MAX}
 .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
 is 0, 
 .Fn getgroups
 returns the number of groups without modifying the

-.Fa gidset
+.Fa grouplist[]

 array.
 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.
 .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
 .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
 .It Bq Er EINVAL
 The argument

-.Fa gidsetlen
+.Fa gidsetsize ,
+although non-zero,

 is smaller than the number of groups in the group set.
 is smaller than the number of groups in the group set.

-.It Bq Er EFAULT
-The argument
-.Fa gidset
-specifies
-an invalid address.

 .El
 .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 ,
 .Sh SEE ALSO
 .Xr setgroups 2 ,

-.Xr initgroups 3
+.Xr initgroups 3 ,
+.Xr compat 5

 .Sh HISTORY
 The
 .Fn getgroups
 .Sh HISTORY
 The
 .Fn getgroups