usr/src/lib/libc/gen/getgrouplist.3

.\" Copyright (c) 1991 Regents of the University of California.
.\" All rights reserved.
.\"
.\" %sccs.include.redist.man%
.\"
.\"     @(#)getgrouplist.3      6.1 (Berkeley) %G%
.\"
.Dd
.Dt GETGROUPLIST 3
.Os
.Sh NAME
.Nm getgrouplist
.Nd calculate group access list
.Sh SYNOPSIS
.Fd #include <unistd.h>
.Ft int
.Fn getgrouplist "const char *name" "int basegid" "int *groups" "int *ngroups"
.Sh DESCRIPTION
The
.Fn getgrouplist
function reads through the group file and calculates
the group access list for the user specified in
.Fa name .
The
.Fa basegid
is automatically included in the groups list.
Typically this value is given as
the group number from the password file.
.Pp
The resulting group list is returned in the integer array pointed to by
.Fa groups .
The caller specifies the size of the
.Fa groups
array in the integer pointed to by
.Fa ngroups ;
the actual number of groups found is returned in
.Fa ngroups .
.Sh RETURN VALUES
The
.Fn getgrouplist
function
returns \-1 if the size of the group list is too small to
hold all the user's groups.
Here, the group array will be filled with as many groups as will fit.
.Sh FILES
.Bl -tag -width /etc/group -compact
.It Pa /etc/group
group membership list
.El
.Sh SEE ALSO
.Xr setgroups 2 ,
.Xr initgroups 3
.Sh HISTORY
The
.Nm
function is
.Ud .
.Sh BUGS
The
.Fn getgrouplist
function
uses the routines based on
.Xr getgrent 3 .
If the invoking program uses any of these routines,
the group structure will
be overwritten in the call to
.Fn getgrouplist .