Manpages

NAME

pthread − POSIX.1c Threading API of GNU Pth

VERSION

GNU Pth 2.0.7 (08-Jun-2006)

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.

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

pthread−config(1), pth(3).

AUTHOR

 Ralf S. Engelschall
 rse [AT] 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);

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.

SEE ALSO

pthread_attr_init(), pthread_attr_getguardsize(), pthread_attr_setscope(), pthread_cancel(), pthread_cleanup_push(), pthread_cond_init(), pthread_cond_signal(), pthread_cond_wait(), pthread_condattr_init(), pthread_create(), pthread_detach(), pthread_equal(), pthread_exit(), pthread_getconcurrency(), pthread_getschedparam(), pthread_join(), pthread_key_create(), pthread_key_delete(), pthread_mutex_init(), pthread_mutex_lock(), pthread_mutex_setprioceiling(), pthread_mutexattr_init(), pthread_mutexattr_gettype(), pthread_mutexattr_setprotocol(), pthread_once(), pthread_self(), pthread_setcancelstate(), pthread_setspecific(), pthread_rwlock_init(), pthread_rwlock_rdlock(), pthread_rwlock_unlock(), pthread_rwlock_wrlock(), pthread_rwlockattr_init(), <sched.h>, <time.h>.

______________________________________________________________________

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.

SEE ALSO

atexit(), fork(), <sys/types.h>

______________________________________________________________________

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.

SEE ALSO

pthread_attr_setstackaddr(), pthread_attr_setstacksize(), pthread_attr_setdetachstate(), pthread_create(), <pthread.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_attr_init(), pthread_attr_setstackaddr(), pthread_attr_setstacksize(), pthread_create(), <pthread.h>.

______________________________________________________________________

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.

SEE ALSO

<pthread.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_attr_init(), pthread_attr_setscope(), pthread_attr_setschedpolicy(), pthread_attr_setschedparam(), pthread_create(), <pthread.h>, pthread_setschedparam(), <sched.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_attr_init(), pthread_attr_setscope(), pthread_attr_setinheritsched(), pthread_attr_setschedpolicy(), pthread_create(), <pthread.h>, pthread_setschedparam(), <sched.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_attr_init(), pthread_attr_setscope(), pthread_attr_setinheritsched(), pthread_attr_setschedparam(), pthread_create(), <pthread.h>, pthread_setschedparam(), <sched.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_attr_init(), pthread_attr_setinheritsched(), pthread_attr_setschedpolicy(), pthread_attr_setschedparam(), pthread_create(), <pthread.h>, pthread_setschedparam(), <sched.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_attr_init(), pthread_attr_setdetachstate(), pthread_attr_setstacksize(), pthread_create(), <limits.h>, <pthread.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_attr_init(), pthread_attr_setstackaddr(), pthread_attr_setdetachstate(), pthread_create(), <limits.h>, <pthread.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_attr_setstackaddr(), pthread_attr_setstacksize(), pthread_attr_setdetachstate(), pthread_create(), <pthread.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_attr_init(), pthread_attr_setstackaddr(), pthread_attr_setstacksize(), pthread_create(), <pthread.h>.

______________________________________________________________________

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.

SEE ALSO

<pthread.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_attr_init(), pthread_attr_setscope(), pthread_attr_setschedpolicy(), pthread_attr_setschedparam(), pthread_create(), <pthread.h>, pthread_setschedparam(), <sched.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_attr_init(), pthread_attr_setscope(), pthread_attr_setinheritsched(), pthread_attr_setschedpolicy(), pthread_create(), <pthread.h>, pthread_setschedparam(), <sched.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_attr_init(), pthread_attr_setscope(), pthread_attr_setinheritsched(), pthread_attr_setschedparam(), pthread_create(), <pthread.h>, pthread_setschedparam(), <sched.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_attr_init(), pthread_attr_setinheritsched(), pthread_attr_setschedpolicy(), pthread_attr_setschedparam(), pthread_create(), <pthread.h>, pthread_setschedparam(), <sched.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_attr_init(), pthread_attr_setdetachstate(), pthread_attr_setstacksize(), pthread_create(), <limits.h>, <pthread.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_attr_init(), pthread_attr_setstackaddr(), pthread_attr_setdetachstate(), pthread_create(), <limits.h>, <pthread.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_exit(), pthread_join(), pthread_setcancelstate(), pthread_cond_wait(), pthread_cond_timedwait(), <pthread.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_cancel(), pthread_setcancelstate(), <pthread.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_cancel(), pthread_setcancelstate(), <pthread.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_cond_init(), pthread_cond_wait(), pthread_cond_timedwait(), <pthread.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_cond_signal(), pthread_cond_broadcast(), pthread_cond_wait(), pthread_cond_timedwait(), <pthread.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_cond_signal(), pthread_cond_broadcast(), pthread_cond_wait(), pthread_cond_timedwait(), <pthread.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_cond_init(), pthread_cond_wait(), pthread_cond_timedwait(), <pthread.h>.

______________________________________________________________________

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

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.

SEE ALSO

pthread_cond_signal(), pthread_cond_broadcast(), <pthread.h>.

______________________________________________________________________

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

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.

SEE ALSO

pthread_cond_signal(), pthread_cond_broadcast(), <pthread.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_condattr_getpshared(), pthread_create(), pthread_mutex_init(), pthread_cond_init(), <pthread.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_condattr_init(), pthread_create(), pthread_mutex_init(), pthread_cond_init(), <pthread.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_condattr_getpshared(), pthread_create(), pthread_mutex_init(), pthread_cond_init(), <pthread.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_condattr_init(), pthread_create(), pthread_mutex_init(), pthread_cond_init(), <pthread.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_exit(), pthread_join(), fork(), <pthread.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_join(), <pthread.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_create(), pthread_self(), <pthread.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_create(), pthread_join(), exit(), _exit(), <pthread.h>.

______________________________________________________________________

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.

SEE ALSO

<pthread.h>.

______________________________________________________________________

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.

SEE ALSO

sched_setparam(), sched_getparam(), sched_setscheduler(), sched_getscheduler(), <pthread.h>, <sched.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_key_create(), <pthread.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_create(), wait(), <pthread.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_getspecific(), pthread_setspecific(), pthread_key_delete(), <pthread.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_key_create(), <pthread.h>.

______________________________________________________________________

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.

SEE ALSO

kill(), pthread_self(), raise(), <signal.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_mutex_getprioceiling(), pthread_mutex_lock(), pthread_mutex_unlock(), pthread_mutex_setprioceiling(), pthread_mutex_trylock(), pthread_mutexattr_getpshared(), pthread_mutexattr_setpshared(), <pthread.h>.

______________________________________________________________________

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

ERRORS

The pthread_mutex_getprioceiling() and pthread_mutex_setprioceiling() functions will fail if:
[ 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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

SEE ALSO

pthread_mutex_init(), pthread_mutex_lock(), pthread_mutex_unlock(), pthread_mutex_trylock(), <pthread.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_mutex_getprioceiling(), pthread_mutex_lock(), pthread_mutex_unlock(), pthread_mutex_setprioceiling(), pthread_mutex_trylock(), pthread_mutexattr_getpshared(), pthread_mutexattr_setpshared(), <pthread.h>.

______________________________________________________________________

NAME

pthread_mutex_lock, pthread_mutex_trylock, pthread_mutex_unlock − lock and unlock a mutex

SYNOPSIS

#include <pthread.h>

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

The mutex object referenced by mutex is locked by calling pthread_mutex_lock(). If the mutex is already locked, the calling thread blocks until the mutex becomes available. This operation returns with the mutex object referenced by mutex in the locked state with the calling thread as its owner.

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

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

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

The pthread_mutex_lock() and pthread_mutex_trylock() functions will fail if:
[ 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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

SEE ALSO

pthread_mutex_init(), pthread_mutex_destroy(), <pthread.h>.

______________________________________________________________________

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

ERRORS

The pthread_mutex_getprioceiling() and pthread_mutex_setprioceiling() functions will fail if:
[ 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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

SEE ALSO

pthread_mutex_init(), pthread_mutex_lock(), pthread_mutex_unlock(), pthread_mutex_trylock(), <pthread.h>.

______________________________________________________________________

NAME

pthread_mutex_lock, pthread_mutex_trylock, pthread_mutex_unlock − lock and unlock a mutex

SYNOPSIS

#include <pthread.h>

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

The mutex object referenced by mutex is locked by calling pthread_mutex_lock(). If the mutex is already locked, the calling thread blocks until the mutex becomes available. This operation returns with the mutex object referenced by mutex in the locked state with the calling thread as its owner.

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

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

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

The pthread_mutex_lock() and pthread_mutex_trylock() functions will fail if:
[ 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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

SEE ALSO

pthread_mutex_init(), pthread_mutex_destroy(), <pthread.h>.

______________________________________________________________________

NAME

pthread_mutex_lock, pthread_mutex_trylock, pthread_mutex_unlock − lock and unlock a mutex

SYNOPSIS

#include <pthread.h>

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

The mutex object referenced by mutex is locked by calling pthread_mutex_lock(). If the mutex is already locked, the calling thread blocks until the mutex becomes available. This operation returns with the mutex object referenced by mutex in the locked state with the calling thread as its owner.

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

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

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

The pthread_mutex_lock() and pthread_mutex_trylock() functions will fail if:
[ 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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

SEE ALSO

pthread_mutex_init(), pthread_mutex_destroy(), <pthread.h>.

______________________________________________________________________

NAME

pthread_mutexattr_init, pthread_mutexattr_destroy − initialise and destroy mutex attributes object

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

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

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

Upon successful completion, pthread_mutexattr_init() and pthread_mutexattr_destroy() return zero. Otherwise, an error number is returned to indicate the error.

ERRORS

The pthread_mutexattr_init() function may fail if:
[ 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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

SEE ALSO

pthread_create(), pthread_mutex_init(), pthread_mutexattr_init(), pthread_cond_init(), <pthread.h>.

______________________________________________________________________

NAME

pthread_mutexattr_setprioceiling, pthread_mutexattr_getprioceiling − set and get prioceiling attribute of mutex attribute object (REALTIME THREADS)

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

The pthread_mutexattr_setprioceiling() and pthread_mutexattr_getprioceiling() functions, respectively, set and get the priority ceiling attribute of a mutex attribute object pointed to by attr which was previously created by the function pthread_mutexattr_init().

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

Upon successful completion, the pthread_mutexattr_setprioceiling() and pthread_mutexattr_getprioceiling() functions return zero. Otherwise, an error number is returned to indicate the error.

ERRORS

The pthread_mutexattr_setprioceiling() and pthread_mutexattr_getprioceiling() functions will fail if:
[ 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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

SEE ALSO

pthread_create(), pthread_mutex_init(), pthread_cond_init(), <pthread.h>.

______________________________________________________________________

NAME

pthread_mutexattr_setprotocol, pthread_mutexattr_getprotocol − set and get protocol attribute of mutex attribute object (REALTIME THREADS)

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

The pthread_mutexattr_setprotocol() and pthread_mutexattr_getprotocol() functions, respectively, set and get the protocol attribute of a mutex attribute object pointed to by attr which was previously created by the function pthread_mutexattr_init().

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

Upon successful completion, the pthread_mutexattr_setprotocol() and pthread_mutexattr_getprotocol() functions return zero. Otherwise, an error number is returned to indicate the error.

ERRORS

The pthread_mutexattr_setprotocol() and pthread_mutexattr_getprotocol() functions will fail if:
[ 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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

SEE ALSO

pthread_create(), pthread_mutex_init(), pthread_cond_init(), <pthread.h>.

______________________________________________________________________

NAME

pthread_mutexattr_getpshared, pthread_mutexattr_setpshared − set and get process−shared attribute

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

The pthread_mutexattr_getpshared() function obtains the value of the process-shared attribute from the attributes object referenced by attr. The pthread_mutexattr_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 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_setpshared() returns zero. Otherwise, an error number is returned to indicate the error.

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

The pthread_mutexattr_getpshared() and pthread_mutexattr_setpshared() functions may fail if:
[ 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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

SEE ALSO

pthread_create(), pthread_mutex_init(), pthread_mutexattr_init(), pthread_cond_init(), <pthread.h>.

______________________________________________________________________

NAME

pthread_mutexattr_gettype, pthread_mutexattr_settype − get or set a mutex type

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

The pthread_mutexattr_gettype() and pthread_mutexattr_settype() functions respectively get and set the mutex type attribute. This attribute is set in the type parameter to these functions. The default value of the type attribute is PTHREAD_MUTEX_DEFAULT .

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

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

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

The pthread_mutexattr_gettype() and pthread_mutexattr_settype() functions will fail if:
[ 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

None.

APPLICATION USAGE

It is advised that an application should not use a PTHREAD_MUTEX_RECURSIVE mutex with condition variables because the implicit unlock performed for a pthread_cond_wait() or pthread_cond_timedwait() may not actually release the mutex (if it had been locked multiple times). If this happens, no other thread can satisfy the condition of the predicate.

FUTURE DIRECTIONS

None.

SEE ALSO

pthread_cond_wait(), pthread_cond_timedwait(), <pthread.h>.

______________________________________________________________________

NAME

pthread_mutexattr_init, pthread_mutexattr_destroy − initialise and destroy mutex attributes object

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

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

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

Upon successful completion, pthread_mutexattr_init() and pthread_mutexattr_destroy() return zero. Otherwise, an error number is returned to indicate the error.

ERRORS

The pthread_mutexattr_init() function may fail if:
[ 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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

SEE ALSO

pthread_create(), pthread_mutex_init(), pthread_mutexattr_init(), pthread_cond_init(), <pthread.h>.

______________________________________________________________________

NAME

pthread_mutexattr_setprioceiling, pthread_mutexattr_getprioceiling − set and get prioceiling attribute of mutex attribute object (REALTIME THREADS)

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

The pthread_mutexattr_setprioceiling() and pthread_mutexattr_getprioceiling() functions, respectively, set and get the priority ceiling attribute of a mutex attribute object pointed to by attr which was previously created by the function pthread_mutexattr_init().

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

Upon successful completion, the pthread_mutexattr_setprioceiling() and pthread_mutexattr_getprioceiling() functions return zero. Otherwise, an error number is returned to indicate the error.

ERRORS

The pthread_mutexattr_setprioceiling() and pthread_mutexattr_getprioceiling() functions will fail if:
[ 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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

SEE ALSO

pthread_create(), pthread_mutex_init(), pthread_cond_init(), <pthread.h>.

______________________________________________________________________

NAME

pthread_mutexattr_setprotocol, pthread_mutexattr_getprotocol − set and get protocol attribute of mutex attribute object (REALTIME THREADS)

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

The pthread_mutexattr_setprotocol() and pthread_mutexattr_getprotocol() functions, respectively, set and get the protocol attribute of a mutex attribute object pointed to by attr which was previously created by the function pthread_mutexattr_init().

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

Upon successful completion, the pthread_mutexattr_setprotocol() and pthread_mutexattr_getprotocol() functions return zero. Otherwise, an error number is returned to indicate the error.

ERRORS

The pthread_mutexattr_setprotocol() and pthread_mutexattr_getprotocol() functions will fail if:
[ 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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

SEE ALSO

pthread_create(), pthread_mutex_init(), pthread_cond_init(), <pthread.h>.

______________________________________________________________________

NAME

pthread_mutexattr_getpshared, pthread_mutexattr_setpshared − set and get process−shared attribute

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

The pthread_mutexattr_getpshared() function obtains the value of the process-shared attribute from the attributes object referenced by attr. The pthread_mutexattr_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 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_setpshared() returns zero. Otherwise, an error number is returned to indicate the error.

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

The pthread_mutexattr_getpshared() and pthread_mutexattr_setpshared() functions may fail if:
[ 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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

SEE ALSO

pthread_create(), pthread_mutex_init(), pthread_mutexattr_init(), pthread_cond_init(), <pthread.h>.

______________________________________________________________________

NAME

pthread_mutexattr_gettype, pthread_mutexattr_settype − get or set a mutex type

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

The pthread_mutexattr_gettype() and pthread_mutexattr_settype() functions respectively get and set the mutex type attribute. This attribute is set in the type parameter to these functions. The default value of the type attribute is PTHREAD_MUTEX_DEFAULT .

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

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

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

The pthread_mutexattr_gettype() and pthread_mutexattr_settype() functions will fail if:
[ 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

None.

APPLICATION USAGE

It is advised that an application should not use a PTHREAD_MUTEX_RECURSIVE mutex with condition variables because the implicit unlock performed for a pthread_cond_wait() or pthread_cond_timedwait() may not actually release the mutex (if it had been locked multiple times). If this happens, no other thread can satisfy the condition of the predicate.

FUTURE DIRECTIONS

None.

SEE ALSO

pthread_cond_wait(), pthread_cond_timedwait(), <pthread.h>.

______________________________________________________________________

NAME

pthread_once − dynamic package initialisation

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

The first call to pthread_once() by any thread in a process, with a given once_control, will call the init_routine() with no arguments. Subsequent calls of pthread_once() with the same once_control will not call the init_routine(). On return from pthread_once(), it is guaranteed that init_routine() has completed. The once_control parameter is used to determine whether the associated initialisation routine has been called.

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

Upon successful completion, pthread_once() returns zero. Otherwise, an error number is returned to indicate the error.

ERRORS

No errors are defined.

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

EXAMPLES

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

SEE ALSO

<pthread,h>.

______________________________________________________________________

NAME

pthread_rwlock_init, pthread_rwlock_destroy − initialise or destroy a read−write lock object

SYNOPSIS

#include <pthread.h>

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

The pthread_rwlock_init() function initialises the read-write lock referenced by rwlock with the attributes referenced by attr. If attr is NULL , the default read-write lock attributes are used; the effect is the same as passing the address of a default read-write lock attributes object. Once initialised, the lock can be used any number of times without being re−initialised. Upon successful initialisation, the state of the read-write lock becomes initialised and unlocked. Results are undefined if pthread_rwlock_init() is called specifying an already initialised read-write lock. Results are undefined if a read-write lock is used without first being initialised.

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

If successful, the pthread_rwlock_init() and pthread_rwlock_destroy() functions return zero. Otherwise, an error number is returned to indicate the error. The [ EBUSY ] and [ EINVAL ] error checks, if implemented, will 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 read-write lock specified by rwlock.

ERRORS

The pthread_rwlock_init() function will fail if:
[ 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

None.

APPLICATION USAGE

Similar functions are being developed by IEEE PASC . In keeping with its objective of ensuring that CAE Specifications are fully aligned with formal standards, The Open Group intends to add any new interfaces adopted by an official IEEE standard in this area.

FUTURE DIRECTIONS

None.

SEE ALSO

<pthread.h>, pthread_rwlock_rdlock(), pthread_rwlock_wrlock(), pthread_rwlockattr_init(), pthread_rwlock_unlock().

______________________________________________________________________

NAME

pthread_rwlock_init, pthread_rwlock_destroy − initialise or destroy a read−write lock object

SYNOPSIS

#include <pthread.h>

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

The pthread_rwlock_init() function initialises the read-write lock referenced by rwlock with the attributes referenced by attr. If attr is NULL , the default read-write lock attributes are used; the effect is the same as passing the address of a default read-write lock attributes object. Once initialised, the lock can be used any number of times without being re−initialised. Upon successful initialisation, the state of the read-write lock becomes initialised and unlocked. Results are undefined if pthread_rwlock_init() is called specifying an already initialised read-write lock. Results are undefined if a read-write lock is used without first being initialised.

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

If successful, the pthread_rwlock_init() and pthread_rwlock_destroy() functions return zero. Otherwise, an error number is returned to indicate the error. The [ EBUSY ] and [ EINVAL ] error checks, if implemented, will 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 read-write lock specified by rwlock.

ERRORS

The pthread_rwlock_init() function will fail if:
[ 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

None.

APPLICATION USAGE

Similar functions are being developed by IEEE PASC . In keeping with its objective of ensuring that CAE Specifications are fully aligned with formal standards, The Open Group intends to add any new interfaces adopted by an official IEEE standard in this area.

FUTURE DIRECTIONS

None.

SEE ALSO

<pthread.h>, pthread_rwlock_rdlock(), pthread_rwlock_wrlock(), pthread_rwlockattr_init(), pthread_rwlock_unlock().

______________________________________________________________________

NAME

pthread_rwlock_rdlock, pthread_rwlock_tryrdlock − lock a read−write lock object for reading

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

The pthread_rwlock_rdlock() function applies a read lock to the read-write lock referenced by rwlock. The calling thread acquires the read lock if a writer does not hold the lock and there are no writers blocked on the lock. It is unspecified whether the calling thread acquires the lock when a writer does not hold the lock and there are writers waiting for the lock. If a writer holds the lock, the calling thread will not acquire the read lock. If the read lock is not acquired, the calling thread blocks (that is, it does not return from the pthread_rwlock_rdlock() call) until it can acquire the lock. Results are undefined if the calling thread holds a write lock on rwlock at the time the call is made.

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

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

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

The pthread_rwlock_tryrdlock() function will fail if:
[ 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

None.

APPLICATION USAGE

Similar functions are being developed by IEEE PASC . In keeping with its objective of ensuring that CAE Specifications are fully aligned with formal standards, The Open Group intends to add any new interfaces adopted by an official IEEE standard in this area.

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

None.

SEE ALSO

<pthread.h>, pthread_rwlock_init(), pthread_rwlock_wrlock(), pthread_rwlockattr_init(), pthread_rwlock_unlock().

______________________________________________________________________

NAME

pthread_rwlock_rdlock, pthread_rwlock_tryrdlock − lock a read−write lock object for reading

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

The pthread_rwlock_rdlock() function applies a read lock to the read-write lock referenced by rwlock. The calling thread acquires the read lock if a writer does not hold the lock and there are no writers blocked on the lock. It is unspecified whether the calling thread acquires the lock when a writer does not hold the lock and there are writers waiting for the lock. If a writer holds the lock, the calling thread will not acquire the read lock. If the read lock is not acquired, the calling thread blocks (that is, it does not return from the pthread_rwlock_rdlock() call) until it can acquire the lock. Results are undefined if the calling thread holds a write lock on rwlock at the time the call is made.

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

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

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

The pthread_rwlock_tryrdlock() function will fail if:
[ 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

None.

APPLICATION USAGE

Similar functions are being developed by IEEE PASC . In keeping with its objective of ensuring that CAE Specifications are fully aligned with formal standards, The Open Group intends to add any new interfaces adopted by an official IEEE standard in this area.

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

None.

SEE ALSO

<pthread.h>, pthread_rwlock_init(), pthread_rwlock_wrlock(), pthread_rwlockattr_init(), pthread_rwlock_unlock().

______________________________________________________________________

NAME

pthread_rwlock_wrlock, pthread_rwlock_trywrlock − lock a read−write lock object for writing

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

The pthread_rwlock_wrlock() function applies a write lock to the read-write lock referenced by rwlock. The calling thread acquires the write lock if no other thread (reader or writer) holds the read-write lock rwlock. Otherwise, the thread blocks (that is, does not return from the pthread_rwlock_wrlock() call) until it can acquire the lock. Results are undefined if the calling thread holds the read-write lock (whether a read or write lock) at the time the call is made.

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

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

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

The pthread_rwlock_trywrlock() function will fail if:
[ 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

None.

APPLICATION USAGE

Similar functions are being developed by IEEE PASC . In keeping with its objective of ensuring that CAE Specifications are fully aligned with formal standards, The Open Group intends to add any new interfaces adopted by an official IEEE standard in this area.

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

None.

SEE ALSO

<pthread.h>, pthread_rwlock_init(), pthread_rwlock_unlock(), pthread_rwlockattr_init(), pthread_rwlock_rdlock().

______________________________________________________________________

NAME

pthread_rwlock_unlock − unlock a read−write lock object

SYNOPSIS

#include <pthread.h>

int pthread_rwlock_unlock(pthread_rwlock_t *rwlock);

DESCRIPTION

The pthread_rwlock_unlock() function is called to release a lock held on the read-write lock object referenced by rwlock. Results are undefined if the read-write lock rwlock is not held by the calling thread.

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

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

ERRORS

The pthread_rwlock_unlock() function may fail if:
[ 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

None.

APPLICATION USAGE

Similar functions are being developed by IEEE PASC . In keeping with its objective of ensuring that CAE Specifications are fully aligned with formal standards, The Open Group intends to add any new interfaces adopted by an official IEEE standard in this area.

FUTURE DIRECTIONS

None.

SEE ALSO

<pthread.h>, pthread_rwlock_init(), pthread_rwlock_wrlock(), pthread_rwlockattr_init(), pthread_rwlock_rdlock().

______________________________________________________________________

NAME

pthread_rwlock_wrlock, pthread_rwlock_trywrlock − lock a read−write lock object for writing

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

The pthread_rwlock_wrlock() function applies a write lock to the read-write lock referenced by rwlock. The calling thread acquires the write lock if no other thread (reader or writer) holds the read-write lock rwlock. Otherwise, the thread blocks (that is, does not return from the pthread_rwlock_wrlock() call) until it can acquire the lock. Results are undefined if the calling thread holds the read-write lock (whether a read or write lock) at the time the call is made.

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

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

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

The pthread_rwlock_trywrlock() function will fail if:
[ 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

None.

APPLICATION USAGE

Similar functions are being developed by IEEE PASC . In keeping with its objective of ensuring that CAE Specifications are fully aligned with formal standards, The Open Group intends to add any new interfaces adopted by an official IEEE standard in this area.

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

None.

SEE ALSO

<pthread.h>, pthread_rwlock_init(), pthread_rwlock_unlock(), pthread_rwlockattr_init(), pthread_rwlock_rdlock().

______________________________________________________________________

NAME

pthread_rwlockattr_init, pthread_rwlockattr_destroy − initialise and destroy read−write lock attributes object

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

The function pthread_rwlockattr_init() initialises a read-write lock attributes object attr with the default value for all of the attributes defined by the implementation.

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

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

ERRORS

The pthread_rwlockattr_init() function will fail if:
[ 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

None.

APPLICATION USAGE

Similar functions are being developed by IEEE PASC . In keeping with its objective of ensuring that CAE Specifications are fully aligned with formal standards, The Open Group intends to add any new interfaces adopted by an official IEEE standard in this area.

FUTURE DIRECTIONS

None.

SEE ALSO

<pthread.h>, pthread_rwlock_init(), pthread_rwlock_unlock(), pthread_rwlock_wrlock(), pthread_rwlock_rdlock(), pthread_rwlockattr_getpshared().

______________________________________________________________________

NAME

pthread_rwlockattr_getpshared, pthread_rwlockattr_setpshared − get and set process−shared attribute of read−write lock attributes object

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

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

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

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

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

The pthread_rwlockattr_getpshared() and pthread_rwlockattr_setpshared() functions may fail if:
[ 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

None.

APPLICATION USAGE

Similar functions are being developed by IEEE PASC . In keeping with its objective of ensuring that CAE Specifications are fully aligned with formal standards, The Open Group intends to add any new interfaces adopted by an official IEEE standard in this area.

FUTURE DIRECTIONS

None.

SEE ALSO

<pthread.h>, pthread_rwlock_init(), pthread_rwlock_unlock(), pthread_rwlock_wrlock(), pthread_rwlock_rdlock(), pthread_rwlockattr_init().

______________________________________________________________________

NAME

pthread_rwlockattr_init, pthread_rwlockattr_destroy − initialise and destroy read−write lock attributes object

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

The function pthread_rwlockattr_init() initialises a read-write lock attributes object attr with the default value for all of the attributes defined by the implementation.

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

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

ERRORS

The pthread_rwlockattr_init() function will fail if:
[ 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

None.

APPLICATION USAGE

Similar functions are being developed by IEEE PASC . In keeping with its objective of ensuring that CAE Specifications are fully aligned with formal standards, The Open Group intends to add any new interfaces adopted by an official IEEE standard in this area.

FUTURE DIRECTIONS

None.

SEE ALSO

<pthread.h>, pthread_rwlock_init(), pthread_rwlock_unlock(), pthread_rwlock_wrlock(), pthread_rwlock_rdlock(), pthread_rwlockattr_getpshared().

______________________________________________________________________

NAME

pthread_rwlockattr_getpshared, pthread_rwlockattr_setpshared − get and set process−shared attribute of read−write lock attributes object

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

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

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

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

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

The pthread_rwlockattr_getpshared() and pthread_rwlockattr_setpshared() functions may fail if:
[ 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

None.

APPLICATION USAGE

Similar functions are being developed by IEEE PASC . In keeping with its objective of ensuring that CAE Specifications are fully aligned with formal standards, The Open Group intends to add any new interfaces adopted by an official IEEE standard in this area.

FUTURE DIRECTIONS

None.

SEE ALSO

<pthread.h>, pthread_rwlock_init(), pthread_rwlock_unlock(), pthread_rwlock_wrlock(), pthread_rwlock_rdlock(), pthread_rwlockattr_init().

______________________________________________________________________

NAME

pthread_self − get calling thread’s ID

SYNOPSIS

#include <pthread.h>

pthread_t pthread_self(void);

DESCRIPTION

The pthread_self() function returns the thread ID of the calling thread.

RETURN VALUE

See DESCRIPTION above.

ERRORS

No errors are defined.

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

EXAMPLES

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

SEE ALSO

pthread_create(), pthread_equal(), <pthread.h>.

______________________________________________________________________

NAME

pthread_setcancelstate, pthread_setcanceltype, pthread_testcancel − set cancelability state

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

The pthread_setcancelstate() function atomically both sets the calling thread’s cancelability state to the indicated state and returns the previous cancelability state at the location referenced by oldstate. Legal values for state are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DISABLE .

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

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

ERRORS

The pthread_setcancelstate() function may fail if:
[ 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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

SEE ALSO

pthread_cancel(), <pthread.h>.

______________________________________________________________________

NAME

pthread_setcancelstate, pthread_setcanceltype, pthread_testcancel − set cancelability state

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

The pthread_setcancelstate() function atomically both sets the calling thread’s cancelability state to the indicated state and returns the previous cancelability state at the location referenced by oldstate. Legal values for state are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DISABLE .

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

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

ERRORS

The pthread_setcancelstate() function may fail if:
[ 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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

SEE ALSO

pthread_cancel(), <pthread.h>.

______________________________________________________________________

NAME

pthread_setconcurrency − get or set level of concurrency

SYNOPSIS

#include <pthread.h>

int pthread_setconcurrency(int new_level);

DESCRIPTION

Refer to pthread_getconcurrency().

______________________________________________________________________

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.

SEE ALSO

sched_setparam(), sched_getparam(), sched_setscheduler(), sched_getscheduler(), <pthread.h>, <sched.h>.

______________________________________________________________________

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.

SEE ALSO

pthread_key_create(), <pthread.h>.

______________________________________________________________________

NAME

pthread_sigmask − examine and change blocked signals

SYNOPSIS

#include <signal.h>

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

DESCRIPTION

Refer to sigprocmask().

______________________________________________________________________

NAME

pthread_setcancelstate, pthread_setcanceltype, pthread_testcancel − set cancelability state

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

The pthread_setcancelstate() function atomically both sets the calling thread’s cancelability state to the indicated state and returns the previous cancelability state at the location referenced by oldstate. Legal values for state are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DISABLE .

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

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

ERRORS

The pthread_setcancelstate() function may fail if:
[ 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

None.

APPLICATION USAGE

None.

FUTURE DIRECTIONS

None.

SEE ALSO

pthread_cancel(), <pthread.h>.