setgroups (BPX1SGR, BPX4SGR) — Set the supplementary group IDs list

Function

The setgroups callable service replaces the existing supplementary group IDs (GIDs) list for the calling process with the list that is specified by the caller.

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state, any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1SGR):	31-bit
AMODE (BPX4SGR):	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

The syntax format is as follows:

CALL BPX1SGR,(SGid_list_count,
              SGid_list,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4SGR with the same parameters. SGid_list is a 64-bit pointer field.

Parameters

SGid_list_count

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that specifies the number of fullword entries in list that is pointed to by the SGid_list parameter. The value must be in the range of zero to NGroups_Max, inclusive.

Specifying 0 causes all existing supplementary group IDs for the calling process to be deleted. After the setgroups service completes, the calling process does not have any supplementary group IDs.

SGid_list

Supplied parameter

Type:: Address
Length:: Fullword (doubleword)

The name of a fullword (doubleword) that contains a pointer to an array of group IDs (GIDs). The setgroups service uses this list to establish the list of supplementary group IDs. The number of entries in the list is defined by the SGid_list_count parameter.

If the SGid_list_count specified is 0, the SGid_list is ignored and does not need to contain a valid address.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

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

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

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

Return_code	Explanation
EFAULT	The SGid_list and SGid_list_count specify an array that is partially or completely outside the addressable storage range.
EINVAL	The SGid_list_count parameter was less than `0` or greater than NGroups_Max.
EMVSSAF2ERR	System authorization facility (SAF) had an error.
EPERM	The caller is not authorized; only authorized users are allowed to alter the supplementary group IDs list.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the setgroups service stores the reason code. The setgroups 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.

Usage notes

To determine the value of NGroups_Max, see sysconf (BPX1SYC, BPX4SYC) — Determine system configuration options.

Related services

Characteristics and restrictions

To set the supplementary group IDs, the requester must be a superuser. If a non-superuser caller requests the setgroups service, the service returns an EPERM Return_code.
To successfully complete the setgroups service, the caller's process must be the only process in the address space. If multiple processes are present (through attach_exec or attach_execMVS), the function does not complete successfully.

Examples

For an example using this callable service, see BPX1SGR (setgroups) example.