pthread_create_withcred_np Subroutine

Purpose

Creates a new thread with a new set of credentials, initializes its attributes, and makes it runnable.

Library

Threads Library (libpthreads.a)

Syntax

#include <pthread.h>
#include <sys/cred.h>

int pthread_create_withcred_np(pthread_t *thread, const pthread_attr_t *attr, 
void *(*start_routine)(void),
void *arg, struct __pthrdscreds *credp)

Description

The pthread_create_withcred_np subroutine is equivalent to the pthread_create routine except that it allows the new thread to be created and start running with the credentials specified by the credp parameter. Only a process that has the credentials capability or is running with an effective user ID as the root user is allowed to modify its credentials using this routine.

You can modify the following credentials:

Effective, real and saved user IDs
Effective, real and saved group IDs
Supplementary group IDs

Note: The administrator can set the lowest user ID value to which a process with credentials capability is allowed to switch its user IDs. A value of 0 can be specified for any of the preceding credentials to indicate that the thread should inherit that specific credential from its caller. The administrator can also set the lowest group ID to which a process with credentials capability is allowed to switch its group IDs.

The __pc_flags flag field in the credp parameter provides options to inherit credentials from the parent thread.

The newly created thread runs with per-thread credentials, and system calls such as getuid or getgid returns the thread's credentials. Similarly, when a file is opened or a message is received, the thread's credentials are used to determine whether the thread has the privilege to execute the operation.

Parameters

Item	Description
thread	Points to the location where the thread ID is stored.
attr	Specifies the thread attributes object to use while creating the thread. If the value is NULL, the default attributes values are used.
start_routine	Points to the routine to be executed by the thread.
arg	Points to the single argument to be passed to the start_routine routine.
credp	Points to a structure of type __pthrdscreds, that contains the credentials structure and the inheritance flags. If set to NULL, the pthread_create_withcred_np subroutine is the same as the pthread_create routine. The __pc_cred field indicates the credentials to be assigned to the new pthread.The __pc_flags field indicates which credentials, if any, are to be inherited from the parent thread. This field is constructed by logically OR'ing one or more of the following values: PTHRDSCREDS_INHERIT_UIDS Inherit user IDs from the parent thread. PTHRDSCREDS_INHERIT_GIDS Inherit group IDs from the parent thread. PTHRDSCREDS_INHERIT_GSETS Inherit the group sets from the parent thread. PTHRDSCREDS_INHERIT_CAPS Inherit capabilities from the parent thread. PTHRDSCREDS_INHERIT_PRIVS Inherit privileges from the parent thread. PTHRDSCREDS_INHERIT_ALL Inherit all the credentials from the parent thread.

Security

Only a process that has the credentials capability or is running with an effective user ID (such as the root user) is allowed to modify its credentials using this routine.

Return Values

If successful, the pthread_create_withcred_np subroutine returns 0. Otherwise, an error number is returned to indicate the error.

Error Codes

Item	Description
EAGAIN	If WLM is running, the limit on the number of threads in the class might have been met.
EFAULT	The credp parameter points to a location outside of the allocated address space of the process.
EINVAL	The credentials specified in the credp parameter are not valid.
EPERM	The caller does not have appropriate permission to set the credentials.

The pthread_create_withcred_np subroutine does not return an error code of EINTR.