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 75The 76.Fn getgrouplist 77and 78.Fn getgroupmembership 79functions read through the group database and calculate 80the group access list for the user specified in 81.Fa name . 82The 83.Fa basegid 84is automatically included in the groups list. 85Typically this value is given as 86the group number from the password database. 87.Pp 88The resulting group list is returned in the integer array pointed to by 89.Fa groups . 90.Pp 91For 92.Fn getgrouplist , 93the caller specifies the size of the 94.Fa groups 95array in the integer pointed to by 96.Fa ngroups . 97.Pp 98For 99.Fn getgroupmembership , 100the caller specifies the size of the 101.Fa groups 102array in 103.Fa maxgrp . 104.Pp 105The actual number of groups found is returned in 106.Fa ngroups . 107.Pp 108Duplicate group ids will be suppressed from the result. 109.Sh RETURN VALUES 110The 111.Fn getgrouplist 112and 113.Fn getgroupmembership 114functions 115return 0 if successful, and 116return \-1 if the size of the group list is too small to 117hold all the user's groups. 118In the latter case, the 119.Fa groups 120array will be filled with as many groups as will fit and 121.Fa ngroups 122will contain the total number of groups found. 123.Sh FILES 124.Bl -tag -width /etc/group -compact 125.It Pa /etc/group 126group membership list 127.El 128.Sh SEE ALSO 129.Xr setgroups 2 , 130.Xr initgroups 3 , 131.Xr group 5 132.Sh HISTORY 133The 134.Fn getgrouplist 135function first appeared in 136.Bx 4.4 . 137The 138.Fn getgroupmembership 139function first appeared in 140.Nx 3.0 141to address an API deficiency in 142.Fn getgrouplist . 143.Sh BUGS 144The 145.Fn getgrouplist 146function 147uses the routines based on 148.Xr getgrent 3 . 149If the invoking program uses any of these routines, 150the group structure will 151be overwritten in the call to 152.Fn getgrouplist . 153