posix_spawnattr_setcred()

Set the user ID (uid) and group ID (gid) of the child process

Synopsis:

#include <posix_spawnattr.h>

int posix_spawnattr_setcred(
       posix_spawnattr_t *attrp,
	uid_t uid, 
	gid_t gid);

Arguments:

attrp

A spawn attributes object attrp used by the implementation.

gid

The group ID that you want to use for the process.

posix_spawnattr_t

A spawn attributes object is of type posix_spawnattr_t (defined in <spawn.h>) and is used to specify the inheritance of process attributes across a spawn operation. IEEE Std 1003.1-2001 doesn't define comparison or assignment operators for the type posix_spawnattr_t.

uid

The user ID that you want to use for the process.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

Use the posix_spawnattr_setcred() function to set the credentials of a spawned process to something other than that of the caller's credentials. Typically, the credentials (i.e. the user ID and group ID) for a process spawned with posix_spawn() and posix_spawnp() inherit the credentials from the calling function. The caller must have an effective uid of root at the time the posix_spawn() or posix_spawnp() call is made; otherwise, the posix_spawn() call returns EPERM. An effective uid of root isn't required to set the credentials to the same values as the caller, which would have the same effect as not calling this function at all.

If the criteria to posix_spawn() is met by the caller, both the real and effective uid/gid of the spawned process is set to the specified credentials; however, the setuid/setgid mode of the spawned image takes precedence over the effective uid/gid of the spawned process in the same way as described for POSIX_SPAWN_RESETIDS (i.e. the setuid/setgid of the spawned image causes the spawned process to inherit the uid/gid of the image as its effective uid/gid respectively. The real uid/gid will be as specified in the credentials).

---

The credentials of the spawned process take effect before the process actually runs, and therefore determines its access to specific resources. This may result in a failure in the spawned process, asynchronous to a successful posix_spawn() or posix_spawnp() call.

---

The credentials established with the posix_spawnattr_setcred() function have no effect unless the POSIX_SPAWNATTR_SETCRED flag has also been set. EPERM won't be returned by posix_spawn() or posix_spawnp() if the POSIX_SPAWNATTR_SETCRED flag isn't set. If both POSIX_SPAWN_SETCRED and POSIX_SPAWN_RESETIDS are set, POSIX_SPAWN_SETCRED will take precedence. This means that when POSIX_SPAWN_SETCRED is set, the posix_spawnattr_getcred() function returns a uid and gid (where the values are greater than or equal to 0 and the parent has root permissions); otherwise, when POSIX_SPAWN_SETCRED isn't set, the default inheritance behavior is used.

---

The POSIX_SPAWN_SETCRED flag has been defined to cause the establishment of desired credentials specified in the posix_spawnattr_t attributes object to be acted upon. Without this flag, any uid and gid specified with posix_spawnattr_setcred() function will be ignored. You can set this flag using posix_spawnattr_setxflags(). The posix_spawnattr_setcred() lets the caller specify both a user ID (uid) and group ID (gid) to assign to the posix_spawnattr_t attributes object. The caller must provide both parameters and can effectively leave one of them unchanged by passing the results of getuid() or getgid() respectively. In order for the uid/gid to take effect, the posix_spawnattr_t attributes object must be passed as a parameter to the posix_spawn() call, the POSIX_SPAWN_SETCRED flag must be set, and the caller must have an effective user ID of 0 (i.e. root). Alternatively, if the caller provides a uid of getuid() and a gid of getgid(), the caller is not required to have root permissions because this is equivalent to the default inheritance behavior. Use the posix_spawnattr_getcred() to let the caller retrieve the uid and gid of the posix_spawnattr_t attributes object set in a previous posix_spawnattr_setcred() call.

---

Returns:

Upon successful completion, posix_spawnattr_setflags() returns zero; otherwise, an error number is returned to indicate the error (errno is set).

Errors:

EINVAL

For any invalid parameter.

EOK

Success.

Classification:

POSIX 1003.1 RTS

See also:

posix_spawn(), posix_spawn_file_actions_addclose(), posix_spawn_file_actions_adddup2(), posix_spawn_file_actions_addopen(), posix_spawn_file_actions_destroy(), posix_spawn_file_actions_init(), posix_spawnattr_addpartid(), posix_spawnattr_addpartition(), posix_spawnattr_destroy(), posix_spawnattr_getcred(), posix_spawnattr_getflags(), posix_spawnattr_getnode(), posix_spawnattr_getpartid(), posix_spawnattr_getpgroup(), posix_spawnattr_getrunmask(), posix_spawnattr_getschedparam(), posix_spawnattr_getschedpolicy(), posix_spawnattr_getsigdefault(), posix_spawnattr_getsigignore(), posix_spawnattr_getsigmask(), posix_spawnattr_getstackmax(), posix_spawnattr_getxflags(), posix_spawnattr_init(), posix_spawnattr_setnode(), posix_spawnattr_setpgroup(), posix_spawnattr_setschedparam(), posix_spawnattr_setrunmask(), posix_spawnattr_setschedpolicy(), posix_spawnattr_setsigdefault(), posix_spawnattr_setsigignore(), posix_spawnattr_setsigmask(), posix_spawnattr_setstackmax(), posix_spawnattr_setxflags(), posix_spawnp()