PROLOG | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | RATIONALE | FUTURE DIRECTIONS | SEE ALSO | COPYRIGHT

SETREGID(3P)              POSIX Programmer's Manual             SETREGID(3P)

PROLOG         top

       This manual page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the
       corresponding Linux manual page for details of Linux behavior), or
       the interface may not be implemented on Linux.

NAME         top

       setregid — set real and effective group IDs

SYNOPSIS         top

       #include <unistd.h>

       int setregid(gid_t rgid, gid_t egid);

DESCRIPTION         top

       The setregid() function shall set the real and effective group IDs of
       the calling process.

       If rgid is −1, the real group ID shall not be changed; if egid is −1,
       the effective group ID shall not be changed.

       The real and effective group IDs may be set to different values in
       the same call.

       Only a process with appropriate privileges can set the real group ID
       and the effective group ID to any valid value.

       A non-privileged process can set either the real group ID to the
       saved set-group-ID from one of the exec family of functions, or the
       effective group ID to the saved set-group-ID or the real group ID.

       If the real group ID is being set (rgid is not −1), or the effective
       group ID is being set to a value not equal to the real group ID, then
       the saved set-group-ID of the current process shall be set equal to
       the new effective group ID.

       Any supplementary group IDs of the calling process remain unchanged.

RETURN VALUE         top

       Upon successful completion, 0 shall be returned. Otherwise, −1 shall
       be returned and errno set to indicate the error, and neither of the
       group IDs are changed.

ERRORS         top

       The setregid() function shall fail if:

       EINVAL The value of the rgid or egid argument is invalid or out-of-
              range.

       EPERM  The process does not have appropriate privileges and a change
              other than changing the real group ID to the saved set-group-
              ID, or changing the effective group ID to the real group ID or
              the saved set-group-ID, was requested.

       The following sections are informative.

EXAMPLES         top

       None.

APPLICATION USAGE         top

       If a non-privileged set-group-ID process sets its effective group ID
       to its real group ID, it can only set its effective group ID back to
       the previous value if rgid was −1 in the setregid() call, since the
       saved-group-ID is not changed in that case. If rgid was equal to the
       real group ID in the setregid() call, then the saved set-group-ID
       will also have been changed to the real user ID.

RATIONALE         top

       Earlier versions of this standard did not specify whether the saved
       set-group-ID was affected by setregid() calls. This version specifies
       common existing practice that constitutes an important security
       feature. The ability to set both the effective group ID and saved
       set-group-ID to be the same as the real group ID means that any
       security weakness in code that is executed after that point cannot
       result in malicious code being executed with the previous effective
       group ID. Privileged applications could already do this using just
       setgid(), but for non-privileged applications the only standard
       method available is to use this feature of setregid().

FUTURE DIRECTIONS         top

       None.

SEE ALSO         top

       exec(1p), getegid(3p), geteuid(3p), getgid(3p), getuid(3p),
       setegid(3p), seteuid(3p), setgid(3p), setreuid(3p), setuid(3p)

       The Base Definitions volume of POSIX.1‐2008, unistd.h(0p)

COPYRIGHT         top

       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information
       Technology -- Portable Operating System Interface (POSIX), The Open
       Group Base Specifications Issue 7, Copyright (C) 2013 by the
       Institute of Electrical and Electronics Engineers, Inc and The Open
       Group.  (This is POSIX.1-2008 with the 2013 Technical Corrigendum 1
       applied.) In the event of any discrepancy between this version and
       the original IEEE and The Open Group Standard, the original IEEE and
       The Open Group Standard is the referee document. The original
       Standard can be obtained online at http://www.unix.org/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the
       source files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .

IEEE/The Open Group                 2013                        SETREGID(3P)