lib/libc/gen/getgrouplist.3

   1 .\"     $NetBSD: getgrouplist.3,v 1.14 2008/05/02 18:11:04 martin Exp $
   2 .\"
   3 .\" Copyright (c) 2005 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Luke Mewburn.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .\" Copyright (c) 1991, 1993
  31 .\"     The Regents of the University of California.  All rights reserved.
  32 .\"
  33 .\" Redistribution and use in source and binary forms, with or without
  34 .\" modification, are permitted provided that the following conditions
  35 .\" are met:
  36 .\" 1. Redistributions of source code must retain the above copyright
  37 .\"    notice, this list of conditions and the following disclaimer.
  38 .\" 2. Redistributions in binary form must reproduce the above copyright
  39 .\"    notice, this list of conditions and the following disclaimer in the
  40 .\"    documentation and/or other materials provided with the distribution.
  41 .\" 3. 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 .\"     @(#)getgrouplist.3      8.1 (Berkeley) 6/9/93
  58 .\"
  59 .Dd January 6, 2005
  60 .Dt GETGROUPLIST 3
  61 .Os
  62 .Sh NAME
  63 .Nm getgrouplist ,
  64 .Nm getgroupmembership ,
  65 .Nd calculate group access list
  66 .Sh LIBRARY
  67 .Lb libc
  68 .Sh SYNOPSIS
  69 .In unistd.h
  70 .Ft int
  71 .Fn getgrouplist "const char *name" "gid_t basegid" "gid_t *groups" "int *ngroups"
  72 .Ft int
  73 .Fn getgroupmembership "const char *name" "gid_t basegid" "gid_t *groups" "int maxgrp" "int *ngroups"
  74 .Sh DESCRIPTION
  75 The
  76 .Fn getgrouplist
  77 and
  78 .Fn getgroupmembership
  79 functions read through the group database and calculate
  80 the group access list for the user specified in
  81 .Fa name .
  82 The
  83 .Fa basegid
  84 is automatically included in the groups list.
  85 Typically this value is given as
  86 the group number from the password database.
  87 .Pp
  88 The resulting group list is returned in the integer array pointed to by
  89 .Fa groups .
  90 .Pp
  91 For
  92 .Fn getgrouplist ,
  93 the caller specifies the size of the
  94 .Fa groups
  95 array in the integer pointed to by
  96 .Fa ngroups .
  97 .Pp
  98 For
  99 .Fn getgroupmembership ,
 100 the caller specifies the size of the
 101 .Fa groups
 102 array in
 103 .Fa maxgrp .
 104 .Pp
 105 The actual number of groups found is returned in
 106 .Fa ngroups .
 107 .Pp
 108 Duplicate group ids will be suppressed from the result.
 109 .Sh RETURN VALUES
 110 The
 111 .Fn getgrouplist
 112 and
 113 .Fn getgroupmembership
 114 functions
 115 return 0 if successful, and
 116 return \-1 if the size of the group list is too small to
 117 hold all the user's groups.
 118 In the latter case, the
 119 .Fa groups
 120 array will be filled with as many groups as will fit and
 121 .Fa ngroups
 122 will contain the total number of groups found.
 123 .Sh FILES
 124 .Bl -tag -width /etc/group -compact
 125 .It Pa /etc/group
 126 group membership list
 127 .El
 128 .Sh SEE ALSO
 129 .Xr setgroups 2 ,
 130 .Xr initgroups 3 ,
 131 .Xr group 5
 132 .Sh HISTORY
 133 The
 134 .Fn getgrouplist
 135 function first appeared in
 136 .Bx 4.4 .
 137 The
 138 .Fn getgroupmembership
 139 function first appeared in
 140 .Nx 3.0
 141 to address an API deficiency in
 142 .Fn getgrouplist .
 143 .Sh BUGS
 144 The
 145 .Fn getgrouplist
 146 function
 147 uses the routines based on
 148 .Xr getgrent 3 .
 149 If the invoking program uses any of these routines,
 150 the group structure will
 151 be overwritten in the call to
 152 .Fn getgrouplist .