pthread_attr_getdetachstate(3T) 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_getstack-
size(), 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_setrsestack-
size_np() - get and set thread attributes
SYNOPSIS
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.
- set the detachstate attribute.
- get the detachstate attribute.
- set the stacksize attribute.
- get the stacksize attribute.
- set the rsestacksize attribute.
- get the rsestacksize attribute.
- set the stackaddr attribute.
- get the stackaddr attribute.
- set the stacksize, stackaddr attributes.
- get the stacksize, stackaddr attributes.
- set the guardsize attribute.
- get the guardsize attribute.
- set the inheritsched attribute.
- get the inheritsched attribute.
- set the schedpolicy attribute.
- get the schedpolicy attribute.
- set the schedparam attributes.
- get the schedparam attributes.
- set the contentionscope attribute.
- get the contentionscope attribute.
- set the processor and binding_type attributes.
- get the processor and binding_type attributes.
The attributes object attr must have previously been initialized with the function before these functions are called.
ATTRIBUTE: detachstate
The legal values for the detachstate attribute are:
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 or function for threads created with this attribute results in an error.
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 or functions for threads created with this attribute to reclaim the system
resources.
The default value of detachstate is
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.
retrieves the value of the detachstate attribute from the thread attributes object attr. This value is returned in the detachstate parame-
ter.
ATTRIBUTE: stacksize
The legal values for the stacksize attribute are:
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
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.
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.
retrieves the value of the stacksize attribute from the thread attributes object attr. This value is returned in the stacksize parameter.
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 param-
eter. Refer to for information on stackaddr attribute.
retrieves the value of stacksize and stackaddr attributes from the thread attributes object attr. These values are returned in the stack-
size parameter and stackaddr parameter. Refer to for information on stackaddr attribute.
ATTRIBUTE: rsestacksize
The legal values for the rsestacksize are:
This defines the size (in bytes) of the register stack for the threads
created with the attributes object.
is used to set the register stack size for a thread and 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.
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 allo-
cated 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 responsi-
ble 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.
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 to set the new stack size.
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
If the value zero is specified, a guard area will not be created.
The default value of guardsize is bytes. The actual value of 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 responsi-
ble for protecting against stack overflow.
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.
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 a call to this function shall store in the guardsize parameter the guard size specified in
the previous function call.
ATTRIBUTE: inheritsched
The legal values for the inheritsched attribute are:
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.
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
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.
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 For a complete list of valid scheduling policies, refer to rtsched(2) and
POSIX.1c does not specify a default value for the schedpolicy attribute. On HP-UX, the default value for system scope threads is
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.
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
and scheduling policies, only the sched_priority member of the schedparam attribute is required. Legal values for sched_priority can be
obtained through and 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
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.
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:
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.
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 This default scope can also be controlled externally by using the options documented in the pthread_scope_options(5) manpage.
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.
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:
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 or cause both processor binding and locality domain binding attributes to be inherited. The
binding_type attribute is ignored.
Threads created with this
processor attribute are allowed to execute on any processor the system chooses. No processor binding is maintained. Speci-
fying or 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.
Threads created with this
processor attribute are bound to the processor specified in the processor parameter. The type of binding (advisory or manda-
tory) is specified in the binding_type attribute.
Threads created with this
processor attribute inherit their processor binding and locality domain binding attributes from the creating thread. Speci-
fying or 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
Threads created with this
processor attribute are allowed to execute on any processor the system chooses. No locality domain binding is maintained.
Specifying or 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 func-
tion definitions, this value should be cast to the type
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
The legal values for the binding_type attribute (if the processor attribute is not or are:
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.
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.
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.
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 The default value of the binding_type attribute is
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.
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 or 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 the processor attribute should be ignored.
RETURN VALUE
Upon successful completion, the following functions return zero: and Otherwise, an error number is returned to indicate the error (the
variable is not set).
ERRORS
If any of the following occur, the and functions return the corresponding error number:
is not defined and these functions are not supported.
If any of the following occur, the and functions return the corresponding error number:
is not defined and these functions are not supported.
If any of the following occur, the and functions return the corresponding error number:
is not defined and these functions are not supported.
If any of the following occur, and return the corresponding error number:
The value specified by
attr is invalid.
The value specified by
stacksize is less than the minimum required stacksize of or exceeds a system-imposed limit.
detachstate, guardsize, inheritsched, processor, binding_type, policy, param, or scope contains an invalid value.
The value contained in
policy is not a supported value.
[ENOSYS] and are not supported on PA-RISC systems.
AUTHOR
and were derived from the IEEE POSIX P1003.1c standard.
and were developed by X/Open.
and were developed by HP.
SEE ALSO
pthread_create(3T), pthread_attr_init(3T), pthread_processor_bind_np(3T), pthread_default_stacksize_np(3T), pthread_scope_options(5).
STANDARDS CONFORMANCE
Pthread Library pthread_attr_getdetachstate(3T)