Thread creation attributes.
[Threads management services.]

---

Detailed Description

Thread creation attributes.

The services described in this section allow to set the attributes of a pthread_attr_t object, passed to the pthread_create() service in order to set the attributes of a created thread.

A pthread_attr_t object has to be initialized with pthread_attr_init() first, which sets attributes to their default values, i.e. in kernel-space:

• detachstate to PTHREAD_CREATE_JOINABLE,
• stacksize to PTHREAD_STACK_MIN,
• inheritsched to PTHREAD_EXPLICIT_SCHED,
• schedpolicy to SCHED_OTHER,
• name to NULL (only available in kernel-space),
• scheduling priority to the minimum,
• floating-point hardware enabled (only available in kernel-space),
• processor affinity set to all available processors (only available as a thread attribute in kernel-space).

In user-space, the attributes and their defaults values are those documented by the underlying threading library (LinuxThreads or NPTL).

Functions
int	pthread_attr_init (pthread_attr_t *attr)
	Initialize a thread attributes object.
int	pthread_attr_destroy (pthread_attr_t *attr)
	Destroy a thread attributes object.
int	pthread_attr_getdetachstate (const pthread_attr_t *attr, int *detachstate)
	Get detachstate attribute.
int	pthread_attr_setdetachstate (pthread_attr_t *attr, int detachstate)
	Set detachstate attribute.
int	pthread_attr_getstacksize (const pthread_attr_t *attr, size_t *stacksize)
	Get stacksize attribute.
int	pthread_attr_setstacksize (pthread_attr_t *attr, size_t stacksize)
	Set stacksize attribute.
int	pthread_attr_getinheritsched (const pthread_attr_t *attr, int *inheritsched)
	Get inheritsched attribute.
int	pthread_attr_setinheritsched (pthread_attr_t *attr, int inheritsched)
	Set inheritsched attribute.
int	pthread_attr_getschedpolicy (const pthread_attr_t *attr, int *policy)
	Get schedpolicy attribute.
int	pthread_attr_setschedpolicy (pthread_attr_t *attr, int policy)
	Set schedpolicy attribute.
int	pthread_attr_getschedparam (const pthread_attr_t *attr, struct sched_param *par)
	Get schedparam attribute.
int	pthread_attr_setschedparam (pthread_attr_t *attr, const struct sched_param *par)
	Set schedparam attribute.
int	pthread_attr_getscope (const pthread_attr_t *attr, int *scope)
	Get contention scope attribute.
int	pthread_attr_setscope (pthread_attr_t *attr, int scope)
	Set contention scope attribute.
int	pthread_attr_getname_np (const pthread_attr_t *attr, const char **name)
	Get name attribute.
int	pthread_attr_setname_np (pthread_attr_t *attr, const char *name)
	Set name attribute.
int	pthread_attr_getfp_np (const pthread_attr_t *attr, int *fp)
	Get the floating point attribute.
int	pthread_attr_setfp_np (pthread_attr_t *attr, int fp)
	Set the floating point attribute.
int	pthread_attr_getaffinity_np (const pthread_attr_t *attr, xnarch_cpumask_t *mask)
	Get the processor affinity attribute.
int	pthread_attr_setaffinity_np (pthread_attr_t *attr, xnarch_cpumask_t mask)
	Set the processor affinity attribute.

---

Function Documentation

int pthread_attr_destroy (  pthread_attr_t *  attr  )

Destroy a thread attributes object. This service invalidates the attribute object pointed to by attr. The object becomes invalid for all services (they all return EINVAL) except pthread_attr_init(). See also: Specification.

int pthread_attr_getaffinity_np (  const pthread_attr_t *  attr, xnarch_cpumask_t *  mask )

Get the processor affinity attribute. This service stores, at the address mask, the value of the affinity attribute in the attribute object attr. The affinity attributes is a bitmask where bits set indicate processor where a thread created with the attribute attr may run. The least significant bit corresponds to the first logical processor. This service is a non-portable extension of the POSIX interface. Parameters: attr  attribute object; mask  address where the value of the affinity attribute will be stored on success. Returns: 0 on success; an error number if: EINVAL, attr is invalid. Valid contexts: kernel module initialization or cleanup routine; Xenomai kernel-space thread.

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

Get detachstate attribute. This service returns, at the address detachstate, the value of the detachstate attribute in the thread attribute object attr. Valid values of this attribute are PTHREAD_CREATE_JOINABLE and PTHREAD_CREATE_DETACHED. A detached thread is a thread which control block is automatically reclaimed when it terminates. The control block of a joinable thread, on the other hand, is only reclaimed when joined with the service pthread_join(). A thread that was created joinable may be detached after creation by using the pthread_detach() service. Parameters: attr  attribute object detachstate  address where the value of the detachstate attribute will be stored on success. Returns: 0 on success; an error number if: EINVAL, attr is invalid; See also: Specification.

int pthread_attr_getfp_np (  const pthread_attr_t *  attr, int *  fp )

Get the floating point attribute. This service returns, at the address fp, the value of the fp attribute in the attribute object attr. The fp attribute is a boolean attribute indicating whether a thread created with the attribute attr may use floating-point hardware. This service is a non-portable extension of the POSIX interface. Parameters: attr  attribute object; fp  address where the value of the fp attribute will be stored on success. Returns: 0 on success; an error number if: EINVAL, attr is invalid. Valid contexts: kernel module initialization or cleanup routine; Xenomai kernel-space thread.

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

Get inheritsched attribute. This service returns at the address inheritsched the value of the inheritsched attribute in the attribute object attr. Threads created with this attribute set to PTHREAD_INHERIT_SCHED will use the same scheduling policy and priority as the thread calling pthread_create(). Threads created with this attribute set to PTHREAD_EXPLICIT_SCHED will use the value of the schedpolicy attribute as scheduling policy, and the value of the schedparam attribute as scheduling priority. Parameters: attr  attribute object; inheritsched  address where the value of the inheritsched attribute will be stored on success. Returns: 0 on success; an error number if: EINVAL, attr is invalid. See also: Specification.

int pthread_attr_getname_np (  const pthread_attr_t *  attr, const char **  name )

Get name attribute. This service stores, at the address name, the value of the name attribute in the attribute object attr. The name attribute is the name under which a thread created with the attribute object attr will appear under /proc/xenomai/sched. The name returned by this function is only valid until the name is changed with pthread_attr_setname_np() or the attr object is destroyed with pthread_attr_destroy(). If name is NULL, a unique default name will be used. This service is a non-portable extension of the POSIX interface. Parameters: attr  attribute object; name  address where the value of the name attribute will be stored on success. Returns: 0 on success; an error number if: EINVAL, attr is invalid. Valid contexts: kernel module initialization or cleanup routine; Xenomai kernel-space thread.

int pthread_attr_getschedparam (  const pthread_attr_t *  attr, struct sched_param *  par )

Get schedparam attribute. This service stores, at the address par, the value of the schedparam attribute in the attribute object attr. The only member of the sched_param structure used by this implementation is sched_priority. Threads created with attr will use the value of this attribute as a scheduling priority if the attribute inheritsched is set to PTHREAD_EXPLICIT_SCHED. Valid priorities range from 1 to 99. Parameters: attr  attribute object; par  address where the value of the schedparam attribute will be stored on success. Returns: 0 on success; an error number if: EINVAL, attr is invalid. See also: Specification.

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

Get schedpolicy attribute. This service stores, at the address policy, the value of the policy attribute in the attribute object attr. Threads created with the attribute object attr use the value of this attribute as scheduling policy if the inheritsched attribute is set to PTHREAD_EXPLICIT_SCHED. The value of this attribute is one of SCHED_FIFO, SCHED_RR or SCHED_OTHER. Parameters: attr  attribute object; policy  address where the value of the policy attribute in the attribute object attr will be stored on success. Returns: 0 on success; an error number if: EINVAL, attr is invalid. See also: Specification.

int pthread_attr_getscope (  const pthread_attr_t *  attr, int *  scope )

Get contention scope attribute. This service stores, at the address scope, the value of the scope attribute in the attribute object attr. The scope attribute represents the scheduling contention scope of threads created with the attribute object attr. This implementation only supports the value PTHREAD_SCOPE_SYSTEM. Parameters: attr  attribute object; scope  address where the value of the scope attribute will be stored on sucess. Returns: 0 on success; an error number if: EINVAL, attr is invalid. See also: Specification.

int pthread_attr_getstacksize (  const pthread_attr_t *  attr, size_t *  stacksize )

Get stacksize attribute. This service stores, at the address stacksize, the value of the stacksize attribute in the attribute object attr. The stacksize attribute is used as the stack size of the threads created using the attribute object attr. Parameters: attr  attribute object; stacksize  address where the value of the stacksize attribute will be stored on success. Returns: 0 on success; an error number if: EINVAL, attr is invalid. See also: Specification.

int pthread_attr_init (  pthread_attr_t *  attr  )

Initialize a thread attributes object. This service initializes the thread creation attributes structure pointed to by attr. Attributes are set to their default values (see Thread creation attributes.). If this service is called specifying a thread attributes object that was already initialized, the attributes object is reinitialized. Parameters: attr  address of the thread attributes object to initialize. Returns: 0. See also: Specification.

int pthread_attr_setaffinity_np (  pthread_attr_t *  attr, xnarch_cpumask_t  mask )

Set the processor affinity attribute. This service sets to mask, the value of the affinity attribute in the attribute object attr. The affinity attributes is a bitmask where bits set indicate processor where a thread created with the attribute attr may run. The least significant bit corresponds to the first logical processor. This service is a non-portable extension of the POSIX interface. Parameters: attr  attribute object; mask  address where the value of the affinity attribute will be stored on success. Returns: 0 on success; an error number if: EINVAL, attr is invalid. Valid contexts: kernel module initialization or cleanup routine; Xenomai kernel-space thread.

int pthread_attr_setdetachstate (  pthread_attr_t *  attr, int  detachstate )

Set detachstate attribute. This service sets to detachstate the value of the detachstate attribute in the attribute object attr. Valid values of this attribute are PTHREAD_CREATE_JOINABLE and PTHREAD_CREATE_DETACHED. A detached thread is a thread which control block is automatically reclaimed when it terminates. The control block of a joinable thread, on the other hand, is only reclaimed when joined with the service pthread_join(). A thread that was created joinable may be detached after creation by using the pthread_detach() service. Parameters: attr  attribute object; detachstate  value of the detachstate attribute. Returns: 0 on success; an error number if: EINVAL, the attribute object attr is invalid See also: Specification.

int pthread_attr_setfp_np (  pthread_attr_t *  attr, int  fp )

Set the floating point attribute. This service set to fp, the value of the fp attribute in the attribute object attr. The fp attribute is a boolean attribute indicating whether a thread created with the attribute attr may use floating-point hardware. This service is a non-portable extension of the POSIX interface. Parameters: attr  attribute object; fp  value of the fp attribute. Returns: 0 on success; an error number if: EINVAL, attr is invalid. Valid contexts: kernel module initialization or cleanup routine; Xenomai kernel-space thread.

int pthread_attr_setinheritsched (  pthread_attr_t *  attr, int  inheritsched )

Set inheritsched attribute. This service set to inheritsched the value of the inheritsched attribute in the attribute object attr. Threads created with this attribute set to PTHREAD_INHERIT_SCHED will use the same scheduling policy and priority as the thread calling pthread_create(). Threads created with this attribute set to PTHREAD_EXPLICIT_SCHED will use the value of the schedpolicy attribute as scheduling policy, and the value of the schedparam attribute as scheduling priority. Parameters: attr  attribute object; inheritsched  value of the inheritsched attribute, PTHREAD_INHERIT_SCHED or PTHREAD_EXPLICIT_SCHED. Returns: 0 on success; an error number if: EINVAL, attr or inheritsched is invalid. See also: Specification.

int pthread_attr_setname_np (  pthread_attr_t *  attr, const char *  name )

Set name attribute. This service set to name, the value of the name attribute in the attribute object attr. The name attribute is the name under which a thread created with the attribute object attr will appear under /proc/xenomai/sched. If name is NULL, a unique default name will be used. This service is a non-portable extension of the POSIX interface. Parameters: attr  attribute object; name  value of the name attribute. Returns: 0 on success; an error number if: EINVAL, attr is invalid; ENOMEM, insufficient memory exists in the system heap to duplicate the name string, increase CONFIG_XENO_OPT_SYS_HEAPSZ. Valid contexts: kernel module initialization or cleanup routine; Xenomai kernel-space thread.

int pthread_attr_setschedparam (  pthread_attr_t *  attr, const struct sched_param *  par )

Set schedparam attribute. This service set to par, the value of the schedparam attribute in the attribute object attr. The only member of the sched_param structure used by this implementation is sched_priority. Threads created with attr will use the value of this attribute as a scheduling priority if the attribute inheritsched is set to PTHREAD_EXPLICIT_SCHED. Valid priorities range from 1 to 99. Parameters: attr  attribute object; par  value of the schedparam attribute. Returns: 0 on success; an error number if: EINVAL, attr or par is invalid. See also: Specification.

int pthread_attr_setschedpolicy (  pthread_attr_t *  attr, int  policy )

Set schedpolicy attribute. This service set to policy the value of the policy attribute in the attribute object attr. Threads created with the attribute object attr use the value of this attribute as scheduling policy if the inheritsched attribute is set to PTHREAD_EXPLICIT_SCHED. The value of this attribute is one of SCHED_FIFO, SCHED_RR or SCHED_OTHER. Parameters: attr  attribute object; policy  value of the policy attribute. Returns: 0 on success; an error number if: EINVAL, attr or policy is invalid. See also: Specification.

int pthread_attr_setscope (  pthread_attr_t *  attr, int  scope )

Set contention scope attribute. This service set to scope the value of the scope attribute in the attribute object attr. The scope attribute represents the scheduling contention scope of threads created with the attribute object attr. This implementation only supports the value PTHREAD_SCOPE_SYSTEM. Parameters: attr  attribute object; scope  value of the scope attribute. Returns: 0 on success; an error number if: ENOTSUP, scope is an unsupported value of the scope attribute. EINVAL, attr is invalid. See also: Specification.

int pthread_attr_setstacksize (  pthread_attr_t *  attr, size_t  stacksize )

Set stacksize attribute. This service set to stacksize, the value of the stacksize attribute in the attribute object attr. The stacksize attribute is used as the stack size of the threads created using the attribute object attr. The minimum value for this attribute is PTHREAD_STACK_MIN. Parameters: attr  attribute object; stacksize  value of the stacksize attribute. Returns: 0 on success; an error number if: EINVAL, attr or stacksize is invalid. See also: Specification.

---