pthread_attr(3T)

NAME

pthread_attr_set*(), pthread_attr_get*() — set and get thread attributes

SYNOPSIS

#include <pthread.h>

int pthread_attr_setdetachstate(pthread_attr_t *attr, int detachstate);

int pthread_attr_getdetachstate(const pthread_attr_t *attr, int *detachstate);

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_setguardsize(pthread_attr_t *attr, size_t guardsize);

int pthread_attr_getguardsize(const pthread_attr_t *attr, size_t *guardsize);

int pthread_attr_setinheritsched(pthread_attr_t *attr, int inheritsched);

int pthread_attr_getinheritsched(const pthread_attr_t *attr, int *inheritsched);

int pthread_attr_setschedpolicy(pthread_attr_t *attr, int policy);

int pthread_attr_getschedpolicy(const pthread_attr_t *attr, int *policy);

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_setscope(pthread_attr_t *attr, int contentionscope);

int pthread_attr_getscope(const pthread_attr_t *attr, int *contentionscope);

int pthread_attr_setprocessor_np(pthread_attr_t *attr, pthread_spu_t processor, int binding_type);

int pthread_attr_getprocessor_np(const pthread_attr_t *attr, pthread_spu_t *processor, int *binding_type);

PARAMETERS

attr: Pointer to the thread attributes object whose attributes are to be set/retrieved.
detachstate: This parameter either specifies the new value of the detachstate attribute (set function) or it points to the memory location where the detachstate attribute of attr is to be returned (get function).
stacksize: This parameter either specifies the new value of the stacksize attribute (set function) or it points to the memory location where the stacksize attribute of attr is to be returned (get function).
stackaddr: This parameter either specifies the new value of the stackaddr attribute (set function) or it points to the memory location where the stackaddr attribute of attr is to be returned (get function).
guardsize: This parameter either specifies the new value of the guardsize attribute (set function) or it points to the memory location where the guardsize attribute of attr is to be returned (get function).
inheritsched: This parameter either specifies the new value of the inheritsched attribute (set function) or it points to the memory location where the inheritsched attribute of attr is to be returned (get function).
policy: This parameter either specifies the new value of the schedpolicy attribute (set function) or it points to the memory location where the schedpolicy attribute of attr is to be returned (get function).
param: This parameter either specifies the new values of the schedparam attributes (set function) or it points to the memory location where the schedparam attributes of attr are to be returned (get function).
contentionscope: This parameter either specifies the new value of the contentionscope attribute (set function) or it points to the memory location where the contentionscope attribute of attr is to be returned (get function).
processor: This parameter either specifies the new value of the processor attribute (set function) or it points to the memory location where the processor attribute of attr is to be returned (get function).
binding_type: This parameter either specifies the new value of the binding_type attribute (set function) or it points to the memory location where the binding_type attribute of attr is to be returned (get function).

DESCRIPTION

These functions set and get the attributes as described below.

pthread_attr_setdetachstate() - set the detachstate attribute. pthread_attr_getdetachstate() - get the detachstate attribute.

pthread_attr_setstacksize() - set the stacksize attribute. pthread_attr_getstacksize() - get the stacksize attribute.

pthread_attr_setstackaddr() - set the stackaddr attribute. pthread_attr_getstackaddr() - get the stackaddr attribute.

pthread_attr_setguardsize() - set the guardsize attribute. pthread_attr_getguardsize() - get the guardsize attribute.

pthread_attr_setinheritsched() - set the inheritsched attribute. pthread_attr_getinheritsched() - get the inheritsched attribute.

pthread_attr_setschedpolicy() - set the schedpolicy attribute. pthread_attr_getschedpolicy() - get the schedpolicy attribute.

pthread_attr_setschedparam() - set the schedparam attributes. pthread_attr_getschedparam() - get the schedparam attributes.

pthread_attr_setscope() - set the contentionscope attribute. pthread_attr_getscope() - get the contentionscope attribute.

pthread_attr_setprocessor_np() - set the processor and binding_type attributes. pthread_attr_getprocessor_np() - get the processor and binding_type attributes.

The attributes object attr must have previously been initialized with the function pthread_attr_init() before these functions are called.

ATTRIBUTE: detachstate

The legal values for the detachstate attribute are:

PTHREAD_CREATE_DETACHED: This option causes all threads created with attr to be in the detached state. The resources associated with threads having this state are reclaimed automatically by the system when the threads terminate. Calling the pthread_detach() or pthread_join() function for threads created with this attribute results in an error.
PTHREAD_CREATE_JOINABLE: This option causes all threads created with attr to be in the joinable state. The resources associated with threads having this state are not reclaimed when the threads terminate. An application must call the pthread_detach() or pthread_join() functions for threads created with this attribute to reclaim the system resources.

The default value of detachstate is PTHREAD_CREATE_JOINABLE.

pthread_attr_setdetachstate() is used to set the detachstate attribute in the initialized attributes object attr. The new value of the detachstate attribute is passed to this function in the detachstate parameter.

pthread_attr_getdetachstate() retrieves the value of the detachstate attribute from the thread attributes object attr. This value is returned in the detachstate parameter.

ATTRIBUTE: stacksize

The legal values for the stacksize attribute are:

PTHREAD_STACK_MIN: This option specifies that the size of the user stack for threads created with this attributes object will be of default stack size. This value is the minimum stack size (in bytes) required for a thread. This minimum value may not be acceptable for all threads.
stacksize: This defines the size (in bytes) of the user stack for threads created with this attributes object. This value must be greater than or equal to the minimum stack size PTHREAD_STACK_MIN.

POSIX.1c does not define a default value. On HP-UX Release 10.30, the default value of the stacksize attribute is 64K.

pthread_attr_setstacksize() is used to set the stacksize attribute in the initialized attributes object attr. The new value of the stacksize attribute is passed to this function in the stacksize parameter.

pthread_attr_getstacksize() retrieves the value of the stacksize attribute from the thread attributes object attr. This value is returned in the stacksize parameter.

ATTRIBUTE: stackaddr

The legal values for the stackaddr attribute are:

NULL: This option specifies that the storage for the user stack of any threads created with this attributes object will be allocated and deallocated by the threads library. The application does not need to allocate and manage thread stacks.
stack_address: This option specifies the base address of a stack that the created thread will use. The application is completely responsible for allocating, managing, and deallocating these stacks. Some options for allocation of storage are the malloc(3C), brk(2), and mmap(2) functions. Note: if this option is used, only one thread should be created with this attributes object. If multiple threads are created, they will all use the same stack.

The default value of the stackaddr attribute is NULL.

pthread_attr_setstackaddr() is used to set the stackaddr attribute in the initialized attributes object attr. The new value of the stackaddr attribute is passed to this function in the stackaddr parameter.

pthread_attr_getstackaddr() retrieves the value of the stackaddr attribute from the thread attributes object attr. This value is returned in the stackaddr parameter.

The guardsize attribute is ignored if the storage for the thread's user stack is not allocated by the library (i.e., the stackaddr attribute is not NULL).

ATTRIBUTE: guardsize

The guardsize attribute allows an application to specify the size of the guard area for threads created with this attributes object. The size of the guard area is specified in bytes. Most systems will round up the guard size to a multiple of the system configurable variable PAGESIZE. If the value zero is specified, a guard area will not be created.

The default value of guardsize is PAGESIZE bytes. The actual value of PAGESIZE is implementation-dependent and may not be the same on all implementations. The guardsize attribute is ignored if the storage for the user stack is not allocated by the pthread library. The application is responsible for protecting against stack overflow.

pthread_attr_setguardsize() is used to set the guardsize attribute in the initialized attributes object attr. The new value of the guardsize attribute is passed to this function in the guardsize parameter.

pthread_attr_getguardsize() retrieves the value of the guardsize attribute from the thread attributes object attr. This value is returned in the guardsize parameter. If the guard area is rounded up to a multiple of PAGESIZE, a call to this function shall store in the guardsize parameter the guard size specified in the previous pthread_attr_setguardsize() function call.

ATTRIBUTE: inheritsched

The legal values for the inheritsched attribute are:

PTHREAD_INHERIT_SCHED: This option specifies that the scheduling policy and associated attributes are to be inherited from the creating thread. The scheduling policy and associated attributes in the attr argument will be ignored when a thread is created with attr.
PTHREAD_EXPLICIT_SCHED: This option specifies that the scheduling policy and associated attributes for the created thread(s) are to be taken from this attributes object. These values will not be inherited from the creating thread.

POSIX.1c does not define a default value for the inheritsched attribute. On HP-UX, the default value is PTHREAD_INHERIT_SCHED.

pthread_attr_setinheritsched() is used to set the inheritsched attribute in the initialized attributes object attr. The new value of the inheritsched attribute is passed in the inheritsched parameter.

pthread_attr_getinheritsched() retrieves the value of the inheritsched attribute from the thread attributes object attr. This value is returned in the inheritsched parameter.

ATTRIBUTE: schedpolicy

The schedpolicy attribute allows threads created with this attributes object to use a specific scheduling policy. To use this attribute, the inheritsched attribute must be set to PTHREAD_EXPLICIT_SCHED. For a complete list of valid scheduling policies, refer to rtsched(2) and <sched.h>.

POSIX.1c does not specify a default value for the schedpolicy attribute. On HP-UX, the default value for system scope threads is SCHED_TIMESHARE.

pthread_attr_setschedpolicy() is used to set the schedpolicy attribute in the initialized attributes object attr. The new value of the schedpolicy attribute is passed to this function in the policy parameter.

pthread_attr_getschedpolicy() retrieves the value of the schedpolicy attribute from the thread attributes object attr. This value is returned in the policy parameter.

ATTRIBUTE: schedparam

The legal values for the schedparam attribute associated with the schedpolicy attribute vary depending upon the scheduling policy. For the SCHED_FIFO and SCHED_RR scheduling policies, only the sched_priority member of the schedparam attribute is required. Legal values for sched_priority can be obtained through sched_get_priority_max() and sched_get_priority_min(). The required contents of schedparam for other scheduling policies is undefined. For a complete list of required and valid scheduling parameters for all scheduling policies, refer to rtsched(2) and <sched.h>.

pthread_attr_setschedparam() is used to set the schedparam attribute in the initialized attributes object attr. The new value of the schedparam attribute is passed to this function in the param parameter.

pthread_attr_getschedparam() retrieves the value of the schedparam attribute from the thread attributes object attr. This value is returned in the param parameter.

ATTRIBUTE: contentionscope

The legal values for the contentionscope attribute are:

PTHREAD_SCOPE_SYSTEM

Threads created with this contention scope contend for resources with all other threads in the system (and within the same scheduling domain). This attribute is generally used to indicate that the user thread should be bound directly to a kernel-scheduled entity.

PTHREAD_SCOPE_PROCESS

Threads created with this contention scope contend directly with other threads within their process that were created with this scheduling contention scope. This attribute is generally used to indicate that the user thread should be unbound (in the Mx1 and MxN Threads Model).

This value is currently not supported on HP-UX release 10.30.

The default value of the contentionscope attribute is not defined by POSIX.1c. On HP-UX release 10.30, the current default value of the contentionscope attribute is PTHREAD_SCOPE_SYSTEM. Note: This default value will change to PTHREAD_SCOPE_PROCESS when HP-UX supports the MxN Threads Model.

pthread_attr_setscope() is used to set the contentionscope attribute in the initialized attributes object attr. The new value of the contentionscope attribute is passed to this function in the contentionscope parameter.

pthread_attr_getscope() retrieves the value of the contentionscope attribute from the thread attributes object attr. This value is returned in the contentionscope parameter.

ATTRIBUTES: processor And binding_type

The legal values for the processor attribute are:

PTHREAD_SPUINHERIT_NP: Threads created with this processor attribute inherit their processor binding attributes from the creating thread. This is the default value of the processor attribute. The binding_type attribute is ignored.
PTHREAD_SPUFLOAT_NP: Threads created with this processor attribute are allowed to execute on any processor the system chooses. No processor binding is maintained. The binding_type attribute is ignored.
(pthread_spu_t)processor_id: Threads created with this processor attribute are bound to the processor specified in the processor parameter. The type of binding (advisory or mandatory) is specified in the binding_type attribute.

The legal values for the binding_type attribute (if the processor attribute is not PTHREAD_SPUINHERIT_NP or PTHREAD_SPUFLOAT_NP) are:

PTHREAD_BIND_ADVISORY_NP: Threads created with this binding_type attribute have advisory processor binding. Refer to pthread_processor_bind_np(3T) for more information on advisory binding. This is the default value of the binding_type attribute.
PTHREAD_BIND_FORCED_NP: Threads created with this binding_type attribute have forced (or mandatory) processor binding. Refer to pthread_processor_bind_np(3T) for more information on forced binding.

The default value of the processor attribute is PTHREAD_SPUINHERIT_NP. The default value of the binding_type attribute is PTHREAD_BIND_ADVISORY_NP.

pthread_attr_setprocessor_np() is used to set the processor and binding_type attributes in the initialized attributes object attr. The new values of the processor and binding_type attributes are passed to this function in the processor and binding_type parameters, respectively.

pthread_attr_getprocessor_np() retrieves the values of the processor and binding_type attributes from the thread attributes object attr. These values are returned in the processor and binding_type parameters, respectively.

RETURN VALUE

Upon successful completion, the following functions return zero: pthread_attr_setstacksize(), pthread_attr_getstacksize(), pthread_attr_setstackaddr(), pthread_attr_getstackaddr(), pthread_attr_setguardsize(), pthread_attr_getguardsize(), pthread_attr_setdetachstate(), pthread_attr_getdetachstate(), pthread_attr_setinheritsched(), pthread_attr_getinheritsched(), pthread_attr_setschedpolicy(), pthread_attr_getschedpolicy(), pthread_attr_setschedparam(), pthread_attr_getschedparam(), pthread_attr_setprocessor_np(), pthread_attr_getprocessor_np(), pthread_attr_setscope(), and pthread_attr_getscope(). Otherwise, an error number is returned to indicate the error (the errno variable is not set).

ERRORS

If any of the following occur, the pthread_attr_setscope(), pthread_attr_getscope(), pthread_attr_setinheritsched(), pthread_attr_getinheritsched(), pthread_attr_setschedpolicy(), and pthread_attr_getschedpolicy() functions return the corresponding error number:

[ENOSYS]: _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and these functions are not supported.

If any of the following occur, the pthread_attr_getstackaddr() and pthread_attr_setstackaddr() functions return the corresponding error number:

[ENOSYS]: _POSIX_THREAD_ATTR_STACKADDR is not defined and these functions are not supported.

If any of the following occur, the pthread_attr_getstacksize() and pthread_attr_setstacksize() functions return the corresponding error number:

[ENOSYS]: _POSIX_THREAD_ATTR_STACKSIZE is not defined and these functions are not supported.

If any of the following occur, pthread_attr_setstacksize(), pthread_attr_getstacksize(), pthread_attr_setstackaddr(), pthread_attr_getstackaddr(), pthread_attr_setguardsize(), pthread_attr_getguardsize(), pthread_attr_setdetachstate(), pthread_attr_getdetachstate(), pthread_attr_setinheritsched(), pthread_attr_getinheritsched(), pthread_attr_setschedpolicy(), pthread_attr_getschedpolicy(), pthread_attr_setschedparam(), pthread_attr_getschedparam(), pthread_attr_setprocessor_np(), pthread_attr_getprocessor_np(), pthread_attr_setscope(), and pthread_attr_getscope() return the corresponding error number:

[EINVAL]: The value specified by attr is invalid.
[EINVAL]: The value specified by stacksize is less than the minimum required stacksize of PTHREAD_STACK_MIN or exceeds a system-imposed limit.
[EINVAL]: detachstate, guardsize, inheritsched, processor, binding_type, policy, param, or scope contains an invalid value.
[ENOTSUP]: The value contained in policy is not a supported value.

AUTHOR

pthread_attr_setstacksize(), pthread_attr_getstacksize(), pthread_attr_setstackaddr(), pthread_attr_getstackaddr(), pthread_attr_setdetachstate(), pthread_attr_getdetachstate(), pthread_attr_setinheritsched(), pthread_attr_getinheritsched(), pthread_attr_setschedpolicy(), pthread_attr_getschedpolicy(), pthread_attr_setschedparam(), pthread_attr_getschedparam(), pthread_attr_setscope(), and pthread_attr_getscope() were derived from the IEEE POSIX P1003.1c standard.

pthread_attr_setguardsize() and pthread_attr_getguardsize() were developed by X/Open.

pthread_attr_setprocessor_np() and pthread_attr_getprocessor_np() were developed by HP.

STANDARDS CONFORMANCE

pthread_attr_setstacksize(): POSIX 1003.1c.
pthread_attr_getstacksize(): POSIX 1003.1c.
pthread_attr_setstacksize(): POSIX 1003.1c.
pthread_attr_getstacksize(): POSIX 1003.1c.
pthread_attr_setstackaddr(): POSIX 1003.1c.
pthread_attr_getstackaddr(): POSIX 1003.1c.
pthread_attr_setguardsize(): X/Open.
pthread_attr_getguardsize(): X/Open.
pthread_attr_setdetachstate(): POSIX 1003.1c.
pthread_attr_getdetachstate(): POSIX 1003.1c.
pthread_attr_setinheritsched(): POSIX 1003.1c.
pthread_attr_getinheritsched(): POSIX 1003.1c.
pthread_attr_setschedpolicy(): POSIX 1003.1c.
pthread_attr_getschedpolicy(): POSIX 1003.1c.
pthread_attr_setschedparam(): POSIX 1003.1c.
pthread_attr_getschedparam(): POSIX 1003.1c.
pthread_attr_setscope(): POSIX 1003.1c.
pthread_attr_getscope(): POSIX 1003.1c.
pthread_attr_setprocessor_np(): None.
pthread_attr_getprocessor_np(): None.