setregid (BPX1SRG, BPX4SRG) — Set the real and/or effective GIDs

Function

The setregid callable service sets the real or effective GIDs for the calling process to the values that are specified by the input real and effective GID values. If a specified value is equal to -1, the corresponding real or effective GID of the calling process is left unchanged.

Requirements

Operation	Environment
Authorization:	Supervisor or problem state, any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1SRG):	31-bit
AMODE (BPX4SRG):	64-bit
ASC mode:	Primary mode
Interrupt status:	Enabled for interrupts
Locks:	Unlocked
Control parameters:	All parameters must be addressable by the caller and in the primary address space.

Format

CALL BPX1SRG,(RGID,
              EGID,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4SRG with the same parameters.

Parameters

RGID

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the real GID to be set for the calling process. If RGID is -1, the real GID for the calling process is left unchanged.

EGID

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the effective GID to be set for the calling process. If EGID is -1, the effective GID for the calling process is left unchanged.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the setregid service returns -1 if it is not successful. If it is successful, the setregid service returns 0.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the setregid service stores the return code. The setregid service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The setregid service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EINVAL	The value of RGID or EGID is not valid.
EPERM	The process does not have appropriate privileges to set the real GID or the effective GID. Refer to Authorization for information on appropriate privileges.
EMVSSAF2ERR	The SAF call IRRSSG00 incurred an error.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the setregid service stores the reason code. The setregid service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For the reason codes, see z/OS UNIX System Services Messages and Codes. The reason code for EMVSSAF2ERR contains the RACF® return and reason codes, respectively, in the two low-order bytes. For a more detailed description of the RACF SETGID service return and reason code values, see the following table:

RACF return code	RACF reason code	Explanation
8	12	Internal error during RACF processing
8	16	Unable to establish recovery

For a more detailed description of the RACF CKPRIV service return and reason code values, see the following table:

RACF return code	RACF reason code	Explanation
8	12	Internal error during RACF processing

Usage notes

A process with appropriate privileges (see Authorization) can set the real and effective GID to any valid GID value. An unprivileged process can only set the effective GID if the EGID argument is equal to the real, effective, or saved GID of the process. An unprivileged process can only set the real GID if the RGID argument is equal to the real, effective, or saved GID of the process.
The setregid does not change any supplementary GIDs of the calling process.

Related services

Characteristics and restrictions

If the setregid service is issued from multiple tasks within one address space, use synchronization to ensure that the setregid services are not performed concurrently. The execution of setregid requests concurrently within one address space can yield unpredictable results.
If the setregid service is issued from an address space with multiple processes, the result of the service call affects all processes in the address space.

Examples

For an example using this callable service, see BPX1SRG (setregid) example.