pthread_attr_getdetachstate(3T)

NAME

pthread_attr_getdetachstate(), pthread_attr_getguardsize(), pthread_attr_getinheritsched(), pthread_attr_getprocessor_np(), pthread_attr_getschedparam(), pthread_attr_getschedpolicy(), pthread_attr_getscope(), pthread_attr_getstackaddr(), pthread_attr_getstacksize(), pthread_attr_getstack(), pthread_attr_getrsestacksize_np(), pthread_attr_setdetachstate(), pthread_attr_setguardsize(), pthread_attr_setinheritsched(), pthread_attr_setprocessor_np(), pthread_attr_setschedparam(), pthread_attr_setschedpolicy(), pthread_attr_setscope(), pthread_attr_setstackaddr(), pthread_attr_setstacksize(), pthread_attr_setstack(), pthread_attr_setrsestacksize_np() — get and set 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 *__restrict attr, size_t *__restrict stacksize);

int pthread_attr_setrsestacksize_np(pthread_attr_t *attr, size_t rsestacksize);

int pthread_attr_getrsestacksize_np(const pthread_attr_t *__restrict attr, size_t *rsestacksize);

int pthread_attr_setstackaddr(pthread_attr_t *attr, void *stackaddr);

int pthread_attr_getstackaddr(const pthread_attr_t *__restrict attr, void **__restrict stackaddr);

int pthread_attr_setstack(pthread_attr_t *attr, void *stackaddr, size_t stacksize);

int pthread_attr_getstack(const pthread_attr_t *__restrict attr, void **__restrict stackaddr, size_t *__restrict stacksize);

int pthread_attr_setguardsize(pthread_attr_t *attr, size_t guardsize);

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

int pthread_attr_setinheritsched(pthread_attr_t *attr, int inheritsched);

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

int pthread_attr_setschedpolicy(pthread_attr_t *attr, int policy);

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

int pthread_attr_setschedparam(pthread_attr_t *__restrict attr, const struct sched_param *__restrict param);

int pthread_attr_getschedparam(const pthread_attr_t *__restrict attr, struct sched_param *__restrict param);

int pthread_attr_setscope(pthread_attr_t *attr, int contentionscope);

int pthread_attr_getscope(const pthread_attr_t *__restrict attr, int *__restrict 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).
rsestacksize: This parameter either specifies the new value of the rsestacksize attribute (set function) or it points to the memory location where the rsestacksize 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_setrsestacksize_np() - set the rsestacksize attribute. pthread_attr_getrsestacksize_np() - get the rsestacksize attribute.

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

pthread_attr_setstack() - set the stacksize, stackaddr attributes. pthread_attr_getstack() - get the stacksize, stackaddr attributes.

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 released on PA-RISC platforms, the default value of the stacksize attribute is 64K, and 256K in HP-UX released on Itanium(R)-based platforms. On Itanium-based systems, stack is equally divided into memory stack and register stack.

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. While modifying the stacksize attribute on Itanium-based platform, user must keep account of memory stack as well as register stack requirement.

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

pthread_attr_setstack() is used to set the stacksize and stackaddr attributes in the initialized attributes object attr. The new value of the stacksize attribute is passed to this function in stacksize parameter. The new value of the stackaddr attribute is passed to this function in stackaddr parameter. Refer to ATTRIBUTE stackaddr for information on stackaddr attribute.

pthread_attr_getstack() retrieves the value of stacksize and stackaddr attributes from the thread attributes object attr. These values are returned in the stacksize parameter and stackaddr parameter. Refer to ATTRIBUTE stackaddr for information on stackaddr attribute.

ATTRIBUTE: rsestacksize

The legal values for the rsestacksize are:

rsestacksize: This defines the size (in bytes) of the register stack for the threads created with the attributes object.

pthread_attr_setrsestacksize_np() is used to set the register stack size for a thread and pthread_default_rsestacksize_np() to set the default register stack size. If either of the set register stack size APIs is called, the register stack portion of the stack space will be that large instead of implementation defined division. The memory stack portion will be the remainder.

pthread_attr_getrsestacksize_np() retrieves the value of the rsestacksize attribute from the thread attributes object attr. This value is returned in the rsestacksize 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. If the size of stack pointed to by stackaddr is different from the default stack size, the application must call pthread_attr_setstacksize() to set the new stack size.

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 (not bound to any particular kernel-scheduled entity).

The default value of the contentionscope attribute is not defined by POSIX.1c. The default value of the contentionscope attribute is set to be PTHREAD_SCOPE_SYSTEM. This default scope can also be controlled externally by using the options documented in the pthread_scope_options(5) manpage.

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. Specifying PTHREAD_LDOMINHERIT_NP or PTHREAD_SPUINHERIT_NP cause both processor binding and locality domain binding attributes to be inherited. 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. Specifying PTHREAD_LDOMFLOAT_NP or PTHREAD_SPUFLOAT_NP cause both processor binding and locality domain binding attributes to be cleared. The thread will be allowed to execute on any processor in the system. 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.
PTHREAD_LDOMINHERIT_NP: Threads created with this processor attribute inherit their processor binding and locality domain binding attributes from the creating thread. Specifying PTHREAD_LDOMINHERIT_NP or PTHREAD_SPUINHERIT_NP cause both processor binding and locality domain binding attributes to be inherited. The binding_type attribute is ignored. Due to differences in data types in function definitions, this value should be cast to the type (pthread_spu_t).
PTHREAD_LDOMFLOAT_NP: Threads created with this processor attribute are allowed to execute on any processor the system chooses. No locality domain binding is maintained. Specifying PTHREAD_LDOMFLOAT_NP or PTHREAD_SPUFLOAT_NP cause both processor binding and locality domain binding attributes to be cleared. The thread will be allowed to execute on any processor in the system. The binding_type attribute is ignored. Due to differences in data types in function definitions, this value should be cast to the type (pthread_spu_t).
(pthread_ldom_t)locality_domain_id: Threads created with this processor attribute are bound to the locality domain specified in the processor parameter. The thread will be allowed to execute on any processor within the specified locality domain. Due to differences in data types in function definitions, this value should be cast to the type (pthread_spu_t).

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

PTHREAD_BIND_ADVISORY_NP: Threads created with this binding_type attribute have advisory processor binding to the processor specified in the processor attribute. Refer to pthread_processor_bind_np(3T) for more information on advisory binding.
PTHREAD_BIND_FORCED_NP: Threads created with this binding_type attribute have forced (or mandatory) processor binding to the processor specified in the processor attribute. Refer to pthread_processor_bind_np(3T) for more information on forced binding.
PTHREAD_BIND_LDOM_NP: Threads created with this binding_type are bound to the locality domain specified in the processor attribute. Refer to pthread_ldom_bind_np(3T) for more information on locality domain binding.
PTHREAD_BIND_NONE_NP: Threads created with this binding_type are not bound to any processor or locality domain. The processor attribute is ignored. This is the default value of the binding_type attribute.

The default value of the processor attribute is PTHREAD_SPUINHERIT_NP. The default value of the binding_type attribute is PTHREAD_BIND_NONE_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.

If the value of the processor attribute is PTHREAD_SPUINHERIT_NP, PTHREAD_SPUFLOAT_NP, PTHREAD_LDOMINHERIT_NP, or PTHREAD_LDOMFLOAT_NP the value of the binding_type attribute should be ignored (float implies there will be no binding for the created thread, inherit implies that the attribute will be set when the new thread is created based on the creating thread's attributes).

If the value of the binding_type attribute is PTHREAD_BIND_NONE_NP the processor attribute should be ignored.

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_getstack(), pthread_attr_setstack(), 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_setstack(), pthread_attr_getstack(), pthread_attr_setrsestackszie_np(), pthread_attr_getrsestackszie_np(), 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.
[ENOSYS]: pthread_attr_setrsestacksize_np() and pthread_attr_getrsestacksize_np() are not supported on PA-RISC systems.

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_setstack(): POSIX 1003.1c.
pthread_attr_getstack(): 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.
pthread_attr_getrsestacksize_np(): None.
pthread_attr_setrsestacksize_np(): None.