1.\" 2.\" Copyright (c) 2008-2011 Apple Inc. All rights reserved. 3.\" 4.\" @APPLE_LICENSE_HEADER_START@ 5.\" 6.\" This file contains Original Code and/or Modifications of Original Code 7.\" as defined in and that are subject to the Apple Public Source License 8.\" Version 2.0 (the 'License'). You may not use this file except in 9.\" compliance with the License. Please obtain a copy of the License at 10.\" http://www.opensource.apple.com/apsl/ and read it before using this 11.\" file. 12.\" 13.\" The Original Code and all software distributed under the License are 14.\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 15.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 16.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 17.\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 18.\" Please see the License for the specific language governing rights and 19.\" limitations under the License. 20.\" 21.\" @APPLE_LICENSE_HEADER_END@ 22.\" 23.\" 24.\" $NetBSD: getgroups.2,v 1.8 1995/02/27 12:32:57 cgd Exp $ 25.\" 26.\" Copyright (c) 1983, 1991, 1993 27.\" The Regents of the University of California. All rights reserved. 28.\" 29.\" Redistribution and use in source and binary forms, with or without 30.\" modification, are permitted provided that the following conditions 31.\" are met: 32.\" 1. Redistributions of source code must retain the above copyright 33.\" notice, this list of conditions and the following disclaimer. 34.\" 2. Redistributions in binary form must reproduce the above copyright 35.\" notice, this list of conditions and the following disclaimer in the 36.\" documentation and/or other materials provided with the distribution. 37.\" 3. All advertising materials mentioning features or use of this software 38.\" must display the following acknowledgement: 39.\" This product includes software developed by the University of 40.\" California, Berkeley and its contributors. 41.\" 4. Neither the name of the University nor the names of its contributors 42.\" may be used to endorse or promote products derived from this software 43.\" without specific prior written permission. 44.\" 45.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 46.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 47.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 48.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 49.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 50.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 51.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 52.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 53.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 54.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 55.\" SUCH DAMAGE. 56.\" 57.\" @(#)getgroups.2 8.2 (Berkeley) 4/16/94 58.\" 59.Dd October 28, 2011 60.Dt GETGROUPS 2 61.Os BSD 4.2 62.Sh NAME 63.Nm getgroups 64.Nd get group access list 65.Sh SYNOPSIS 66.Fd #include <unistd.h> 67.Ft int 68.Fo getgroups 69.Fa "int gidsetsize" 70.Fa "gid_t grouplist[]" 71.Fc 72.Sh DESCRIPTION 73.Fn getgroups 74gets the current group access list of the current user process 75and stores it in the array 76.Fa grouplist[] . 77The parameter 78.Fa gidsetsize 79indicates the number of entries that may be placed in 80.Fa grouplist[] . 81.Fn getgroups 82returns the actual number of groups returned in 83.Fa grouplist[] . 84However, no more than 85.Dv {NGROUPS_MAX} 86will be returned. If 87.Fa gidsetsize 88is 0, 89.Fn getgroups 90returns the number of groups without modifying the 91.Fa grouplist[] 92array. 93.Pp 94Calling 95.Xr initgroups 3 96to opt-in for supplementary groups will cause 97.Fn getgroups 98to return a single entry, the GID that was passed to 99.Xr initgroups 3 . 100.Pp 101To provide compatibility with applications that use 102.Fn getgroups 103in environments where users may be in more than 104.Dv {NGROUPS_MAX} 105groups, a variant of 106.Fn getgroups , 107obtained when compiling with either the macros 108.Dv _DARWIN_UNLIMITED_GETGROUPS 109or 110.Dv _DARWIN_C_SOURCE 111defined, can be used that is not limited to 112.Dv {NGROUPS_MAX} 113groups. 114However, this variant only returns the user's default group access list and 115not the group list modified by a call to 116.Xr setgroups 2 117(either in the current process or an ancestor process). 118Use of 119.Xr setgroups 2 120is highly discouraged, and there is no foolproof way to determine if it has 121been previously called. 122.Sh RETURN VALUES 123A successful call returns the number of groups in the group set. 124Otherwise, a value of -1 is returned and the global integer variable 125.Va errno 126is set to indicate the error. 127.Sh ERRORS 128The possible errors for 129.Fn getgroups 130are: 131.Bl -tag -width Er 132.\" ========== 133.It Bq Er EFAULT 134The argument 135.Fa grouplist 136specifies an invalid address. 137.\" ========== 138.It Bq Er EINVAL 139The argument 140.Fa gidsetsize , 141although non-zero, 142is smaller than the number of groups in the group set. 143.El 144.Sh LEGACY SYNOPSIS 145.Fd #include <sys/param.h> 146.Fd #include <sys/types.h> 147.Fd #include <unistd.h> 148.Pp 149The include files 150.In sys/param.h 151and 152.In sys/types.h 153are necessary. 154.Sh SEE ALSO 155.Xr setgroups 2 , 156.Xr initgroups 3 , 157.Xr compat 5 158.Sh HISTORY 159The 160.Fn getgroups 161function call appeared in 162.Bx 4.2 . 163