NAME

pthread_attr_init, pthread_attr_destroy, pthread_attr_setstacksize, pthread_attr_getstacksize, pthread_attr_setstackaddr, pthread_attr_getstackaddr, pthread_attr_setschedparam, pthread_attr_getschedparam, pthread_attr_setdetachstate, pthread_attr_getdetachstate,
– thread creation attributes

SYNOPSIS

#include <pthread.h>

int pthread_attr_init(pthread_attr_t *attr );

int pthread_attr_destroy(pthread_attr_t *attr );

int pthread_attr_setstacksize(pthread_attr_t *attr,

          size_t stacksize );

int pthread_attr_getstacksize(const pthread_attr_t *attr,

         size_t *stacksize );

int pthread_attr_setstackaddr(pthread_attr_t *attr,

         void *stackaddr );

int pthread_attr_getstackaddr(const pthread_attr_t *attr,

         void **stackaddr );

int pthread_attr_setschedparam(pthread_attr_t *attr,

         const struct sched_param *param );

int pthread_attr_getschedparam(const pthread_attr_t *attr,

         struct sched_param *param );

int pthread_attr_getdetachstate(const pthread_attr_t *attr,

         int *detachstate );

int pthread_attr_setdetachstate(const pthread_attr_t *attr,

         int detachstate );

All pthread_attr_get* and pthread_attr_set* functions are callable from an ISR.

DESCRIPTION

The pthread approach to setting attributes for threads is to request the initialization of an attribute object, attr , and pass the initialized attribute object to pthread_create().

All attributes in attr are independent of one another and may be singularly modified or retrieved. attr , itself, is independent of any thread and can be modified or used to create new threads. However, any change to attr after a thread is created will not affect that thread.

init

The pthread_attr_init() function initializes a thread attributes object ( attr ) with the default value for each attribute as follows:

NOTE: Attribute objects should be destroyed before an initialized attribute object is re-initialized.

destroy

pthread_attr_destroy() destroys a thread attributes object ( attr ), which cannot be reused until it is reinitialized.

stacksize and stackaddr

The pthread_attr_setstacksize() and pthread_attr_getstacksize() functions set and get the stacksize thread attribute in the attr object. The stacksize default argument is NULL, and a processor specific thread default stack size is used.

The pthread_attr_setstackaddr() and pthread_attr_getstackaddr() functions set and get the stackaddr thread attribute in the attr object. The stackaddr default is NULL (See pthread_create() ).

schedparam (priority)

The pthread_attr_setschedparam() and pthread_attr_getschedparam() functions set and get the scheduling parameter thread attributes in the attr argument, determined by the scheduling policy set in the attr object. The only required member of the param structure for the SCHED_OTHER , SCHED_FIFO , and SCHED_RR policies is sched_priority (see NOTES section below). You can use these functions to get and set the priority of the thread to be created. The sched_priority of the param structure is NULL, by default, which means the newly created thread inherits the priority of its parent thread.

detach state

The pthread_attr_setdetachstate() and pthread_attr_getdetachstate() are used to find detach state information about current memory that is attached to the thread. The detachstate attribute controls whether the thread is created in a detached state. If the thread is created detached, then use of the ID of the newly created thread by the pthread_detach() or pthread_join() function is an error.

The pthread_attr_getdetachstate() and pthread_attr_setdetachstate() functions, respectively, shall get and set the detachstate attribute in the attr object.

For pthread_attr_getdetachstate(), detachstate shall be set to either PTHREAD_CREATE_DETACHED or PTHREAD_CREATE_JOINABLE.

For pthread_attr_setdetachstate(), the application shall set detachstate to either PTHREAD_CREATE_DETACHED or PTHREAD_CREATE_JOINABLE.

A value of PTHREAD_CREATE_DETACHED shall cause all threads created with attr to be in the detached state, whereas using a value of PTHREAD_CREATE_JOINABLE shall cause all threads created with attr to be in the joinable state. The default value of the detachstate attribute shall be PTHREAD_CREATE_JOINABLE.

RETURN VALUES

Upon successful completion, the following functions return 0; otherwise, an error number is returned to indicate the error.

ERRORS

If any of the following conditions occur, pthread_attr_init() returns the corresponding error number:

ENOMEM

Insufficient memory exists to create the thread attributes object.

If any of the following conditions occur, pthread_attr_setstacksize() returns the corresponding error number:

EINVAL

The value of stacksize is less than PTHREAD_STACK_MIN or exceeds a system-imposed limit.

If any of the following conditions occur, pthread_attr_destroy() , pthread_attr_setstacksize() , pthread_attr_getstacksize() , pthread_attr_setstackaddr() , pthread_attr_getstackaddr() , pthread_attr_setschedparam() , and pthread_attr_getschedparam() return the corresponding error number:

EINVAL

The value of attr is not valid.

If any of the following conditions occur, pthread_attr_setstacksize() returns the corresponding error number:

EINVAL

The value of stacksize is less than PTHREAD_STACK_MIN.

If any of the following conditions occur, pthread_attr_setschedparam() returns the corresponding error number:

EINVAL

The value of the sched_priority member of the param structure is less than or equal to 0 or greater than PTHREAD_PRIO_MAX.

If any of the following conditions occur, pthread_attr_getstacksize() returns the corresponding error number:

EINVAL

The value of stacksize is NULL.

If any of the following conditions occur, pthread_attr_getstackaddr() returns the corresponding error number:

EINVAL

The value of stackaddr is NULL.

If any of the following conditions occur, either pthread_attr_setschedparam() and pthread_attr_getschedparam() returns the corresponding error number:

EINVAL

The value of param is NULL.

If any of the following conditions occur, either pthread_attr_setdetachstate() and pthread_attr_getdetachstate() returns the corresponding error number:

EINVAL

The value of detachstate is not valid.

SEE ALSO

pthread_create()