Thread creation attributes.

Thread creation attributes. More...

Collaboration diagram for Thread creation attributes.:

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

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).

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 limited form of the schedparam attribute in the attribute object attr.

The limited form only defines the sched_priority member, that is sufficent to hold the scheduling parameter for SCHED_FIFO, SCHED_RR and SCHED_OTHER class members. 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.

pthread_attr_getschedparam_ex() should be used to retrieve the parameters for extended scheduling classes, such as SCHED_SPORADIC or SCHED_TP.

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_getschedparam_ex	(	const pthread_attr_t *	attr,
		struct sched_param_ex *	par
	)

Get schedparam_ex extended attribute.

This service is an extended version of pthread_attr_getschedparam(), that also supports Xenomai-specific or additional POSIX scheduling policies, which are not available with the host Linux environment.

Typically, SCHED_SPORADIC or SCHED_TP parameters can be retrieved from this call.

Parameters

attr	attribute object;
par	address where the value of the extended schedparam_ex 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, SCHED_SPORADIC, SCHED_TP 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.

Referenced by rt_task_create().

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.

Referenced by rt_task_create().

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.

Referenced by rt_task_create().

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 limited form of the schedparam attribute in the attribute object attr.

The limited form only defines the sched_priority member, that is sufficent to hold the scheduling parameter for SCHED_FIFO, SCHED_RR and SCHED_OTHER class members. 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.

Referenced by rt_task_create().

int pthread_attr_setschedparam_ex	(	pthread_attr_t *	attr,
		const struct sched_param_ex *	par
	)

Set extended schedparam_ex attribute.

This service is an extended version of pthread_attr_setschedparam(), that also supports Xenomai-specific or additional POSIX scheduling policies, which are not available with the host Linux environment.

Typically, SCHED_SPORADIC or SCHED_TP parameters can be set using this call.

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, SCHED_SPORADIC, SCHED_TP 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.

Referenced by rt_task_create().

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.

Referenced by rt_task_create().