'\" te
.\" Copyright (c) 2015, Oracle and/or its                                     affiliates. All rights reserved.
.TH getgrouplist 3C "22 Sep 2015" "SunOS 5.11" "Standard C Library Functions"
.SH NAME
getgrouplist \- obtain a list of group memberships of a user
.SH SYNOPSIS
.LP
.nf
 #include <grp.h>
int getgrouplist(const char *user, gid_t group, gid_t *groups, int *ngroups);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBgetgrouplist()\fR function takes \fBuser\fR and \fBgroup\fR as arguments, along with \fBgroups\fR and \fBngroups\fR. \fBuser\fR and \fBgroup\fR are taken from the user's password entry. \fBgroup\fR is a pointer to an array of \fBgid_ts\fR, and \fBngroups\fR is a pointer to an integer holding the number of \fBgid_ts\fR in groups.
.sp
.LP
The \fBgetgrouplist()\fR function fills in the given array group with the group IDs of all the groups to which the user belongs. \fB*ngroups\fR of these group IDs will be returned in the array groups. The resulting value of \fB*ngroups\fR will include \fBgroup\fR in the count. The overall value of \fBngroups\fR can be greater than the number of group IDs stored in groups.
.sp
.LP
Before returning, the \fBgetgrouplist()\fR function sets the integer variable pointed by \fBngroups\fR to the number of group IDs found for the user. This is true even when the \fBgetgrouplist()\fR function returns an error.
.SH RETURN VALUES
.sp
.LP
The \fBgetgrouplist()\fR function returns the new value \fB*ngroups\fR if it is less than or equal to the original value of \fB*ngroups\fR.
.sp
.LP
The \fBgetgrouplist()\fR function returns \fB-1\fR if the new value of \fB*ngroups\fR is greater than the original value. In other words, if the \fBgetgrouplist()\fR function returns \fB-1\fR, there were more groups than the buffer at \fB*group\fR could hold. In this case, \fB*ngroups\fR retains its new value, and can be checked by the caller to facilitate a subsequent call to the \fBgetgrouplist()\fR function with an appropriately sized array at \fB*groups\fR.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
MT-LevelSafe
.TE

.SH SEE ALSO
.sp
.LP
\fBIntro\fR(2), \fBinitgroups\fR(3C), \fBgetgrnam\fR(3C), \fBgetpwnam\fR(3C), \fBstandards\fR(5).
.SH NOTES
.sp
.LP
The \fBgetgroupsbymember()\fR function is not a standard function, therefore \fB_EXTENSIONS_\fR are defined when you include <\fBgrp.h\fR>, else this function is not declared.