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.
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. |
|
AMODE 64 callers use BPX4SGR with the same parameters. SGid_list is a 64-bit pointer field.
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.
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.
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 | 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. |
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.
To determine the value of NGroups_Max, see sysconf (BPX1SYC, BPX4SYC) — Determine system configuration options.
For an example using this callable service, see BPX1SGR (setgroups) example.