getgroups
Prev  Section 2  Next

Name

getgroups, setgroups — get/set list of supplementary group IDs

Synopsis

#include <sys/types.h>
#include <unistd.h>
int getgroups( int   size,
  gid_t   list[]); 
#include <grp.h>
int setgroups( size_t   size,
  const gid_t *  list);
[Note] Note
Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
setgroups():
_BSD_SOURCE

DESCRIPTION

getgroups()

Up to size supplementary group IDs (of the calling process) are returned in list. It is unspecified whether the effective group ID of the calling process is included in the returned list. (Thus, an application should also call getegid(2) and add or remove the resulting value.) If size is zero, list is not modified, but the total number of supplementary group IDs for the process is returned.

setgroups()

Sets the supplementary group IDs for the process. Appropriate privileges (Linux: the CAP_SETGID capability) are required.

RETURN VALUE

getgroups()

On success, the number of supplementary group IDs is returned. On error, −1 is returned, and errno is set appropriately.

setgroups()

On success, zero is returned. On error, −1 is returned, and errno is set appropriately.

ERRORS

EFAULT

list has an invalid address.

EINVAL

For setgroups(), size is greater than NGROUPS (32 for Linux 2.0.32). For getgroups(), size is less than the number of supplementary group IDs, but is not zero.

EPERM

The calling process has insufficient privilege to call setgroups().

CONFORMING TO

SVr4, 4.3BSD. The getgroups() function is in POSIX.1-2001. Since setgroups() requires privilege, it is not covered by POSIX.1-2001.

NOTES

A process can have up to at least NGROUPS_MAX supplementary group IDs in addition to the effective group ID. The set of supplementary group IDs is inherited from the parent process and may be changed using setgroups(). The maximum number of supplementary group IDs can be found using sysconf(3):

    long ngroups_max;
    ngroups_max = sysconf(_SC_NGROUPS_MAX);

The maximal return value of getgroups() cannot be larger than one more than the value obtained this way.

SEE ALSO

getgid(2), setgid(2), initgroups(3), capabilities(7)

COLOPHON

This page is part of release 2.79 of the Linux man-pages project. A description of the project, and information about reporting bugs, can be found at http://www.kernel.org/doc/man-pages/.


Copyright 1993 Rickard E. Faith (faithcs.unc.edu)

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Since the Linux kernel and libraries are constantly changing, this
manual page may be incorrect or out-of-date.  The author(s) assume no
responsibility for errors or omissions, or for damages resulting from
the use of the information contained herein.  The author(s) may not
have taken the same level of care in the production of this manual,
which is licensed free of charge, as they might when working
professionally.

Formatted or processed versions of this manual, if unaccompanied by
the source, must acknowledge the copyright and authors of this work.

Modified Thu Oct 31 12:04:29 1996 by Eric S. Raymond <esrthyrsus.com>
Modified, 27 May 2004, Michael Kerrisk <mtk.manpagesgmail.com>
    Added notes on capability requirements
Prev  Up  Next
getgid  Home  gethostid