Content-type: text/html Manpage of pthread

pthread

Section: POSIX Threading API of NGPT (3)
Updated: 26-Jul-2000
Index Return to Main Contents

NAME

pthread - POSIX.1c Threading API of GNU Pth

VERSION

GNU Pth 1.4a3 (26-Jul-2000)

SYNOPSIS

Application Makefiles:

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

AUTHOR

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

______________________________________________________________________

NAME

pthread.h - threads

SYNOPSIS

#include <pthread.h>

DESCRIPTION

The <pthread.h> header defines the following symbols:

 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);
 int   pthread_attr_setweight_np(pthread_attr_t *, int);
 int   pthread_attr_setsuspendstate_np(pthread_attr_t *, int);
 int   pthread_attr_getsuspendstate_np(pthread_attr_t *, int *);
 int   pthread_suspend_np(pthread_t);   /*ibm*/
 int   pthread_resume_np(pthread_t);    /*ibm*/
 int   pthread_getstacksize_np(pthread_t, int *); /*ibm*/
 void *pthread_getcontext_np(pthread_t);  /*ibm*/

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

APPLICATION USAGE

An interpretation request has been filed with IEEE PASC concerning requirements for visibility of symbols in this header.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_atfork - register fork handlers

SYNOPSIS

#include <sys/types.h>

#include <unistd.h>

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

DESCRIPTION

The pthread_atfork() function declares fork handlers to be called before and after fork(), in the context of the thread that called fork(). The prepare fork handler is called before fork() processing commences. The parent fork handle is called after fork() processing completes in the parent process. The child fork handler is called after fork() processing completes in the child process. If no handling is desired at one or more of these three points, the corresponding fork handler address(es) may be set to NULL.

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

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

ERRORS

The pthread_atfork() function will fail if:

[ENOMEM]: Insufficient table space exists to record the fork handler addresses.

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

EXAMPLES

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_attr_init, pthread_attr_destroy - initialise and destroy threads attribute object

SYNOPSIS

#include <pthread.h>

int pthread_attr_init(pthread_attr_t *attr);

int pthread_attr_destroy(pthread_attr_t *attr);

DESCRIPTION

The function pthread_attr_init() initialises a thread attributes object attr with the default value for all of the individual attributes used by a given implementation.

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

Upon successful completion, pthread_attr_init() and pthread_attr_destroy() return a value of 0. Otherwise, an error number is returned to indicate the error.

ERRORS

The pthread_attr_init() function will fail if:

[ENOMEM]: Insufficient memory exists to initialise the thread attributes object.

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

EXAMPLES

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_attr_setdetachstate, pthread_attr_getdetachstate - set and get detachstate attribute

SYNOPSIS

#include <pthread.h>

int pthread_attr_setdetachstate(pthread_attr_t *attr, int detachstate);

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

DESCRIPTION

The detachstate attribute controls whether the thread is created in a detached state. If the thread is created detached, then use of the ID of the newly created thread by the pthread_detach() or pthread_join() function is an error.

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

Upon successful completion, pthread_attr_setdetachstate() and pthread_attr_getdetachstate() return a value of 0. Otherwise, an error number is returned to indicate the error.

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

ERRORS

The pthread_attr_setdetachstate() function will fail if:

[EINVAL]: The value of detachstate was not valid

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

EXAMPLES

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_attr_getguardsize, pthread_attr_setguardsize - get or set the thread guardsize attribute

SYNOPSIS

#include <pthread.h>

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 controls the size of the guard area for the created thread's stack. The guardsize attribute provides protection against overflow of the stack pointer. If a thread's stack is created with guard protection, the implementation allocates extra memory at the overflow end of the stack as a buffer against stack overflow of the stack pointer. If an application overflows into this buffer an error results (possibly in a SIGSEGV signal being delivered to the thread).

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

If successful, the pthread_attr_getguardsize() and pthread_attr_setguardsize() functions return zero. Otherwise, an error number is returned to indicate the error.

ERRORS

The pthread_attr_getguardsize() and pthread_attr_setguardsize() functions will fail if:

[EINVAL]: The attribute attr is invalid.
[EINVAL]: The parameter guardsize is invalid.
[EINVAL]: The parameter guardsize contains an invalid value.

EXAMPLES

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_attr_setinheritsched, pthread_attr_getinheritsched - set and get inheritsched attribute (REALTIME THREADS)

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

The functions pthread_attr_setinheritsched() and pthread_attr_getinheritsched(), respectively, set and get the inheritsched attribute in the attr argument.

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

If successful, the pthread_attr_setinheritsched() and pthread_attr_getinheritsched() functions return zero. Otherwise, an error number is returned to indicate the error.

ERRORS

The pthread_attr_setinheritsched() and pthread_attr_getinheritsched() functions will fail if:

[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

None.

APPLICATION USAGE

After these attributes have been set, a thread can be created with the specified attributes using pthread_create(). Using these routines does not affect the current running thread.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_attr_setschedparam, pthread_attr_getschedparam - set and get schedparam attribute

SYNOPSIS

#include <pthread.h>

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

The functions pthread_attr_setschedparam() and pthread_attr_getschedparam(), respectively, set and get the scheduling parameter attributes in the attr argument. The contents of the param structure are defined in <sched.h>. For the SCHED_FIFO and SCHED_RR policies, the only required member of param is sched_priority.

RETURN VALUE

If successful, the pthread_attr_setschedparam() and pthread_attr_getschedparam() functions return zero. Otherwise, an error number is returned to indicate the error.

ERRORS

The pthread_attr_setschedparam() 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.

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

EXAMPLES

None.

APPLICATION USAGE

After these attributes have been set, a thread can be created with the specified attributes using pthread_create(). Using these routines does not affect the current running thread.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_attr_setschedpolicy, pthread_attr_getschedpolicy - set and get schedpolicy attribute (REALTIME THREADS)

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

The functions pthread_attr_setschedpolicy() and pthread_attr_getschedpolicy(), respectively, set and get the schedpolicy attribute in the attr argument.

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

If successful, the pthread_attr_setschedpolicy() and pthread_attr_getschedpolicy() functions return zero. Otherwise, an error number is returned to indicate the error.

ERRORS

The pthread_attr_setschedpolicy() and pthread_attr_getschedpolicy() functions will fail if:

[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

None.

APPLICATION USAGE

After these attributes have been set, a thread can be created with the specified attributes using pthread_create(). Using these routines does not affect the current running thread.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_attr_setscope, pthread_attr_getscope - set and get contentionscope attribute (REALTIME THREADS)

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

The pthread_attr_setscope() and pthread_attr_getscope() functions are used to set and get the contentionscope attribute in the attr object.

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

If successful, the pthread_attr_setscope() and pthread_attr_getscope() functions return zero. Otherwise, an error number is returned to indicate the error.

ERRORS

The pthread_attr_setscope() and pthread_attr_getscope() functions will fail if:

[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

None.

APPLICATION USAGE

After these attributes have been set, a thread can be created with the specified attributes using pthread_create(). Using these routines does not affect the current running thread.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_attr_setstackaddr, pthread_attr_getstackaddr - set and get stackaddr attribute

SYNOPSIS

#include <pthread.h>

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

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

DESCRIPTION

The functions pthread_attr_setstackaddr() and pthread_attr_getstackaddr(), respectively, set and get the thread creation stackaddr attribute in the attr object.

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

Upon successful completion, pthread_attr_setstackaddr() and pthread_attr_getstackaddr() return a value of 0. Otherwise, an error number is returned to indicate the error.

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

ERRORS

No errors are defined.

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

EXAMPLES

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_attr_setstacksize, pthread_attr_getstacksize - set and get stacksize attribute

SYNOPSIS

#include <pthread.h>

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 functions pthread_attr_setstacksize() and pthread_attr_getstacksize(), respectively, set and get the thread creation stacksize attribute in the attr object.

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

RETURN VALUE

Upon successful completion, pthread_attr_setstacksize() and pthread_attr_getstacksize() return a value of 0. Otherwise, an error number is returned to indicate the error. The pthread_attr_getstacksize() function stores the stacksize attribute value in stacksize if successful.

ERRORS

The pthread_attr_setstacksize() function will fail if:

[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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_attr_init, pthread_attr_destroy - initialise and destroy threads attribute object

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

The function pthread_attr_init() initialises a thread attributes object attr with the default value for all of the individual attributes used by a given implementation.

RETURN VALUE

Upon successful completion, pthread_attr_init() and pthread_attr_destroy() return a value of 0. Otherwise, an error number is returned to indicate the error.

ERRORS

The pthread_attr_init() function will fail if:

[ENOMEM]: Insufficient memory exists to initialise the thread attributes object.

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

EXAMPLES

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_attr_setdetachstate, pthread_attr_getdetachstate - set and get detachstate attribute

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

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

RETURN VALUE

Upon successful completion, pthread_attr_setdetachstate() and pthread_attr_getdetachstate() return a value of 0. Otherwise, an error number is returned to indicate the error.

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

ERRORS

The pthread_attr_setdetachstate() function will fail if:

[EINVAL]: The value of detachstate was not valid

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

EXAMPLES

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_attr_getguardsize, pthread_attr_setguardsize - get or set the thread guardsize attribute

SYNOPSIS

#include <pthread.h>

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

RETURN VALUE

If successful, the pthread_attr_getguardsize() and pthread_attr_setguardsize() functions return zero. Otherwise, an error number is returned to indicate the error.

ERRORS

The pthread_attr_getguardsize() and pthread_attr_setguardsize() functions will fail if:

[EINVAL]: The attribute attr is invalid.
[EINVAL]: The parameter guardsize is invalid.
[EINVAL]: The parameter guardsize contains an invalid value.

EXAMPLES

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_attr_setinheritsched, pthread_attr_getinheritsched - set and get inheritsched attribute (REALTIME THREADS)

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

The functions pthread_attr_setinheritsched() and pthread_attr_getinheritsched(), respectively, set and get the inheritsched attribute in the attr argument.

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

If successful, the pthread_attr_setinheritsched() and pthread_attr_getinheritsched() functions return zero. Otherwise, an error number is returned to indicate the error.

ERRORS

The pthread_attr_setinheritsched() and pthread_attr_getinheritsched() functions will fail if:

[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

None.

APPLICATION USAGE

After these attributes have been set, a thread can be created with the specified attributes using pthread_create(). Using these routines does not affect the current running thread.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_attr_setschedparam, pthread_attr_getschedparam - set and get schedparam attribute

SYNOPSIS

#include <pthread.h>

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

If successful, the pthread_attr_setschedparam() and pthread_attr_getschedparam() functions return zero. Otherwise, an error number is returned to indicate the error.

ERRORS

The pthread_attr_setschedparam() 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.

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

EXAMPLES

None.

APPLICATION USAGE

After these attributes have been set, a thread can be created with the specified attributes using pthread_create(). Using these routines does not affect the current running thread.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_attr_setschedpolicy, pthread_attr_getschedpolicy - set and get schedpolicy attribute (REALTIME THREADS)

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

The functions pthread_attr_setschedpolicy() and pthread_attr_getschedpolicy(), respectively, set and get the schedpolicy attribute in the attr argument.

RETURN VALUE

If successful, the pthread_attr_setschedpolicy() and pthread_attr_getschedpolicy() functions return zero. Otherwise, an error number is returned to indicate the error.

ERRORS

The pthread_attr_setschedpolicy() and pthread_attr_getschedpolicy() functions will fail if:

[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

None.

APPLICATION USAGE

After these attributes have been set, a thread can be created with the specified attributes using pthread_create(). Using these routines does not affect the current running thread.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_attr_setscope, pthread_attr_getscope - set and get contentionscope attribute (REALTIME THREADS)

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

The pthread_attr_setscope() and pthread_attr_getscope() functions are used to set and get the contentionscope attribute in the attr object.

RETURN VALUE

If successful, the pthread_attr_setscope() and pthread_attr_getscope() functions return zero. Otherwise, an error number is returned to indicate the error.

ERRORS

The pthread_attr_setscope() and pthread_attr_getscope() functions will fail if:

[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

None.

APPLICATION USAGE

After these attributes have been set, a thread can be created with the specified attributes using pthread_create(). Using these routines does not affect the current running thread.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_attr_setstackaddr, pthread_attr_getstackaddr - set and get stackaddr attribute

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

The functions pthread_attr_setstackaddr() and pthread_attr_getstackaddr(), respectively, set and get the thread creation stackaddr attribute in the attr object.

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

Upon successful completion, pthread_attr_setstackaddr() and pthread_attr_getstackaddr() return a value of 0. Otherwise, an error number is returned to indicate the error.

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

ERRORS

No errors are defined.

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

EXAMPLES

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_attr_setstacksize, pthread_attr_getstacksize - set and get stacksize attribute

SYNOPSIS

#include <pthread.h>

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 functions pthread_attr_setstacksize() and pthread_attr_getstacksize(), respectively, set and get the thread creation stacksize attribute in the attr object.

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

RETURN VALUE

ERRORS

The pthread_attr_setstacksize() function will fail if:

[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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_cancel - cancel execution of a thread

SYNOPSIS

#include <pthread.h>

int pthread_cancel(pthread_t thread);

DESCRIPTION

The pthread_cancel() function requests that thread be canceled. The target threads cancelability state and type determines when the cancellation takes effect. When the cancellation is acted on, the cancellation cleanup handlers for thread are called. When the last cancellation cleanup handler returns, the thread-specific data destructor functions are called for thread. When the last destructor function returns, thread is terminated.

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

RETURN VALUE

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

ERRORS

The pthread_cancel() function may fail if:

[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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_cleanup_push, pthread_cleanup_pop - establish cancellation handlers

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

The pthread_cleanup_push() function pushes the specified cancellation cleanup handler routine onto the calling thread's cancellation cleanup stack. The cancellation cleanup handler is popped from the cancellation cleanup stack and invoked with the argument arg when: (a) the thread exits (that is, calls pthread_exit()), (b) the thread acts upon a cancellation request, or (c) the thread calls pthread_cleanup_pop() with a non-zero execute argument.

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

The pthread_cleanup_push() and pthread_cleanup_pop() functions return no value.

ERRORS

No errors are defined.

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

EXAMPLES

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_cleanup_push, pthread_cleanup_pop - establish cancellation handlers

SYNOPSIS

#include <pthread.h>

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

RETURN VALUE

The pthread_cleanup_push() and pthread_cleanup_pop() functions return no value.

ERRORS

No errors are defined.

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

EXAMPLES

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_cond_signal, pthread_cond_broadcast - signal or broadcast a condition

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

These two functions are used to unblock threads blocked on a condition variable.

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

If successful, the pthread_cond_signal() and pthread_cond_broadcast() functions return zero. Otherwise, an error number is returned to indicate the error.

ERRORS

The pthread_cond_signal() and pthread_cond_broadcast() function may fail if:

[EINVAL]: The value cond does not refer to an initialised condition variable.

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

EXAMPLES

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_cond_init, pthread_cond_destroy - initialise and destroy condition variables

SYNOPSIS

#include <pthread.h>

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

The function pthread_cond_init() initialises the condition variable referenced by cond with attributes referenced by attr. If attr is NULL, the default condition variable attributes are used; the effect is the same as passing the address of a default condition variable attributes object. Upon successful initialisation, the state of the condition variable becomes initialised.

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

If successful, the pthread_cond_init() and pthread_cond_destroy() functions return zero. Otherwise, an error number is returned to indicate the error. The [EBUSY] and [EINVAL] error checks, if implemented, act as if they were performed immediately at the beginning of processing for the function and caused an error return prior to modifying the state of the condition variable specified by cond.

ERRORS

The pthread_cond_init() function will fail if:

[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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_cond_init, pthread_cond_destroy - initialise and destroy condition variables

SYNOPSIS

#include <pthread.h>

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.

RETURN VALUE

ERRORS

The pthread_cond_init() function will fail if:

[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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_cond_signal, pthread_cond_broadcast - signal or broadcast a condition

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

These two functions are used to unblock threads blocked on a condition variable.

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.

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

RETURN VALUE

If successful, the pthread_cond_signal() and pthread_cond_broadcast() functions return zero. Otherwise, an error number is returned to indicate the error.

ERRORS

The pthread_cond_signal() and pthread_cond_broadcast() function may fail if:

[EINVAL]: The value cond does not refer to an initialised condition variable.

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

EXAMPLES

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_cond_wait, pthread_cond_timedwait - wait on a condition

SYNOPSIS

#include <pthread.h>

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

The pthread_cond_wait() and pthread_cond_timedwait() functions are used to block on a condition variable. They are called with mutex locked by the calling thread or undefined behaviour will result.

These functions atomically release mutex and cause the calling thread to block on the condition variable cond; atomically here means "atomically with respect to access by another thread to the mutex and then the condition variable". 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

Except in the case of [ETIMEDOUT], all these error checks act as if they were performed immediately at the beginning of processing for the function and cause an error return, in effect, prior to modifying the state of the mutex specified by mutex or the condition variable specified by cond.

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

ERRORS

The pthread_cond_timedwait() function will fail if:

[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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_cond_wait, pthread_cond_timedwait - wait on a condition

SYNOPSIS

#include <pthread.h>

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

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

RETURN VALUE

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

ERRORS

The pthread_cond_timedwait() function will fail if:

[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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_condattr_init, pthread_condattr_destroy - initialise and destroy condition variable attributes object

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

The function pthread_condattr_init() initialises a condition variable attributes object attr with the default value for all of the attributes defined by the implementation.

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

If successful, the pthread_condattr_init() and pthread_condattr_destroy() functions return zero. Otherwise, an error number is returned to indicate the error.

ERRORS

The pthread_condattr_init() function will fail if:

[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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_condattr_getpshared, pthread_condattr_setpshared - get and set the process-shared condition variable attributes

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

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

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_setpshared() function returns zero. Otherwise, an error number is returned to indicate the error.

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

The pthread_condattr_getpshared() and pthread_condattr_setpshared() functions may fail if:

[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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_condattr_init, pthread_condattr_destroy - initialise and destroy condition variable attributes object

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

The function pthread_condattr_init() initialises a condition variable attributes object attr with the default value for all of the attributes defined by the implementation.

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

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_init() and pthread_condattr_destroy() functions return zero. Otherwise, an error number is returned to indicate the error.

ERRORS

The pthread_condattr_init() function will fail if:

[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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_condattr_getpshared, pthread_condattr_setpshared - get and set the process-shared condition variable attributes

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

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_setpshared() function returns zero. Otherwise, an error number is returned to indicate the error.

ERRORS

The pthread_condattr_getpshared() and pthread_condattr_setpshared() functions may fail if:

[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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_create - thread creation

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

The pthread_create() function is used to create a new thread, with attributes specified by attr, within a process. If attr is NULL, the default attributes are used. If the attributes specified by attr are modified later, the thread's attributes are not affected. Upon successful completion, pthread_create() stores the ID of the created thread in the location referenced by thread.

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

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

ERRORS

The pthread_create() function will fail if:

[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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_detach - detach a thread

SYNOPSIS

#include <pthread.h>

int pthread_detach(pthread_t thread);

DESCRIPTION

The pthread_detach() function is used to indicate to the implementation that storage for the thread thread can be reclaimed when that thread terminates. If thread has not terminated, pthread_detach() will not cause it to terminate. The effect of multiple pthread_detach() calls on the same target thread is unspecified.

RETURN VALUE

If the call succeeds, pthread_detach() returns 0. Otherwise, an error number is returned to indicate the error.

ERRORS

The pthread_detach() function will fail if:

[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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_equal - compare thread IDs

SYNOPSIS

#include <pthread.h>

int pthread_equal(pthread_t t1, pthread_t t2);

DESCRIPTION

This function compares the thread IDs t1 and t2.

RETURN VALUE

The pthread_equal() function returns a non-zero value if t1 and t2 are equal; otherwise, zero is returned.

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

ERRORS

No errors are defined.

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

EXAMPLES

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_exit - thread termination

SYNOPSIS

#include <pthread.h>

void pthread_exit(void *value_ptr);

DESCRIPTION

The pthread_exit() function terminates the calling thread and makes the value value_ptr available to any successful join with the terminating thread. Any cancellation cleanup handlers that have been pushed and not yet popped are popped in the reverse order that they were pushed and then executed. After all cancellation cleanup handlers have been executed, if the thread has any thread-specific data, appropriate destructor functions will be called in an unspecified order. Thread termination does not release any application visible process resources, including, but not limited to, mutexes and file descriptors, nor does it perform any process level cleanup actions, including, but not limited to, calling any atexit() routines that may exist.

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

The pthread_exit() function cannot return to its caller.

ERRORS

No errors are defined.

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

EXAMPLES

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_getconcurrency, pthread_setconcurrency - get or set level of concurrency

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

Unbound threads in a process may or may not be required to be simultaneously active. By default, the threads implementation ensures that a sufficient number of threads are active so that the process can continue to make progress. While this conserves system resources, it may not produce the most effective level of concurrency.

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

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

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

The pthread_setconcurrency() function will fail if:

[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

None.

APPLICATION USAGE

Use of these functions changes the state of the underlying concurrency upon which the application depends. Library developers are advised to not use the pthread_getconcurrency() and pthread_setconcurrency() functions since their use may conflict with an applications use of these functions.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_getschedparam, pthread_setschedparam - dynamic thread scheduling parameters access (REALTIME THREADS)

SYNOPSIS

#include <pthread.h>

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() and pthread_setschedparam() allow the scheduling policy and scheduling parameters of individual threads within a multi-threaded process to be retrieved and set. For SCHED_FIFO and SCHED_RR, the only required member of the sched_param structure is the priority sched_priority. For SCHED_OTHER, the affected scheduling parameters are implementation-dependent.

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

If successful, the pthread_getschedparam() and pthread_setschedparam() functions return zero. Otherwise, an error number is returned to indicate the error.

ERRORS

The pthread_getschedparam() and pthread_setschedparam() functions will fail if:

[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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_setspecific, pthread_getspecific - thread-specific data management

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

The pthread_setspecific() function associates a thread-specific value with a key obtained via a previous call to pthread_key_create(). Different threads may bind different values to the same key. These values are typically pointers to blocks of dynamically allocated memory that have been reserved for use by the calling thread.

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

The function pthread_getspecific() returns the thread-specific data value associated with the given key. If no thread-specific data value is associated with key, then the value NULL is returned.

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

ERRORS

The pthread_setspecific() function will fail if:

[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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_join - wait for thread termination

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

The pthread_join() function suspends execution of the calling thread until the target thread terminates, unless the target thread has already terminated. On return from a successful pthread_join() call with a non-NULL value_ptr argument, the value passed to pthread_exit() by the terminating thread is made available in the location referenced by value_ptr. When a pthread_join() returns successfully, the target thread has been terminated. The results of multiple simultaneous calls to pthread_join() specifying the same target thread are undefined. If the thread calling pthread_join() is canceled, then the target thread will not be detached.

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

RETURN VALUE

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

ERRORS

The pthread_join() function will fail if:

[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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_key_create - thread-specific data key creation

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

This function creates a thread-specific data key visible to all threads in the process. Key values provided by pthread_key_create() are opaque objects used to locate thread-specific data. Although the same key value may be used by different threads, the values bound to the key by pthread_setspecific() are maintained on a per-thread basis and persist for the life of the calling thread.

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

If successful, the pthread_key_create() function stores the newly created key value at *key and returns zero. Otherwise, an error number is returned to indicate the error.

ERRORS

The pthread_key_create() function will fail if:

[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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_key_delete - thread-specific data key deletion

SYNOPSIS

#include <pthread.h>

int pthread_key_delete(pthread_key_t key);

DESCRIPTION

This function deletes a thread-specific data key previously returned by pthread_key_create(). The thread-specific data values associated with key need not be NULL at the time pthread_key_delete() is called. It is the responsibility of the application to free any application storage or perform any cleanup actions for data structures related to the deleted key or associated thread-specific data in any threads; this cleanup can be done either before or after pthread_key_delete() is called. Any attempt to use key following the call to pthread_key_delete() results in undefined behaviour.

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

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

ERRORS

The pthread_key_delete() function may fail if:

[EINVAL]: The key value is invalid.

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

EXAMPLES

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_kill - send a signal to a thread

SYNOPSIS

#include <signal.h>

int pthread_kill(pthread_t thread, int sig);

DESCRIPTION

The pthread_kill() function is used to request that a signal be delivered to the specified thread.

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

RETURN VALUE

Upon successful completion, the function returns a value of zero. Otherwise the function returns an error number. If the pthread_kill() function fails, no signal is sent.

ERRORS

The pthread_kill() function will fail if:

[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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_mutex_init, pthread_mutex_destroy - initialise or destroy a mutex

SYNOPSIS

#include <pthread.h>

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

The pthread_mutex_init() function initialises the mutex referenced by mutex with attributes specified by attr. If attr is NULL, the default mutex attributes are used; the effect is the same as passing the address of a default mutex attributes object. Upon successful initialisation, the state of the mutex becomes initialised and unlocked.

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

If successful, the pthread_mutex_init() and pthread_mutex_destroy() functions return zero. Otherwise, an error number is returned to indicate the error. The [EBUSY] and [EINVAL] error checks, if implemented, act as if they were performed immediately at the beginning of processing for the function and cause an error return prior to modifying the state of the mutex specified by mutex.

ERRORS

The pthread_mutex_init() function will fail if:

[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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

______________________________________________________________________

NAME

pthread_mutex_setprioceiling, pthread_mutex_getprioceiling - change the priority ceiling of a mutex (REALTIME THREADS)

SYNOPSIS

#include <pthread.h>

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_getprioceiling() function returns the current priority ceiling of the mutex.

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

If successful, the pthread_mutex_setprioceiling()<

pthread

NAME

VERSION

SYNOPSIS

DESCRIPTION

Overview

Supported Features

Notes

Further Reading

SEE ALSO

AUTHOR

______________________________________________________________________

NAME

SYNOPSIS

DESCRIPTION

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

ERRORS

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

ERRORS

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

ERRORS

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

ERRORS

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

ERRORS

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

ERRORS

EXAMPLES

APPLICATION USAGE

FUTURE DIRECTIONS

SEE ALSO

______________________________________________________________________

NAME