bsd/man/man2/getgroups.2

   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
  74 gets the current group access list of the current user process
  75 and stores it in the array
  76 .Fa grouplist[] .
  77 The parameter
  78 .Fa gidsetsize
  79 indicates the number of entries that may be placed in
  80 .Fa grouplist[] .
  81 .Fn getgroups
  82 returns the actual number of groups returned in
  83 .Fa grouplist[] .
  84 However, no more than
  85 .Dv {NGROUPS_MAX}
  86 will be returned. If
  87 .Fa gidsetsize
  88 is 0,
  89 .Fn getgroups
  90 returns the number of groups without modifying the
  91 .Fa grouplist[]
  92 array.
  93 .Pp
  94 Calling
  95 .Xr initgroups 3
  96 to opt-in for supplementary groups will cause
  97 .Fn getgroups
  98 to return a single entry, the GID that was passed to
  99 .Xr initgroups 3 .
 100 .Pp
 101 To provide compatibility with applications that use
 102 .Fn getgroups
 103 in environments where users may be in more than
 104 .Dv {NGROUPS_MAX}
 105 groups, a variant of
 106 .Fn getgroups ,
 107 obtained when compiling with either the macros
 108 .Dv _DARWIN_UNLIMITED_GETGROUPS
 109 or
 110 .Dv _DARWIN_C_SOURCE
 111 defined, can be used that is not limited to
 112 .Dv {NGROUPS_MAX}
 113 groups.
 114 However, this variant only returns the user's default group access list and
 115 not the group list modified by a call to
 116 .Xr setgroups 2
 117 (either in the current process or an ancestor process).
 118 Use of
 119 .Xr setgroups 2
 120 is highly discouraged, and there is no foolproof way to determine if it has
 121 been previously called.
 122 .Sh RETURN VALUES
 123 A successful call returns the number of groups in the group set.
 124 Otherwise, a value of -1 is returned and the global integer variable
 125 .Va errno
 126 is set to indicate the error.
 127 .Sh ERRORS
 128 The possible errors for
 129 .Fn getgroups
 130 are:
 131 .Bl -tag -width Er
 132 .\" ==========
 133 .It Bq Er EFAULT
 134 The argument
 135 .Fa grouplist
 136 specifies an invalid address.
 137 .\" ==========
 138 .It Bq Er EINVAL
 139 The argument
 140 .Fa gidsetsize ,
 141 although non-zero,
 142 is 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
 149 The include files
 150 .In sys/param.h
 151 and
 152 .In sys/types.h
 153 are necessary.
 154 .Sh SEE ALSO
 155 .Xr setgroups 2 ,
 156 .Xr initgroups 3 ,
 157 .Xr compat 5
 158 .Sh HISTORY
 159 The
 160 .Fn getgroups
 161 function call appeared in
 162 .Bx 4.2 .