setgid, setrgid, setegid, setregid, or setgidx Subroutine

Purpose

Sets the process group IDs.

Library

Standard C Library (libc.a)

Syntax

#include <unistd.h>
int setgid (GID)
gid_t  GID;
int setrgid (RGID)
gid_t  RGID;

int setegid (EGID)
gid_t  EGID;

int setregid (RGID, EGID)
gid_t RGID;
gid_t EGID;
#include <unistd.h>
#include <sys/id.h>

int setgidx ( which, GID )
int which;
gid_t GID;

Description

The setgid, setrgid, setegid, setregid, and setgidx subroutines set the process group IDs of the calling process. The following semantics are supported:

Item Description
setgid If the effective user ID of the process is the root user, the process's real, effective, and saved group IDs are set to the value of the GID parameter. Otherwise, the process effective group ID is reset if the GID parameter is equal to either the current real or saved group IDs, or one of its supplementary group IDs. Supplementary group IDs of the calling process are not changed.
setegid The process effective group ID is reset if one of the following conditions is met:
  • The EGID parameter is equal to either the current real or saved group IDs.
  • The EGID parameter is equal to one of its supplementary group IDs.
  • The effective user ID of the process is the root user.
setrgid The EPERM error code is always returned.
setregid The RGID and EGID parameters can have one of the following relationships:
RGID != EGID
If the EGID parameter is equal to either the process's real or saved group IDs, the process effective group ID is set to the EGID parameter. Otherwise, the EPERM error code is returned.
RGID == EGID
If the effective user ID of the process is the root user, the process's real and effective group IDs are set to the EGID parameter. If the EGID parameter is equal to the process's real or saved group IDs, the process effective group ID is set to EGID. Otherwise, the EPERM error code is returned.
setgidx The which parameter can have one of the following values:
ID_EFFECTIVE
GID must be either the real or saved GID or one of the values in the concurrent group set. The effective group ID for the current process will be set to GID.
ID_EFFECTIVE|ID_REAL
Invoker must have appropriate privilege. The real and effective group ID for the current process will be set to GID.
ID_EFFECTIVE|ID_REAL|ID_SAVED
Invoker must have appropriate privilege. The real, effective and saved group ID for the current process will be set to GID.

The setegid, setrgid, setregid, and setgidx subroutines are thread-safe.

The operating system does not support setuid (setuid, setruid, seteuid, setreuid or setuidx Subroutine) or setgid shell scripts.

These subroutines are part of Base Operating System (BOS) Runtime.

Parameters

Item Description
GID Specifies the value of the group ID to set.
RGID Specifies the value of the real group ID to set.
EGID Specifies the value of the effective group ID to set.
which Specifies which group ID values to set.

Return Values

Item Description
0 Indicates that the subroutine was successful.
-1 Indicates the subroutine failed. The errno global variable is set to indicate the error.

Error Codes

If the setgid, setegid, or setgidx subroutine fails, one or more of the following are returned:

Item Description
EPERM Indicates the process does not have appropriate privileges and the GID or EGID parameter is not equal to either the real or saved group IDs of the process.
EINVAL Indicates the value of the GID, EGID or which parameter is invalid.