+.\"
+.\" 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
.\"
.\" @(#)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
projects / apple / xnu.git / blobdiff