setgid(2)

1setgid(2)                     System Calls Manual                    setgid(2)
2
3
4

NAME

6       setgid - set group identity
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <unistd.h>
13
14       int setgid(gid_t gid);
15

DESCRIPTION

17       setgid()  sets  the  effective group ID of the calling process.  If the
18       calling process is privileged (more precisely: has the CAP_SETGID capa‐
19       bility  in its user namespace), the real GID and saved set-group-ID are
20       also set.
21
22       Under Linux, setgid() is implemented like the POSIX  version  with  the
23       _POSIX_SAVED_IDS  feature.   This allows a set-group-ID program that is
24       not set-user-ID-root to drop all of its group privileges, do  some  un-
25       privileged work, and then reengage the original effective group ID in a
26       secure manner.
27

RETURN VALUE

29       On success, zero is returned.  On error, -1 is returned, and  errno  is
30       set to indicate the error.
31

ERRORS

33       EINVAL The  group  ID  specified in gid is not valid in this user name‐
34              space.
35
36       EPERM  The calling  process  is  not  privileged  (does  not  have  the
37              CAP_SETGID  capability  in its user namespace), and gid does not
38              match the real group ID or saved  set-group-ID  of  the  calling
39              process.
40

VERSIONS

42   C library/kernel differences
43       At the kernel level, user IDs and group IDs are a per-thread attribute.
44       However, POSIX requires that all threads in a process  share  the  same
45       credentials.   The  NPTL threading implementation handles the POSIX re‐
46       quirements by providing wrapper functions for the various system  calls
47       that  change process UIDs and GIDs.  These wrapper functions (including
48       the one for setgid()) employ a signal-based technique  to  ensure  that
49       when  one  thread  changes credentials, all of the other threads in the
50       process also change their credentials.  For details, see nptl(7).
51

STANDARDS

53       POSIX.1-2008.
54

HISTORY

56       POSIX.1-2001, SVr4.
57
58       The original Linux setgid() system call  supported  only  16-bit  group
59       IDs.   Subsequently,  Linux 2.4 added setgid32() supporting 32-bit IDs.
60       The glibc setgid() wrapper function transparently deals with the varia‐
61       tion across kernel versions.
62