The GNU C Library - Setting Groups

Setting the Group IDs

This section describes the functions for altering the group IDs (real and effective) of a process. To use these facilities, you must include the header files `sys/types.h' and `unistd.h'.

Function int setgid (gid_t newgid)

This function sets both the real and effective group ID of the process to newgid, provided that the process has appropriate privileges.

If the process is not privileged, then newgid must either be equal to the real group ID or the saved group ID. In this case, setgid sets only the effective group ID and not the real group ID.

The return values and error conditions for setgid are the same as those for setuid .

Function int setregid (gid_t rgid, fid_t egid)

This function sets the real group ID of the process to rgid and the effective group ID to egid. If rgid is -1 , it means not to change the real group ID; likewise if egid is -1 , it means not to change the effective group ID.

The setregid function is provided for compatibility with 4.3 BSD Unix, which does not support saved IDs. You can use this function to swap the effective and real group IDs of the process. (Privileged processes are not limited to this usage.) If saved IDs are supported, you should use that feature instead of using this function. See Enable/Disable Setuid.

The return values and error conditions for setregid are the same as those for setreuid .

The GNU system also lets privileged processes change their supplementary group IDs. To use setgroups or initgroups , your programs should include the header file `grp.h'.

Function int setgroups (size_t count, gid_t *groups)

This function sets the process's supplementary group IDs. It can only be called from privileged processes. The count argument specifies the number of group IDs in the array groups.

This function returns 0 if successful and -1 on error. The following errno error conditions are defined for this function:

EPERM

The calling process is not privileged.

Function int initgroups (const char *user, gid_t gid)

The initgroups function effectively calls setgroups to set the process's supplementary group IDs to be the normal default for the user name user. The group ID gid is also included.