NAME

VERSION

SYNOPSIS

 #   manually
 CFLAGS=-I/path/to/pth/include
 LDFLAGS=-L/path/to/pth/lib
 LIBS=-lpthread

 #   automatically
 CFLAGS=`pthread-config --cflags`
 LDFLAGS=`pthread-config --ldflags`
 LIBS=`pthread-config --libs`

Application source files:

 #include <pthread.h>

DESCRIPTION

Overview

This is the IEEE Std. 1003.1c ("POSIX.1c") conforming threading API of GNU Portable Threads (Pth). This API is commonly known as ``POSIX threads'' or in short ``Pthreads''. It is provided by Pth with the intention of backward compatibility to existing multithreaded applications. It is implemented by mapping the various Pthread API functions to the corresponding native Pth API functions.

Supported Features

The following defined feature macros in "pthread.h" indicate supported features:

 #define _POSIX_THREADS
 #define _POSIX_THREAD_ATTR_STACKADDR
 #define _POSIX_THREAD_ATTR_STACKSIZE

The following undefined feature macros in "pthread.h" indicate (still) unsupported features:

 #undef  _POSIX_THREAD_PRIORITY_SCHEDULING
 #undef  _POSIX_THREAD_PRIO_INHERIT
 #undef  _POSIX_THREAD_PRIO_PROTECT
 #undef  _POSIX_THREAD_PROCESS_SHARED
 #undef  _POSIX_THREAD_SAFE_FUNCTIONS

Notes

A few notes which you should keep in mind when working with the Pth Pthread API.

Non-Preemptive Scheduling

First you have to always remember when working with this Pthread library that it uses non-preemptive scheduling, because it is directly based on Pth (Pth for portability reasons is a pure non-preemptive thread scheduling system). So there is no implicit yielding of execution control unless you can "pthread_*" functions which could block and you cannot expect granular concurrency in your application, of course. Nevertheless the responsiveness and concurrency of an event driven application is increased greatly because of overlapping I/O.

Conflicts with Vendor Implementation

There can be a conflict between the Pth "pthread.h" header and a possibly existing vendor "/usr/include/pthread.h" header which was implicitly included by some standard vendor headers (like "/usr/include/unistd.h"). When this occurs try to ``"#define"'' header-dependent values which prevent the inclusion of the vendor header.

Further Reading

There is ``The Single UNIX Specification, Version 2 - Threads'', from The Open Group of 1997 under http://www.opengroup.org/onlinepubs/007908799/xsh/threads.html. This is a very complete publically available description of the Pthread API. For convinience reasons, a translated copy of these freely available HTML pages are appended to this manpage below. These are Copyright (C) 1997 The Open Group.

Second, you can also buy the official standard from IEEE. It is the IEEE POSIX 1003.1c-1995 standard (also known as ISO/IEC 9945-1:1996), which is available as part of the ANSI/IEEE 1003.1, 1996 edition, standard.

Finally you can look at the files "pthread.c" and "pthread.h" in the Pth source tree for details of the implementation, of course.

SEE ALSO

AUTHOR

 Ralf S. Engelschall
 rse@engelschall.com
 www.engelschall.com

______________________________________________________________________

NAME

SYNOPSIS

DESCRIPTION

 PTHREAD_CANCEL_ASYNCHRONOUS
 PTHREAD_CANCEL_ENABLE
 PTHREAD_CANCEL_DEFERRED
 PTHREAD_CANCEL_DISABLE
 PTHREAD_CANCELED
 PTHREAD_COND_INITIALIZER
 PTHREAD_CREATE_DETACHED
 PTHREAD_CREATE_JOINABLE
 PTHREAD_EXPLICIT_SCHED
 PTHREAD_INHERIT_SCHED
 PTHREAD_MUTEX_DEFAULT
 PTHREAD_MUTEX_ERRORCHECK
 PTHREAD_MUTEX_NORMAL
 PTHREAD_MUTEX_INITIALIZER
 PTHREAD_MUTEX_RECURSIVE
 PTHREAD_ONCE_INIT
 PTHREAD_PRIO_INHERIT
 PTHREAD_PRIO_NONE
 PTHREAD_PRIO_PROTECT
 PTHREAD_PROCESS_SHARED
 PTHREAD_PROCESS_PRIVATE
 PTHREAD_RWLOCK_INITIALIZER
 PTHREAD_SCOPE_PROCESS
 PTHREAD_SCOPE_SYSTEM

The pthread_attr_t, pthread_cond_t, pthread_condattr_t, pthread_key_t, pthread_mutex_t, pthread_mutexattr_t, pthread_once_t, pthread_rwlock_t, pthread_rwlockattr_t and pthread_t types are defined as described in <sys/types.h>.

The following are declared as functions and may also be declared as macros. Function prototypes must be provided for use with an ISO C compiler.

 int   pthread_attr_destroy(pthread_attr_t *);
 int   pthread_attr_getdetachstate(const pthread_attr_t *, int *);
 int   pthread_attr_getguardsize(const pthread_attr_t *, size_t *);
 int   pthread_attr_getinheritsched(const pthread_attr_t *, int *);
 int   pthread_attr_getschedparam(const pthread_attr_t *, struct sched_param *);
 int   pthread_attr_getschedpolicy(const pthread_attr_t *, int *);
 int   pthread_attr_getscope(const pthread_attr_t *, int *);
 int   pthread_attr_getstackaddr(const pthread_attr_t *, void **);
 int   pthread_attr_getstacksize(const pthread_attr_t *, size_t *);
 int   pthread_attr_init(pthread_attr_t *);
 int   pthread_attr_setdetachstate(pthread_attr_t *, int);
 int   pthread_attr_setguardsize(pthread_attr_t *, size_t);
 int   pthread_attr_setinheritsched(pthread_attr_t *, int);
 int   pthread_attr_setschedparam(pthread_attr_t *, const struct sched_param *);
 int   pthread_attr_setschedpolicy(pthread_attr_t *, int);
 int   pthread_attr_setscope(pthread_attr_t *, int);
 int   pthread_attr_setstackaddr(pthread_attr_t *, void *);
 int   pthread_attr_setstacksize(pthread_attr_t *, size_t);
 int   pthread_cancel(pthread_t);
 void  pthread_cleanup_push(void*), void *);
 void  pthread_cleanup_pop(int);
 int   pthread_cond_broadcast(pthread_cond_t *);
 int   pthread_cond_destroy(pthread_cond_t *);
 int   pthread_cond_init(pthread_cond_t *, const pthread_condattr_t *);
 int   pthread_cond_signal(pthread_cond_t *);
 int   pthread_cond_timedwait(pthread_cond_t *, pthread_mutex_t *, const struct timespec *);
 int   pthread_cond_wait(pthread_cond_t *, pthread_mutex_t *);
 int   pthread_condattr_destroy(pthread_condattr_t *);
 int   pthread_condattr_getpshared(const pthread_condattr_t *, int *);
 int   pthread_condattr_init(pthread_condattr_t *);
 int   pthread_condattr_setpshared(pthread_condattr_t *, int);
 int   pthread_create(pthread_t *, const pthread_attr_t *, void *(*)(void *), void *);
 int   pthread_detach(pthread_t);
 int   pthread_equal(pthread_t, pthread_t);
 void  pthread_exit(void *);
 int   pthread_getconcurrency(void);
 int   pthread_getschedparam(pthread_t, int *, struct sched_param *);
 void *pthread_getspecific(pthread_key_t);
 int   pthread_join(pthread_t, void **);
 int   pthread_key_create(pthread_key_t *, void (*)(void *));
 int   pthread_key_delete(pthread_key_t);
 int   pthread_mutex_destroy(pthread_mutex_t *);
 int   pthread_mutex_getprioceiling(const pthread_mutex_t *, int *);
 int   pthread_mutex_init(pthread_mutex_t *, const pthread_mutexattr_t *);
 int   pthread_mutex_lock(pthread_mutex_t *);
 int   pthread_mutex_setprioceiling(pthread_mutex_t *, int, int *);
 int   pthread_mutex_trylock(pthread_mutex_t *);
 int   pthread_mutex_unlock(pthread_mutex_t *);
 int   pthread_mutexattr_destroy(pthread_mutexattr_t *);
 int   pthread_mutexattr_getprioceiling(const pthread_mutexattr_t *, int *);
 int   pthread_mutexattr_getprotocol(const pthread_mutexattr_t *, int *);
 int   pthread_mutexattr_getpshared(const pthread_mutexattr_t *, int *);
 int   pthread_mutexattr_gettype(const pthread_mutexattr_t *, int *);
 int   pthread_mutexattr_init(pthread_mutexattr_t *);
 int   pthread_mutexattr_setprioceiling(pthread_mutexattr_t *, int);
 int   pthread_mutexattr_setprotocol(pthread_mutexattr_t *, int);
 int   pthread_mutexattr_setpshared(pthread_mutexattr_t *, int);
 int   pthread_mutexattr_settype(pthread_mutexattr_t *, int);
 int   pthread_once(pthread_once_t *, void (*)(void));
 int   pthread_rwlock_destroy(pthread_rwlock_t *);
 int   pthread_rwlock_init(pthread_rwlock_t *, const pthread_rwlockattr_t *);
 int   pthread_rwlock_rdlock(pthread_rwlock_t *);
 int   pthread_rwlock_tryrdlock(pthread_rwlock_t *);
 int   pthread_rwlock_trywrlock(pthread_rwlock_t *);
 int   pthread_rwlock_unlock(pthread_rwlock_t *);
 int   pthread_rwlock_wrlock(pthread_rwlock_t *);
 int   pthread_rwlockattr_destroy(pthread_rwlockattr_t *);
 int   pthread_rwlockattr_getpshared(const pthread_rwlockattr_t *, int *);
 int   pthread_rwlockattr_init(pthread_rwlockattr_t *);
 int   pthread_rwlockattr_setpshared(pthread_rwlockattr_t *, int);
 pthread_t pthread_self(void);
 int   pthread_setcancelstate(int, int *);
 int   pthread_setcanceltype(int, int *);
 int   pthread_setconcurrency(int);
 int   pthread_setschedparam(pthread_t, int, const struct sched_param *);
 int   pthread_setspecific(pthread_key_t, const void *);
 void  pthread_testcancel(void);

Inclusion of the <pthread.h> header will make visible symbols defined in the headers <sched.h> and <time.h>.

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

#include <unistd.h>

int pthread_atfork(void (*prepare)(void), void (*parent)(void), void (*child)(void));

DESCRIPTION

The order of calls to pthread_atfork() is significant. The parent and child fork handlers are called in the order in which they were established by calls to pthread_atfork(). The prepare fork handlers are called in the opposite order.

RETURN VALUE

ERRORS

[ENOMEM]

Insufficient table space exists to record the fork handler addresses.

The pthread_atfork() function will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_attr_init(pthread_attr_t *attr);

int pthread_attr_destroy(pthread_attr_t *attr);

DESCRIPTION

The resulting attribute object (possibly modified by setting individual attribute values), when used by pthread_create(), defines the attributes of the thread created. A single attributes object can be used in multiple simultaneous calls to pthread_create().

The pthread_attr_destroy() function is used to destroy a thread attributes object. An implementation may cause pthread_attr_destroy() to set attr to an implementation-dependent invalid value. The behaviour of using the attribute after it has been destroyed is undefined.

RETURN VALUE

ERRORS

[ENOMEM]

Insufficient memory exists to initialise the thread attributes object.

These functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_attr_setdetachstate(pthread_attr_t *attr, int detachstate);

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

DESCRIPTION

The pthread_attr_setdetachstate() and pthread_attr_getdetachstate(), respectively, set and get the detachstate attribute in the attr object.

The detachstate can be set to either PTHREAD_CREATE_DETACHED or PTHREAD_CREATE_JOINABLE. A value of PTHREAD_CREATE_DETACHED causes all threads created with attr to be in the detached state, whereas using a value of PTHREAD_CREATE_JOINABLE causes all threads created with attr to be in the joinable state. The default value of the detachstate attribute is PTHREAD_CREATE_JOINABLE .

RETURN VALUE

The pthread_attr_getdetachstate() function stores the value of the detachstate attribute in detachstate if successful.

ERRORS

[EINVAL]

The value of detachstate was not valid

These functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

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

DESCRIPTION

The guardsize attribute is provided to the application for two reasons:

1.

Overflow protection can potentially result in wasted system resources. An application that creates a large number of threads, and which knows its threads will never overflow their stack, can save system resources by turning off guard areas.

2.

When threads allocate large data structures on the stack, large guard areas may be needed to detect stack overflow.

The pthread_attr_getguardsize() function gets the guardsize attribute in the attr object. This attribute is returned in the guardsize parameter.

The pthread_attr_setguardsize() function sets the guardsize attribute in the attr object. The new value of this attribute is obtained from the guardsize parameter. If guardsize is zero, a guard area will not be provided for threads created with attr. If guardsize is greater than zero, a guard area of at least size guardsize bytes is provided for each thread created with attr.

A conforming implementation is permitted to round up the value contained in guardsize to a multiple of the configurable system variable PAGESIZE (see <sys/mman.h>). If an implementation rounds up the value of guardsize to a multiple of PAGESIZE, a call to pthread_attr_getguardsize() specifying attr will store in the guardsize parameter the guard size specified by the previous pthread_attr_setguardsize() function call.

The default value of the guardsize attribute is PAGESIZE bytes. The actual value of PAGESIZE is implementation-dependent and may not be the same on all implementations.

If the stackaddr attribute has been set (that is, the caller is allocating and managing its own thread stacks), the guardsize attribute is ignored and no protection will be provided by the implementation. It is the responsibility of the application to manage stack overflow along with stack allocation and management in this case.

RETURN VALUE

ERRORS

[EINVAL]

The attribute attr is invalid.

[EINVAL]

The parameter guardsize is invalid.

[EINVAL]

The parameter guardsize contains an invalid value.

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

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

DESCRIPTION

When the attribute objects are used by pthread_create() , the inheritsched attribute determines how the other scheduling attributes of the created thread are to be set:

PTHREAD_INHERIT_SCHED

Specifies that the scheduling policy and associated attributes are to be inherited from the creating thread, and the scheduling attributes in this attr argument are to be ignored.

PTHREAD_EXPLICIT_SCHED

Specifies that the scheduling policy and associated attributes are to be set to the corresponding values from this attribute object.

The symbols PTHREAD_INHERIT_SCHED and PTHREAD_EXPLICIT_SCHED are defined in the header <pthread.h>.

RETURN VALUE

ERRORS

[ENOSYS]

The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the implementation does not support the function.

The pthread_attr_setinheritsched() function may fail if:

[EINVAL]

The value of the attribute being set is not valid.

[ENOTSUP]

An attempt was made to set the attribute to an unsupported value.

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

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

DESCRIPTION

RETURN VALUE

ERRORS

[EINVAL]

The value of the attribute being set is not valid.

[ENOTSUP]

An attempt was made to set the attribute to an unsupported value.

The pthread_attr_setschedparam() and pthread_attr_getschedparam() functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

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

DESCRIPTION

The supported values of policy include SCHED_FIFO, SCHED_RR and SCHED_OTHER, which are defined by the header <sched.h>. When threads executing with the scheduling policy SCHED_FIFO or SCHED_RR are waiting on a mutex, they acquire the mutex in priority order when the mutex is unlocked.

RETURN VALUE

ERRORS

[ENOSYS]

The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the implementation does not support the function.

The pthread_attr_setschedpolicy() function may fail if:

[EINVAL]

The value of the attribute being set is not valid.

[ENOTSUP]

An attempt was made to set the attribute to an unsupported value.

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

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

DESCRIPTION

The contentionscope attribute may have the values PTHREAD_SCOPE_SYSTEM, signifying system scheduling contention scope, or PTHREAD_SCOPE_PROCESS, signifying process scheduling contention scope. The symbols PTHREAD_SCOPE_SYSTEM and PTHREAD_SCOPE_PROCESS are defined by the header <pthread.h>.

RETURN VALUE

ERRORS

[ENOSYS]

The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the implementation does not support the function.

The pthread_attr_setscope(), function may fail if:

[EINVAL]

The value of the attribute being set is not valid.

[ENOTSUP]

An attempt was made to set the attribute to an unsupported value.

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

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

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

DESCRIPTION

The stackaddr attribute specifies the location of storage to be used for the created thread's stack. The size of the storage is at least PTHREAD_STACK_MIN.

RETURN VALUE

The pthread_attr_getstackaddr() function stores the stackaddr attribute value in stackaddr if successful.

ERRORS

These functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

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

DESCRIPTION

The stacksize attribute defines the minimum stack size (in bytes) allocated for the created threads stack.

RETURN VALUE

ERRORS

[EINVAL]

The value of stacksize is less than PTHREAD_STACK_MIN or exceeds a system-imposed limit.

These functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_attr_init(pthread_attr_t *attr); int pthread_attr_destroy(pthread_attr_t *attr);

DESCRIPTION

The resulting attribute object (possibly modified by setting individual attribute values), when used by pthread_create(), defines the attributes of the thread created. A single attributes object can be used in multiple simultaneous calls to pthread_create().

The pthread_attr_destroy() function is used to destroy a thread attributes object. An implementation may cause pthread_attr_destroy() to set attr to an implementation-dependent invalid value. The behaviour of using the attribute after it has been destroyed is undefined.

RETURN VALUE

ERRORS

[ENOMEM]

Insufficient memory exists to initialise the thread attributes object.

These functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

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

DESCRIPTION

The pthread_attr_setdetachstate() and pthread_attr_getdetachstate(), respectively, set and get the detachstate attribute in the attr object.

The detachstate can be set to either PTHREAD_CREATE_DETACHED or PTHREAD_CREATE_JOINABLE. A value of PTHREAD_CREATE_DETACHED causes all threads created with attr to be in the detached state, whereas using a value of PTHREAD_CREATE_JOINABLE causes all threads created with attr to be in the joinable state. The default value of the detachstate attribute is PTHREAD_CREATE_JOINABLE .

RETURN VALUE

The pthread_attr_getdetachstate() function stores the value of the detachstate attribute in detachstate if successful.

ERRORS

[EINVAL]

The value of detachstate was not valid

These functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

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

DESCRIPTION

The guardsize attribute is provided to the application for two reasons:

1.

Overflow protection can potentially result in wasted system resources. An application that creates a large number of threads, and which knows its threads will never overflow their stack, can save system resources by turning off guard areas.

2.

When threads allocate large data structures on the stack, large guard areas may be needed to detect stack overflow.

The pthread_attr_getguardsize() function gets the guardsize attribute in the attr object. This attribute is returned in the guardsize parameter.

The pthread_attr_setguardsize() function sets the guardsize attribute in the attr object. The new value of this attribute is obtained from the guardsize parameter. If guardsize is zero, a guard area will not be provided for threads created with attr. If guardsize is greater than zero, a guard area of at least size guardsize bytes is provided for each thread created with attr.

A conforming implementation is permitted to round up the value contained in guardsize to a multiple of the configurable system variable PAGESIZE (see <sys/mman.h>). If an implementation rounds up the value of guardsize to a multiple of PAGESIZE, a call to pthread_attr_getguardsize() specifying attr will store in the guardsize parameter the guard size specified by the previous pthread_attr_setguardsize() function call.

The default value of the guardsize attribute is PAGESIZE bytes. The actual value of PAGESIZE is implementation-dependent and may not be the same on all implementations.

If the stackaddr attribute has been set (that is, the caller is allocating and managing its own thread stacks), the guardsize attribute is ignored and no protection will be provided by the implementation. It is the responsibility of the application to manage stack overflow along with stack allocation and management in this case.

RETURN VALUE

ERRORS

[EINVAL]

The attribute attr is invalid.

[EINVAL]

The parameter guardsize is invalid.

[EINVAL]

The parameter guardsize contains an invalid value.

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

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

DESCRIPTION

When the attribute objects are used by pthread_create() , the inheritsched attribute determines how the other scheduling attributes of the created thread are to be set:

PTHREAD_INHERIT_SCHED

Specifies that the scheduling policy and associated attributes are to be inherited from the creating thread, and the scheduling attributes in this attr argument are to be ignored.

PTHREAD_EXPLICIT_SCHED

Specifies that the scheduling policy and associated attributes are to be set to the corresponding values from this attribute object.

The symbols PTHREAD_INHERIT_SCHED and PTHREAD_EXPLICIT_SCHED are defined in the header <pthread.h>.

RETURN VALUE

ERRORS

[ENOSYS]

The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the implementation does not support the function.

The pthread_attr_setinheritsched() function may fail if:

[EINVAL]

The value of the attribute being set is not valid.

[ENOTSUP]

An attempt was made to set the attribute to an unsupported value.

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

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

DESCRIPTION

RETURN VALUE

ERRORS

[EINVAL]

The value of the attribute being set is not valid.

[ENOTSUP]

An attempt was made to set the attribute to an unsupported value.

The pthread_attr_setschedparam() and pthread_attr_getschedparam() functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

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

DESCRIPTION

The supported values of policy include SCHED_FIFO, SCHED_RR and SCHED_OTHER, which are defined by the header <sched.h>. When threads executing with the scheduling policy SCHED_FIFO or SCHED_RR are waiting on a mutex, they acquire the mutex in priority order when the mutex is unlocked.

RETURN VALUE

ERRORS

[ENOSYS]

The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the implementation does not support the function.

The pthread_attr_setschedpolicy() function may fail if:

[EINVAL]

The value of the attribute being set is not valid.

[ENOTSUP]

An attempt was made to set the attribute to an unsupported value.

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

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

DESCRIPTION

The contentionscope attribute may have the values PTHREAD_SCOPE_SYSTEM, signifying system scheduling contention scope, or PTHREAD_SCOPE_PROCESS, signifying process scheduling contention scope. The symbols PTHREAD_SCOPE_SYSTEM and PTHREAD_SCOPE_PROCESS are defined by the header <pthread.h>.

RETURN VALUE

ERRORS

[ENOSYS]

The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the implementation does not support the function.

The pthread_attr_setscope(), function may fail if:

[EINVAL]

The value of the attribute being set is not valid.

[ENOTSUP]

An attempt was made to set the attribute to an unsupported value.

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

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

DESCRIPTION

The stackaddr attribute specifies the location of storage to be used for the created thread's stack. The size of the storage is at least PTHREAD_STACK_MIN.

RETURN VALUE

The pthread_attr_getstackaddr() function stores the stackaddr attribute value in stackaddr if successful.

ERRORS

These functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

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

DESCRIPTION

The stacksize attribute defines the minimum stack size (in bytes) allocated for the created threads stack.

RETURN VALUE

ERRORS

[EINVAL]

The value of stacksize is less than PTHREAD_STACK_MIN or exceeds a system-imposed limit.

These functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_cancel(pthread_t thread);

DESCRIPTION

The cancellation processing in the target thread runs asynchronously with respect to the calling thread returning from pthread_cancel().

RETURN VALUE

ERRORS

[ESRCH]

No thread could be found corresponding to that specified by the given thread ID.

The pthread_cancel() function will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

void pthread_cleanup_push(void (*routine)(void*), void *arg); void pthread_cleanup_pop(int execute);

DESCRIPTION

The pthread_cleanup_pop() function removes the routine at the top of the calling thread's cancellation cleanup stack and optionally invokes it (if execute is non-zero).

These functions may be implemented as macros and will appear as statements and in pairs within the same lexical scope (that is, the pthread_cleanup_push() macro may be thought to expand to a token list whose first token is `{' with pthread_cleanup_pop() expanding to a token list whose last token is the corresponding `}'.

The effect of calling longjmp() or siglongjmp() is undefined if there have been any calls to pthread_cleanup_push() or pthread_cleanup_pop() made without the matching call since the jump buffer was filled. The effect of calling longjmp() or siglongjmp() from inside a cancellation cleanup handler is also undefined unless the jump buffer was also filled in the cancellation cleanup handler.

RETURN VALUE

ERRORS

These functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

void pthread_cleanup_push(void (*routine)(void*), void *arg); void pthread_cleanup_pop(int execute);

DESCRIPTION

The pthread_cleanup_pop() function removes the routine at the top of the calling thread's cancellation cleanup stack and optionally invokes it (if execute is non-zero).

These functions may be implemented as macros and will appear as statements and in pairs within the same lexical scope (that is, the pthread_cleanup_push() macro may be thought to expand to a token list whose first token is `{' with pthread_cleanup_pop() expanding to a token list whose last token is the corresponding `}'.

The effect of calling longjmp() or siglongjmp() is undefined if there have been any calls to pthread_cleanup_push() or pthread_cleanup_pop() made without the matching call since the jump buffer was filled. The effect of calling longjmp() or siglongjmp() from inside a cancellation cleanup handler is also undefined unless the jump buffer was also filled in the cancellation cleanup handler.

RETURN VALUE

ERRORS

These functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_cond_signal(pthread_cond_t *cond); int pthread_cond_broadcast(pthread_cond_t *cond);

DESCRIPTION

The pthread_cond_signal() call unblocks at least one of the threads that are blocked on the specified condition variable cond (if any threads are blocked on cond).

The pthread_cond_broadcast() call unblocks all threads currently blocked on the specified condition variable cond.

If more than one thread is blocked on a condition variable, the scheduling policy determines the order in which threads are unblocked. When each thread unblocked as a result of a pthread_cond_signal() or pthread_cond_broadcast() returns from its call to pthread_cond_wait() or pthread_cond_timedwait(), the thread owns the mutex with which it called pthread_cond_wait() or pthread_cond_timedwait(). The thread(s) that are unblocked contend for the mutex according to the scheduling policy (if applicable), and as if each had called pthread_mutex_lock().

The pthread_cond_signal() or pthread_cond_broadcast() functions may be called by a thread whether or not it currently owns the mutex that threads calling pthread_cond_wait() or pthread_cond_timedwait() have associated with the condition variable during their waits; however, if predictable scheduling behaviour is required, then that mutex is locked by the thread calling pthread_cond_signal() or pthread_cond_broadcast().

The pthread_cond_signal() and pthread_cond_broadcast() functions have no effect if there are no threads currently blocked on cond.

RETURN VALUE

ERRORS

[EINVAL]

The value cond does not refer to an initialised condition variable.

These functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_cond_init(pthread_cond_t *cond, const pthread_condattr_t *attr); int pthread_cond_destroy(pthread_cond_t *cond); pthread_cond_t cond = PTHREAD_COND_INITIALIZER;

DESCRIPTION

Attempting to initialise an already initialised condition variable results in undefined behaviour.

The function pthread_cond_destroy() destroys the given condition variable specified by cond; the object becomes, in effect, uninitialised. An implementation may cause pthread_cond_destroy() to set the object referenced by cond to an invalid value. A destroyed condition variable object can be re-initialised using pthread_cond_init(); the results of otherwise referencing the object after it has been destroyed are undefined.

It is safe to destroy an initialised condition variable upon which no threads are currently blocked. Attempting to destroy a condition variable upon which other threads are currently blocked results in undefined behaviour.

In cases where default condition variable attributes are appropriate, the macro PTHREAD_COND_INITIALIZER can be used to initialise condition variables that are statically allocated. The effect is equivalent to dynamic initialisation by a call to pthread_cond_init() with parameter attr specified as NULL, except that no error checks are performed.

RETURN VALUE

ERRORS

[EAGAIN]

The system lacked the necessary resources (other than memory) to initialise another condition variable.

[ENOMEM]

Insufficient memory exists to initialise the condition variable.

The pthread_cond_init() function may fail if:

[EBUSY]

The implementation has detected an attempt to re-initialise the object referenced by cond, a previously initialised, but not yet destroyed, condition variable.

[EINVAL]

The value specified by attr is invalid.

The pthread_cond_destroy() function may fail if:

[EBUSY]

The implementation has detected an attempt to destroy the object referenced by cond while it is referenced (for example, while being used in a pthread_cond_wait() or pthread_cond_timedwait()) by another thread.

[EINVAL]

The value specified by cond is invalid.

These functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_cond_init(pthread_cond_t *cond, const pthread_condattr_t *attr); int pthread_cond_destroy(pthread_cond_t *cond); pthread_cond_t cond = PTHREAD_COND_INITIALIZER;

DESCRIPTION

Attempting to initialise an already initialised condition variable results in undefined behaviour.

The function pthread_cond_destroy() destroys the given condition variable specified by cond; the object becomes, in effect, uninitialised. An implementation may cause pthread_cond_destroy() to set the object referenced by cond to an invalid value. A destroyed condition variable object can be re-initialised using pthread_cond_init(); the results of otherwise referencing the object after it has been destroyed are undefined.

It is safe to destroy an initialised condition variable upon which no threads are currently blocked. Attempting to destroy a condition variable upon which other threads are currently blocked results in undefined behaviour.

In cases where default condition variable attributes are appropriate, the macro PTHREAD_COND_INITIALIZER can be used to initialise condition variables that are statically allocated. The effect is equivalent to dynamic initialisation by a call to pthread_cond_init() with parameter attr specified as NULL, except that no error checks are performed.

RETURN VALUE

ERRORS

[EAGAIN]

The system lacked the necessary resources (other than memory) to initialise another condition variable.

[ENOMEM]

Insufficient memory exists to initialise the condition variable.

The pthread_cond_init() function may fail if:

[EBUSY]

The implementation has detected an attempt to re-initialise the object referenced by cond, a previously initialised, but not yet destroyed, condition variable.

[EINVAL]

The value specified by attr is invalid.

The pthread_cond_destroy() function may fail if:

[EBUSY]

The implementation has detected an attempt to destroy the object referenced by cond while it is referenced (for example, while being used in a pthread_cond_wait() or pthread_cond_timedwait()) by another thread.

[EINVAL]

The value specified by cond is invalid.

These functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_cond_signal(pthread_cond_t *cond); int pthread_cond_broadcast(pthread_cond_t *cond);

DESCRIPTION

The pthread_cond_signal() call unblocks at least one of the threads that are blocked on the specified condition variable cond (if any threads are blocked on cond).

The pthread_cond_broadcast() call unblocks all threads currently blocked on the specified condition variable cond.

If more than one thread is blocked on a condition variable, the scheduling policy determines the order in which threads are unblocked. When each thread unblocked as a result of a pthread_cond_signal() or pthread_cond_broadcast() returns from its call to pthread_cond_wait() or pthread_cond_timedwait(), the thread owns the mutex with which it called pthread_cond_wait() or pthread_cond_timedwait(). The thread(s) that are unblocked contend for the mutex according to the scheduling policy (if applicable), and as if each had called pthread_mutex_lock().

The pthread_cond_signal() or pthread_cond_broadcast() functions may be called by a thread whether or not it currently owns the mutex that threads calling pthread_cond_wait() or pthread_cond_timedwait() have associated with the condition variable during their waits; however, if predictable scheduling behaviour is required, then that mutex is locked by the thread calling pthread_cond_signal() or pthread_cond_broadcast().

The pthread_cond_signal() and pthread_cond_broadcast() functions have no effect if there are no threads currently blocked on cond.

RETURN VALUE

ERRORS

[EINVAL]

The value cond does not refer to an initialised condition variable.

These functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_cond_wait(pthread_cond_t *cond, pthread_mutex_t *mutex); int pthread_cond_timedwait(pthread_cond_t *cond, pthread_mutex_t *mutex, const struct timespec *abstime);

DESCRIPTION

These functions atomically release mutex and cause the calling thread to block on the condition variable cond; atomically here means &quot;atomically with respect to access by another thread to the mutex and then the condition variable&quot;. That is, if another thread is able to acquire the mutex after the about-to-block thread has released it, then a subsequent call to pthread_cond_signal() or pthread_cond_broadcast() in that thread behaves as if it were issued after the about-to-block thread has blocked.

Upon successful return, the mutex has been locked and is owned by the calling thread.

When using condition variables there is always a boolean predicate involving shared variables associated with each condition wait that is true if the thread should proceed. Spurious wakeups from the pthread_cond_wait() or pthread_cond_timedwait() functions may occur. Since the return from pthread_cond_wait() or pthread_cond_timedwait() does not imply anything about the value of this predicate, the predicate should be re-evaluated upon such return.

The effect of using more than one mutex for concurrent pthread_cond_wait() or pthread_cond_timedwait() operations on the same condition variable is undefined; that is, a condition variable becomes bound to a unique mutex when a thread waits on the condition variable, and this (dynamic) binding ends when the wait returns.

A condition wait (whether timed or not) is a cancellation point. When the cancelability enable state of a thread is set to PTHREAD_CANCEL_DEFERRED, a side effect of acting upon a cancellation request while in a condition wait is that the mutex is (in effect) re-acquired before calling the first cancellation cleanup handler. The effect is as if the thread were unblocked, allowed to execute up to the point of returning from the call to pthread_cond_wait() or pthread_cond_timedwait(), but at that point notices the cancellation request and instead of returning to the caller of pthread_cond_wait() or pthread_cond_timedwait(), starts the thread cancellation activities, which includes calling cancellation cleanup handlers.

A thread that has been unblocked because it has been canceled while blocked in a call to pthread_cond_wait() or pthread_cond_timedwait() does not consume any condition signal that may be directed concurrently at the condition variable if there are other threads blocked on the condition variable.

The pthread_cond_timedwait() function is the same as pthread_cond_wait() except that an error is returned if the absolute time specified by abstime passes (that is, system time equals or exceeds abstime) before the condition cond is signaled or broadcasted, or if the absolute time specified by abstime has already been passed at the time of the call. When such time-outs occur, pthread_cond_timedwait() will nonetheless release and reacquire the mutex referenced by mutex. The function pthread_cond_timedwait() is also a cancellation point.

If a signal is delivered to a thread waiting for a condition variable, upon return from the signal handler the thread resumes waiting for the condition variable as if it was not interrupted, or it returns zero due to spurious wakeup.

RETURN VALUE

Upon successful completion, a value of zero is returned. Otherwise, an error number is returned to indicate the error.

ERRORS

[ETIMEDOUT]

The time specified by abstime to pthread_cond_timedwait() has passed.

The pthread_cond_wait() and pthread_cond_timedwait() functions may fail if:

[EINVAL]

The value specified by cond, mutex, or abstime is invalid.

[EINVAL]

Different mutexes were supplied for concurrent pthread_cond_wait() or pthread_cond_timedwait() operations on the same condition variable.

[EINVAL]

The mutex was not owned by the current thread at the time of the call.

These functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_cond_wait(pthread_cond_t *cond, pthread_mutex_t *mutex); int pthread_cond_timedwait(pthread_cond_t *cond, pthread_mutex_t *mutex, const struct timespec *abstime);

DESCRIPTION

These functions atomically release mutex and cause the calling thread to block on the condition variable cond; atomically here means &quot;atomically with respect to access by another thread to the mutex and then the condition variable&quot;. That is, if another thread is able to acquire the mutex after the about-to-block thread has released it, then a subsequent call to pthread_cond_signal() or pthread_cond_broadcast() in that thread behaves as if it were issued after the about-to-block thread has blocked.

Upon successful return, the mutex has been locked and is owned by the calling thread.

When using condition variables there is always a boolean predicate involving shared variables associated with each condition wait that is true if the thread should proceed. Spurious wakeups from the pthread_cond_wait() or pthread_cond_timedwait() functions may occur. Since the return from pthread_cond_wait() or pthread_cond_timedwait() does not imply anything about the value of this predicate, the predicate should be re-evaluated upon such return.

The effect of using more than one mutex for concurrent pthread_cond_wait() or pthread_cond_timedwait() operations on the same condition variable is undefined; that is, a condition variable becomes bound to a unique mutex when a thread waits on the condition variable, and this (dynamic) binding ends when the wait returns.

A condition wait (whether timed or not) is a cancellation point. When the cancelability enable state of a thread is set to PTHREAD_CANCEL_DEFERRED, a side effect of acting upon a cancellation request while in a condition wait is that the mutex is (in effect) re-acquired before calling the first cancellation cleanup handler. The effect is as if the thread were unblocked, allowed to execute up to the point of returning from the call to pthread_cond_wait() or pthread_cond_timedwait(), but at that point notices the cancellation request and instead of returning to the caller of pthread_cond_wait() or pthread_cond_timedwait(), starts the thread cancellation activities, which includes calling cancellation cleanup handlers.

A thread that has been unblocked because it has been canceled while blocked in a call to pthread_cond_wait() or pthread_cond_timedwait() does not consume any condition signal that may be directed concurrently at the condition variable if there are other threads blocked on the condition variable.

The pthread_cond_timedwait() function is the same as pthread_cond_wait() except that an error is returned if the absolute time specified by abstime passes (that is, system time equals or exceeds abstime) before the condition cond is signaled or broadcasted, or if the absolute time specified by abstime has already been passed at the time of the call. When such time-outs occur, pthread_cond_timedwait() will nonetheless release and reacquire the mutex referenced by mutex. The function pthread_cond_timedwait() is also a cancellation point.

If a signal is delivered to a thread waiting for a condition variable, upon return from the signal handler the thread resumes waiting for the condition variable as if it was not interrupted, or it returns zero due to spurious wakeup.

RETURN VALUE

Upon successful completion, a value of zero is returned. Otherwise, an error number is returned to indicate the error.

ERRORS

[ETIMEDOUT]

The time specified by abstime to pthread_cond_timedwait() has passed.

The pthread_cond_wait() and pthread_cond_timedwait() functions may fail if:

[EINVAL]

The value specified by cond, mutex, or abstime is invalid.

[EINVAL]

Different mutexes were supplied for concurrent pthread_cond_wait() or pthread_cond_timedwait() operations on the same condition variable.

[EINVAL]

The mutex was not owned by the current thread at the time of the call.

These functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_condattr_init(pthread_condattr_t *attr); int pthread_condattr_destroy(pthread_condattr_t *attr);

DESCRIPTION

Attempting to initialise an already initialised condition variable attributes object results in undefined behaviour.

After a condition variable attributes object has been used to initialise one or more condition variables, any function affecting the attributes object (including destruction) does not affect any previously initialised condition variables.

The pthread_condattr_destroy() function destroys a condition variable attributes object; the object becomes, in effect, uninitialised. An implementation may cause pthread_condattr_destroy() to set the object referenced by attr to an invalid value. A destroyed condition variable attributes object can be re-initialised using pthread_condattr_init(); the results of otherwise referencing the object after it has been destroyed are undefined.

Additional attributes, their default values, and the names of the associated functions to get and set those attribute values are implementation-dependent.

RETURN VALUE

ERRORS

[ENOMEM]

Insufficient memory exists to initialise the condition variable attributes object.

The pthread_condattr_destroy() function may fail if:

[EINVAL]

The value specified by attr is invalid.

These functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_condattr_getpshared(const pthread_condattr_t *attr, int *pshared); int pthread_condattr_setpshared(pthread_condattr_t *attr, int pshared);

DESCRIPTION

The process-shared attribute is set to PTHREAD_PROCESS_SHARED to permit a condition variable to be operated upon by any thread that has access to the memory where the condition variable is allocated, even if the condition variable is allocated in memory that is shared by multiple processes. If the process-shared attribute is PTHREAD_PROCESS_PRIVATE, the condition variable will only be operated upon by threads created within the same process as the thread that initialised the condition variable; if threads of differing processes attempt to operate on such a condition variable, the behaviour is undefined. The default value of the attribute is PTHREAD_PROCESS_PRIVATE.

Additional attributes, their default values, and the names of the associated functions to get and set those attribute values are implementation-dependent.

RETURN VALUE

If successful, the pthread_condattr_getpshared() function returns zero and stores the value of the process-shared attribute of attr into the object referenced by the pshared parameter. Otherwise, an error number is returned to indicate the error.

ERRORS

[EINVAL]

The value specified by attr is invalid.

The pthread_condattr_setpshared() function may fail if:

[EINVAL]

The new value specified for the attribute is outside the range of legal values for that attribute.

These functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_condattr_init(pthread_condattr_t *attr); int pthread_condattr_destroy(pthread_condattr_t *attr);

DESCRIPTION

Attempting to initialise an already initialised condition variable attributes object results in undefined behaviour.

After a condition variable attributes object has been used to initialise one or more condition variables, any function affecting the attributes object (including destruction) does not affect any previously initialised condition variables.

The pthread_condattr_destroy() function destroys a condition variable attributes object; the object becomes, in effect, uninitialised. An implementation may cause pthread_condattr_destroy() to set the object referenced by attr to an invalid value. A destroyed condition variable attributes object can be re-initialised using pthread_condattr_init(); the results of otherwise referencing the object after it has been destroyed are undefined.

Additional attributes, their default values, and the names of the associated functions to get and set those attribute values are implementation-dependent.

RETURN VALUE

ERRORS

[ENOMEM]

Insufficient memory exists to initialise the condition variable attributes object.

The pthread_condattr_destroy() function may fail if:

[EINVAL]

The value specified by attr is invalid.

These functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_condattr_getpshared(const pthread_condattr_t *attr, int *pshared); int pthread_condattr_setpshared(pthread_condattr_t *attr, int pshared);

DESCRIPTION

The process-shared attribute is set to PTHREAD_PROCESS_SHARED to permit a condition variable to be operated upon by any thread that has access to the memory where the condition variable is allocated, even if the condition variable is allocated in memory that is shared by multiple processes. If the process-shared attribute is PTHREAD_PROCESS_PRIVATE, the condition variable will only be operated upon by threads created within the same process as the thread that initialised the condition variable; if threads of differing processes attempt to operate on such a condition variable, the behaviour is undefined. The default value of the attribute is PTHREAD_PROCESS_PRIVATE.

Additional attributes, their default values, and the names of the associated functions to get and set those attribute values are implementation-dependent.

RETURN VALUE

If successful, the pthread_condattr_getpshared() function returns zero and stores the value of the process-shared attribute of attr into the object referenced by the pshared parameter. Otherwise, an error number is returned to indicate the error.

ERRORS

[EINVAL]

The value specified by attr is invalid.

The pthread_condattr_setpshared() function may fail if:

[EINVAL]

The new value specified for the attribute is outside the range of legal values for that attribute.

These functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_create(pthread_t *thread, const pthread_attr_t *attr, void *(*start_routine)(void*), void *arg);

DESCRIPTION

The thread is created executing start_routine with arg as its sole argument. If the start_routine returns, the effect is as if there was an implicit call to pthread_exit() using the return value of start_routine as the exit status. Note that the thread in which main() was originally invoked differs from this. When it returns from main(), the effect is as if there was an implicit call to exit() using the return value of main() as the exit status.

The signal state of the new thread is initialised as follows:

o

The signal mask is inherited from the creating thread.

o

The set of signals pending for the new thread is empty.

If pthread_create() fails, no new thread is created and the contents of the location referenced by thread are undefined.

RETURN VALUE

ERRORS

[EAGAIN]

The system lacked the necessary resources to create another thread, or the system-imposed limit on the total number of threads in a process PTHREAD_THREADS_MAX would be exceeded.

[EINVAL]

The value specified by attr is invalid.

[EPERM]

The caller does not have appropriate permission to set the required scheduling parameters or scheduling policy.

The pthread_create() function will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_detach(pthread_t thread);

DESCRIPTION

RETURN VALUE

ERRORS

[EINVAL]

The implementation has detected that the value specified by thread does not refer to a joinable thread.

[ESRCH]

No thread could be found corresponding to that specified by the given thread ID.

The pthread_detach() function will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_equal(pthread_t t1, pthread_t t2);

DESCRIPTION

RETURN VALUE

If either t1 or t2 are not valid thread IDs, the behaviour is undefined.

ERRORS

The pthread_equal() function will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

void pthread_exit(void *value_ptr);

DESCRIPTION

An implicit call to pthread_exit() is made when a thread other than the thread in which main() was first invoked returns from the start routine that was used to create it. The function's return value serves as the thread's exit status.

The behaviour of pthread_exit() is undefined if called from a cancellation cleanup handler or destructor function that was invoked as a result of either an implicit or explicit call to pthread_exit().

After a thread has terminated, the result of access to local (auto) variables of the thread is undefined. Thus, references to local variables of the exiting thread should not be used for the pthread_exit() value_ptr parameter value.

The process exits with an exit status of 0 after the last thread has been terminated. The behaviour is as if the implementation called exit() with a zero argument at thread termination time.

RETURN VALUE

ERRORS

The pthread_exit() function will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_getconcurrency(void); int pthread_setconcurrency(int new_level);

DESCRIPTION

The pthread_setconcurrency() function allows an application to inform the threads implementation of its desired concurrency level, new_level. The actual level of concurrency provided by the implementation as a result of this function call is unspecified.

If new_level is zero, it causes the implementation to maintain the concurrency level at its discretion as if pthread_setconcurrency() was never called.

The pthread_getconcurrency() function returns the value set by a previous call to the pthread_setconcurrency() function. If the pthread_setconcurrency() function was not previously called, this function returns zero to indicate that the implementation is maintaining the concurrency level.

When an application calls pthread_setconcurrency() it is informing the implementation of its desired concurrency level. The implementation uses this as a hint, not a requirement.

If an implementation does not support multiplexing of user threads on top of several kernel scheduled entities, the pthread_setconcurrency() and pthread_getconcurrency() functions will be provided for source code compatibility but they will have no effect when called. To maintain the function semantics, the new_level parameter will be saved when pthread_setconcurrency() is called so that a subsequent call to pthread_getconcurrency() returns the same value.

RETURN VALUE

The pthread_getconcurrency() function always returns the concurrency level set by a previous call to pthread_setconcurrency(). If the pthread_setconcurrency() function has never been called, pthread_getconcurrency() returns zero.

ERRORS

[EINVAL]

The value specified by new_level is negative.

[EAGAIN]

The value specific by new_level would cause a system resource to be exceeded.

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_getschedparam(pthread_t thread, int *policy, struct sched_param *param); int pthread_setschedparam(pthread_t thread, int policy, const struct sched_param *param);

DESCRIPTION

The pthread_getschedparam() function retrieves the scheduling policy and scheduling parameters for the thread whose thread ID is given by thread and stores those values in policy and param, respectively. The priority value returned from pthread_getschedparam() is the value specified by the most recent pthread_setschedparam() or pthread_create() call affecting the target thread, and reflects any temporary adjustments to its priority as a result of any priority inheritance or ceiling functions. The pthread_setschedparam() function sets the scheduling policy and associated scheduling parameters for the thread whose thread ID is given by thread to the policy and associated parameters provided in policy and param, respectively.

The policy parameter may have the value SCHED_OTHER, that has implementation-dependent scheduling parameters, SCHED_FIFO or SCHED_RR, that have the single scheduling parameter, priority.

If the pthread_setschedparam() function fails, no scheduling parameters will be changed for the target thread.

RETURN VALUE

ERRORS

[ENOSYS]

The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the implementation does not support the function.

The pthread_getschedparam() function may fail if:

[ESRCH]

The value specified by thread does not refer to a existing thread.

The pthread_setschedparam() function may fail if:

[EINVAL]

The value specified by policy or one of the scheduling parameters associated with the scheduling policy policy is invalid.

[ENOTSUP]

An attempt was made to set the policy or scheduling parameters to an unsupported value.

[EPERM]

The caller does not have the appropriate permission to set either the scheduling parameters or the scheduling policy of the specified thread.

[EPERM]

The implementation does not allow the application to modify one of the parameters to the value specified.

[ESRCH]

The value specified by thread does not refer to a existing thread.

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_setspecific(pthread_key_t key, const void *value); void *pthread_getspecific(pthread_key_t key);

DESCRIPTION

The pthread_getspecific() function returns the value currently bound to the specified key on behalf of the calling thread.

The effect of calling pthread_setspecific() or pthread_getspecific() with a key value not obtained from pthread_key_create() or after key has been deleted with pthread_key_delete() is undefined.

Both pthread_setspecific() and pthread_getspecific() may be called from a thread-specific data destructor function. However, calling pthread_setspecific() from a destructor may result in lost storage or infinite loops.

Both functions may be implemented as macros.

RETURN VALUE

If successful, the pthread_setspecific() function returns zero. Otherwise, an error number is returned to indicate the error.

ERRORS

[ENOMEM]

Insufficient memory exists to associate the value with the key.

The pthread_setspecific() function may fail if:

[EINVAL]

The key value is invalid.

No errors are returned from pthread_getspecific().

These functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_join(pthread_t thread, void **value_ptr);

DESCRIPTION

It is unspecified whether a thread that has exited but remains unjoined counts against _POSIX_THREAD_THREADS_MAX.

RETURN VALUE

ERRORS

[EINVAL]

The implementation has detected that the value specified by thread does not refer to a joinable thread.

[ESRCH]

No thread could be found corresponding to that specified by the given thread ID.

The pthread_join() function may fail if:

[EDEADLK]

A deadlock was detected or the value of thread specifies the calling thread.

The pthread_join() function will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_key_create(pthread_key_t *key, void (*destructor)(void*));

DESCRIPTION

Upon key creation, the value NULL is associated with the new key in all active threads. Upon thread creation, the value NULL is associated with all defined keys in the new thread.

An optional destructor function may be associated with each key value. At thread exit, if a key value has a non-NULL destructor pointer, and the thread has a non-NULL value associated with that key, the function pointed to is called with the current associated value as its sole argument. The order of destructor calls is unspecified if more than one destructor exists for a thread when it exits.

If, after all the destructors have been called for all non-NULL values with associated destructors, there are still some non-NULL values with associated destructors, then the process will be repeated. If, after at least PTHREAD_DESTRUCTOR_ITERATIONS iterations of destructor calls for outstanding non-NULL values, there are still some non-NULL values with associated destructors, implementations may stop calling destructors, or they may continue calling destructors until no non-NULL values with associated destructors exist, even though this might result in an infinite loop.

RETURN VALUE

ERRORS

[EAGAIN]

The system lacked the necessary resources to create another thread-specific data key, or the system-imposed limit on the total number of keys per process PTHREAD_KEYS_MAX has been exceeded.

[ENOMEM]

Insufficient memory exists to create the key.

The pthread_key_create() function will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_key_delete(pthread_key_t key);

DESCRIPTION

The pthread_key_delete() function is callable from within destructor functions. No destructor functions will be invoked by pthread_key_delete(). Any destructor function that may have been associated with key will no longer be called upon thread exit.

RETURN VALUE

ERRORS

[EINVAL]

The key value is invalid.

The pthread_key_delete() function will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_kill(pthread_t thread, int sig);

DESCRIPTION

As in kill(), if sig is zero, error checking is performed but no signal is actually sent.

RETURN VALUE

ERRORS

[ESRCH]

No thread could be found corresponding to that specified by the given thread ID.

[EINVAL]

The value of the sig argument is an invalid or unsupported signal number.

The pthread_kill() function will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_mutex_init(pthread_mutex_t *mutex, const pthread_mutexattr_t *attr); int pthread_mutex_destroy(pthread_mutex_t *mutex); pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER;

DESCRIPTION

Attempting to initialise an already initialised mutex results in undefined behaviour.

The pthread_mutex_destroy() function destroys the mutex object referenced by mutex; the mutex object becomes, in effect, uninitialised. An implementation may cause pthread_mutex_destroy() to set the object referenced by mutex to an invalid value. A destroyed mutex object can be re-initialised using pthread_mutex_init(); the results of otherwise referencing the object after it has been destroyed are undefined.

It is safe to destroy an initialised mutex that is unlocked. Attempting to destroy a locked mutex results in undefined behaviour.

In cases where default mutex attributes are appropriate, the macro PTHREAD_MUTEX_INITIALIZER can be used to initialise mutexes that are statically allocated. The effect is equivalent to dynamic initialisation by a call to pthread_mutex_init() with parameter attr specified as NULL, except that no error checks are performed.

RETURN VALUE

ERRORS

[EAGAIN]

The system lacked the necessary resources (other than memory) to initialise another mutex.

[ENOMEM]

Insufficient memory exists to initialise the mutex.

[EPERM]

The caller does not have the privilege to perform the operation.

The pthread_mutex_init() function may fail if:

[EBUSY]

The implementation has detected an attempt to re-initialise the object referenced by mutex, a previously initialised, but not yet destroyed, mutex.

[EINVAL]

The value specified by attr is invalid.

The pthread_mutex_destroy() function may fail if:

[EBUSY]

The implementation has detected an attempt to destroy the object referenced by mutex while it is locked or referenced (for example, while being used in a pthread_cond_wait() or pthread_cond_timedwait()) by another thread.

[EINVAL]

The value specified by mutex is invalid.

These functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_mutex_setprioceiling(pthread_mutex_t *mutex, int prioceiling, int *old_ceiling);

int pthread_mutex_getprioceiling(const pthread_mutex_t *mutex, int *prioceiling);

DESCRIPTION

The pthread_mutex_setprioceiling() function either locks the mutex if it is unlocked, or blocks until it can successfully lock the mutex, then it changes the mutex's priority ceiling and releases the mutex. When the change is successful, the previous value of the priority ceiling is returned in old_ceiling. The process of locking the mutex need not adhere to the priority protect protocol.

If the pthread_mutex_setprioceiling() function fails, the mutex priority ceiling is not changed.

RETURN VALUE

ERRORS

[ENOSYS]

The option _POSIX_THREAD_PRIO_PROTECT is not defined and the implementation does not support the function.

The pthread_mutex_setprioceiling() and pthread_mutex_getprioceiling() functions may fail if:

[EINVAL]

The priority requested by prioceiling is out of range.

[EINVAL]

The value specified by mutex does not refer to a currently existing mutex.

[ENOSYS]

The implementation does not support the priority ceiling protocol for mutexes.

[EPERM]

The caller does not have the privilege to perform the operation.

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_mutex_init(pthread_mutex_t *mutex, const pthread_mutexattr_t *attr); int pthread_mutex_destroy(pthread_mutex_t *mutex); pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER;

DESCRIPTION

Attempting to initialise an already initialised mutex results in undefined behaviour.

The pthread_mutex_destroy() function destroys the mutex object referenced by mutex; the mutex object becomes, in effect, uninitialised. An implementation may cause pthread_mutex_destroy() to set the object referenced by mutex to an invalid value. A destroyed mutex object can be re-initialised using pthread_mutex_init(); the results of otherwise referencing the object after it has been destroyed are undefined.

It is safe to destroy an initialised mutex that is unlocked. Attempting to destroy a locked mutex results in undefined behaviour.

In cases where default mutex attributes are appropriate, the macro PTHREAD_MUTEX_INITIALIZER can be used to initialise mutexes that are statically allocated. The effect is equivalent to dynamic initialisation by a call to pthread_mutex_init() with parameter attr specified as NULL, except that no error checks are performed.

RETURN VALUE

ERRORS

[EAGAIN]

The system lacked the necessary resources (other than memory) to initialise another mutex.

[ENOMEM]

Insufficient memory exists to initialise the mutex.

[EPERM]

The caller does not have the privilege to perform the operation.

The pthread_mutex_init() function may fail if:

[EBUSY]

The implementation has detected an attempt to re-initialise the object referenced by mutex, a previously initialised, but not yet destroyed, mutex.

[EINVAL]

The value specified by attr is invalid.

The pthread_mutex_destroy() function may fail if:

[EBUSY]

The implementation has detected an attempt to destroy the object referenced by mutex while it is locked or referenced (for example, while being used in a pthread_cond_wait() or pthread_cond_timedwait()) by another thread.

[EINVAL]

The value specified by mutex is invalid.

These functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_mutex_lock(pthread_mutex_t *mutex); int pthread_mutex_trylock(pthread_mutex_t *mutex); int pthread_mutex_unlock(pthread_mutex_t *mutex);

DESCRIPTION

If the mutex type is PTHREAD_MUTEX_NORMAL, deadlock detection is not provided. Attempting to relock the mutex causes deadlock. If a thread attempts to unlock a mutex that it has not locked or a mutex which is unlocked, undefined behaviour results.

If the mutex type is PTHREAD_MUTEX_ERRORCHECK, then error checking is provided. If a thread attempts to relock a mutex that it has already locked, an error will be returned. If a thread attempts to unlock a mutex that it has not locked or a mutex which is unlocked, an error will be returned.

If the mutex type is PTHREAD_MUTEX_RECURSIVE, then the mutex maintains the concept of a lock count. When a thread successfully acquires a mutex for the first time, the lock count is set to one. Every time a thread relocks this mutex, the lock count is incremented by one. Each time the thread unlocks the mutex, the lock count is decremented by one. When the lock count reaches zero, the mutex becomes available for other threads to acquire. If a thread attempts to unlock a mutex that it has not locked or a mutex which is unlocked, an error will be returned.

If the mutex type is PTHREAD_MUTEX_DEFAULT, attempting to recursively lock the mutex results in undefined behaviour. Attempting to unlock the mutex if it was not locked by the calling thread results in undefined behaviour. Attempting to unlock the mutex if it is not locked results in undefined behaviour.

The function pthread_mutex_trylock() is identical to pthread_mutex_lock() except that if the mutex object referenced by mutex is currently locked (by any thread, including the current thread), the call returns immediately.

The pthread_mutex_unlock() function releases the mutex object referenced by mutex. The manner in which a mutex is released is dependent upon the mutex's type attribute. If there are threads blocked on the mutex object referenced by mutex when pthread_mutex_unlock() is called, resulting in the mutex becoming available, the scheduling policy is used to determine which thread shall acquire the mutex. (In the case of PTHREAD_MUTEX_RECURSIVE mutexes, the mutex becomes available when the count reaches zero and the calling thread no longer has any locks on this mutex).

If a signal is delivered to a thread waiting for a mutex, upon return from the signal handler the thread resumes waiting for the mutex as if it was not interrupted.

RETURN VALUE

The function pthread_mutex_trylock() returns zero if a lock on the mutex object referenced by mutex is acquired. Otherwise, an error number is returned to indicate the error.

ERRORS

[EINVAL]

The mutex was created with the protocol attribute having the value PTHREAD_PRIO_PROTECT and the calling thread's priority is higher than the mutex's current priority ceiling.

The pthread_mutex_trylock() function will fail if:

[EBUSY]

The mutex could not be acquired because it was already locked.

The pthread_mutex_lock(), pthread_mutex_trylock() and pthread_mutex_unlock() functions may fail if:

[EINVAL]

The value specified by mutex does not refer to an initialised mutex object.

[EAGAIN]

The mutex could not be acquired because the maximum number of recursive locks for mutex has been exceeded.

The pthread_mutex_lock() function may fail if:

[EDEADLK]

The current thread already owns the mutex.

The pthread_mutex_unlock() function may fail if:

[EPERM]

The current thread does not own the mutex.

These functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_mutex_setprioceiling(pthread_mutex_t *mutex, int prioceiling, int *old_ceiling);

int pthread_mutex_getprioceiling(const pthread_mutex_t *mutex, int *prioceiling);

DESCRIPTION

The pthread_mutex_setprioceiling() function either locks the mutex if it is unlocked, or blocks until it can successfully lock the mutex, then it changes the mutex's priority ceiling and releases the mutex. When the change is successful, the previous value of the priority ceiling is returned in old_ceiling. The process of locking the mutex need not adhere to the priority protect protocol.

If the pthread_mutex_setprioceiling() function fails, the mutex priority ceiling is not changed.

RETURN VALUE

ERRORS

[ENOSYS]

The option _POSIX_THREAD_PRIO_PROTECT is not defined and the implementation does not support the function.

The pthread_mutex_setprioceiling() and pthread_mutex_getprioceiling() functions may fail if:

[EINVAL]

The priority requested by prioceiling is out of range.

[EINVAL]

The value specified by mutex does not refer to a currently existing mutex.

[ENOSYS]

The implementation does not support the priority ceiling protocol for mutexes.

[EPERM]

The caller does not have the privilege to perform the operation.

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_mutex_lock(pthread_mutex_t *mutex); int pthread_mutex_trylock(pthread_mutex_t *mutex); int pthread_mutex_unlock(pthread_mutex_t *mutex);

DESCRIPTION

If the mutex type is PTHREAD_MUTEX_NORMAL, deadlock detection is not provided. Attempting to relock the mutex causes deadlock. If a thread attempts to unlock a mutex that it has not locked or a mutex which is unlocked, undefined behaviour results.

If the mutex type is PTHREAD_MUTEX_ERRORCHECK, then error checking is provided. If a thread attempts to relock a mutex that it has already locked, an error will be returned. If a thread attempts to unlock a mutex that it has not locked or a mutex which is unlocked, an error will be returned.

If the mutex type is PTHREAD_MUTEX_RECURSIVE, then the mutex maintains the concept of a lock count. When a thread successfully acquires a mutex for the first time, the lock count is set to one. Every time a thread relocks this mutex, the lock count is incremented by one. Each time the thread unlocks the mutex, the lock count is decremented by one. When the lock count reaches zero, the mutex becomes available for other threads to acquire. If a thread attempts to unlock a mutex that it has not locked or a mutex which is unlocked, an error will be returned.

If the mutex type is PTHREAD_MUTEX_DEFAULT, attempting to recursively lock the mutex results in undefined behaviour. Attempting to unlock the mutex if it was not locked by the calling thread results in undefined behaviour. Attempting to unlock the mutex if it is not locked results in undefined behaviour.

The function pthread_mutex_trylock() is identical to pthread_mutex_lock() except that if the mutex object referenced by mutex is currently locked (by any thread, including the current thread), the call returns immediately.

The pthread_mutex_unlock() function releases the mutex object referenced by mutex. The manner in which a mutex is released is dependent upon the mutex's type attribute. If there are threads blocked on the mutex object referenced by mutex when pthread_mutex_unlock() is called, resulting in the mutex becoming available, the scheduling policy is used to determine which thread shall acquire the mutex. (In the case of PTHREAD_MUTEX_RECURSIVE mutexes, the mutex becomes available when the count reaches zero and the calling thread no longer has any locks on this mutex).

If a signal is delivered to a thread waiting for a mutex, upon return from the signal handler the thread resumes waiting for the mutex as if it was not interrupted.

RETURN VALUE

The function pthread_mutex_trylock() returns zero if a lock on the mutex object referenced by mutex is acquired. Otherwise, an error number is returned to indicate the error.

ERRORS

[EINVAL]

The mutex was created with the protocol attribute having the value PTHREAD_PRIO_PROTECT and the calling thread's priority is higher than the mutex's current priority ceiling.

The pthread_mutex_trylock() function will fail if:

[EBUSY]

The mutex could not be acquired because it was already locked.

The pthread_mutex_lock(), pthread_mutex_trylock() and pthread_mutex_unlock() functions may fail if:

[EINVAL]

The value specified by mutex does not refer to an initialised mutex object.

[EAGAIN]

The mutex could not be acquired because the maximum number of recursive locks for mutex has been exceeded.

The pthread_mutex_lock() function may fail if:

[EDEADLK]

The current thread already owns the mutex.

The pthread_mutex_unlock() function may fail if:

[EPERM]

The current thread does not own the mutex.

These functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_mutex_lock(pthread_mutex_t *mutex); int pthread_mutex_trylock(pthread_mutex_t *mutex); int pthread_mutex_unlock(pthread_mutex_t *mutex);

DESCRIPTION

If the mutex type is PTHREAD_MUTEX_NORMAL, deadlock detection is not provided. Attempting to relock the mutex causes deadlock. If a thread attempts to unlock a mutex that it has not locked or a mutex which is unlocked, undefined behaviour results.

If the mutex type is PTHREAD_MUTEX_ERRORCHECK, then error checking is provided. If a thread attempts to relock a mutex that it has already locked, an error will be returned. If a thread attempts to unlock a mutex that it has not locked or a mutex which is unlocked, an error will be returned.

If the mutex type is PTHREAD_MUTEX_RECURSIVE, then the mutex maintains the concept of a lock count. When a thread successfully acquires a mutex for the first time, the lock count is set to one. Every time a thread relocks this mutex, the lock count is incremented by one. Each time the thread unlocks the mutex, the lock count is decremented by one. When the lock count reaches zero, the mutex becomes available for other threads to acquire. If a thread attempts to unlock a mutex that it has not locked or a mutex which is unlocked, an error will be returned.

If the mutex type is PTHREAD_MUTEX_DEFAULT, attempting to recursively lock the mutex results in undefined behaviour. Attempting to unlock the mutex if it was not locked by the calling thread results in undefined behaviour. Attempting to unlock the mutex if it is not locked results in undefined behaviour.

The function pthread_mutex_trylock() is identical to pthread_mutex_lock() except that if the mutex object referenced by mutex is currently locked (by any thread, including the current thread), the call returns immediately.

The pthread_mutex_unlock() function releases the mutex object referenced by mutex. The manner in which a mutex is released is dependent upon the mutex's type attribute. If there are threads blocked on the mutex object referenced by mutex when pthread_mutex_unlock() is called, resulting in the mutex becoming available, the scheduling policy is used to determine which thread shall acquire the mutex. (In the case of PTHREAD_MUTEX_RECURSIVE mutexes, the mutex becomes available when the count reaches zero and the calling thread no longer has any locks on this mutex).

If a signal is delivered to a thread waiting for a mutex, upon return from the signal handler the thread resumes waiting for the mutex as if it was not interrupted.

RETURN VALUE

The function pthread_mutex_trylock() returns zero if a lock on the mutex object referenced by mutex is acquired. Otherwise, an error number is returned to indicate the error.

ERRORS

[EINVAL]

The mutex was created with the protocol attribute having the value PTHREAD_PRIO_PROTECT and the calling thread's priority is higher than the mutex's current priority ceiling.

The pthread_mutex_trylock() function will fail if:

[EBUSY]

The mutex could not be acquired because it was already locked.

The pthread_mutex_lock(), pthread_mutex_trylock() and pthread_mutex_unlock() functions may fail if:

[EINVAL]

The value specified by mutex does not refer to an initialised mutex object.

[EAGAIN]

The mutex could not be acquired because the maximum number of recursive locks for mutex has been exceeded.

The pthread_mutex_lock() function may fail if:

[EDEADLK]

The current thread already owns the mutex.

The pthread_mutex_unlock() function may fail if:

[EPERM]

The current thread does not own the mutex.

These functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_mutexattr_init(pthread_mutexattr_t *attr); int pthread_mutexattr_destroy(pthread_mutexattr_t *attr);

DESCRIPTION

The effect of initialising an already initialised mutex attributes object is undefined.

After a mutex attributes object has been used to initialise one or more mutexes, any function affecting the attributes object (including destruction) does not affect any previously initialised mutexes.

The pthread_mutexattr_destroy() function destroys a mutex attributes object; the object becomes, in effect, uninitialised. An implementation may cause pthread_mutexattr_destroy() to set the object referenced by attr to an invalid value. A destroyed mutex attributes object can be re-initialised using pthread_mutexattr_init(); the results of otherwise referencing the object after it has been destroyed are undefined.

RETURN VALUE

ERRORS

[ENOMEM]

Insufficient memory exists to initialise the mutex attributes object.

The pthread_mutexattr_destroy() function may fail if:

[EINVAL]

The value specified by attr is invalid.

These functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *attr, int prioceiling); int pthread_mutexattr_getprioceiling(const pthread_mutexattr_t *attr, int *prioceiling);

DESCRIPTION

The prioceiling attribute contains the priority ceiling of initialised mutexes. The values of prioceiling will be within the maximum range of priorities defined by SCHED_FIFO.

The prioceiling attribute defines the priority ceiling of initialised mutexes, which is the minimum priority level at which the critical section guarded by the mutex is executed. In order to avoid priority inversion, the priority ceiling of the mutex will be set to a priority higher than or equal to the highest priority of all the threads that may lock that mutex. The values of prioceiling will be within the maximum range of priorities defined under the SCHED_FIFO scheduling policy.

RETURN VALUE

ERRORS

[ENOSYS]

The option _POSIX_THREAD_PRIO_PROTECT is not defined and the implementation does not support the function.

The pthread_mutexattr_setprioceiling() and pthread_mutexattr_getprioceiling() functions may fail if:

[EINVAL]

The value specified by attr or prioceiling is invalid.

[EPERM]

The caller does not have the privilege to perform the operation.

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_mutexattr_setprotocol(pthread_mutexattr_t *attr, int protocol); int pthread_mutexattr_getprotocol(const pthread_mutexattr_t *attr, int *protocol);

DESCRIPTION

The protocol attribute defines the protocol to be followed in utilising mutexes. The value of protocol may be one of PTHREAD_PRIO_NONE, PTHREAD_PRIO_INHERIT or PTHREAD_PRIO_PROTECT, which are defined by the header <pthread.h>.

When a thread owns a mutex with the PTHREAD_PRIO_NONE protocol attribute, its priority and scheduling are not affected by its mutex ownership.

When a thread is blocking higher priority threads because of owning one or more mutexes with the PTHREAD_PRIO_INHERIT protocol attribute, it executes at the higher of its priority or the priority of the highest priority thread waiting on any of the mutexes owned by this thread and initialised with this protocol.

When a thread owns one or more mutexes initialised with the PTHREAD_PRIO_PROTECT protocol, it executes at the higher of its priority or the highest of the priority ceilings of all the mutexes owned by this thread and initialised with this attribute, regardless of whether other threads are blocked on any of these mutexes or not.

While a thread is holding a mutex which has been initialised with the PRIO_INHERIT or PRIO_PROTECT protocol attributes, it will not be subject to being moved to the tail of the scheduling queue at its priority in the event that its original priority is changed, such as by a call to sched_setparam(). Likewise, when a thread unlocks a mutex that has been initialised with the PRIO_INHERIT or PRIO_PROTECT protocol attributes, it will not be subject to being moved to the tail of the scheduling queue at its priority in the event that its original priority is changed.

If a thread simultaneously owns several mutexes initialised with different protocols, it will execute at the highest of the priorities that it would have obtained by each of these protocols.

When a thread makes a call to pthread_mutex_lock(), if the symbol _POSIX_THREAD_PRIO_INHERIT is defined and the mutex was initialised with the protocol attribute having the value PTHREAD_PRIO_INHERIT, when the calling thread is blocked because the mutex is owned by another thread, that owner thread will inherit the priority level of the calling thread as long as it continues to own the mutex. The implementation updates its execution priority to the maximum of its assigned priority and all its inherited priorities. Furthermore, if this owner thread itself becomes blocked on another mutex, the same priority inheritance effect will be propagated to this other owner thread, in a recursive manner.

RETURN VALUE

ERRORS

[ENOSYS]

Neither one of the options _POSIX_THREAD_PRIO_PROTECT and _POSIX_THREAD_PRIO_INHERIT is defined and the implementation does not support the function.

[ENOTSUP]

The value specified by protocol is an unsupported value.

The pthread_mutexattr_setprotocol() and pthread_mutexattr_getprotocol() functions may fail if:

[EINVAL]

The value specified by attr ro protocol is invalid.

[EPERM]

The caller does not have the privilege to perform the operation.

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_mutexattr_getpshared(const pthread_mutexattr_t *attr, int *pshared); int pthread_mutexattr_setpshared(pthread_mutexattr_t *attr, int pshared);

DESCRIPTION

The process-shared attribute is set to PTHREAD_PROCESS_SHARED to permit a mutex to be operated upon by any thread that has access to the memory where the mutex is allocated, even if the mutex is allocated in memory that is shared by multiple processes. If the process-shared attribute is PTHREAD_PROCESS_PRIVATE, the mutex will only be operated upon by threads created within the same process as the thread that initialised the mutex; if threads of differing processes attempt to operate on such a mutex, the behaviour is undefined. The default value of the attribute is PTHREAD_PROCESS_PRIVATE.

RETURN VALUE

Upon successful completion, pthread_mutexattr_getpshared() returns zero and stores the value of the process-shared attribute of attr into the object referenced by the pshared parameter. Otherwise, an error number is returned to indicate the error.

ERRORS

[EINVAL]

The value specified by attr is invalid.

The pthread_mutexattr_setpshared() function may fail if:

[EINVAL]

The new value specified for the attribute is outside the range of legal values for that attribute.

These functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_mutexattr_gettype(const pthread_mutexattr_t *attr, int *type); int pthread_mutexattr_settype(pthread_mutexattr_t *attr, int type);

DESCRIPTION

The type of mutex is contained in the type attribute of the mutex attributes. Valid mutex types include:

PTHREAD_MUTEX_NORMAL

This type of mutex does not detect deadlock. A thread attempting to relock this mutex without first unlocking it will deadlock. Attempting to unlock a mutex locked by a different thread results in undefined behaviour. Attempting to unlock an unlocked mutex results in undefined behaviour.

PTHREAD_MUTEX_ERRORCHECK

This type of mutex provides error checking. A thread attempting to relock this mutex without first unlocking it will return with an error. A thread attempting to unlock a mutex which another thread has locked will return with an error. A thread attempting to unlock an unlocked mutex will return with an error.

PTHREAD_MUTEX_RECURSIVE

A thread attempting to relock this mutex without first unlocking it will succeed in locking the mutex. The relocking deadlock which can occur with mutexes of type PTHREAD_MUTEX_NORMAL cannot occur with this type of mutex. Multiple locks of this mutex require the same number of unlocks to release the mutex before another thread can acquire the mutex. A thread attempting to unlock a mutex which another thread has locked will return with an error. A thread attempting to unlock an unlocked mutex will return with an error.

PTHREAD_MUTEX_DEFAULT

Attempting to recursively lock a mutex of this type results in undefined behaviour. Attempting to unlock a mutex of this type which was not locked by the calling thread results in undefined behaviour. Attempting to unlock a mutex of this type which is not locked results in undefined behaviour. An implementation is allowed to map this mutex to one of the other mutex types.

RETURN VALUE

Upon successful completion, the pthread_mutexattr_gettype() function returns zero and stores the value of the type attribute of attr into the object referenced by the type parameter. Otherwise an error is returned to indicate the error.

ERRORS

[EINVAL]

The value type is invalid.

The pthread_mutexattr_gettype() and pthread_mutexattr_settype() functions may fail if:

[EINVAL]

The value specified by attr is invalid.

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_mutexattr_init(pthread_mutexattr_t *attr); int pthread_mutexattr_destroy(pthread_mutexattr_t *attr);

DESCRIPTION

The effect of initialising an already initialised mutex attributes object is undefined.

After a mutex attributes object has been used to initialise one or more mutexes, any function affecting the attributes object (including destruction) does not affect any previously initialised mutexes.

The pthread_mutexattr_destroy() function destroys a mutex attributes object; the object becomes, in effect, uninitialised. An implementation may cause pthread_mutexattr_destroy() to set the object referenced by attr to an invalid value. A destroyed mutex attributes object can be re-initialised using pthread_mutexattr_init(); the results of otherwise referencing the object after it has been destroyed are undefined.

RETURN VALUE

ERRORS

[ENOMEM]

Insufficient memory exists to initialise the mutex attributes object.

The pthread_mutexattr_destroy() function may fail if:

[EINVAL]

The value specified by attr is invalid.

These functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *attr, int prioceiling); int pthread_mutexattr_getprioceiling(const pthread_mutexattr_t *attr, int *prioceiling);

DESCRIPTION

The prioceiling attribute contains the priority ceiling of initialised mutexes. The values of prioceiling will be within the maximum range of priorities defined by SCHED_FIFO.

The prioceiling attribute defines the priority ceiling of initialised mutexes, which is the minimum priority level at which the critical section guarded by the mutex is executed. In order to avoid priority inversion, the priority ceiling of the mutex will be set to a priority higher than or equal to the highest priority of all the threads that may lock that mutex. The values of prioceiling will be within the maximum range of priorities defined under the SCHED_FIFO scheduling policy.

RETURN VALUE

ERRORS

[ENOSYS]

The option _POSIX_THREAD_PRIO_PROTECT is not defined and the implementation does not support the function.

The pthread_mutexattr_setprioceiling() and pthread_mutexattr_getprioceiling() functions may fail if:

[EINVAL]

The value specified by attr or prioceiling is invalid.

[EPERM]

The caller does not have the privilege to perform the operation.

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_mutexattr_setprotocol(pthread_mutexattr_t *attr, int protocol); int pthread_mutexattr_getprotocol(const pthread_mutexattr_t *attr, int *protocol);

DESCRIPTION

The protocol attribute defines the protocol to be followed in utilising mutexes. The value of protocol may be one of PTHREAD_PRIO_NONE, PTHREAD_PRIO_INHERIT or PTHREAD_PRIO_PROTECT, which are defined by the header <pthread.h>.

When a thread owns a mutex with the PTHREAD_PRIO_NONE protocol attribute, its priority and scheduling are not affected by its mutex ownership.

When a thread is blocking higher priority threads because of owning one or more mutexes with the PTHREAD_PRIO_INHERIT protocol attribute, it executes at the higher of its priority or the priority of the highest priority thread waiting on any of the mutexes owned by this thread and initialised with this protocol.

When a thread owns one or more mutexes initialised with the PTHREAD_PRIO_PROTECT protocol, it executes at the higher of its priority or the highest of the priority ceilings of all the mutexes owned by this thread and initialised with this attribute, regardless of whether other threads are blocked on any of these mutexes or not.

While a thread is holding a mutex which has been initialised with the PRIO_INHERIT or PRIO_PROTECT protocol attributes, it will not be subject to being moved to the tail of the scheduling queue at its priority in the event that its original priority is changed, such as by a call to sched_setparam(). Likewise, when a thread unlocks a mutex that has been initialised with the PRIO_INHERIT or PRIO_PROTECT protocol attributes, it will not be subject to being moved to the tail of the scheduling queue at its priority in the event that its original priority is changed.

If a thread simultaneously owns several mutexes initialised with different protocols, it will execute at the highest of the priorities that it would have obtained by each of these protocols.

When a thread makes a call to pthread_mutex_lock(), if the symbol _POSIX_THREAD_PRIO_INHERIT is defined and the mutex was initialised with the protocol attribute having the value PTHREAD_PRIO_INHERIT, when the calling thread is blocked because the mutex is owned by another thread, that owner thread will inherit the priority level of the calling thread as long as it continues to own the mutex. The implementation updates its execution priority to the maximum of its assigned priority and all its inherited priorities. Furthermore, if this owner thread itself becomes blocked on another mutex, the same priority inheritance effect will be propagated to this other owner thread, in a recursive manner.

RETURN VALUE

ERRORS

[ENOSYS]

Neither one of the options _POSIX_THREAD_PRIO_PROTECT and _POSIX_THREAD_PRIO_INHERIT is defined and the implementation does not support the function.

[ENOTSUP]

The value specified by protocol is an unsupported value.

The pthread_mutexattr_setprotocol() and pthread_mutexattr_getprotocol() functions may fail if:

[EINVAL]

The value specified by attr ro protocol is invalid.

[EPERM]

The caller does not have the privilege to perform the operation.

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_mutexattr_getpshared(const pthread_mutexattr_t *attr, int *pshared); int pthread_mutexattr_setpshared(pthread_mutexattr_t *attr, int pshared);

DESCRIPTION

The process-shared attribute is set to PTHREAD_PROCESS_SHARED to permit a mutex to be operated upon by any thread that has access to the memory where the mutex is allocated, even if the mutex is allocated in memory that is shared by multiple processes. If the process-shared attribute is PTHREAD_PROCESS_PRIVATE, the mutex will only be operated upon by threads created within the same process as the thread that initialised the mutex; if threads of differing processes attempt to operate on such a mutex, the behaviour is undefined. The default value of the attribute is PTHREAD_PROCESS_PRIVATE.

RETURN VALUE

Upon successful completion, pthread_mutexattr_getpshared() returns zero and stores the value of the process-shared attribute of attr into the object referenced by the pshared parameter. Otherwise, an error number is returned to indicate the error.

ERRORS

[EINVAL]

The value specified by attr is invalid.

The pthread_mutexattr_setpshared() function may fail if:

[EINVAL]

The new value specified for the attribute is outside the range of legal values for that attribute.

These functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_mutexattr_gettype(const pthread_mutexattr_t *attr, int *type); int pthread_mutexattr_settype(pthread_mutexattr_t *attr, int type);

DESCRIPTION

The type of mutex is contained in the type attribute of the mutex attributes. Valid mutex types include:

PTHREAD_MUTEX_NORMAL

This type of mutex does not detect deadlock. A thread attempting to relock this mutex without first unlocking it will deadlock. Attempting to unlock a mutex locked by a different thread results in undefined behaviour. Attempting to unlock an unlocked mutex results in undefined behaviour.

PTHREAD_MUTEX_ERRORCHECK

This type of mutex provides error checking. A thread attempting to relock this mutex without first unlocking it will return with an error. A thread attempting to unlock a mutex which another thread has locked will return with an error. A thread attempting to unlock an unlocked mutex will return with an error.

PTHREAD_MUTEX_RECURSIVE

A thread attempting to relock this mutex without first unlocking it will succeed in locking the mutex. The relocking deadlock which can occur with mutexes of type PTHREAD_MUTEX_NORMAL cannot occur with this type of mutex. Multiple locks of this mutex require the same number of unlocks to release the mutex before another thread can acquire the mutex. A thread attempting to unlock a mutex which another thread has locked will return with an error. A thread attempting to unlock an unlocked mutex will return with an error.

PTHREAD_MUTEX_DEFAULT

Attempting to recursively lock a mutex of this type results in undefined behaviour. Attempting to unlock a mutex of this type which was not locked by the calling thread results in undefined behaviour. Attempting to unlock a mutex of this type which is not locked results in undefined behaviour. An implementation is allowed to map this mutex to one of the other mutex types.

RETURN VALUE

Upon successful completion, the pthread_mutexattr_gettype() function returns zero and stores the value of the type attribute of attr into the object referenced by the type parameter. Otherwise an error is returned to indicate the error.

ERRORS

[EINVAL]

The value type is invalid.

The pthread_mutexattr_gettype() and pthread_mutexattr_settype() functions may fail if:

[EINVAL]

The value specified by attr is invalid.

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_once(pthread_once_t *once_control, void (*init_routine)(void)); pthread_once_t once_control = PTHREAD_ONCE_INIT;

DESCRIPTION

The function pthread_once() is not a cancellation point. However, if init_routine() is a cancellation point and is canceled, the effect on once_control is as if pthread_once() was never called.

The constant PTHREAD_ONCE_INIT is defined by the header <pthread.h>.

The behaviour of pthread_once() is undefined if once_control has automatic storage duration or is not initialised by PTHREAD_ONCE_INIT.

RETURN VALUE

ERRORS

The pthread_once() function will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_rwlock_init(pthread_rwlock_t *rwlock, const pthread_rwlockattr_t *attr); int pthread_rwlock_destroy(pthread_rwlock_t *rwlock); pthread_rwlock_t rwlock=PTHREAD_RWLOCK_INITIALIZER;

DESCRIPTION

If the pthread_rwlock_init() function fails, rwlock is not initialised and the contents of rwlock are undefined.

The pthread_rwlock_destroy() function destroys the read-write lock object referenced by rwlock and releases any resources used by the lock. The effect of subsequent use of the lock is undefined until the lock is re-initialised by another call to pthread_rwlock_init(). An implementation may cause pthread_rwlock_destroy() to set the object referenced by rwlock to an invalid value. Results are undefined if pthread_rwlock_destroy() is called when any thread holds rwlock. Attempting to destroy an uninitialised read-write lock results in undefined behaviour. A destroyed read-write lock object can be re-initialised using pthread_rwlock_init(); the results of otherwise referencing the read-write lock object after it has been destroyed are undefined.

In cases where default read-write lock attributes are appropriate, the macro PTHREAD_RWLOCK_INITIALIZER can be used to initialise read-write locks that are statically allocated. The effect is equivalent to dynamic initialisation by a call to pthread_rwlock_init() with the parameter attr specified as NULL, except that no error checks are performed.

RETURN VALUE

ERRORS

[EAGAIN]

The system lacked the necessary resources (other than memory) to initialise another read-write lock.

[ENOMEM]

Insufficient memory exists to initialise the read-write lock.

[EPERM]

The caller does not have the privilege to perform the operation.

The pthread_rwlock_init() function may fail if:

[EBUSY]

The implementation has detected an attempt to re-initialise the object referenced by rwlock, a previously initialised but not yet destroyed read-write lock.

[EINVAL]

The value specified by attr is invalid.

The pthread_rwlock_destroy() function may fail if:

[EBUSY]

The implementation has detected an attempt to destroy the object referenced by rwlock while it is locked.

[EINVAL]

The value specified by attr is invalid.

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_rwlock_init(pthread_rwlock_t *rwlock, const pthread_rwlockattr_t *attr); int pthread_rwlock_destroy(pthread_rwlock_t *rwlock); pthread_rwlock_t rwlock=PTHREAD_RWLOCK_INITIALIZER;

DESCRIPTION

If the pthread_rwlock_init() function fails, rwlock is not initialised and the contents of rwlock are undefined.

The pthread_rwlock_destroy() function destroys the read-write lock object referenced by rwlock and releases any resources used by the lock. The effect of subsequent use of the lock is undefined until the lock is re-initialised by another call to pthread_rwlock_init(). An implementation may cause pthread_rwlock_destroy() to set the object referenced by rwlock to an invalid value. Results are undefined if pthread_rwlock_destroy() is called when any thread holds rwlock. Attempting to destroy an uninitialised read-write lock results in undefined behaviour. A destroyed read-write lock object can be re-initialised using pthread_rwlock_init(); the results of otherwise referencing the read-write lock object after it has been destroyed are undefined.

In cases where default read-write lock attributes are appropriate, the macro PTHREAD_RWLOCK_INITIALIZER can be used to initialise read-write locks that are statically allocated. The effect is equivalent to dynamic initialisation by a call to pthread_rwlock_init() with the parameter attr specified as NULL, except that no error checks are performed.

RETURN VALUE

ERRORS

[EAGAIN]

The system lacked the necessary resources (other than memory) to initialise another read-write lock.

[ENOMEM]

Insufficient memory exists to initialise the read-write lock.

[EPERM]

The caller does not have the privilege to perform the operation.

The pthread_rwlock_init() function may fail if:

[EBUSY]

The implementation has detected an attempt to re-initialise the object referenced by rwlock, a previously initialised but not yet destroyed read-write lock.

[EINVAL]

The value specified by attr is invalid.

The pthread_rwlock_destroy() function may fail if:

[EBUSY]

The implementation has detected an attempt to destroy the object referenced by rwlock while it is locked.

[EINVAL]

The value specified by attr is invalid.

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_rwlock_rdlock(pthread_rwlock_t *rwlock); int pthread_rwlock_tryrdlock(pthread_rwlock_t *rwlock);

DESCRIPTION

Implementations are allowed to favour writers over readers to avoid writer starvation.

A thread may hold multiple concurrent read locks on rwlock (that is, successfully call the pthread_rwlock_rdlock() function n times). If so, the thread must perform matching unlocks (that is, it must call the pthread_rwlock_unlock() function n times).

The function pthread_rwlock_tryrdlock() applies a read lock as in the pthread_rwlock_rdlock() function with the exception that the function fails if any thread holds a write lock on rwlock or there are writers blocked on rwlock.

Results are undefined if any of these functions are called with an uninitialised read-write lock.

If a signal is delivered to a thread waiting for a read-write lock for reading, upon return from the signal handler the thread resumes waiting for the read-write lock for reading as if it was not interrupted.

RETURN VALUE

The function pthread_rwlock_tryrdlock() returns zero if the lock for reading on the read-write lock object referenced by rwlock is acquired. Otherwise an error number is returned to indicate the error.

ERRORS

[EBUSY]

The read-write lock could not be acquired for reading because a writer holds the lock or was blocked on it.

The pthread_rwlock_rdlock() and pthread_rwlock_tryrdlock() functions may fail if:

[EINVAL]

The value specified by rwlock does not refer to an initialised read-write lock object.

[EDEADLK]

The current thread already owns the read-write lock for writing.

[EAGAIN]

The read lock could not be acquired because the maximum number of read locks for rwlock has been exceeded.

EXAMPLES

APPLICATION USAGE

Realtime applications may encounter priority inversion when using read-write locks. The problem occurs when a high priority thread &quot;locks&quot; a read-write lock that is about to be &quot;unlocked&quot; by a low priority thread, but the low priority thread is preempted by a medium priority thread. This scenario leads to priority inversion; a high priority thread is blocked by lower priority threads for an unlimited period of time. During system design, realtime programmers must take into account the possibility of this kind of priority inversion. They can deal with it in a number of ways, such as by having critical sections that are guarded by read-write locks execute at a high priority, so that a thread cannot be preempted while executing in its critical section.

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_rwlock_rdlock(pthread_rwlock_t *rwlock); int pthread_rwlock_tryrdlock(pthread_rwlock_t *rwlock);

DESCRIPTION

Implementations are allowed to favour writers over readers to avoid writer starvation.

A thread may hold multiple concurrent read locks on rwlock (that is, successfully call the pthread_rwlock_rdlock() function n times). If so, the thread must perform matching unlocks (that is, it must call the pthread_rwlock_unlock() function n times).

The function pthread_rwlock_tryrdlock() applies a read lock as in the pthread_rwlock_rdlock() function with the exception that the function fails if any thread holds a write lock on rwlock or there are writers blocked on rwlock.

Results are undefined if any of these functions are called with an uninitialised read-write lock.

If a signal is delivered to a thread waiting for a read-write lock for reading, upon return from the signal handler the thread resumes waiting for the read-write lock for reading as if it was not interrupted.

RETURN VALUE

The function pthread_rwlock_tryrdlock() returns zero if the lock for reading on the read-write lock object referenced by rwlock is acquired. Otherwise an error number is returned to indicate the error.

ERRORS

[EBUSY]

The read-write lock could not be acquired for reading because a writer holds the lock or was blocked on it.

The pthread_rwlock_rdlock() and pthread_rwlock_tryrdlock() functions may fail if:

[EINVAL]

The value specified by rwlock does not refer to an initialised read-write lock object.

[EDEADLK]

The current thread already owns the read-write lock for writing.

[EAGAIN]

The read lock could not be acquired because the maximum number of read locks for rwlock has been exceeded.

EXAMPLES

APPLICATION USAGE

Realtime applications may encounter priority inversion when using read-write locks. The problem occurs when a high priority thread &quot;locks&quot; a read-write lock that is about to be &quot;unlocked&quot; by a low priority thread, but the low priority thread is preempted by a medium priority thread. This scenario leads to priority inversion; a high priority thread is blocked by lower priority threads for an unlimited period of time. During system design, realtime programmers must take into account the possibility of this kind of priority inversion. They can deal with it in a number of ways, such as by having critical sections that are guarded by read-write locks execute at a high priority, so that a thread cannot be preempted while executing in its critical section.

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_rwlock_wrlock(pthread_rwlock_t *rwlock); int pthread_rwlock_trywrlock(pthread_rwlock_t *rwlock);

DESCRIPTION

Implementations are allowed to favour writers over readers to avoid writer starvation.

The function pthread_rwlock_trywrlock() applies a write lock like the pthread_rwlock_wrlock() function, with the exception that the function fails if any thread currently holds rwlock (for reading or writing).

Results are undefined if any of these functions are called with an uninitialised read-write lock.

If a signal is delivered to a thread waiting for a read-write lock for writing, upon return from the signal handler the thread resumes waiting for the read-write lock for writing as if it was not interrupted.

RETURN VALUE

The function pthread_rwlock_trywrlock() returns zero if the lock for writing on the read-write lock object referenced by rwlock is acquired. Otherwise an error number is returned to indicate the error.

ERRORS

[EBUSY]

The read-write lock could not be acquired for writing because it was already locked for reading or writing.

The pthread_rwlock_wrlock() and pthread_rwlock_trywrlock() functions may fail if:

[EINVAL]

The value specified by rwlock does not refer to an initialised read-write lock object.

[EDEADLK]

The current thread already owns the read-write lock for writing or reading.

EXAMPLES

APPLICATION USAGE

Realtime applications may encounter priority inversion when using read-write locks. The problem occurs when a high priority thread &quot;locks&quot; a read-write lock that is about to be &quot;unlocked&quot; by a low priority thread, but the low priority thread is preempted by a medium priority thread. This scenario leads to priority inversion; a high priority thread is blocked by lower priority threads for an unlimited period of time. During system design, realtime programmers must take into account the possibility of this kind of priority inversion. They can deal with it in a number of ways, such as by having critical sections that are guarded by read-write locks execute at a high priority, so that a thread cannot be preempted while executing in its critical section.

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_rwlock_unlock(pthread_rwlock_t *rwlock);

DESCRIPTION

If this function is called to release a read lock from the read-write lock object and there are other read locks currently held on this read-write lock object, the read-write lock object remains in the read locked state. If this function releases the calling thread's last read lock on this read-write lock object, then the calling thread is no longer one of the owners of the object. If this function releases the last read lock for this read-write lock object, the read-write lock object will be put in the unlocked state with no owners.

If this function is called to release a write lock for this read-write lock object, the read-write lock object will be put in the unlocked state with no owners.

If the call to the pthread_rwlock_unlock() function results in the read-write lock object becoming unlocked and there are multiple threads waiting to acquire the read-write lock object for writing, the scheduling policy is used to determine which thread acquires the read-write lock object for writing. If there are multiple threads waiting to acquire the read-write lock object for reading, the scheduling policy is used to determine the order in which the waiting threads acquire the read-write lock object for reading. If there are multiple threads blocked on rwlock for both read locks and write locks, it is unspecified whether the readers acquire the lock first or whether a writer acquires the lock first.

Results are undefined if any of these functions are called with an uninitialised read-write lock.

RETURN VALUE

ERRORS

[EINVAL]

The value specified by rwlock does not refer to an initialised read-write lock object.

[EPERM]

The current thread does not own the read-write lock.

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_rwlock_wrlock(pthread_rwlock_t *rwlock); int pthread_rwlock_trywrlock(pthread_rwlock_t *rwlock);

DESCRIPTION

Implementations are allowed to favour writers over readers to avoid writer starvation.

The function pthread_rwlock_trywrlock() applies a write lock like the pthread_rwlock_wrlock() function, with the exception that the function fails if any thread currently holds rwlock (for reading or writing).

Results are undefined if any of these functions are called with an uninitialised read-write lock.

If a signal is delivered to a thread waiting for a read-write lock for writing, upon return from the signal handler the thread resumes waiting for the read-write lock for writing as if it was not interrupted.

RETURN VALUE

The function pthread_rwlock_trywrlock() returns zero if the lock for writing on the read-write lock object referenced by rwlock is acquired. Otherwise an error number is returned to indicate the error.

ERRORS

[EBUSY]

The read-write lock could not be acquired for writing because it was already locked for reading or writing.

The pthread_rwlock_wrlock() and pthread_rwlock_trywrlock() functions may fail if:

[EINVAL]

The value specified by rwlock does not refer to an initialised read-write lock object.

[EDEADLK]

The current thread already owns the read-write lock for writing or reading.

EXAMPLES

APPLICATION USAGE

Realtime applications may encounter priority inversion when using read-write locks. The problem occurs when a high priority thread &quot;locks&quot; a read-write lock that is about to be &quot;unlocked&quot; by a low priority thread, but the low priority thread is preempted by a medium priority thread. This scenario leads to priority inversion; a high priority thread is blocked by lower priority threads for an unlimited period of time. During system design, realtime programmers must take into account the possibility of this kind of priority inversion. They can deal with it in a number of ways, such as by having critical sections that are guarded by read-write locks execute at a high priority, so that a thread cannot be preempted while executing in its critical section.

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_rwlockattr_init(pthread_rwlockattr_t *attr); int pthread_rwlockattr_destroy(pthread_rwlockattr_t *attr);

DESCRIPTION

Results are undefined if pthread_rwlockattr_init() is called specifying an already initialised read-write lock attributes object.

After a read-write lock attributes object has been used to initialise one or more read-write locks, any function affecting the attributes object (including destruction) does not affect any previously initialised read-write locks.

The pthread_rwlockattr_destroy() function destroys a read-write lock attributes object. The effect of subsequent use of the object is undefined until the object is re-initialised by another call to pthread_rwlockattr_init(). An implementation may cause pthread_rwlockattr_destroy() to set the object referenced by attr to an invalid value.

RETURN VALUE

ERRORS

[ENOMEM]

Insufficient memory exists to initialise the read-write lock attributes object.

The pthread_rwlockattr_destroy() function may fail if:

[EINVAL]

The value specified by attr is invalid.

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_rwlockattr_getpshared(const pthread_rwlockattr_t *attr, int *pshared); int pthread_rwlockattr_setpshared(pthread_rwlockattr_t *attr, int pshared);

DESCRIPTION

The pthread_rwlockattr_getpshared() function obtains the value of the process-shared attribute from the initialised attributes object referenced by attr. The pthread_rwlockattr_setpshared() function is used to set the process-shared attribute in an initialised attributes object referenced by attr.

RETURN VALUE

Upon successful completion, the pthread_rwlockattr_getpshared() returns zero and stores the value of the process-shared attribute of attr into the object referenced by the pshared parameter. Otherwise an error number is returned to indicate the error.

ERRORS

[EINVAL]

The value specified by attr is invalid.

The pthread_rwlockattr_setpshared() function may fail if:

[EINVAL]

The new value specified for the attribute is outside the range of legal values for that attribute.

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_rwlockattr_init(pthread_rwlockattr_t *attr); int pthread_rwlockattr_destroy(pthread_rwlockattr_t *attr);

DESCRIPTION

Results are undefined if pthread_rwlockattr_init() is called specifying an already initialised read-write lock attributes object.

After a read-write lock attributes object has been used to initialise one or more read-write locks, any function affecting the attributes object (including destruction) does not affect any previously initialised read-write locks.

The pthread_rwlockattr_destroy() function destroys a read-write lock attributes object. The effect of subsequent use of the object is undefined until the object is re-initialised by another call to pthread_rwlockattr_init(). An implementation may cause pthread_rwlockattr_destroy() to set the object referenced by attr to an invalid value.

RETURN VALUE

ERRORS

[ENOMEM]

Insufficient memory exists to initialise the read-write lock attributes object.

The pthread_rwlockattr_destroy() function may fail if:

[EINVAL]

The value specified by attr is invalid.

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_rwlockattr_getpshared(const pthread_rwlockattr_t *attr, int *pshared); int pthread_rwlockattr_setpshared(pthread_rwlockattr_t *attr, int pshared);

DESCRIPTION

The pthread_rwlockattr_getpshared() function obtains the value of the process-shared attribute from the initialised attributes object referenced by attr. The pthread_rwlockattr_setpshared() function is used to set the process-shared attribute in an initialised attributes object referenced by attr.

RETURN VALUE

Upon successful completion, the pthread_rwlockattr_getpshared() returns zero and stores the value of the process-shared attribute of attr into the object referenced by the pshared parameter. Otherwise an error number is returned to indicate the error.

ERRORS

[EINVAL]

The value specified by attr is invalid.

The pthread_rwlockattr_setpshared() function may fail if:

[EINVAL]

The new value specified for the attribute is outside the range of legal values for that attribute.

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

pthread_t pthread_self(void);

DESCRIPTION

RETURN VALUE

ERRORS

The pthread_self() function will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_setcancelstate(int state, int *oldstate); int pthread_setcanceltype(int type, int *oldtype); void pthread_testcancel(void);

DESCRIPTION

The pthread_setcanceltype() function atomically both sets the calling thread's cancelability type to the indicated type and returns the previous cancelability type at the location referenced by oldtype. Legal values for type are PTHREAD_CANCEL_DEFERRED and PTHREAD_CANCEL_ASYNCHRONOUS.

The cancelability state and type of any newly created threads, including the thread in which main() was first invoked, are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DEFERRED respectively.

The pthread_testcancel() function creates a cancellation point in the calling thread. The pthread_testcancel() function has no effect if cancelability is disabled.

RETURN VALUE

ERRORS

[EINVAL]

The specified state is not PTHREAD_CANCEL_ENABLE or PTHREAD_CANCEL_DISABLE.

The pthread_setcanceltype() function may fail if:

[EINVAL]

The specified type is not PTHREAD_CANCEL_DEFERRED or PTHREAD_CANCEL_ASYNCHRONOUS.

These functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_setcancelstate(int state, int *oldstate); int pthread_setcanceltype(int type, int *oldtype); void pthread_testcancel(void);

DESCRIPTION

The pthread_setcanceltype() function atomically both sets the calling thread's cancelability type to the indicated type and returns the previous cancelability type at the location referenced by oldtype. Legal values for type are PTHREAD_CANCEL_DEFERRED and PTHREAD_CANCEL_ASYNCHRONOUS.

The cancelability state and type of any newly created threads, including the thread in which main() was first invoked, are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DEFERRED respectively.

The pthread_testcancel() function creates a cancellation point in the calling thread. The pthread_testcancel() function has no effect if cancelability is disabled.

RETURN VALUE

ERRORS

[EINVAL]

The specified state is not PTHREAD_CANCEL_ENABLE or PTHREAD_CANCEL_DISABLE.

The pthread_setcanceltype() function may fail if:

[EINVAL]

The specified type is not PTHREAD_CANCEL_DEFERRED or PTHREAD_CANCEL_ASYNCHRONOUS.

These functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_setconcurrency(int new_level);

DESCRIPTION

______________________________________________________________________

NAME

SYNOPSIS

int pthread_getschedparam(pthread_t thread, int *policy, struct sched_param *param); int pthread_setschedparam(pthread_t thread, int policy, const struct sched_param *param);

DESCRIPTION

The pthread_getschedparam() function retrieves the scheduling policy and scheduling parameters for the thread whose thread ID is given by thread and stores those values in policy and param, respectively. The priority value returned from pthread_getschedparam() is the value specified by the most recent pthread_setschedparam() or pthread_create() call affecting the target thread, and reflects any temporary adjustments to its priority as a result of any priority inheritance or ceiling functions. The pthread_setschedparam() function sets the scheduling policy and associated scheduling parameters for the thread whose thread ID is given by thread to the policy and associated parameters provided in policy and param, respectively.

The policy parameter may have the value SCHED_OTHER, that has implementation-dependent scheduling parameters, SCHED_FIFO or SCHED_RR, that have the single scheduling parameter, priority.

If the pthread_setschedparam() function fails, no scheduling parameters will be changed for the target thread.

RETURN VALUE

ERRORS

[ENOSYS]

The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the implementation does not support the function.

The pthread_getschedparam() function may fail if:

[ESRCH]

The value specified by thread does not refer to a existing thread.

The pthread_setschedparam() function may fail if:

[EINVAL]

The value specified by policy or one of the scheduling parameters associated with the scheduling policy policy is invalid.

[ENOTSUP]

An attempt was made to set the policy or scheduling parameters to an unsupported value.

[EPERM]

The caller does not have the appropriate permission to set either the scheduling parameters or the scheduling policy of the specified thread.

[EPERM]

The implementation does not allow the application to modify one of the parameters to the value specified.

[ESRCH]

The value specified by thread does not refer to a existing thread.

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_setspecific(pthread_key_t key, const void *value); void *pthread_getspecific(pthread_key_t key);

DESCRIPTION

The pthread_getspecific() function returns the value currently bound to the specified key on behalf of the calling thread.

The effect of calling pthread_setspecific() or pthread_getspecific() with a key value not obtained from pthread_key_create() or after key has been deleted with pthread_key_delete() is undefined.

Both pthread_setspecific() and pthread_getspecific() may be called from a thread-specific data destructor function. However, calling pthread_setspecific() from a destructor may result in lost storage or infinite loops.

Both functions may be implemented as macros.

RETURN VALUE

If successful, the pthread_setspecific() function returns zero. Otherwise, an error number is returned to indicate the error.

ERRORS

[ENOMEM]

Insufficient memory exists to associate the value with the key.

The pthread_setspecific() function may fail if:

[EINVAL]

The key value is invalid.

No errors are returned from pthread_getspecific().

These functions will not return an error code of [EINTR].

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

int pthread_sigmask(int how, const sigset_t *set, sigset_t *oset);

DESCRIPTION

______________________________________________________________________

NAME

SYNOPSIS

int pthread_setcancelstate(int state, int *oldstate); int pthread_setcanceltype(int type, int *oldtype); void pthread_testcancel(void);

DESCRIPTION

The pthread_setcanceltype() function atomically both sets the calling thread's cancelability type to the indicated type and returns the previous cancelability type at the location referenced by oldtype. Legal values for type are PTHREAD_CANCEL_DEFERRED and PTHREAD_CANCEL_ASYNCHRONOUS.

The cancelability state and type of any newly created threads, including the thread in which main() was first invoked, are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DEFERRED respectively.

The pthread_testcancel() function creates a cancellation point in the calling thread. The pthread_testcancel() function has no effect if cancelability is disabled.

RETURN VALUE

ERRORS

[EINVAL]

The specified state is not PTHREAD_CANCEL_ENABLE or PTHREAD_CANCEL_DISABLE.