Added/updated glibc feature test macro requirements

[thirdparty/man-pages.git] / man3 / getgrouplist.3

.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de)
.\" Distributed under GPL
.\" Thanks to glibc info pages
.\"
.\" Modified 2003-11-18, aeb: glibc is broken
.TH GETGROUPLIST 3 2007-07-26 "GNU" "Linux Programmer's Manual"
.SH NAME
getgrouplist \-  list of groups a user belongs to
.SH SYNOPSIS
.sp
.B #include <grp.h>
.sp
.BI "int getgrouplist(const char *" user ", gid_t " group ,
.br
.BI "                 gid_t *" groups ", int *" ngroups );
.sp
.in -4n
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.in
.sp
.BR getgrouplist ():
_BSD_SOURCE
.SH DESCRIPTION
The
.BR getgrouplist ()
function scans the group database for all the groups
.I user
belongs to.
Up to
.RI * ngroups
group IDs corresponding to these groups are stored in the array
.IR groups ;
the return value from the function is the number of group IDs
actually stored.
The group
.I group
is automatically included in the list of groups returned by
.BR getgrouplist ().
.SH "RETURN VALUE"
If
.RI * ngroups
is smaller than the total number of groups found, then
.BR getgrouplist ()
returns \-1.
In all cases the actual number of groups is stored in
.RI * ngroups .
.SH "VERSIONS"
This function is present since glibc 2.2.4.
.SH "CONFORMING TO"
This function is non-standard; it appears on most BSDs.
.SH BUGS
The glibc 2.3.2 implementation of this function is broken:
it overwrites memory when the actual number of groups is larger than
.RI * ngroups .
.SH EXAMPLE
.nf
/* This crashes with glibc 2.3.2 */
#include <stdio.h>
#include <stdlib.h>
#include <grp.h>
#include <pwd.h>

int
main(void)
{
    int i, ng = 0;
    char *user = "who";       /* username here */
    gid_t *groups = NULL;
    struct passwd *pw = getpwnam(user);

    if (pw == NULL)
        exit(EXIT_SUCCESS);

    if (getgrouplist(user, pw\->pw_gid, NULL, &ng) < 0) {
        groups = (gid_t *) malloc(ng * sizeof (gid_t));
        getgrouplist(user, pw\->pw_gid, groups, &ng);
    }

    for (i = 0; i < ng; i++)
        printf("%d\en", groups[i]);

    exit(EXIT_SUCCESS);
}
.fi
.SH "SEE ALSO"
.BR getgroups (2),
.BR setgroups (2)