qsysetregid()--Set Real and Effective Group IDs

Syntax

 #include <qsysetids.h>

 int qsysetregid(gid_t rgid, gid_t egid);

  Service Program Name: QSYSETIDS

  Default Public Authority: *USE

  Threadsafe: Yes

The qsysetregid() function is used to set the real and effective group IDs. The real and effective group IDs may be set to different values in the same call.

A thread with *ALLOBJ special authority can set the real group ID and the effective group ID to any valid value.

A thread without *ALLOBJ special authority can only set the real group ID to the saved group ID. A thread without *ALLOBJ special authority can only set the effective group ID to the saved group ID or the real group ID.

Any supplemental group IDs remain unchanged.

Job scoped locks with a lock state of *SHRRD are held on the user profiles associated with the real user ID, effective user ID, saved user ID, real group ID, effective group ID, saved group ID, and all of the supplemental groups.

Parameters

real gid

(Input) Group ID.

This field must contain one of the following values:

0: There is no real group ID.
1 to 4294967294: The group ID value for the set operation.
4294967295: The real group ID does not change. This value is the same as X'FFFFFFFF' or -1 in languages that do not support unsigned integers.

effective gid

(Input) Group ID.

This field must contain one of the following values:

0: There is no effective group ID.
1 to 4294967294: The group ID value for the set operation.
4294967295: The effective group ID does not change. This value is the same as X'FFFFFFFF' or -1 in languages that do not support unsigned integers.

Authorities and Locks

*ALLOBJ special authority: *ALLOBJ special authority is required to change the real group ID if rgid is not equal to the saved group ID. *ALLOBJ special authority is required to set the effective group ID if the egid is not equal to the real group ID or the saved group ID.
User profile associated with rgid lock: *SHRRD
User profile associated with egid lock: *SHRRD

Return Value

0: qsysetregid() was successful.
-1: qsysetregid() was not successful. The errno is set to indicate the error.

Error Conditions

If qsysetregid() is not successful, errno indicates one of the following errors.

Error condition

Additional information

[EAGAIN]

User profile associated with the rgid or rgid is locked. Try again.

[EDAMAGE]

The user profile associated with one of the GIDs or an internal system object is damaged.

[EINVAL]

The value of the gid argument is not valid. Following are possible reasons:

Out of range.
Not associated with a user profile.

[ENOTSUP]

Operation not supported. The current effective user profile specifies OWNER(*GRPPRF), but the group profile associated with this gid is not equal to the user profile's first group and the user's first group is not in the list of supplemental groups.

[EPERM]

Operation not permitted. Following are possible reasons:

The thread does not have *ALLOBJ special authority and a change other than changing the real group ID to the saved group ID, or changing the effective group ID to the real group ID or the saved group ID was requested.
Tried to set effective group ID to 0 when there are supplemental groups.

[EUNKNOWN]

An unknown error has occurred. Check the joblog for error messages.

API introduced: V4R5

[ Back to top | UNIX-Type APIs | APIs by category ]