qsysetgroups()--Set Supplemental Group IDs


  Syntax
 #include <qsysetid.h>

 int qsysetgroups(int gidsetsize, gid_t grouplist[])
  Service Program Name: QSYSETIDS

  Default Public Authority: *USE

  Threadsafe: No

The qsysetgroups API sets the supplementary group IDs of the calling thread. The qsysetgroups API cannot set more than (NGROUPS_MAX-1) groups in the group set.

The real group ID, effective group ID and saved group ID 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

gidsetsize
(Input) The number of elements in the supplied array grouplist. If the number of elements is specified as 0, the current supplementary groups will be removed.

grouplist
(Input) The supplementary group IDs.

Authorities and locks

User profile associated with gid Authority
*USE authority is required to the user profile associated with each gid in the group list if the gid is not equal to the current thread's real, effective, or saved group IDs or one of the groups in the current thread's supplemental group list.

User profile associated with each gid Lock
*SHRRD

Return Value

0 qsysetgroups() was successful.
-1 qsysetgroups() was not successful. The errno global variable is set to indicate the error.


Error Conditions

If qsysetgroups() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

Error condition Additional information
[EAGAIN]

User profile associated with a gid is locked. Try again.

[EDAMAGE]

The user profile associated with a gid or an internal system object is damaged.

[EINVAL]

One of the GID values in the grouplist argument is not valid. Following are possible reasons:

  • Out of range.
  • Not associated with a user profile.
  • gidsetsize too large.
[ENOTSUP]

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

[EPERM]

Operation not permitted. Following are possible reasons:

  • The thread does not have *USE authority to the user profile associated with the GID and the GID to be set is not the same as the real, effective, saved group IDs or any of the supplemental groups.
  • Supplemental groups cannot be set if effective GID is 0.
[EUNKNOWN]

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



API introduced: V5R2

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