setgid, setrgid, setegid, or setregid Subroutine

Base Operating System and Extensions Technical Reference, Volume 2

setgid, setrgid, setegid, or setregid 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;

Description

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

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.

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

Parameters

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.

Return Values

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 either the setgid or setegid subroutine fails, one or more of the following are returned:

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 or EGID parameter is invalid.

Implementation Specifics

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

The operating system does not support setuid or setgid shell scripts.

Related Information

The getgid subroutine, getgroups subroutine, setgroups subroutine, setuid subroutine.

The setgroups command.

List of Security and Auditing Subroutines, Subroutines Overview in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.