*** /dev/null Sat Nov 23 01:33:07 2024
--- - Sat Nov 23 01:33:09 2024
***************
*** 0 ****
--- 1,9843 ----
+ ##
+ ## GNU Pth - The GNU Portable Threads
+ ## Copyright (c) 1999-2000 Ralf S. Engelschall <rse@engelschall.com>
+ ##
+ ## This file is part of GNU Pth, a non-preemptive thread scheduling
+ ## library which can be found at http://www.gnu.org/software/pth/.
+ ##
+ ## This library is free software; you can redistribute it and/or
+ ## modify it under the terms of the GNU Lesser General Public
+ ## License as published by the Free Software Foundation; either
+ ## version 2.1 of the License, or (at your option) any later version.
+ ##
+ ## This library is distributed in the hope that it will be useful,
+ ## but WITHOUT ANY WARRANTY; without even the implied warranty of
+ ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ ## Lesser General Public License for more details.
+ ##
+ ## You should have received a copy of the GNU Lesser General Public
+ ## License along with this library; if not, write to the Free Software
+ ## Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
+ ## USA, or contact Ralf S. Engelschall <rse@engelschall.com>.
+ ##
+ ## pthread.pod: POSIX.1c Threads ("Pthreads") manual page for Pth
+ ##
+ ## This manual page includes parts from:
+ ## The Single UNIX Specification, Version 2 - Threads
+ ## http://www.opengroup.org/onlinepubs/007908799/xsh/threads.html
+ ## Copyright (C) 1997 The Open Group, All Rights Reserved.
+ ##
+ ##
+ # ``The trouble with computers is that they
+ # do what you tell them, not what you want.''
+
+ =pod
+
+ =head1 NAME
+
+ B<pthread> - POSIX.1c Threading API of GNU Pth
+
+ =head1 VERSION
+
+ GNU Pth PTH_VERSION_STR
+
+ =head1 SYNOPSIS
+
+ B<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`
+
+ B<Application source files:>
+
+ #include <pthread.h>
+
+ =head1 DESCRIPTION
+
+ =head2 Overview
+
+ This is the IEEE Std. 1003.1c ("POSIX.1c") conforming threading API of
+ GNU Portable Threads (B<Pth>). This API is commonly known as ``I<POSIX
+ threads>'' or in short ``I<Pthreads>''. It is provided by B<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 B<Pth> API functions.
+
+ =head2 Supported Features
+
+ The following defined feature macros in C<pthread.h> indicate supported
+ features:
+
+ #define _POSIX_THREADS
+ #define _POSIX_THREAD_ATTR_STACKADDR
+ #define _POSIX_THREAD_ATTR_STACKSIZE
+
+ The following undefined feature macros in C<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
+
+ =head2 Notes
+
+ A few notes which you should keep in mind when working with the B<Pth> Pthread
+ API.
+
+ =over 4
+
+ =item B<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 B<Pth>
+ (B<Pth> for portability reasons is a pure non-preemptive thread scheduling
+ system). So there is no implicit yielding of execution control unless you can
+ C<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.
+
+ =item B<Conflicts with Vendor Implementation>
+
+ There can be a conflict between the B<Pth> C<pthread.h> header and a possibly
+ existing vendor C</usr/include/pthread.h> header which was implicitly included
+ by some standard vendor headers (like C</usr/include/unistd.h>). When this
+ occurs try to ``C<#define>'' header-dependent values which prevent the
+ inclusion of the vendor header.
+
+ =back
+
+ =head2 Further Reading
+
+ There is ``I<The Single UNIX Specification, Version
+ 2 - Threads>'', from I<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 I<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 C<pthread.c> and C<pthread.h> in the B<Pth>
+ source tree for details of the implementation, of course.
+
+ =head1 SEE ALSO
+
+ pthread-config(1), pth(3).
+
+ =head1 AUTHOR
+
+ Ralf S. Engelschall
+ rse@engelschall.com
+ www.engelschall.com
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread.h> - threads
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ =head1 DESCRIPTION
+
+ The
+ I<<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 B<pthread_attr_t>, B<pthread_cond_t>, B<pthread_condattr_t>,
+ B<pthread_key_t>, B<pthread_mutex_t>, B<pthread_mutexattr_t>,
+ B<pthread_once_t>, B<pthread_rwlock_t>, B<pthread_rwlockattr_t> and
+ B<pthread_t> types are defined as described in I<<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 I<<pthread.h>> header will make visible symbols defined
+ in the headers I<<sched.h>> and I<<time.h>>.
+
+ =head1 APPLICATION USAGE
+
+ An interpretation request has been filed with IEEE PASC concerning
+ requirements for visibility of symbols in this header.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_attr_init()>,
+ I<pthread_attr_getguardsize()>,
+ I<pthread_attr_setscope()>,
+ I<pthread_cancel()>,
+ I<pthread_cleanup_push()>,
+ I<pthread_cond_init()>,
+ I<pthread_cond_signal()>,
+ I<pthread_cond_wait()>,
+ I<pthread_condattr_init()>,
+ I<pthread_create()>,
+ I<pthread_detach()>,
+ I<pthread_equal()>,
+ I<pthread_exit()>,
+ I<pthread_getconcurrency()>,
+ I<pthread_getschedparam()>,
+ I<pthread_join()>,
+ I<pthread_key_create()>,
+ I<pthread_key_delete()>,
+ I<pthread_mutex_init()>,
+ I<pthread_mutex_lock()>,
+ I<pthread_mutex_setprioceiling()>,
+ I<pthread_mutexattr_init()>,
+ I<pthread_mutexattr_gettype()>,
+ I<pthread_mutexattr_setprotocol()>,
+ I<pthread_once()>,
+ I<pthread_self()>,
+ I<pthread_setcancelstate()>,
+ I<pthread_setspecific()>,
+ I<pthread_rwlock_init()>,
+ I<pthread_rwlock_rdlock()>,
+ I<pthread_rwlock_unlock()>,
+ I<pthread_rwlock_wrlock()>,
+ I<pthread_rwlockattr_init()>,
+ I<<sched.h>>,
+ I<<time.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_atfork> - register fork handlers
+
+ =head1 SYNOPSIS
+
+ #include <sys/types.h>
+
+ #include <unistd.h>
+
+ int pthread_atfork(void (*I<prepare>)(void), void (*I<parent>)(void),
+ void (*I<child>)(void));
+
+ =head1 DESCRIPTION
+
+ The I<pthread_atfork()> function declares fork handlers to be called
+ before and after I<fork()>, in the context of the thread that called
+ I<fork()>. The I<prepare> fork handler is called before I<fork()>
+ processing commences. The I<parent> fork handle is called after
+ I<fork()> processing completes in the parent process. The I<child> fork
+ handler is called after I<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 I<pthread_atfork()> is significant. The I<parent>
+ and I<child> fork handlers are called in the order in which they were
+ established by calls to I<pthread_atfork()>. The I<prepare> fork
+ handlers are called in the opposite order.
+
+ =head1 RETURN VALUE
+
+ Upon successful completion, I<pthread_atfork()> returns a value of zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The I<pthread_atfork()> function will fail if:
+
+ =over 4
+
+ =item [ENOMEM]
+
+ Insufficient table space exists to record the fork handler addresses.
+
+ =back
+
+ The I<pthread_atfork()> function will not return an error code of
+ [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<atexit()>,
+ I<fork()>,
+ I<<sys/types.h>>
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_attr_init,> B<pthread_attr_destroy>
+ - initialise and destroy threads attribute object
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_attr_init(pthread_attr_t *I<attr>);
+
+ int pthread_attr_destroy(pthread_attr_t *I<attr>);
+
+ =head1 DESCRIPTION
+
+ The function I<pthread_attr_init()> initialises a thread attributes
+ object I<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 I<pthread_create()>, defines the
+ attributes of the thread created. A single attributes object can be used
+ in multiple simultaneous calls to I<pthread_create()>.
+
+ The I<pthread_attr_destroy()> function is used to destroy a thread
+ attributes object. An implementation may cause I<pthread_attr_destroy()>
+ to set I<attr> to an implementation-dependent invalid value. The
+ behaviour of using the attribute after it has been destroyed is
+ undefined.
+
+ =head1 RETURN VALUE
+
+ Upon successful completion, I<pthread_attr_init()> and
+ I<pthread_attr_destroy()> return a value of 0. Otherwise, an error
+ number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The I<pthread_attr_init()> function will fail if:
+
+ =over 4
+
+ =item [ENOMEM]
+
+ Insufficient memory exists to initialise the thread attributes object.
+
+ =back
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_attr_setstackaddr()>,
+ I<pthread_attr_setstacksize()>,
+ I<pthread_attr_setdetachstate()>,
+ I<pthread_create()>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_attr_setdetachstate,> B<pthread_attr_getdetachstate>
+ - set and get detachstate attribute
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_attr_setdetachstate(pthread_attr_t *I<attr>, int I<detachstate>);
+
+ int pthread_attr_getdetachstate(const pthread_attr_t *I<attr>, int *I<detachstate>);
+
+ =head1 DESCRIPTION
+
+ The I<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 I<pthread_detach()> or I<pthread_join()>
+ function is an error.
+
+ The I<pthread_attr_setdetachstate()> and
+ I<pthread_attr_getdetachstate()>, respectively, set and get the
+ I<detachstate> attribute in the I<attr> object.
+
+ The I<detachstate> can be set to either PTHREAD_CREATE_DETACHED or
+ PTHREAD_CREATE_JOINABLE. A value of PTHREAD_CREATE_DETACHED causes
+ all threads created with I<attr> to be in the detached state, whereas
+ using a value of PTHREAD_CREATE_JOINABLE causes all threads created
+ with I<attr> to be in the joinable state. The default value of the
+ I<detachstate> attribute is PTHREAD_CREATE_JOINABLE .
+
+ =head1 RETURN VALUE
+
+ Upon successful completion, I<pthread_attr_setdetachstate()> and
+ I<pthread_attr_getdetachstate()> return a value of 0. Otherwise, an
+ error number is returned to indicate the error.
+
+ The I<pthread_attr_getdetachstate()> function stores the value of the
+ I<detachstate> attribute in I<detachstate> if successful.
+
+ =head1 ERRORS
+
+ The I<pthread_attr_setdetachstate()> function will fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value of I<detachstate> was not valid
+
+ =back
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_attr_init()>,
+ I<pthread_attr_setstackaddr()>,
+ I<pthread_attr_setstacksize()>,
+ I<pthread_create()>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_attr_getguardsize,> B<pthread_attr_setguardsize> -
+ get or set the thread guardsize attribute
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_attr_getguardsize(const pthread_attr_t I<*attr>, size_t
+ I<*guardsize>); int pthread_attr_setguardsize(pthread_attr_t I<*attr>,
+ size_t I<guardsize>);
+
+ =head1 DESCRIPTION
+
+ The I<guardsize> attribute controls the size of the guard area for the
+ created thread's stack. The I<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 I<guardsize> attribute is provided to the application
+ for two reasons:
+
+ =over 4
+
+ =item 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.
+
+ =item 2.
+
+ When threads allocate large data structures on the stack,
+ large guard areas may be needed to detect stack overflow.
+
+ =back
+
+ The I<pthread_attr_getguardsize()> function gets the I<guardsize>
+ attribute in the I<attr> object. This attribute is returned in the
+ I<guardsize> parameter.
+
+ The I<pthread_attr_setguardsize()> function sets the I<guardsize>
+ attribute in the I<attr> object. The new value of this attribute is
+ obtained from the I<guardsize> parameter. If I<guardsize> is zero,
+ a guard area will not be provided for threads created with I<attr>.
+ If I<guardsize> is greater than zero, a guard area of at least size
+ I<guardsize> bytes is provided for each thread created with I<attr>.
+
+ A conforming implementation is permitted to round up the value
+ contained in I<guardsize> to a multiple of the configurable system
+ variable PAGESIZE (see I<<sys/mman.h>>). If an implementation rounds
+ up the value of I<guardsize> to a multiple of PAGESIZE, a call to
+ I<pthread_attr_getguardsize()> specifying I<attr> will store in the
+ I<guardsize> parameter the guard size specified by the previous
+ I<pthread_attr_setguardsize()> function call.
+
+ The default value of the I<guardsize> attribute is PAGESIZE bytes. The
+ actual value of PAGESIZE is implementation-dependent and may not be the
+ same on all implementations.
+
+ If the I<stackaddr> attribute has been set (that is, the caller is
+ allocating and managing its own thread stacks), the I<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.
+
+ =head1 RETURN VALUE
+
+ If successful, the I<pthread_attr_getguardsize()> and
+ I<pthread_attr_setguardsize()> functions return zero. Otherwise, an
+ error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The I<pthread_attr_getguardsize()> and I<pthread_attr_setguardsize()>
+ functions will fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The attribute I<attr> is invalid.
+
+ =item [EINVAL]
+
+ The parameter I<guardsize> is invalid.
+
+ =item [EINVAL]
+
+ The parameter I<guardsize> contains an invalid value.
+
+ =back
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_attr_setinheritsched,> B<pthread_attr_getinheritsched>
+ - set and get inheritsched attribute
+ (B<REALTIME THREADS>)
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_attr_setinheritsched(pthread_attr_t *I<attr>,
+ int I<inheritsched>);
+ int pthread_attr_getinheritsched(const pthread_attr_t *I<attr>,
+ int *I<inheritsched>);
+
+ =head1 DESCRIPTION
+
+ The functions I<pthread_attr_setinheritsched()> and
+ I<pthread_attr_getinheritsched()>, respectively, set and get the
+ I<inheritsched> attribute in the I<attr> argument.
+
+ When the attribute objects are used by I<pthread_create()>, the
+ I<inheritsched> attribute determines how the other scheduling attributes
+ of the created thread are to be set:
+
+ =over 4
+
+ =item 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 I<attr> argument are to be ignored.
+
+ =item PTHREAD_EXPLICIT_SCHED
+
+ Specifies that the scheduling policy and associated attributes
+ are to be set to the corresponding values from this attribute object.
+
+ =back
+
+ The symbols PTHREAD_INHERIT_SCHED and PTHREAD_EXPLICIT_SCHED are defined
+ in the header I<<pthread.h>>.
+
+ =head1 RETURN VALUE
+
+ If successful, the I<pthread_attr_setinheritsched()> and
+ I<pthread_attr_getinheritsched()> functions return zero. Otherwise, an
+ error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The I<pthread_attr_setinheritsched()> and
+ I<pthread_attr_getinheritsched()> functions will fail if:
+
+ =over 4
+
+ =item [ENOSYS]
+
+ The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the
+ implementation does not support the function.
+
+ =back
+
+ The
+ I<pthread_attr_setinheritsched()>
+ function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value of the attribute being set is not valid.
+
+ =item [ENOTSUP]
+
+ An attempt was made to set the attribute to an unsupported value.
+
+ =back
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ After these attributes have been set, a thread can be created with the
+ specified attributes using I<pthread_create()>. Using these routines
+ does not affect the current running thread.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_attr_init()>,
+ I<pthread_attr_setscope()>,
+ I<pthread_attr_setschedpolicy()>,
+ I<pthread_attr_setschedparam()>,
+ I<pthread_create()>,
+ I<<pthread.h>>,
+ I<pthread_setschedparam()>,
+ I<<sched.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_attr_setschedparam,> B<pthread_attr_getschedparam>
+ - set and get schedparam attribute
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_attr_setschedparam(pthread_attr_t *I<attr>, const struct sched_param *I<param>);
+
+ int pthread_attr_getschedparam(const pthread_attr_t *I<attr>, struct sched_param *I<param>);
+
+ =head1 DESCRIPTION
+
+ The functions I<pthread_attr_setschedparam()> and
+ I<pthread_attr_getschedparam()>, respectively, set and get the
+ scheduling parameter attributes in the I<attr> argument. The contents of
+ the I<param> structure are defined in I<<sched.h>>. For the SCHED_FIFO
+ and SCHED_RR policies, the only required member of I<param> is
+ I<sched_priority>.
+
+ =head1 RETURN VALUE
+
+ If successful, the I<pthread_attr_setschedparam()> and
+ I<pthread_attr_getschedparam()> functions return zero. Otherwise, an
+ error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The I<pthread_attr_setschedparam()> function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value of the attribute being set is not valid.
+
+ =item [ENOTSUP]
+
+ An attempt was made to set the attribute to an unsupported value.
+
+ =back
+
+ The
+ I<pthread_attr_setschedparam()>
+ and
+ I<pthread_attr_getschedparam()>
+ functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ After these attributes have been set, a thread can be created with the
+ specified attributes using I<pthread_create()>. Using these routines
+ does not affect the current running thread.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_attr_init()>,
+ I<pthread_attr_setscope()>,
+ I<pthread_attr_setinheritsched()>,
+ I<pthread_attr_setschedpolicy()>,
+ I<pthread_create()>,
+ I<<pthread.h>>,
+ I<pthread_setschedparam()>,
+ I<<sched.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_attr_setschedpolicy,> B<pthread_attr_getschedpolicy>
+ - set and get schedpolicy attribute
+ (B<REALTIME THREADS>)
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_attr_setschedpolicy(pthread_attr_t *I<attr>, int I<policy>);
+ int pthread_attr_getschedpolicy(const pthread_attr_t *I<attr>,
+ int *I<policy>);
+
+ =head1 DESCRIPTION
+
+ The functions I<pthread_attr_setschedpolicy()> and
+ I<pthread_attr_getschedpolicy()>, respectively, set and get the
+ I<schedpolicy> attribute in the I<attr> argument.
+
+ The supported values of I<policy> include SCHED_FIFO, SCHED_RR and
+ SCHED_OTHER, which are defined by the header I<<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.
+
+ =head1 RETURN VALUE
+
+ If successful, the I<pthread_attr_setschedpolicy()> and
+ I<pthread_attr_getschedpolicy()> functions return zero. Otherwise, an
+ error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The I<pthread_attr_setschedpolicy()> and
+ I<pthread_attr_getschedpolicy()> functions will fail if:
+
+ =over 4
+
+ =item [ENOSYS]
+
+ The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the
+ implementation does not support the function.
+
+ =back
+
+ The I<pthread_attr_setschedpolicy()> function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value of the attribute being set is not valid.
+
+ =item [ENOTSUP]
+
+ An attempt was made to set the attribute to an unsupported value.
+
+ =back
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ After these attributes have been set, a thread can be created with the
+ specified attributes using I<pthread_create()>. Using these routines
+ does not affect the current running thread.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_attr_init()>,
+ I<pthread_attr_setscope()>,
+ I<pthread_attr_setinheritsched()>,
+ I<pthread_attr_setschedparam()>,
+ I<pthread_create()>,
+ I<<pthread.h>>,
+ I<pthread_setschedparam()>,
+ I<<sched.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_attr_setscope,> B<pthread_attr_getscope>
+ - set and get contentionscope attribute
+ (B<REALTIME THREADS>)
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_attr_setscope(pthread_attr_t *I<attr>, int I<contentionscope>);
+ int pthread_attr_getscope(const pthread_attr_t *I<attr>,
+ int *I<contentionscope>);
+
+ =head1 DESCRIPTION
+
+ The I<pthread_attr_setscope()> and I<pthread_attr_getscope()> functions
+ are used to set and get the I<contentionscope> attribute in the I<attr>
+ object.
+
+ The I<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 I<<pthread.h>>.
+
+ =head1 RETURN VALUE
+
+ If successful, the I<pthread_attr_setscope()> and
+ I<pthread_attr_getscope()> functions return zero. Otherwise, an error
+ number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The I<pthread_attr_setscope()> and I<pthread_attr_getscope()> functions
+ will fail if:
+
+ =over 4
+
+ =item [ENOSYS]
+
+ The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the
+ implementation does not support the function.
+
+ =back
+
+ The
+ I<pthread_attr_setscope()>,
+ function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value of the attribute being set is not valid.
+
+ =item [ENOTSUP]
+
+ An attempt was made to set the attribute to an unsupported value.
+
+ =back
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ After these attributes have been set, a thread can be created with the
+ specified attributes using I<pthread_create()>. Using these routines
+ does not affect the current running thread.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_attr_init()>,
+ I<pthread_attr_setinheritsched()>,
+ I<pthread_attr_setschedpolicy()>,
+ I<pthread_attr_setschedparam()>,
+ I<pthread_create()>,
+ I<<pthread.h>>,
+ I<pthread_setschedparam()>,
+ I<<sched.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_attr_setstackaddr,> B<pthread_attr_getstackaddr>
+ - set and get stackaddr attribute
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_attr_setstackaddr(pthread_attr_t *I<attr>, void *I<stackaddr>);
+
+ int pthread_attr_getstackaddr(const pthread_attr_t *I<attr>, void **I<stackaddr>);
+
+ =head1 DESCRIPTION
+
+ The functions I<pthread_attr_setstackaddr()> and
+ I<pthread_attr_getstackaddr()>, respectively, set and get the thread
+ creation I<stackaddr> attribute in the I<attr> object.
+
+ The I<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.
+
+ =head1 RETURN VALUE
+
+ Upon successful completion, I<pthread_attr_setstackaddr()> and
+ I<pthread_attr_getstackaddr()> return a value of 0. Otherwise, an error
+ number is returned to indicate the error.
+
+ The I<pthread_attr_getstackaddr()> function stores the I<stackaddr>
+ attribute value in I<stackaddr> if successful.
+
+ =head1 ERRORS
+
+ No errors are defined.
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_attr_init()>,
+ I<pthread_attr_setdetachstate()>,
+ I<pthread_attr_setstacksize()>,
+ I<pthread_create()>,
+ I<<limits.h>>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_attr_setstacksize,> B<pthread_attr_getstacksize>
+ - set and get stacksize attribute
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_attr_setstacksize(pthread_attr_t *I<attr>, size_t I<stacksize>);
+ int pthread_attr_getstacksize(const pthread_attr_t *I<attr>,
+ size_t *I<stacksize>);
+
+ =head1 DESCRIPTION
+
+ The functions
+ I<pthread_attr_setstacksize()>
+ and
+ I<pthread_attr_getstacksize()>,
+ respectively, set and get the thread creation
+ I<stacksize>
+ attribute in the
+ I<attr>
+ object.
+
+ The
+ I<stacksize>
+ attribute defines the minimum stack size (in bytes) allocated for
+ the created threads stack.
+
+ =head1 RETURN VALUE
+
+ Upon successful completion,
+ I<pthread_attr_setstacksize()>
+ and
+ I<pthread_attr_getstacksize()>
+ return a value of 0.
+ Otherwise, an error number is returned to indicate the error.
+ The
+ I<pthread_attr_getstacksize()>
+ function stores the
+ I<stacksize>
+ attribute value in
+ I<stacksize>
+ if successful.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_attr_setstacksize()>
+ function will fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value of
+ I<stacksize>
+ is less than PTHREAD_STACK_MIN or exceeds a system-imposed limit.
+
+ =back
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_attr_init()>,
+ I<pthread_attr_setstackaddr()>,
+ I<pthread_attr_setdetachstate()>,
+ I<pthread_create()>,
+ I<<limits.h>>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_attr_init,> B<pthread_attr_destroy>
+ - initialise and destroy threads attribute object
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_attr_init(pthread_attr_t *I<attr>);
+ int pthread_attr_destroy(pthread_attr_t *I<attr>);
+
+ =head1 DESCRIPTION
+
+ The function
+ I<pthread_attr_init()>
+ initialises a thread attributes object
+ I<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
+ I<pthread_create()>,
+ defines the attributes of the thread created.
+ A single attributes object can be used in multiple simultaneous calls to
+ I<pthread_create()>.
+
+ The
+ I<pthread_attr_destroy()>
+ function is used to destroy a thread attributes object.
+ An implementation may cause
+ I<pthread_attr_destroy()>
+ to set
+ I<attr>
+ to an implementation-dependent invalid value.
+ The behaviour of using the attribute after it has been destroyed is undefined.
+
+ =head1 RETURN VALUE
+
+ Upon successful completion,
+ I<pthread_attr_init()>
+ and
+ I<pthread_attr_destroy()>
+ return a value of 0.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_attr_init()>
+ function will fail if:
+
+ =over 4
+
+ =item [ENOMEM]
+
+ Insufficient memory exists to initialise the thread attributes object.
+
+ =back
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_attr_setstackaddr()>,
+ I<pthread_attr_setstacksize()>,
+ I<pthread_attr_setdetachstate()>,
+ I<pthread_create()>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_attr_setdetachstate,> B<pthread_attr_getdetachstate>
+ - set and get detachstate attribute
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_attr_setdetachstate(pthread_attr_t *I<attr>, int I<detachstate>);
+ int pthread_attr_getdetachstate(const pthread_attr_t *I<attr>,
+ int *I<detachstate>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<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
+ I<pthread_detach()>
+ or
+ I<pthread_join()>
+ function is an error.
+
+ The
+ I<pthread_attr_setdetachstate()>
+ and
+ I<pthread_attr_getdetachstate()>,
+ respectively, set and get the
+ I<detachstate>
+ attribute in the
+ I<attr>
+ object.
+
+ The
+ I<detachstate>
+ can be set to either PTHREAD_CREATE_DETACHED or PTHREAD_CREATE_JOINABLE.
+ A value of PTHREAD_CREATE_DETACHED causes all threads created with
+ I<attr>
+ to be in the detached state, whereas using a value of
+ PTHREAD_CREATE_JOINABLE
+ causes all threads created with
+ I<attr>
+ to be in the joinable state.
+ The default value of the
+ I<detachstate>
+ attribute is
+ PTHREAD_CREATE_JOINABLE .
+
+ =head1 RETURN VALUE
+
+ Upon successful completion,
+ I<pthread_attr_setdetachstate()>
+ and
+ I<pthread_attr_getdetachstate()>
+ return a value of 0.
+ Otherwise, an error number is returned to indicate the error.
+
+ The
+ I<pthread_attr_getdetachstate()>
+ function stores the value of the
+ I<detachstate>
+ attribute in
+ I<detachstate>
+ if successful.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_attr_setdetachstate()>
+ function will fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value of
+ I<detachstate>
+ was not valid
+
+ =back
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_attr_init()>,
+ I<pthread_attr_setstackaddr()>,
+ I<pthread_attr_setstacksize()>,
+ I<pthread_create()>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_attr_getguardsize,> B<pthread_attr_setguardsize> -
+ get or set the thread guardsize attribute
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_attr_getguardsize(const pthread_attr_t I<*attr>,
+ size_t I<*guardsize>);
+ int pthread_attr_setguardsize(pthread_attr_t I<*attr>,
+ size_t I<guardsize>);
+
+ =head1 DESCRIPTION
+
+ The I<guardsize> attribute controls the size
+ of the guard area for the created thread's stack. The I<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 I<guardsize> attribute is provided to the application
+ for two reasons:
+
+ =over 4
+
+ =item 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.
+
+ =item 2.
+
+ When threads allocate large data structures on the stack,
+ large guard areas may be needed to detect stack overflow.
+
+ =back
+
+ The
+ I<pthread_attr_getguardsize()>
+ function gets the
+ I<guardsize> attribute in the I<attr> object. This attribute is
+ returned in the I<guardsize> parameter.
+
+ The
+ I<pthread_attr_setguardsize()>
+ function sets the
+ I<guardsize> attribute in the I<attr> object. The new value of
+ this attribute is obtained from the I<guardsize> parameter.
+ If I<guardsize> is zero, a guard area will not be
+ provided for threads created with I<attr>. If I<guardsize> is
+ greater
+ than zero, a guard area of at least size I<guardsize>
+ bytes is provided for each thread created with I<attr>.
+
+ A conforming implementation is permitted to round up
+ the value contained in I<guardsize> to a multiple
+ of the configurable system variable PAGESIZE (see
+ I<<sys/mman.h>>).
+ If an implementation rounds up the
+ value of I<guardsize> to a multiple of PAGESIZE, a call to
+ I<pthread_attr_getguardsize()>
+ specifying I<attr> will
+ store in the I<guardsize> parameter the guard size specified by the
+ previous
+ I<pthread_attr_setguardsize()>
+ function call.
+
+ The default value of the I<guardsize> attribute is PAGESIZE bytes.
+ The actual value of PAGESIZE is
+ implementation-dependent and may not be the same on all implementations.
+
+ If the I<stackaddr> attribute has been set (that is, the caller
+ is allocating and managing its own thread stacks), the
+ I<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.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_attr_getguardsize()>
+ and
+ I<pthread_attr_setguardsize()>
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+
+
+ =head1 ERRORS
+
+ The
+ I<pthread_attr_getguardsize()>
+ and
+ I<pthread_attr_setguardsize()>
+ functions will fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The attribute I<attr> is invalid.
+
+ =item [EINVAL]
+
+ The parameter I<guardsize> is invalid.
+
+ =item [EINVAL]
+
+ The parameter I<guardsize> contains an invalid value.
+
+ =back
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_attr_setinheritsched,> B<pthread_attr_getinheritsched>
+ - set and get inheritsched attribute
+ (B<REALTIME THREADS>)
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_attr_setinheritsched(pthread_attr_t *I<attr>,
+ int I<inheritsched>);
+ int pthread_attr_getinheritsched(const pthread_attr_t *I<attr>,
+ int *I<inheritsched>);
+
+ =head1 DESCRIPTION
+
+ The functions
+ I<pthread_attr_setinheritsched()>
+ and
+ I<pthread_attr_getinheritsched()>,
+ respectively, set and get the
+ I<inheritsched>
+ attribute in the
+ I<attr>
+ argument.
+
+ When the attribute objects are used by
+ I<pthread_create()>,
+ the
+ I<inheritsched>
+ attribute determines how the other scheduling attributes of
+ the created thread are to be set:
+
+ =over 4
+
+ =item 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
+ I<attr>
+ argument are to be ignored.
+
+ =item PTHREAD_EXPLICIT_SCHED
+
+ Specifies that the scheduling policy and associated attributes
+ are to be set to the corresponding values from this attribute object.
+
+ =back
+
+ The symbols PTHREAD_INHERIT_SCHED and PTHREAD_EXPLICIT_SCHED
+ are defined in the header
+ I<<pthread.h>>.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_attr_setinheritsched()>
+ and
+ I<pthread_attr_getinheritsched()>
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_attr_setinheritsched()>
+ and
+ I<pthread_attr_getinheritsched()>
+ functions will fail if:
+
+ =over 4
+
+ =item [ENOSYS]
+
+ The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the
+ implementation does not support the function.
+
+ =back
+
+ The
+ I<pthread_attr_setinheritsched()>
+ function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value of the attribute being set is not valid.
+
+ =item [ENOTSUP]
+
+ An attempt was made to set the attribute to an unsupported value.
+
+ =back
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ After these attributes have been set, a thread can be created with
+ the specified attributes using
+ I<pthread_create()>.
+ Using these routines does not affect the current running thread.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_attr_init()>,
+ I<pthread_attr_setscope()>,
+ I<pthread_attr_setschedpolicy()>,
+ I<pthread_attr_setschedparam()>,
+ I<pthread_create()>,
+ I<<pthread.h>>,
+ I<pthread_setschedparam()>,
+ I<<sched.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_attr_setschedparam,> B<pthread_attr_getschedparam>
+ - set and get schedparam attribute
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_attr_setschedparam(pthread_attr_t *I<attr>,
+ const struct sched_param *I<param>);
+ int pthread_attr_getschedparam(const pthread_attr_t *I<attr>,
+ struct sched_param *I<param>);
+
+ =head1 DESCRIPTION
+
+ The functions
+ I<pthread_attr_setschedparam()>
+ and
+ I<pthread_attr_getschedparam()>,
+ respectively, set and get the scheduling parameter
+ attributes in the
+ I<attr>
+ argument.
+ The contents of the
+ I<param>
+ structure are defined in
+ I<<sched.h>>.
+ For the SCHED_FIFO and SCHED_RR policies,
+ the only required member of
+ I<param>
+ is
+ I<sched_priority>.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_attr_setschedparam()>
+ and
+ I<pthread_attr_getschedparam()>
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_attr_setschedparam()>
+ function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value of the attribute being set is not valid.
+
+ =item [ENOTSUP]
+
+ An attempt was made to set the attribute to an unsupported value.
+
+ =back
+
+ The
+ I<pthread_attr_setschedparam()>
+ and
+ I<pthread_attr_getschedparam()>
+ functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ After these attributes have been set, a thread can be created with
+ the specified attributes using
+ I<pthread_create()>.
+ Using these routines does not affect the current running thread.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_attr_init()>,
+ I<pthread_attr_setscope()>,
+ I<pthread_attr_setinheritsched()>,
+ I<pthread_attr_setschedpolicy()>,
+ I<pthread_create()>,
+ I<<pthread.h>>,
+ I<pthread_setschedparam()>,
+ I<<sched.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_attr_setschedpolicy,> B<pthread_attr_getschedpolicy>
+ - set and get schedpolicy attribute
+ (B<REALTIME THREADS>)
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_attr_setschedpolicy(pthread_attr_t *I<attr>, int I<policy>);
+ int pthread_attr_getschedpolicy(const pthread_attr_t *I<attr>,
+ int *I<policy>);
+
+ =head1 DESCRIPTION
+
+ The functions
+ I<pthread_attr_setschedpolicy()>
+ and
+ I<pthread_attr_getschedpolicy()>,
+ respectively, set and get the
+ I<schedpolicy>
+ attribute in the
+ I<attr>
+ argument.
+
+ The supported values of
+ I<policy>
+ include SCHED_FIFO, SCHED_RR and SCHED_OTHER,
+ which are defined by the header
+ I<<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.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_attr_setschedpolicy()>
+ and
+ I<pthread_attr_getschedpolicy()>
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_attr_setschedpolicy()>
+ and
+ I<pthread_attr_getschedpolicy()>
+ functions will fail if:
+
+ =over 4
+
+ =item [ENOSYS]
+
+ The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the
+ implementation does not support the function.
+
+ =back
+
+ The
+ I<pthread_attr_setschedpolicy()>
+ function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value of the attribute being set is not valid.
+
+ =item [ENOTSUP]
+
+ An attempt was made to set the attribute to an unsupported value.
+
+ =back
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ After these attributes have been set, a thread can be created with
+ the specified attributes using
+ I<pthread_create()>.
+ Using these routines does not affect the current running thread.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_attr_init()>,
+ I<pthread_attr_setscope()>,
+ I<pthread_attr_setinheritsched()>,
+ I<pthread_attr_setschedparam()>,
+ I<pthread_create()>,
+ I<<pthread.h>>,
+ I<pthread_setschedparam()>,
+ I<<sched.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_attr_setscope,> B<pthread_attr_getscope>
+ - set and get contentionscope attribute
+ (B<REALTIME THREADS>)
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_attr_setscope(pthread_attr_t *I<attr>, int I<contentionscope>);
+ int pthread_attr_getscope(const pthread_attr_t *I<attr>,
+ int *I<contentionscope>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_attr_setscope()>
+ and
+ I<pthread_attr_getscope()>
+ functions are used to set and get the
+ I<contentionscope>
+ attribute in the
+ I<attr>
+ object.
+
+ The
+ I<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
+ I<<pthread.h>>.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_attr_setscope()>
+ and
+ I<pthread_attr_getscope()>
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_attr_setscope()>
+ and
+ I<pthread_attr_getscope()>
+ functions will fail if:
+
+ =over 4
+
+ =item [ENOSYS]
+
+ The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the
+ implementation does not support the function.
+
+ =back
+
+ The
+ I<pthread_attr_setscope()>,
+ function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value of the attribute being set is not valid.
+
+ =item [ENOTSUP]
+
+ An attempt was made to set the attribute to an unsupported value.
+
+ =back
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ After these attributes have been set, a thread can be created with
+ the specified attributes using
+ I<pthread_create()>.
+ Using these routines does not affect the current running thread.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_attr_init()>,
+ I<pthread_attr_setinheritsched()>,
+ I<pthread_attr_setschedpolicy()>,
+ I<pthread_attr_setschedparam()>,
+ I<pthread_create()>,
+ I<<pthread.h>>,
+ I<pthread_setschedparam()>,
+ I<<sched.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_attr_setstackaddr,> B<pthread_attr_getstackaddr>
+ - set and get stackaddr attribute
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_attr_setstackaddr(pthread_attr_t *I<attr>, void *I<stackaddr>);
+ int pthread_attr_getstackaddr(const pthread_attr_t *I<attr>,
+ void **I<stackaddr>);
+
+ =head1 DESCRIPTION
+
+ The functions
+ I<pthread_attr_setstackaddr()>
+ and
+ I<pthread_attr_getstackaddr()>,
+ respectively, set and get the thread creation
+ I<stackaddr>
+ attribute in the
+ I<attr>
+ object.
+
+ The
+ I<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.
+
+ =head1 RETURN VALUE
+
+ Upon successful completion,
+ I<pthread_attr_setstackaddr()>
+ and
+ I<pthread_attr_getstackaddr()>
+ return a value of 0.
+ Otherwise, an error number is returned to indicate the error.
+
+ The
+ I<pthread_attr_getstackaddr()>
+ function stores the
+ I<stackaddr>
+ attribute value in
+ I<stackaddr>
+ if successful.
+
+ =head1 ERRORS
+
+ No errors are defined.
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_attr_init()>,
+ I<pthread_attr_setdetachstate()>,
+ I<pthread_attr_setstacksize()>,
+ I<pthread_create()>,
+ I<<limits.h>>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_attr_setstacksize,> B<pthread_attr_getstacksize>
+ - set and get stacksize attribute
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_attr_setstacksize(pthread_attr_t *I<attr>, size_t I<stacksize>);
+ int pthread_attr_getstacksize(const pthread_attr_t *I<attr>,
+ size_t *I<stacksize>);
+
+ =head1 DESCRIPTION
+
+ The functions
+ I<pthread_attr_setstacksize()>
+ and
+ I<pthread_attr_getstacksize()>,
+ respectively, set and get the thread creation
+ I<stacksize>
+ attribute in the
+ I<attr>
+ object.
+
+ The
+ I<stacksize>
+ attribute defines the minimum stack size (in bytes) allocated for
+ the created threads stack.
+
+ =head1 RETURN VALUE
+
+ Upon successful completion,
+ I<pthread_attr_setstacksize()>
+ and
+ I<pthread_attr_getstacksize()>
+ return a value of 0.
+ Otherwise, an error number is returned to indicate the error.
+ The
+ I<pthread_attr_getstacksize()>
+ function stores the
+ I<stacksize>
+ attribute value in
+ I<stacksize>
+ if successful.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_attr_setstacksize()>
+ function will fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value of
+ I<stacksize>
+ is less than PTHREAD_STACK_MIN or exceeds a system-imposed limit.
+
+ =back
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_attr_init()>,
+ I<pthread_attr_setstackaddr()>,
+ I<pthread_attr_setdetachstate()>,
+ I<pthread_create()>,
+ I<<limits.h>>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_cancel> - cancel execution of a thread
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_cancel(pthread_t I<thread>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_cancel()>
+ function requests that
+ I<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
+ I<thread>
+ are called.
+ When the last cancellation cleanup handler returns,
+ the thread-specific data destructor functions are called for
+ I<thread>.
+ When the last destructor function returns,
+ I<thread>
+ is terminated.
+
+ The cancellation processing in the target thread runs asynchronously
+ with respect to the calling thread returning from
+ I<pthread_cancel()>.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_cancel()>
+ function returns zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_cancel()>
+ function may fail if:
+
+ =over 4
+
+ =item [ESRCH]
+
+ No thread could be found corresponding to that specified
+ by the given thread ID.
+
+ =back
+
+ The
+ I<pthread_cancel()>
+ function will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_exit()>,
+ I<pthread_join()>,
+ I<pthread_setcancelstate()>,
+ I<pthread_cond_wait()>,
+ I<pthread_cond_timedwait()>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_cleanup_push,> B<pthread_cleanup_pop> - establish cancellation handlers
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ void pthread_cleanup_push(void (*I<routine>)(void*), void *I<arg>);
+ void pthread_cleanup_pop(int I<execute>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_cleanup_push()>
+ function pushes the specified cancellation cleanup handler
+ I<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
+ I<arg>
+ when: (a) the thread exits (that is, calls
+ I<pthread_exit()>),
+ (b) the thread acts upon a cancellation request, or
+ (c) the thread calls
+ I<pthread_cleanup_pop()>
+ with a non-zero
+ I<execute>
+ argument.
+
+ The
+ I<pthread_cleanup_pop()>
+ function removes the routine at the top of the calling thread's
+ cancellation cleanup stack and optionally invokes it (if
+ I<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
+ I<pthread_cleanup_push()>
+ macro may be thought to expand to a token list whose first
+ token is
+ B<`{'>
+ with
+ I<pthread_cleanup_pop()>
+ expanding to a token list whose last token is the corresponding
+ B<`}'>.
+
+ The effect of calling
+ I<longjmp()>
+ or
+ I<siglongjmp()>
+ is undefined if there have been any calls to
+ I<pthread_cleanup_push()>
+ or
+ I<pthread_cleanup_pop()>
+ made without the matching call
+ since the jump buffer was filled.
+ The effect of calling
+ I<longjmp()>
+ or
+ I<siglongjmp()>
+ from inside a cancellation cleanup handler is also
+ undefined unless the jump buffer was also filled in the
+ cancellation cleanup handler.
+
+ =head1 RETURN VALUE
+
+ The
+ I<pthread_cleanup_push()>
+ and
+ I<pthread_cleanup_pop()>
+ functions return no value.
+
+ =head1 ERRORS
+
+ No errors are defined.
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_cancel()>,
+ I<pthread_setcancelstate()>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_cleanup_push,> B<pthread_cleanup_pop> - establish cancellation handlers
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ void pthread_cleanup_push(void (*I<routine>)(void*), void *I<arg>);
+ void pthread_cleanup_pop(int I<execute>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_cleanup_push()>
+ function pushes the specified cancellation cleanup handler
+ I<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
+ I<arg>
+ when: (a) the thread exits (that is, calls
+ I<pthread_exit()>),
+ (b) the thread acts upon a cancellation request, or
+ (c) the thread calls
+ I<pthread_cleanup_pop()>
+ with a non-zero
+ I<execute>
+ argument.
+
+ The
+ I<pthread_cleanup_pop()>
+ function removes the routine at the top of the calling thread's
+ cancellation cleanup stack and optionally invokes it (if
+ I<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
+ I<pthread_cleanup_push()>
+ macro may be thought to expand to a token list whose first
+ token is
+ B<`{'>
+ with
+ I<pthread_cleanup_pop()>
+ expanding to a token list whose last token is the corresponding
+ B<`}'>.
+
+ The effect of calling
+ I<longjmp()>
+ or
+ I<siglongjmp()>
+ is undefined if there have been any calls to
+ I<pthread_cleanup_push()>
+ or
+ I<pthread_cleanup_pop()>
+ made without the matching call
+ since the jump buffer was filled.
+ The effect of calling
+ I<longjmp()>
+ or
+ I<siglongjmp()>
+ from inside a cancellation cleanup handler is also
+ undefined unless the jump buffer was also filled in the
+ cancellation cleanup handler.
+
+ =head1 RETURN VALUE
+
+ The
+ I<pthread_cleanup_push()>
+ and
+ I<pthread_cleanup_pop()>
+ functions return no value.
+
+ =head1 ERRORS
+
+ No errors are defined.
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_cancel()>,
+ I<pthread_setcancelstate()>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_cond_signal,> B<pthread_cond_broadcast> - signal or broadcast a
+ condition
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_cond_signal(pthread_cond_t *I<cond>);
+ int pthread_cond_broadcast(pthread_cond_t *I<cond>);
+
+ =head1 DESCRIPTION
+
+ These two functions are used to unblock
+ threads blocked on a condition variable.
+
+ The
+ I<pthread_cond_signal()>
+ call unblocks at least one of the threads that are blocked on the
+ specified condition variable
+ I<cond>
+ (if any threads are blocked on
+ I<cond>).
+
+ The
+ I<pthread_cond_broadcast()>
+ call unblocks all threads currently blocked on the specified condition variable
+ I<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
+ I<pthread_cond_signal()>
+ or
+ I<pthread_cond_broadcast()>
+ returns from its call to
+ I<pthread_cond_wait()>
+ or
+ I<pthread_cond_timedwait()>,
+ the thread owns the mutex with which it called
+ I<pthread_cond_wait()>
+ or
+ I<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
+ I<pthread_mutex_lock()>.
+
+ The
+ I<pthread_cond_signal()>
+ or
+ I<pthread_cond_broadcast()>
+ functions may be called by a thread whether or not it
+ currently owns the mutex that threads calling
+ I<pthread_cond_wait()>
+ or
+ I<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
+ I<pthread_cond_signal()>
+ or
+ I<pthread_cond_broadcast()>.
+
+ The
+ I<pthread_cond_signal()>
+ and
+ I<pthread_cond_broadcast()>
+ functions have no effect if there are no threads
+ currently blocked on
+ I<cond>.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_cond_signal()>
+ and
+ I<pthread_cond_broadcast()>
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_cond_signal()>
+ and
+ I<pthread_cond_broadcast()>
+ function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value
+ I<cond>
+ does not refer to an initialised condition variable.
+
+ =back
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_cond_init()>,
+ I<pthread_cond_wait()>,
+ I<pthread_cond_timedwait()>,
+ I<<pthread.h>>.
+
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_cond_init,> B<pthread_cond_destroy> - initialise and destroy
+ condition variables
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_cond_init(pthread_cond_t *I<cond>,
+ const pthread_condattr_t *I<attr>);
+ int pthread_cond_destroy(pthread_cond_t *I<cond>);
+ pthread_cond_t I<cond> = PTHREAD_COND_INITIALIZER;
+
+ =head1 DESCRIPTION
+
+ The function
+ I<pthread_cond_init()>
+ initialises the condition variable referenced by
+ I<cond>
+ with attributes referenced by
+ I<attr>.
+ If
+ I<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
+ I<pthread_cond_destroy()>
+ destroys the given condition variable specified by
+ I<cond>;
+ the object becomes, in effect, uninitialised.
+ An implementation may cause
+ I<pthread_cond_destroy()>
+ to set the object referenced by
+ I<cond>
+ to an invalid value.
+ A destroyed condition variable object
+ can be re-initialised using
+ I<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
+ I<pthread_cond_init()>
+ with parameter
+ I<attr>
+ specified as NULL, except that no error checks are performed.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_cond_init()>
+ and
+ I<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
+ I<cond>.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_cond_init()>
+ function will fail if:
+
+ =over 4
+
+ =item [EAGAIN]
+
+ The system lacked the necessary resources (other
+ than memory) to initialise another condition variable.
+
+ =item [ENOMEM]
+
+ Insufficient memory exists to initialise the condition variable.
+
+ =back
+
+ The
+ I<pthread_cond_init()>
+ function may fail if:
+
+ =over 4
+
+ =item [EBUSY]
+
+ The implementation has detected an attempt
+ to re-initialise the object referenced by
+ I<cond>,
+ a previously initialised, but
+ not yet destroyed, condition variable.
+
+ =item [EINVAL]
+
+ The value specified by
+ I<attr>
+ is invalid.
+
+ =back
+
+
+
+ The
+ I<pthread_cond_destroy()>
+ function may fail if:
+
+ =over 4
+
+ =item [EBUSY]
+
+ The implementation has detected an attempt to destroy
+ the object referenced by
+ I<cond>
+ while it is referenced
+ (for example, while being used in a
+ I<pthread_cond_wait()>
+ or
+ I<pthread_cond_timedwait()>)
+ by another thread.
+
+ =item [EINVAL]
+
+ The value specified by
+ I<cond>
+ is invalid.
+
+ =back
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_cond_signal()>,
+ I<pthread_cond_broadcast()>,
+ I<pthread_cond_wait()>,
+ I<pthread_cond_timedwait()>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_cond_init,> B<pthread_cond_destroy> - initialise and destroy
+ condition variables
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_cond_init(pthread_cond_t *I<cond>,
+ const pthread_condattr_t *I<attr>);
+ int pthread_cond_destroy(pthread_cond_t *I<cond>);
+ pthread_cond_t I<cond> = PTHREAD_COND_INITIALIZER;
+
+ =head1 DESCRIPTION
+
+ The function
+ I<pthread_cond_init()>
+ initialises the condition variable referenced by
+ I<cond>
+ with attributes referenced by
+ I<attr>.
+ If
+ I<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
+ I<pthread_cond_destroy()>
+ destroys the given condition variable specified by
+ I<cond>;
+ the object becomes, in effect, uninitialised.
+ An implementation may cause
+ I<pthread_cond_destroy()>
+ to set the object referenced by
+ I<cond>
+ to an invalid value.
+ A destroyed condition variable object
+ can be re-initialised using
+ I<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
+ I<pthread_cond_init()>
+ with parameter
+ I<attr>
+ specified as NULL, except that no error checks are performed.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_cond_init()>
+ and
+ I<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
+ I<cond>.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_cond_init()>
+ function will fail if:
+
+ =over 4
+
+ =item [EAGAIN]
+
+ The system lacked the necessary resources (other
+ than memory) to initialise another condition variable.
+
+ =item [ENOMEM]
+
+ Insufficient memory exists to initialise the condition variable.
+
+ =back
+
+ The
+ I<pthread_cond_init()>
+ function may fail if:
+
+ =over 4
+
+ =item [EBUSY]
+
+ The implementation has detected an attempt
+ to re-initialise the object referenced by
+ I<cond>,
+ a previously initialised, but
+ not yet destroyed, condition variable.
+
+ =item [EINVAL]
+
+ The value specified by
+ I<attr>
+ is invalid.
+
+ =back
+
+
+
+ The
+ I<pthread_cond_destroy()>
+ function may fail if:
+
+ =over 4
+
+ =item [EBUSY]
+
+ The implementation has detected an attempt to destroy
+ the object referenced by
+ I<cond>
+ while it is referenced
+ (for example, while being used in a
+ I<pthread_cond_wait()>
+ or
+ I<pthread_cond_timedwait()>)
+ by another thread.
+
+ =item [EINVAL]
+
+ The value specified by
+ I<cond>
+ is invalid.
+
+ =back
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_cond_signal()>,
+ I<pthread_cond_broadcast()>,
+ I<pthread_cond_wait()>,
+ I<pthread_cond_timedwait()>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_cond_signal,> B<pthread_cond_broadcast> - signal or broadcast a
+ condition
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_cond_signal(pthread_cond_t *I<cond>);
+ int pthread_cond_broadcast(pthread_cond_t *I<cond>);
+
+ =head1 DESCRIPTION
+
+ These two functions are used to unblock
+ threads blocked on a condition variable.
+
+ The
+ I<pthread_cond_signal()>
+ call unblocks at least one of the threads that are blocked on the
+ specified condition variable
+ I<cond>
+ (if any threads are blocked on
+ I<cond>).
+
+ The
+ I<pthread_cond_broadcast()>
+ call unblocks all threads currently blocked on the specified condition variable
+ I<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
+ I<pthread_cond_signal()>
+ or
+ I<pthread_cond_broadcast()>
+ returns from its call to
+ I<pthread_cond_wait()>
+ or
+ I<pthread_cond_timedwait()>,
+ the thread owns the mutex with which it called
+ I<pthread_cond_wait()>
+ or
+ I<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
+ I<pthread_mutex_lock()>.
+
+ The
+ I<pthread_cond_signal()>
+ or
+ I<pthread_cond_broadcast()>
+ functions may be called by a thread whether or not it
+ currently owns the mutex that threads calling
+ I<pthread_cond_wait()>
+ or
+ I<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
+ I<pthread_cond_signal()>
+ or
+ I<pthread_cond_broadcast()>.
+
+ The
+ I<pthread_cond_signal()>
+ and
+ I<pthread_cond_broadcast()>
+ functions have no effect if there are no threads
+ currently blocked on
+ I<cond>.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_cond_signal()>
+ and
+ I<pthread_cond_broadcast()>
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_cond_signal()>
+ and
+ I<pthread_cond_broadcast()>
+ function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value
+ I<cond>
+ does not refer to an initialised condition variable.
+
+ =back
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_cond_init()>,
+ I<pthread_cond_wait()>,
+ I<pthread_cond_timedwait()>,
+ I<<pthread.h>>.
+
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_cond_wait,> B<pthread_cond_timedwait> - wait on a condition
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_cond_wait(pthread_cond_t *I<cond>, pthread_mutex_t *I<mutex>);
+ int pthread_cond_timedwait(pthread_cond_t *I<cond>,
+ pthread_mutex_t *I<mutex>, const struct timespec *I<abstime>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_cond_wait()>
+ and
+ I<pthread_cond_timedwait()>
+ functions are used to block on a condition variable.
+ They are called with
+ I<mutex>
+ locked by the calling thread or undefined behaviour will result.
+
+ These functions atomically release
+ I<mutex>
+ and cause the calling thread to block on the condition variable
+ I<cond>;
+ atomically here means "atomically with respect to access by another
+ thread to the mutex and then the condition variable".
+ That is, if another thread is able to acquire the mutex
+ after the about-to-block thread has released it,
+ then a subsequent call to
+ I<pthread_cond_signal()>
+ or
+ I<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
+ I<pthread_cond_wait()>
+ or
+ I<pthread_cond_timedwait()>
+ functions may occur.
+ Since the return from
+ I<pthread_cond_wait()>
+ or
+ I<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
+ I<pthread_cond_wait()>
+ or
+ I<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
+ I<pthread_cond_wait()>
+ or
+ I<pthread_cond_timedwait()>,
+ but at that point
+ notices the cancellation request and instead of returning to the caller
+ of
+ I<pthread_cond_wait()>
+ or
+ I<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
+ I<pthread_cond_wait()>
+ or
+ I<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
+ I<pthread_cond_timedwait()>
+ function is the same as
+ I<pthread_cond_wait()>
+ except that
+ an error is returned
+ if the absolute time specified by
+ I<abstime>
+ passes (that is, system time equals or exceeds
+ I<abstime>)
+ before the condition
+ I<cond>
+ is signaled or broadcasted,
+ or if the absolute time specified by
+ I<abstime>
+ has already been passed at the time of the call.
+ When such time-outs occur,
+ I<pthread_cond_timedwait()>
+ will nonetheless release
+ and reacquire the mutex referenced by
+ I<mutex>.
+ The function
+ I<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.
+
+ =head1 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
+ I<mutex>
+ or the condition variable specified by
+ I<cond>.
+
+ Upon successful completion, a value of zero is returned.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_cond_timedwait()>
+ function will fail if:
+
+ =over 4
+
+ =item [ETIMEDOUT]
+
+ The time specified by
+ I<abstime>
+ to
+ I<pthread_cond_timedwait()>
+ has passed.
+
+ =back
+
+ The
+ I<pthread_cond_wait()>
+ and
+ I<pthread_cond_timedwait()>
+ functions may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value specified by
+ I<cond>,
+ I<mutex>,
+ or
+ I<abstime>
+ is invalid.
+
+ =item [EINVAL]
+
+ Different mutexes were supplied for concurrent
+ I<pthread_cond_wait()>
+ or
+ I<pthread_cond_timedwait()>
+ operations on the same condition variable.
+
+ =item [EINVAL]
+
+ The mutex was not owned by the current thread at the time of the call.
+
+ =back
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_cond_signal()>,
+ I<pthread_cond_broadcast()>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_cond_wait,> B<pthread_cond_timedwait> - wait on a condition
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_cond_wait(pthread_cond_t *I<cond>, pthread_mutex_t *I<mutex>);
+ int pthread_cond_timedwait(pthread_cond_t *I<cond>,
+ pthread_mutex_t *I<mutex>, const struct timespec *I<abstime>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_cond_wait()>
+ and
+ I<pthread_cond_timedwait()>
+ functions are used to block on a condition variable.
+ They are called with
+ I<mutex>
+ locked by the calling thread or undefined behaviour will result.
+
+ These functions atomically release
+ I<mutex>
+ and cause the calling thread to block on the condition variable
+ I<cond>;
+ atomically here means "atomically with respect to access by another
+ thread to the mutex and then the condition variable".
+ That is, if another thread is able to acquire the mutex
+ after the about-to-block thread has released it,
+ then a subsequent call to
+ I<pthread_cond_signal()>
+ or
+ I<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
+ I<pthread_cond_wait()>
+ or
+ I<pthread_cond_timedwait()>
+ functions may occur.
+ Since the return from
+ I<pthread_cond_wait()>
+ or
+ I<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
+ I<pthread_cond_wait()>
+ or
+ I<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
+ I<pthread_cond_wait()>
+ or
+ I<pthread_cond_timedwait()>,
+ but at that point
+ notices the cancellation request and instead of returning to the caller
+ of
+ I<pthread_cond_wait()>
+ or
+ I<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
+ I<pthread_cond_wait()>
+ or
+ I<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
+ I<pthread_cond_timedwait()>
+ function is the same as
+ I<pthread_cond_wait()>
+ except that
+ an error is returned
+ if the absolute time specified by
+ I<abstime>
+ passes (that is, system time equals or exceeds
+ I<abstime>)
+ before the condition
+ I<cond>
+ is signaled or broadcasted,
+ or if the absolute time specified by
+ I<abstime>
+ has already been passed at the time of the call.
+ When such time-outs occur,
+ I<pthread_cond_timedwait()>
+ will nonetheless release
+ and reacquire the mutex referenced by
+ I<mutex>.
+ The function
+ I<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.
+
+ =head1 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
+ I<mutex>
+ or the condition variable specified by
+ I<cond>.
+
+ Upon successful completion, a value of zero is returned.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_cond_timedwait()>
+ function will fail if:
+
+ =over 4
+
+ =item [ETIMEDOUT]
+
+ The time specified by
+ I<abstime>
+ to
+ I<pthread_cond_timedwait()>
+ has passed.
+
+ =back
+
+ The
+ I<pthread_cond_wait()>
+ and
+ I<pthread_cond_timedwait()>
+ functions may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value specified by
+ I<cond>,
+ I<mutex>,
+ or
+ I<abstime>
+ is invalid.
+
+ =item [EINVAL]
+
+ Different mutexes were supplied for concurrent
+ I<pthread_cond_wait()>
+ or
+ I<pthread_cond_timedwait()>
+ operations on the same condition variable.
+
+ =item [EINVAL]
+
+ The mutex was not owned by the current thread at the time of the call.
+
+ =back
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_cond_signal()>,
+ I<pthread_cond_broadcast()>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_condattr_init,> B<pthread_condattr_destroy>
+ - initialise and destroy condition variable attributes object
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_condattr_init(pthread_condattr_t *I<attr>);
+ int pthread_condattr_destroy(pthread_condattr_t *I<attr>);
+
+ =head1 DESCRIPTION
+
+ The function
+ I<pthread_condattr_init()>
+ initialises a condition variable attributes object
+ I<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
+ I<pthread_condattr_destroy()>
+ function destroys a condition variable attributes object;
+ the object becomes, in effect, uninitialised.
+ An implementation may cause
+ I<pthread_condattr_destroy()>
+ to set the object referenced by
+ I<attr>
+ to an invalid value.
+ A destroyed condition variable attributes object
+ can be re-initialised using
+ I<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.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_condattr_init()>
+ and
+ I<pthread_condattr_destroy()>
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_condattr_init()>
+ function will fail if:
+
+ =over 4
+
+ =item [ENOMEM]
+
+ Insufficient memory exists to initialise the condition variable
+ attributes object.
+
+ =back
+
+ The
+ I<pthread_condattr_destroy()>
+ function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value specified by
+ I<attr>
+ is invalid.
+
+ =back
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_condattr_getpshared()>,
+ I<pthread_create()>,
+ I<pthread_mutex_init()>,
+ I<pthread_cond_init()>,
+ I<<pthread.h>>.
+
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_condattr_getpshared,> B<pthread_condattr_setpshared>
+ - get and set the process-shared condition variable attributes
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_condattr_getpshared(const pthread_condattr_t *I<attr>,
+ int *I<pshared>);
+ int pthread_condattr_setpshared(pthread_condattr_t *I<attr>,
+ int I<pshared>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_condattr_getpshared()>
+ function obtains the value of the
+ I<process-shared>
+ attribute from the attributes object referenced by
+ I<attr>.
+ The
+ I<pthread_condattr_setpshared()>
+ function is used to set the
+ I<process-shared>
+ attribute in an initialised attributes object referenced by
+ I<attr>.
+
+ The
+ I<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
+ I<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.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_condattr_setpshared()>
+ function returns zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ If successful, the
+ I<pthread_condattr_getpshared()>
+ function returns zero
+ and stores the value of the
+ I<process-shared>
+ attribute of
+ I<attr>
+ into the object referenced by the
+ I<pshared>
+ parameter.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_condattr_getpshared()>
+ and
+ I<pthread_condattr_setpshared()>
+ functions may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value specified by
+ I<attr>
+ is invalid.
+
+ =back
+
+ The
+ I<pthread_condattr_setpshared()>
+ function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The new value specified for the attribute
+ is outside the range of legal values for that attribute.
+
+ =back
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_condattr_init()>,
+ I<pthread_create()>,
+ I<pthread_mutex_init()>,
+ I<pthread_cond_init()>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_condattr_init,> B<pthread_condattr_destroy>
+ - initialise and destroy condition variable attributes object
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_condattr_init(pthread_condattr_t *I<attr>);
+ int pthread_condattr_destroy(pthread_condattr_t *I<attr>);
+
+ =head1 DESCRIPTION
+
+ The function
+ I<pthread_condattr_init()>
+ initialises a condition variable attributes object
+ I<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
+ I<pthread_condattr_destroy()>
+ function destroys a condition variable attributes object;
+ the object becomes, in effect, uninitialised.
+ An implementation may cause
+ I<pthread_condattr_destroy()>
+ to set the object referenced by
+ I<attr>
+ to an invalid value.
+ A destroyed condition variable attributes object
+ can be re-initialised using
+ I<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.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_condattr_init()>
+ and
+ I<pthread_condattr_destroy()>
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_condattr_init()>
+ function will fail if:
+
+ =over 4
+
+ =item [ENOMEM]
+
+ Insufficient memory exists to initialise the condition variable
+ attributes object.
+
+ =back
+
+ The
+ I<pthread_condattr_destroy()>
+ function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value specified by
+ I<attr>
+ is invalid.
+
+ =back
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_condattr_getpshared()>,
+ I<pthread_create()>,
+ I<pthread_mutex_init()>,
+ I<pthread_cond_init()>,
+ I<<pthread.h>>.
+
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_condattr_getpshared,> B<pthread_condattr_setpshared>
+ - get and set the process-shared condition variable attributes
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_condattr_getpshared(const pthread_condattr_t *I<attr>,
+ int *I<pshared>);
+ int pthread_condattr_setpshared(pthread_condattr_t *I<attr>,
+ int I<pshared>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_condattr_getpshared()>
+ function obtains the value of the
+ I<process-shared>
+ attribute from the attributes object referenced by
+ I<attr>.
+ The
+ I<pthread_condattr_setpshared()>
+ function is used to set the
+ I<process-shared>
+ attribute in an initialised attributes object referenced by
+ I<attr>.
+
+ The
+ I<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
+ I<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.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_condattr_setpshared()>
+ function returns zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ If successful, the
+ I<pthread_condattr_getpshared()>
+ function returns zero
+ and stores the value of the
+ I<process-shared>
+ attribute of
+ I<attr>
+ into the object referenced by the
+ I<pshared>
+ parameter.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_condattr_getpshared()>
+ and
+ I<pthread_condattr_setpshared()>
+ functions may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value specified by
+ I<attr>
+ is invalid.
+
+ =back
+
+ The
+ I<pthread_condattr_setpshared()>
+ function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The new value specified for the attribute
+ is outside the range of legal values for that attribute.
+
+ =back
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_condattr_init()>,
+ I<pthread_create()>,
+ I<pthread_mutex_init()>,
+ I<pthread_cond_init()>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_create> - thread creation
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_create(pthread_t *I<thread>, const pthread_attr_t *I<attr>,
+ void *(*I<start_routine>)(void*), void *I<arg>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_create()>
+ function is used to create a new thread, with attributes specified by
+ I<attr>,
+ within a process.
+ If
+ I<attr>
+ is NULL,
+ the default attributes are used.
+ If the attributes specified by
+ I<attr>
+ are modified later, the thread's attributes are not affected.
+ Upon successful completion,
+ I<pthread_create()>
+ stores the ID of the created thread in the location referenced by
+ I<thread>.
+
+ The thread is created executing
+ I<start_routine>
+ with
+ I<arg>
+ as its sole argument.
+ If the
+ I<start_routine>
+ returns, the effect is as if there was an implicit call to
+ I<pthread_exit()>
+ using the return value of
+ I<start_routine>
+ as the exit status.
+ Note that the thread in which
+ I<main()>
+ was originally invoked differs from this.
+ When it returns from
+ I<main()>,
+ the effect is as if there was an implicit call to
+ I<exit()>
+ using the return value of
+ I<main()>
+ as the exit status.
+
+ The signal state of the new thread is initialised as follows:
+
+ =over 4
+
+ =item o
+
+ The signal mask is inherited from the creating thread.
+
+ =item o
+
+ The set of signals pending for the new thread is empty.
+
+ =back
+
+ If
+ I<pthread_create()>
+ fails, no new thread is created
+ and the contents of the location referenced by
+ I<thread>
+ are undefined.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_create()>
+ function returns zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_create()>
+ function will fail if:
+
+ =over 4
+
+ =item [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.
+
+ =item [EINVAL]
+
+ The value specified by
+ I<attr>
+ is invalid.
+
+ =item [EPERM]
+
+ The caller does not have appropriate permission to set the required
+ scheduling parameters or scheduling policy.
+
+ =back
+
+ The
+ I<pthread_create()>
+ function will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_exit()>,
+ I<pthread_join()>,
+ I<fork()>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_detach> - detach a thread
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_detach(pthread_t I<thread>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_detach()>
+ function is used to indicate to the implementation that storage
+ for the thread
+ I<thread>
+ can be reclaimed when that thread terminates.
+ If
+ I<thread>
+ has not terminated,
+ I<pthread_detach()>
+ will not cause it to terminate.
+ The effect of multiple
+ I<pthread_detach()>
+ calls on the same target thread is unspecified.
+
+ =head1 RETURN VALUE
+
+ If the call succeeds,
+ I<pthread_detach()>
+ returns 0.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_detach()>
+ function will fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The implementation has detected that the value specified by
+ I<thread>
+ does not refer to a joinable thread.
+
+ =item [ESRCH]
+
+ No thread could be found corresponding to that specified
+ by the given thread ID.
+
+ =back
+
+ The
+ I<pthread_detach()>
+ function will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_join()>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_equal> - compare thread IDs
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_equal(pthread_t I<t1>, pthread_t I<t2>);
+
+ =head1 DESCRIPTION
+
+ This function compares the thread IDs
+ I<t1>
+ and
+ I<t2>.
+
+ =head1 RETURN VALUE
+
+ The
+ I<pthread_equal()>
+ function returns a non-zero value if
+ I<t1>
+ and
+ I<t2>
+ are equal;
+ otherwise, zero is returned.
+
+ If either
+ I<t1>
+ or
+ I<t2>
+ are not valid thread IDs, the behaviour is undefined.
+
+ =head1 ERRORS
+
+ No errors are defined.
+
+ The
+ I<pthread_equal()>
+ function will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_create()>,
+ I<pthread_self()>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_exit> - thread termination
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ void pthread_exit(void *I<value_ptr>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_exit()>
+ function terminates the calling thread and makes the value
+ I<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
+ I<atexit()>
+ routines that may exist.
+
+ An implicit call to
+ I<pthread_exit()>
+ is made when a thread other than the thread in which
+ I<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
+ I<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
+ I<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
+ I<pthread_exit()>
+ I<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
+ I<exit()>
+ with a zero argument at thread termination time.
+
+ =head1 RETURN VALUE
+
+ The
+ I<pthread_exit()>
+ function cannot return to its caller.
+
+ =head1 ERRORS
+
+ No errors are defined.
+
+ The
+ I<pthread_exit()>
+ function will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_create()>,
+ I<pthread_join()>,
+ I<exit()>,
+ I<_exit()>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_getconcurrency,> B<pthread_setconcurrency> -
+ get or set level of concurrency
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_getconcurrency(void);
+ int pthread_setconcurrency(int I<new_level>);
+
+ =head1 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
+ I<pthread_setconcurrency()>
+ function allows an application to inform
+ the threads implementation of its desired concurrency level,
+ I<new_level>.
+ The actual level of concurrency provided by the implementation as a
+ result of this function call is unspecified.
+
+ If I<new_level> is zero, it causes the implementation to maintain
+ the concurrency level at its discretion as if
+ I<pthread_setconcurrency()>
+ was never called.
+
+ The
+ I<pthread_getconcurrency()>
+ function returns the
+ value set by a previous call to the
+ I<pthread_setconcurrency()>
+ function. If the
+ I<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
+ I<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
+ I<pthread_setconcurrency()>
+ and
+ I<pthread_getconcurrency()>
+ functions
+ will be provided for source code
+ compatibility but they will have no effect when called. To maintain
+ the function semantics, the I<new_level>
+ parameter will be saved when
+ I<pthread_setconcurrency()>
+ is called so
+ that a subsequent call to
+ I<pthread_getconcurrency()>
+ returns the same value.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_setconcurrency()>
+ function returns zero. Otherwise, an error number is returned
+ to indicate the error.
+
+ The
+ I<pthread_getconcurrency()>
+ function always returns the concurrency level set by a previous call to
+ I<pthread_setconcurrency()>.
+ If the
+ I<pthread_setconcurrency()>
+ function has never been called,
+ I<pthread_getconcurrency()>
+ returns zero.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_setconcurrency()>
+ function will fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value specified by I<new_level> is negative.
+
+ =item [EAGAIN]
+
+ The value specific by I<new_level> would cause a system resource
+ to be exceeded.
+
+ =back
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 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
+ I<pthread_getconcurrency()>
+ and
+ I<pthread_setconcurrency()>
+ functions since their
+ use may conflict with an applications use of these functions.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_getschedparam,> B<pthread_setschedparam>
+ - dynamic thread scheduling parameters access
+ (B<REALTIME THREADS>)
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_getschedparam(pthread_t I<thread>, int *I<policy>,
+ struct sched_param *I<param>);
+ int pthread_setschedparam(pthread_t I<thread>, int I<policy>,
+ const struct sched_param *I<param>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_getschedparam()>
+ and
+ I<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
+ B<sched_param>
+ structure is the priority
+ I<sched_priority>.
+ For SCHED_OTHER,
+ the affected scheduling parameters are implementation-dependent.
+
+ The
+ I<pthread_getschedparam()>
+ function retrieves the scheduling policy and scheduling parameters
+ for the thread whose thread ID is given by
+ I<thread>
+ and stores those values in
+ I<policy>
+ and
+ I<param>,
+ respectively.
+ The priority value returned from
+ I<pthread_getschedparam()>
+ is the value specified by the most recent
+ I<pthread_setschedparam()>
+ or
+ I<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
+ I<pthread_setschedparam()>
+ function sets the scheduling policy
+ and associated scheduling parameters for the thread whose
+ thread ID is given by
+ I<thread>
+ to the policy and associated parameters provided in
+ I<policy>
+ and
+ I<param>,
+ respectively.
+
+ The
+ I<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,
+ I<priority.>
+
+ If the
+ I<pthread_setschedparam()>
+ function fails, no scheduling parameters will be changed
+ for the target thread.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_getschedparam()>
+ and
+ I<pthread_setschedparam()>
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_getschedparam()>
+ and
+ I<pthread_setschedparam()>
+ functions will fail if:
+
+ =over 4
+
+ =item [ENOSYS]
+
+ The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the
+ implementation does not support the function.
+
+ =back
+
+ The
+ I<pthread_getschedparam()>
+ function may fail if:
+
+ =over 4
+
+ =item [ESRCH]
+
+ The value specified by
+ I<thread>
+ does not refer to a existing thread.
+
+ =back
+
+ The
+ I<pthread_setschedparam()>
+ function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value specified by
+ I<policy>
+ or one of the scheduling parameters associated with
+ the scheduling policy
+ I<policy>
+ is invalid.
+
+ =item [ENOTSUP]
+
+ An attempt was made to set the policy or scheduling parameters to
+ an unsupported value.
+
+ =item [EPERM]
+
+ The caller does not have the appropriate permission to set
+ either the scheduling parameters or the scheduling policy of the
+ specified thread.
+
+ =item [EPERM]
+
+ The implementation does not allow the application to modify
+ one of the parameters to the value specified.
+
+ =item [ESRCH]
+
+ The value specified by
+ I<thread>
+ does not refer to a existing thread.
+
+ =back
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<sched_setparam()>,
+ I<sched_getparam()>,
+ I<sched_setscheduler()>,
+ I<sched_getscheduler()>,
+ I<<pthread.h>>,
+ I<<sched.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_setspecific,> B<pthread_getspecific> - thread-specific data management
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_setspecific(pthread_key_t I<key>, const void *I<value>);
+ void *pthread_getspecific(pthread_key_t I<key>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_setspecific()>
+ function associates a thread-specific
+ I<value>
+ with a
+ I<key>
+ obtained via a previous call to
+ I<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
+ I<pthread_getspecific()>
+ function returns the value currently bound to the specified
+ I<key>
+ on behalf of the calling thread.
+
+ The effect of calling
+ I<pthread_setspecific()>
+ or
+ I<pthread_getspecific()>
+ with a
+ I<key>
+ value not obtained from
+ I<pthread_key_create()>
+ or after
+ I<key>
+ has been deleted with
+ I<pthread_key_delete()>
+ is undefined.
+
+ Both
+ I<pthread_setspecific()>
+ and
+ I<pthread_getspecific()>
+ may be called from a thread-specific data destructor function.
+ However, calling
+ I<pthread_setspecific()>
+ from a destructor may result in lost storage or infinite loops.
+
+ Both functions may be implemented as macros.
+
+ =head1 RETURN VALUE
+
+ The function
+ I<pthread_getspecific()>
+ returns the thread-specific data value
+ associated with the given
+ I<key>.
+ If no thread-specific data value is associated with
+ I<key>,
+ then the value NULL is returned.
+
+ If successful, the
+ I<pthread_setspecific()>
+ function returns zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_setspecific()>
+ function will fail if:
+
+ =over 4
+
+ =item [ENOMEM]
+
+ Insufficient memory exists to associate the value with the key.
+
+ =back
+
+ The
+ I<pthread_setspecific()>
+ function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The key value is invalid.
+
+ =back
+
+ No errors are returned from
+ I<pthread_getspecific()>.
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_key_create()>,
+ I<<pthread.h>>.
+
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_join> - wait for thread termination
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_join(pthread_t I<thread>, void **I<value_ptr>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_join()>
+ function suspends execution of the calling thread until the target
+ I<thread>
+ terminates, unless the target
+ I<thread>
+ has already terminated.
+ On return from a successful
+ I<pthread_join()>
+ call with a non-NULL
+ I<value_ptr>
+ argument, the value passed to
+ I<pthread_exit()>
+ by the terminating thread is made available in the location referenced by
+ I<value_ptr>.
+ When a
+ I<pthread_join()>
+ returns successfully, the target thread has been terminated.
+ The results of multiple simultaneous calls to
+ I<pthread_join()>
+ specifying the same target thread are undefined.
+ If the thread calling
+ I<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.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_join()>
+ function returns zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_join()>
+ function will fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The implementation has detected that the value specified by
+ I<thread>
+ does not refer to a joinable thread.
+
+ =item [ESRCH]
+
+ No thread could be found corresponding to that specified
+ by the given thread ID.
+
+ =back
+
+ The
+ I<pthread_join()>
+ function may fail if:
+
+ =over 4
+
+ =item [EDEADLK]
+
+ A deadlock was detected or
+ the value of
+ I<thread>
+ specifies the calling thread.
+
+ =back
+
+ The
+ I<pthread_join()>
+ function will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_create()>,
+ I<wait()>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_key_create> - thread-specific data key creation
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_key_create(pthread_key_t *I<key>, void (*I<destructor>)(void*));
+
+ =head1 DESCRIPTION
+
+ This function creates a thread-specific data
+ key visible to all threads in the process.
+ Key values provided by
+ I<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
+ I<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.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_key_create()>
+ function stores the newly created key value at
+ I<*key>
+ and returns zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_key_create()>
+ function will fail if:
+
+ =over 4
+
+ =item [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.
+
+ =item [ENOMEM]
+
+ Insufficient memory exists to create the key.
+
+ =back
+
+ The
+ I<pthread_key_create()>
+ function will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_getspecific()>,
+ I<pthread_setspecific()>,
+ I<pthread_key_delete()>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_key_delete> - thread-specific data key deletion
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_key_delete(pthread_key_t I<key>);
+
+ =head1 DESCRIPTION
+
+ This function deletes a thread-specific data
+ key previously returned by
+ I<pthread_key_create()>.
+ The thread-specific data values associated with
+ I<key>
+ need not be NULL at the time
+ I<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
+ I<pthread_key_delete()>
+ is called.
+ Any attempt to use
+ I<key>
+ following the call to
+ I<pthread_key_delete()>
+ results in undefined behaviour.
+
+ The
+ I<pthread_key_delete()>
+ function is callable from within destructor functions.
+ No destructor functions will be invoked by
+ I<pthread_key_delete()>.
+ Any destructor function that may have been associated with
+ I<key>
+ will no longer be called upon thread exit.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_key_delete()>
+ function returns zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_key_delete()>
+ function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The
+ I<key>
+ value is invalid.
+
+ =back
+
+ The
+ I<pthread_key_delete()>
+ function will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_key_create()>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_kill> - send a signal to a thread
+
+ =head1 SYNOPSIS
+
+ #include <signal.h>
+
+ int pthread_kill(pthread_t I<thread>, int I<sig>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_kill()>
+ function is used to request that a signal be delivered to the specified thread.
+
+ As in
+ I<kill()>,
+ if
+ I<sig>
+ is zero, error checking is performed but no signal is actually sent.
+
+ =head1 RETURN VALUE
+
+ Upon successful completion, the function returns a value of zero.
+ Otherwise the function returns an error number.
+ If the
+ I<pthread_kill()>
+ function fails, no signal is sent.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_kill()>
+ function will fail if:
+
+ =over 4
+
+ =item [ESRCH]
+
+ No thread could be found corresponding to that specified
+ by the given thread ID.
+
+ =item [EINVAL]
+
+ The value of the
+ I<sig>
+ argument is an invalid or unsupported signal number.
+
+ =back
+
+ The
+ I<pthread_kill()>
+ function will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<kill()>,
+ I<pthread_self()>,
+ I<raise()>,
+ I<<signal.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_mutex_init,> B<pthread_mutex_destroy> - initialise or destroy a mutex
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_mutex_init(pthread_mutex_t *I<mutex>,
+ const pthread_mutexattr_t *I<attr>);
+ int pthread_mutex_destroy(pthread_mutex_t *I<mutex>);
+ pthread_mutex_t I<mutex> = PTHREAD_MUTEX_INITIALIZER;
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_mutex_init()>
+ function initialises the mutex referenced by
+ I<mutex>
+ with attributes specified
+ by
+ I<attr>.
+ If
+ I<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
+ I<pthread_mutex_destroy()>
+ function destroys the mutex object referenced by
+ I<mutex>;
+ the mutex object becomes, in effect, uninitialised.
+ An implementation may cause
+ I<pthread_mutex_destroy()>
+ to set the object referenced by
+ I<mutex>
+ to an invalid value.
+ A destroyed mutex object
+ can be re-initialised using
+ I<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
+ I<pthread_mutex_init()>
+ with parameter
+ I<attr>
+ specified as NULL,
+ except that no error checks are performed.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_mutex_init()>
+ and
+ I<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
+ I<mutex>.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_mutex_init()>
+ function will fail if:
+
+ =over 4
+
+ =item [EAGAIN]
+
+ The system lacked the necessary resources (other than memory)
+ to initialise another mutex.
+
+ =item [ENOMEM]
+
+ Insufficient memory exists to initialise the mutex.
+
+ =item [EPERM]
+
+ The caller does not have the privilege to perform the operation.
+
+ =back
+
+ The
+ I<pthread_mutex_init()>
+ function may fail if:
+
+ =over 4
+
+ =item [EBUSY]
+
+ The implementation has detected an attempt
+ to re-initialise the object referenced by
+ I<mutex>,
+ a previously initialised, but
+ not yet destroyed, mutex.
+
+ =item [EINVAL]
+
+ The value specified by
+ I<attr>
+ is invalid.
+
+ =back
+
+ The
+ I<pthread_mutex_destroy()>
+ function may fail if:
+
+ =over 4
+
+ =item [EBUSY]
+
+ The implementation has detected an attempt to destroy
+ the object referenced by
+ I<mutex>
+ while it is locked or referenced
+ (for example, while being used in a
+ I<pthread_cond_wait()>
+ or
+ I<pthread_cond_timedwait()>)
+ by another thread.
+
+ =item [EINVAL]
+
+ The value specified by
+ I<mutex>
+ is invalid.
+
+ =back
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_mutex_getprioceiling()>,
+ I<pthread_mutex_lock()>,
+ I<pthread_mutex_unlock()>,
+ I<pthread_mutex_setprioceiling()>,
+ I<pthread_mutex_trylock()>,
+ I<pthread_mutexattr_getpshared()>,
+ I<pthread_mutexattr_setpshared()>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_mutex_setprioceiling,> B<pthread_mutex_getprioceiling>
+ - change the priority ceiling of a mutex
+ (B<REALTIME THREADS>)
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_mutex_setprioceiling(pthread_mutex_t *I<mutex>, int I<prioceiling>, int *I<old_ceiling>);
+
+ int pthread_mutex_getprioceiling(const pthread_mutex_t *I<mutex>, int *I<prioceiling>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_mutex_getprioceiling()>
+ function returns the current priority ceiling of the mutex.
+
+ The
+ I<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
+ I<old_ceiling>.
+ The process of locking the mutex need not adhere
+ to the priority protect protocol.
+
+ If the
+ I<pthread_mutex_setprioceiling()>
+ function fails, the mutex priority ceiling is not changed.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_mutex_setprioceiling()>
+ and
+ I<pthread_mutex_getprioceiling()>
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_mutex_getprioceiling()>
+ and
+ I<pthread_mutex_setprioceiling()>
+ functions will fail if:
+
+ =over 4
+
+ =item [ENOSYS]
+
+ The option _POSIX_THREAD_PRIO_PROTECT is not defined and
+ the implementation does not support the function.
+
+ =back
+
+ The
+ I<pthread_mutex_setprioceiling()>
+ and
+ I<pthread_mutex_getprioceiling()>
+ functions may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The priority requested by
+ I<prioceiling>
+ is out of range.
+
+ =item [EINVAL]
+
+ The value specified by
+ I<mutex>
+ does not refer to a currently existing mutex.
+
+ =item [ENOSYS]
+
+ The implementation does not support the priority ceiling protocol for mutexes.
+
+ =item [EPERM]
+
+ The caller does not have the privilege to perform the operation.
+
+ =back
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_mutex_init()>,
+ I<pthread_mutex_lock()>,
+ I<pthread_mutex_unlock()>,
+ I<pthread_mutex_trylock()>,
+ I<<pthread.h>>.
+
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_mutex_init,> B<pthread_mutex_destroy> - initialise or destroy a mutex
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_mutex_init(pthread_mutex_t *I<mutex>,
+ const pthread_mutexattr_t *I<attr>);
+ int pthread_mutex_destroy(pthread_mutex_t *I<mutex>);
+ pthread_mutex_t I<mutex> = PTHREAD_MUTEX_INITIALIZER;
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_mutex_init()>
+ function initialises the mutex referenced by
+ I<mutex>
+ with attributes specified
+ by
+ I<attr>.
+ If
+ I<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
+ I<pthread_mutex_destroy()>
+ function destroys the mutex object referenced by
+ I<mutex>;
+ the mutex object becomes, in effect, uninitialised.
+ An implementation may cause
+ I<pthread_mutex_destroy()>
+ to set the object referenced by
+ I<mutex>
+ to an invalid value.
+ A destroyed mutex object
+ can be re-initialised using
+ I<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
+ I<pthread_mutex_init()>
+ with parameter
+ I<attr>
+ specified as NULL,
+ except that no error checks are performed.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_mutex_init()>
+ and
+ I<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
+ I<mutex>.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_mutex_init()>
+ function will fail if:
+
+ =over 4
+
+ =item [EAGAIN]
+
+ The system lacked the necessary resources (other than memory)
+ to initialise another mutex.
+
+ =item [ENOMEM]
+
+ Insufficient memory exists to initialise the mutex.
+
+ =item [EPERM]
+
+ The caller does not have the privilege to perform the operation.
+
+ =back
+
+ The
+ I<pthread_mutex_init()>
+ function may fail if:
+
+ =over 4
+
+ =item [EBUSY]
+
+ The implementation has detected an attempt
+ to re-initialise the object referenced by
+ I<mutex>,
+ a previously initialised, but
+ not yet destroyed, mutex.
+
+ =item [EINVAL]
+
+ The value specified by
+ I<attr>
+ is invalid.
+
+ =back
+
+ The
+ I<pthread_mutex_destroy()>
+ function may fail if:
+
+ =over 4
+
+ =item [EBUSY]
+
+ The implementation has detected an attempt to destroy
+ the object referenced by
+ I<mutex>
+ while it is locked or referenced
+ (for example, while being used in a
+ I<pthread_cond_wait()>
+ or
+ I<pthread_cond_timedwait()>)
+ by another thread.
+
+ =item [EINVAL]
+
+ The value specified by
+ I<mutex>
+ is invalid.
+
+ =back
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_mutex_getprioceiling()>,
+ I<pthread_mutex_lock()>,
+ I<pthread_mutex_unlock()>,
+ I<pthread_mutex_setprioceiling()>,
+ I<pthread_mutex_trylock()>,
+ I<pthread_mutexattr_getpshared()>,
+ I<pthread_mutexattr_setpshared()>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_mutex_lock,> B<pthread_mutex_trylock,> B<pthread_mutex_unlock>
+ - lock and unlock a mutex
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_mutex_lock(pthread_mutex_t *I<mutex>);
+ int pthread_mutex_trylock(pthread_mutex_t *I<mutex>);
+ int pthread_mutex_unlock(pthread_mutex_t *I<mutex>);
+
+ =head1 DESCRIPTION
+
+ The mutex object referenced by
+ I<mutex>
+ is locked by calling
+ I<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
+ I<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
+ I<pthread_mutex_trylock()>
+ is identical to
+ I<pthread_mutex_lock()>
+ except that if the mutex object referenced by
+ I<mutex>
+ is currently locked (by any thread, including the
+ current thread), the call returns immediately.
+
+ The
+ I<pthread_mutex_unlock()>
+ function releases the mutex object referenced by
+ I<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
+ I<mutex> when
+ I<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.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_mutex_lock()>
+ and
+ I<pthread_mutex_unlock()>
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ The function
+ I<pthread_mutex_trylock()>
+ returns zero if a lock on the mutex object referenced by
+ I<mutex>
+ is acquired.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_mutex_lock()>
+ and
+ I<pthread_mutex_trylock()>
+ functions will fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The
+ I<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.
+
+ =back
+
+ The
+ I<pthread_mutex_trylock()>
+ function will fail if:
+
+ =over 4
+
+ =item [EBUSY]
+
+ The
+ I<mutex>
+ could not be acquired because it was already locked.
+
+ =back
+
+ The
+ I<pthread_mutex_lock()>,
+ I<pthread_mutex_trylock()>
+ and
+ I<pthread_mutex_unlock()>
+ functions may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value specified by
+ I<mutex>
+ does not refer to an initialised mutex object.
+
+ =item [EAGAIN]
+
+ The mutex could not be acquired because the maximum
+ number of recursive locks for I<mutex> has been exceeded.
+
+ =back
+
+ The
+ I<pthread_mutex_lock()>
+ function may fail if:
+
+ =over 4
+
+ =item [EDEADLK]
+
+ The current thread already owns the mutex.
+
+ =back
+
+ The
+ I<pthread_mutex_unlock()>
+ function may fail if:
+
+ =over 4
+
+ =item [EPERM]
+
+ The current thread does not own the mutex.
+
+ =back
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_mutex_init()>,
+ I<pthread_mutex_destroy()>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_mutex_setprioceiling,> B<pthread_mutex_getprioceiling>
+ - change the priority ceiling of a mutex
+ (B<REALTIME THREADS>)
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_mutex_setprioceiling(pthread_mutex_t *I<mutex>, int
+ I<prioceiling>, int *I<old_ceiling>);
+
+ int pthread_mutex_getprioceiling(const pthread_mutex_t *I<mutex>,
+ int *I<prioceiling>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_mutex_getprioceiling()>
+ function returns the current priority ceiling of the mutex.
+
+ The
+ I<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
+ I<old_ceiling>.
+ The process of locking the mutex need not adhere
+ to the priority protect protocol.
+
+ If the
+ I<pthread_mutex_setprioceiling()>
+ function fails, the mutex priority ceiling is not changed.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_mutex_setprioceiling()>
+ and
+ I<pthread_mutex_getprioceiling()>
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_mutex_getprioceiling()>
+ and
+ I<pthread_mutex_setprioceiling()>
+ functions will fail if:
+
+ =over 4
+
+ =item [ENOSYS]
+
+ The option _POSIX_THREAD_PRIO_PROTECT is not defined and
+ the implementation does not support the function.
+
+ =back
+
+ The
+ I<pthread_mutex_setprioceiling()>
+ and
+ I<pthread_mutex_getprioceiling()>
+ functions may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The priority requested by
+ I<prioceiling>
+ is out of range.
+
+ =item [EINVAL]
+
+ The value specified by
+ I<mutex>
+ does not refer to a currently existing mutex.
+
+ =item [ENOSYS]
+
+ The implementation does not support the priority ceiling protocol for mutexes.
+
+ =item [EPERM]
+
+ The caller does not have the privilege to perform the operation.
+
+ =back
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_mutex_init()>,
+ I<pthread_mutex_lock()>,
+ I<pthread_mutex_unlock()>,
+ I<pthread_mutex_trylock()>,
+ I<<pthread.h>>.
+
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_mutex_lock,> B<pthread_mutex_trylock,> B<pthread_mutex_unlock>
+ - lock and unlock a mutex
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_mutex_lock(pthread_mutex_t *I<mutex>);
+ int pthread_mutex_trylock(pthread_mutex_t *I<mutex>);
+ int pthread_mutex_unlock(pthread_mutex_t *I<mutex>);
+
+ =head1 DESCRIPTION
+
+ The mutex object referenced by
+ I<mutex>
+ is locked by calling
+ I<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
+ I<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
+ I<pthread_mutex_trylock()>
+ is identical to
+ I<pthread_mutex_lock()>
+ except that if the mutex object referenced by
+ I<mutex>
+ is currently locked (by any thread, including the
+ current thread), the call returns immediately.
+
+ The
+ I<pthread_mutex_unlock()>
+ function releases the mutex object referenced by
+ I<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
+ I<mutex> when
+ I<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.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_mutex_lock()>
+ and
+ I<pthread_mutex_unlock()>
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ The function
+ I<pthread_mutex_trylock()>
+ returns zero if a lock on the mutex object referenced by
+ I<mutex>
+ is acquired.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_mutex_lock()>
+ and
+ I<pthread_mutex_trylock()>
+ functions will fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The
+ I<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.
+
+ =back
+
+ The
+ I<pthread_mutex_trylock()>
+ function will fail if:
+
+ =over 4
+
+ =item [EBUSY]
+
+ The
+ I<mutex>
+ could not be acquired because it was already locked.
+
+ =back
+
+ The
+ I<pthread_mutex_lock()>,
+ I<pthread_mutex_trylock()>
+ and
+ I<pthread_mutex_unlock()>
+ functions may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value specified by
+ I<mutex>
+ does not refer to an initialised mutex object.
+
+ =item [EAGAIN]
+
+ The mutex could not be acquired because the maximum
+ number of recursive locks for I<mutex> has been exceeded.
+
+ =back
+
+ The
+ I<pthread_mutex_lock()>
+ function may fail if:
+
+ =over 4
+
+ =item [EDEADLK]
+
+ The current thread already owns the mutex.
+
+ =back
+
+ The
+ I<pthread_mutex_unlock()>
+ function may fail if:
+
+ =over 4
+
+ =item [EPERM]
+
+ The current thread does not own the mutex.
+
+ =back
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_mutex_init()>,
+ I<pthread_mutex_destroy()>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_mutex_lock,> B<pthread_mutex_trylock,> B<pthread_mutex_unlock>
+ - lock and unlock a mutex
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_mutex_lock(pthread_mutex_t *I<mutex>);
+ int pthread_mutex_trylock(pthread_mutex_t *I<mutex>);
+ int pthread_mutex_unlock(pthread_mutex_t *I<mutex>);
+
+ =head1 DESCRIPTION
+
+ The mutex object referenced by
+ I<mutex>
+ is locked by calling
+ I<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
+ I<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
+ I<pthread_mutex_trylock()>
+ is identical to
+ I<pthread_mutex_lock()>
+ except that if the mutex object referenced by
+ I<mutex>
+ is currently locked (by any thread, including the
+ current thread), the call returns immediately.
+
+ The
+ I<pthread_mutex_unlock()>
+ function releases the mutex object referenced by
+ I<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
+ I<mutex> when
+ I<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.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_mutex_lock()>
+ and
+ I<pthread_mutex_unlock()>
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ The function
+ I<pthread_mutex_trylock()>
+ returns zero if a lock on the mutex object referenced by
+ I<mutex>
+ is acquired.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_mutex_lock()>
+ and
+ I<pthread_mutex_trylock()>
+ functions will fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The
+ I<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.
+
+ =back
+
+ The
+ I<pthread_mutex_trylock()>
+ function will fail if:
+
+ =over 4
+
+ =item [EBUSY]
+
+ The
+ I<mutex>
+ could not be acquired because it was already locked.
+
+ =back
+
+ The
+ I<pthread_mutex_lock()>,
+ I<pthread_mutex_trylock()>
+ and
+ I<pthread_mutex_unlock()>
+ functions may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value specified by
+ I<mutex>
+ does not refer to an initialised mutex object.
+
+ =item [EAGAIN]
+
+ The mutex could not be acquired because the maximum
+ number of recursive locks for I<mutex> has been exceeded.
+
+ =back
+
+ The
+ I<pthread_mutex_lock()>
+ function may fail if:
+
+ =over 4
+
+ =item [EDEADLK]
+
+ The current thread already owns the mutex.
+
+ =back
+
+ The
+ I<pthread_mutex_unlock()>
+ function may fail if:
+
+ =over 4
+
+ =item [EPERM]
+
+ The current thread does not own the mutex.
+
+ =back
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_mutex_init()>,
+ I<pthread_mutex_destroy()>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_mutexattr_init,> B<pthread_mutexattr_destroy>
+ - initialise and destroy mutex attributes object
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_mutexattr_init(pthread_mutexattr_t *I<attr>);
+ int pthread_mutexattr_destroy(pthread_mutexattr_t *I<attr>);
+
+ =head1 DESCRIPTION
+
+ The function
+ I<pthread_mutexattr_init()>
+ initialises a mutex attributes object
+ I<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
+ I<pthread_mutexattr_destroy()>
+ function destroys a mutex attributes object;
+ the object becomes, in effect, uninitialised.
+ An implementation may cause
+ I<pthread_mutexattr_destroy()>
+ to set the object referenced by
+ I<attr>
+ to an invalid value.
+ A destroyed mutex attributes object
+ can be re-initialised using
+ I<pthread_mutexattr_init()>;
+ the results of otherwise referencing the object after it has been
+ destroyed are undefined.
+
+ =head1 RETURN VALUE
+
+ Upon successful completion,
+ I<pthread_mutexattr_init()>
+ and
+ I<pthread_mutexattr_destroy()>
+ return zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_mutexattr_init()>
+ function may fail if:
+
+ =over 4
+
+ =item [ENOMEM]
+
+ Insufficient memory exists to initialise the mutex attributes object.
+
+ =back
+
+ The
+ I<pthread_mutexattr_destroy()>
+ function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value specified by
+ I<attr>
+ is invalid.
+
+ =back
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_create()>,
+ I<pthread_mutex_init()>,
+ I<pthread_mutexattr_init()>,
+ I<pthread_cond_init()>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_mutexattr_setprioceiling,> B<pthread_mutexattr_getprioceiling>
+ - set and get prioceiling attribute of mutex attribute object
+ (B<REALTIME THREADS>)
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *I<attr>,
+ int I<prioceiling>);
+ int pthread_mutexattr_getprioceiling(const pthread_mutexattr_t *I<attr>,
+ int *I<prioceiling>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_mutexattr_setprioceiling()>
+ and
+ I<pthread_mutexattr_getprioceiling()>
+ functions, respectively, set and get the priority ceiling attribute of
+ a mutex attribute object pointed to by
+ I<attr>
+ which was previously created by the function
+ I<pthread_mutexattr_init()>.
+
+ The
+ I<prioceiling>
+ attribute contains the priority ceiling of initialised mutexes.
+ The values of
+ I<prioceiling>
+ will be within the maximum range of priorities defined by SCHED_FIFO.
+
+ The
+ I<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
+ I<prioceiling>
+ will be within the maximum range of priorities
+ defined under the SCHED_FIFO scheduling policy.
+
+ =head1 RETURN VALUE
+
+ Upon successful completion, the
+ I<pthread_mutexattr_setprioceiling()>
+ and
+ I<pthread_mutexattr_getprioceiling()>
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_mutexattr_setprioceiling()>
+ and
+ I<pthread_mutexattr_getprioceiling()>
+ functions will fail if:
+
+ =over 4
+
+ =item [ENOSYS]
+
+ The option _POSIX_THREAD_PRIO_PROTECT is not defined and the
+ implementation does not support the function.
+
+ =back
+
+ The
+ I<pthread_mutexattr_setprioceiling()>
+ and
+ I<pthread_mutexattr_getprioceiling()>
+ functions may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value specified by
+ I<attr>
+ or
+ I<prioceiling>
+ is invalid.
+
+ =item [EPERM]
+
+ The caller does not have the privilege to perform the operation.
+
+ =back
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_create()>,
+ I<pthread_mutex_init()>,
+ I<pthread_cond_init()>,
+ I<<pthread.h>>.
+
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_mutexattr_setprotocol,> B<pthread_mutexattr_getprotocol>
+ - set and get protocol attribute of mutex attribute object
+ (B<REALTIME THREADS>)
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_mutexattr_setprotocol(pthread_mutexattr_t *I<attr>,
+ int I<protocol>);
+ int pthread_mutexattr_getprotocol(const pthread_mutexattr_t *I<attr>,
+ int *I<protocol>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_mutexattr_setprotocol()>
+ and
+ I<pthread_mutexattr_getprotocol()>
+ functions, respectively, set and get the protocol attribute of a mutex
+ attribute object pointed to by
+ I<attr>
+ which was previously created by the function
+ I<pthread_mutexattr_init()>.
+
+ The
+ I<protocol>
+ attribute defines the protocol to be followed in utilising mutexes.
+ The value of
+ I<protocol>
+ may be one of PTHREAD_PRIO_NONE, PTHREAD_PRIO_INHERIT or
+ PTHREAD_PRIO_PROTECT, which are defined by the header
+ I<<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
+ I<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
+ I<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.
+
+ =head1 RETURN VALUE
+
+ Upon successful completion, the
+ I<pthread_mutexattr_setprotocol()>
+ and
+ I<pthread_mutexattr_getprotocol()>
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_mutexattr_setprotocol()>
+ and
+ I<pthread_mutexattr_getprotocol()>
+ functions will fail if:
+
+ =over 4
+
+ =item [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.
+
+ =item [ENOTSUP]
+
+ The value specified by
+ I<protocol>
+ is an unsupported value.
+
+ =back
+
+ The
+ I<pthread_mutexattr_setprotocol()>
+ and
+ I<pthread_mutexattr_getprotocol()>
+ functions may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value specified by
+ I<attr>
+ ro
+ I<protocol>
+ is invalid.
+
+ =item [EPERM]
+
+ The caller does not have the privilege to perform the operation.
+
+ =back
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_create()>,
+ I<pthread_mutex_init()>,
+ I<pthread_cond_init()>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_mutexattr_getpshared,> B<pthread_mutexattr_setpshared>
+ - set and get process-shared attribute
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_mutexattr_getpshared(const pthread_mutexattr_t *I<attr>,
+ int *I<pshared>);
+ int pthread_mutexattr_setpshared(pthread_mutexattr_t *I<attr>,
+ int I<pshared>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_mutexattr_getpshared()>
+ function obtains the value of the
+ I<process-shared>
+ attribute from the attributes object referenced by
+ I<attr>.
+ The
+ I<pthread_mutexattr_setpshared()>
+ function is used to set the
+ I<process-shared>
+ attribute in an initialised attributes object referenced by
+ I<attr>.
+
+ The
+ I<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
+ I<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.
+
+ =head1 RETURN VALUE
+
+ Upon successful completion,
+ I<pthread_mutexattr_setpshared()>
+ returns zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ Upon successful completion,
+ I<pthread_mutexattr_getpshared()>
+ returns zero and stores the value of the
+ I<process-shared>
+ attribute of
+ I<attr>
+ into the object referenced by the
+ I<pshared>
+ parameter.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_mutexattr_getpshared()>
+ and
+ I<pthread_mutexattr_setpshared()>
+ functions may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value specified by
+ I<attr>
+ is invalid.
+
+ =back
+
+ The
+ I<pthread_mutexattr_setpshared()>
+ function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The new value specified for the attribute
+ is outside the range of legal values for that attribute.
+
+ =back
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_create()>,
+ I<pthread_mutex_init()>,
+ I<pthread_mutexattr_init()>,
+ I<pthread_cond_init()>,
+ I<<pthread.h>>.
+
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_mutexattr_gettype,> B<pthread_mutexattr_settype>
+ - get or set a mutex type
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_mutexattr_gettype(const pthread_mutexattr_t I<*attr>, int I<*type>);
+ int pthread_mutexattr_settype(pthread_mutexattr_t I<*attr>, int I<type>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_mutexattr_gettype()>
+ and
+ I<pthread_mutexattr_settype()>
+ functions respectively get and set the mutex I<type> attribute.
+ This attribute is set in the I<type> parameter
+ to these functions. The default value of the I<type>
+ attribute is PTHREAD_MUTEX_DEFAULT.
+
+ The type of mutex is contained in the I<type> attribute of the
+ mutex attributes. Valid mutex types include:
+
+ =over 4
+
+ =item 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.
+
+ =item 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.
+
+ =item 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.
+
+ =item 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.
+
+ =back
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_mutexattr_settype()>
+ function
+ returns zero. Otherwise, an error number is
+ returned to indicate the error.
+
+ Upon successful completion, the
+ I<pthread_mutexattr_gettype()>
+ function returns zero and stores the value of the
+ I<type> attribute of I<attr> into the object referenced by the
+ I<type>
+ parameter. Otherwise an error is returned to indicate
+ the error.
+
+
+ =head1 ERRORS
+
+ The
+ I<pthread_mutexattr_gettype()>
+ and
+ I<pthread_mutexattr_settype()>
+ functions will fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value I<type> is invalid.
+
+ =back
+
+ The
+ I<pthread_mutexattr_gettype()>
+ and
+ I<pthread_mutexattr_settype()>
+ functions may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value specified by I<attr> is invalid.
+
+ =back
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 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
+ I<pthread_cond_wait()>
+ or
+ I<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.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_cond_wait()>,
+ I<pthread_cond_timedwait()>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_mutexattr_init,> B<pthread_mutexattr_destroy>
+ - initialise and destroy mutex attributes object
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_mutexattr_init(pthread_mutexattr_t *I<attr>);
+ int pthread_mutexattr_destroy(pthread_mutexattr_t *I<attr>);
+
+ =head1 DESCRIPTION
+
+ The function
+ I<pthread_mutexattr_init()>
+ initialises a mutex attributes object
+ I<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
+ I<pthread_mutexattr_destroy()>
+ function destroys a mutex attributes object;
+ the object becomes, in effect, uninitialised.
+ An implementation may cause
+ I<pthread_mutexattr_destroy()>
+ to set the object referenced by
+ I<attr>
+ to an invalid value.
+ A destroyed mutex attributes object
+ can be re-initialised using
+ I<pthread_mutexattr_init()>;
+ the results of otherwise referencing the object after it has been
+ destroyed are undefined.
+
+ =head1 RETURN VALUE
+
+ Upon successful completion,
+ I<pthread_mutexattr_init()>
+ and
+ I<pthread_mutexattr_destroy()>
+ return zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_mutexattr_init()>
+ function may fail if:
+
+ =over 4
+
+ =item [ENOMEM]
+
+ Insufficient memory exists to initialise the mutex attributes object.
+
+ =back
+
+ The
+ I<pthread_mutexattr_destroy()>
+ function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value specified by
+ I<attr>
+ is invalid.
+
+ =back
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_create()>,
+ I<pthread_mutex_init()>,
+ I<pthread_mutexattr_init()>,
+ I<pthread_cond_init()>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_mutexattr_setprioceiling,> B<pthread_mutexattr_getprioceiling>
+ - set and get prioceiling attribute of mutex attribute object
+ (B<REALTIME THREADS>)
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *I<attr>,
+ int I<prioceiling>);
+ int pthread_mutexattr_getprioceiling(const pthread_mutexattr_t *I<attr>,
+ int *I<prioceiling>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_mutexattr_setprioceiling()>
+ and
+ I<pthread_mutexattr_getprioceiling()>
+ functions, respectively, set and get the priority ceiling attribute of
+ a mutex attribute object pointed to by
+ I<attr>
+ which was previously created by the function
+ I<pthread_mutexattr_init()>.
+
+ The
+ I<prioceiling>
+ attribute contains the priority ceiling of initialised mutexes.
+ The values of
+ I<prioceiling>
+ will be within the maximum range of priorities defined by SCHED_FIFO.
+
+ The
+ I<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
+ I<prioceiling>
+ will be within the maximum range of priorities
+ defined under the SCHED_FIFO scheduling policy.
+
+ =head1 RETURN VALUE
+
+ Upon successful completion, the
+ I<pthread_mutexattr_setprioceiling()>
+ and
+ I<pthread_mutexattr_getprioceiling()>
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_mutexattr_setprioceiling()>
+ and
+ I<pthread_mutexattr_getprioceiling()>
+ functions will fail if:
+
+ =over 4
+
+ =item [ENOSYS]
+
+ The option _POSIX_THREAD_PRIO_PROTECT is not defined and the
+ implementation does not support the function.
+
+ =back
+
+ The
+ I<pthread_mutexattr_setprioceiling()>
+ and
+ I<pthread_mutexattr_getprioceiling()>
+ functions may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value specified by
+ I<attr>
+ or
+ I<prioceiling>
+ is invalid.
+
+ =item [EPERM]
+
+ The caller does not have the privilege to perform the operation.
+
+ =back
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_create()>,
+ I<pthread_mutex_init()>,
+ I<pthread_cond_init()>,
+ I<<pthread.h>>.
+
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_mutexattr_setprotocol,> B<pthread_mutexattr_getprotocol>
+ - set and get protocol attribute of mutex attribute object
+ (B<REALTIME THREADS>)
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_mutexattr_setprotocol(pthread_mutexattr_t *I<attr>,
+ int I<protocol>);
+ int pthread_mutexattr_getprotocol(const pthread_mutexattr_t *I<attr>,
+ int *I<protocol>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_mutexattr_setprotocol()>
+ and
+ I<pthread_mutexattr_getprotocol()>
+ functions, respectively, set and get the protocol attribute of a mutex
+ attribute object pointed to by
+ I<attr>
+ which was previously created by the function
+ I<pthread_mutexattr_init()>.
+
+ The
+ I<protocol>
+ attribute defines the protocol to be followed in utilising mutexes.
+ The value of
+ I<protocol>
+ may be one of PTHREAD_PRIO_NONE, PTHREAD_PRIO_INHERIT or
+ PTHREAD_PRIO_PROTECT, which are defined by the header
+ I<<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
+ I<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
+ I<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.
+
+ =head1 RETURN VALUE
+
+ Upon successful completion, the
+ I<pthread_mutexattr_setprotocol()>
+ and
+ I<pthread_mutexattr_getprotocol()>
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_mutexattr_setprotocol()>
+ and
+ I<pthread_mutexattr_getprotocol()>
+ functions will fail if:
+
+ =over 4
+
+ =item [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.
+
+ =item [ENOTSUP]
+
+ The value specified by
+ I<protocol>
+ is an unsupported value.
+
+ =back
+
+ The
+ I<pthread_mutexattr_setprotocol()>
+ and
+ I<pthread_mutexattr_getprotocol()>
+ functions may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value specified by
+ I<attr>
+ ro
+ I<protocol>
+ is invalid.
+
+ =item [EPERM]
+
+ The caller does not have the privilege to perform the operation.
+
+ =back
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_create()>,
+ I<pthread_mutex_init()>,
+ I<pthread_cond_init()>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_mutexattr_getpshared,> B<pthread_mutexattr_setpshared>
+ - set and get process-shared attribute
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_mutexattr_getpshared(const pthread_mutexattr_t *I<attr>,
+ int *I<pshared>);
+ int pthread_mutexattr_setpshared(pthread_mutexattr_t *I<attr>,
+ int I<pshared>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_mutexattr_getpshared()>
+ function obtains the value of the
+ I<process-shared>
+ attribute from the attributes object referenced by
+ I<attr>.
+ The
+ I<pthread_mutexattr_setpshared()>
+ function is used to set the
+ I<process-shared>
+ attribute in an initialised attributes object referenced by
+ I<attr>.
+
+ The
+ I<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
+ I<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.
+
+ =head1 RETURN VALUE
+
+ Upon successful completion,
+ I<pthread_mutexattr_setpshared()>
+ returns zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ Upon successful completion,
+ I<pthread_mutexattr_getpshared()>
+ returns zero and stores the value of the
+ I<process-shared>
+ attribute of
+ I<attr>
+ into the object referenced by the
+ I<pshared>
+ parameter.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_mutexattr_getpshared()>
+ and
+ I<pthread_mutexattr_setpshared()>
+ functions may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value specified by
+ I<attr>
+ is invalid.
+
+ =back
+
+ The
+ I<pthread_mutexattr_setpshared()>
+ function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The new value specified for the attribute
+ is outside the range of legal values for that attribute.
+
+ =back
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_create()>,
+ I<pthread_mutex_init()>,
+ I<pthread_mutexattr_init()>,
+ I<pthread_cond_init()>,
+ I<<pthread.h>>.
+
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_mutexattr_gettype,> B<pthread_mutexattr_settype>
+ - get or set a mutex type
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_mutexattr_gettype(const pthread_mutexattr_t I<*attr>, int I<*type>);
+ int pthread_mutexattr_settype(pthread_mutexattr_t I<*attr>, int I<type>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_mutexattr_gettype()>
+ and
+ I<pthread_mutexattr_settype()>
+ functions respectively get and set the mutex I<type> attribute.
+ This attribute is set in the I<type> parameter
+ to these functions. The default value of the I<type>
+ attribute is PTHREAD_MUTEX_DEFAULT.
+
+ The type of mutex is contained in the I<type> attribute of the
+ mutex attributes. Valid mutex types include:
+
+ =over 4
+
+ =item 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.
+
+ =item 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.
+
+ =item 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.
+
+ =item 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.
+
+ =back
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_mutexattr_settype()>
+ function
+ returns zero. Otherwise, an error number is
+ returned to indicate the error.
+
+ Upon successful completion, the
+ I<pthread_mutexattr_gettype()>
+ function returns zero and stores the value of the
+ I<type> attribute of I<attr> into the object referenced by the
+ I<type>
+ parameter. Otherwise an error is returned to indicate
+ the error.
+
+
+ =head1 ERRORS
+
+ The
+ I<pthread_mutexattr_gettype()>
+ and
+ I<pthread_mutexattr_settype()>
+ functions will fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value I<type> is invalid.
+
+ =back
+
+ The
+ I<pthread_mutexattr_gettype()>
+ and
+ I<pthread_mutexattr_settype()>
+ functions may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value specified by I<attr> is invalid.
+
+ =back
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 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
+ I<pthread_cond_wait()>
+ or
+ I<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.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_cond_wait()>,
+ I<pthread_cond_timedwait()>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_once> - dynamic package initialisation
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_once(pthread_once_t *I<once_control>,
+ void (*I<init_routine>)(void));
+ pthread_once_t I<once_control> = PTHREAD_ONCE_INIT;
+
+ =head1 DESCRIPTION
+
+ The first call to
+ I<pthread_once()>
+ by any thread in a process, with a given
+ I<once_control>,
+ will call the
+ I<init_routine()>
+ with no arguments.
+ Subsequent calls of
+ I<pthread_once()>
+ with the same
+ I<once_control>
+ will not call the
+ I<init_routine()>.
+ On return from
+ I<pthread_once()>,
+ it is guaranteed that
+ I<init_routine()>
+ has completed.
+ The
+ I<once_control>
+ parameter is used to determine whether
+ the associated initialisation routine has been called.
+
+ The function
+ I<pthread_once()>
+ is not a cancellation point.
+ However, if
+ I<init_routine()>
+ is a cancellation point and is canceled,
+ the effect on
+ I<once_control>
+ is as if
+ I<pthread_once()>
+ was never called.
+
+ The constant PTHREAD_ONCE_INIT
+ is defined by the header
+ I<<pthread.h>>.
+
+ The behaviour of
+ I<pthread_once()>
+ is undefined if
+ I<once_control>
+ has automatic storage duration or is not initialised by
+ PTHREAD_ONCE_INIT.
+
+ =head1 RETURN VALUE
+
+ Upon successful completion,
+ I<pthread_once()>
+ returns zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ No errors are defined.
+
+ The
+ I<pthread_once()>
+ function will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<<pthread,h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_rwlock_init,> B<pthread_rwlock_destroy>
+ - initialise or destroy a read-write lock object
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_rwlock_init(pthread_rwlock_t *rwlock,
+ const pthread_rwlockattr_t I<*attr>);
+ int pthread_rwlock_destroy(pthread_rwlock_t I<*rwlock>);
+ pthread_rwlock_t I<rwlock>=PTHREAD_RWLOCK_INITIALIZER;
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_rwlock_init()>
+ function initialises the read-write lock referenced by I<rwlock> with
+ the attributes referenced by I<attr>. If I<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
+ I<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
+ I<pthread_rwlock_init()>
+ function fails, I<rwlock> is not initialised and the contents of
+ I<rwlock> are undefined.
+
+ The
+ I<pthread_rwlock_destroy()>
+ function destroys the read-write lock object referenced by I<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
+ I<pthread_rwlock_init()>.
+ An implementation may cause
+ I<pthread_rwlock_destroy()>
+ to set the object referenced by I<rwlock> to an invalid value.
+ Results are undefined if
+ I<pthread_rwlock_destroy()>
+ is called when any thread holds I<rwlock>.
+ Attempting to destroy an uninitialised
+ read-write lock results in undefined behaviour.
+ A destroyed read-write lock object can be re-initialised using
+ I<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
+ I<pthread_rwlock_init()>
+ with the parameter I<attr> specified as NULL, except that no error
+ checks are performed.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_rwlock_init()>
+ and
+ I<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
+ I<rwlock>.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_rwlock_init()>
+ function will fail if:
+
+ =over 4
+
+ =item [EAGAIN]
+
+ The system lacked the necessary resources (other than memory)
+ to initialise another read-write lock.
+
+ =item [ENOMEM]
+
+ Insufficient memory exists to initialise the read-write lock.
+
+ =item [EPERM]
+
+ The caller does not have the privilege to perform the operation.
+
+ =back
+
+ The
+ I<pthread_rwlock_init()>
+ function may fail if:
+
+ =over 4
+
+ =item [EBUSY]
+
+ The implementation has detected an attempt to re-initialise the
+ object referenced by I<rwlock>, a previously initialised but
+ not yet destroyed read-write lock.
+
+ =item [EINVAL]
+
+ The value specified by I<attr> is invalid.
+
+ =back
+
+ The
+ I<pthread_rwlock_destroy()>
+ function may fail if:
+
+ =over 4
+
+ =item [EBUSY]
+
+ The implementation has detected an attempt to destroy the
+ object referenced by I<rwlock> while it is locked.
+
+ =item [EINVAL]
+
+ The value specified by I<attr> is invalid.
+
+ =back
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 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.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<<pthread.h>>,
+ I<pthread_rwlock_rdlock()>,
+ I<pthread_rwlock_wrlock()>,
+ I<pthread_rwlockattr_init()>,
+ I<pthread_rwlock_unlock()>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_rwlock_init,> B<pthread_rwlock_destroy>
+ - initialise or destroy a read-write lock object
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_rwlock_init(pthread_rwlock_t *rwlock,
+ const pthread_rwlockattr_t I<*attr>);
+ int pthread_rwlock_destroy(pthread_rwlock_t I<*rwlock>);
+ pthread_rwlock_t I<rwlock>=PTHREAD_RWLOCK_INITIALIZER;
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_rwlock_init()>
+ function initialises the read-write lock referenced by I<rwlock> with
+ the attributes referenced by I<attr>. If I<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
+ I<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
+ I<pthread_rwlock_init()>
+ function fails, I<rwlock> is not initialised and the contents of
+ I<rwlock> are undefined.
+
+ The
+ I<pthread_rwlock_destroy()>
+ function destroys the read-write lock object referenced by I<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
+ I<pthread_rwlock_init()>.
+ An implementation may cause
+ I<pthread_rwlock_destroy()>
+ to set the object referenced by I<rwlock> to an invalid value.
+ Results are undefined if
+ I<pthread_rwlock_destroy()>
+ is called when any thread holds I<rwlock>.
+ Attempting to destroy an uninitialised
+ read-write lock results in undefined behaviour.
+ A destroyed read-write lock object can be re-initialised using
+ I<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
+ I<pthread_rwlock_init()>
+ with the parameter I<attr> specified as NULL, except that no error
+ checks are performed.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_rwlock_init()>
+ and
+ I<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
+ I<rwlock>.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_rwlock_init()>
+ function will fail if:
+
+ =over 4
+
+ =item [EAGAIN]
+
+ The system lacked the necessary resources (other than memory)
+ to initialise another read-write lock.
+
+ =item [ENOMEM]
+
+ Insufficient memory exists to initialise the read-write lock.
+
+ =item [EPERM]
+
+ The caller does not have the privilege to perform the operation.
+
+ =back
+
+ The
+ I<pthread_rwlock_init()>
+ function may fail if:
+
+ =over 4
+
+ =item [EBUSY]
+
+ The implementation has detected an attempt to re-initialise the
+ object referenced by I<rwlock>, a previously initialised but
+ not yet destroyed read-write lock.
+
+ =item [EINVAL]
+
+ The value specified by I<attr> is invalid.
+
+ =back
+
+ The
+ I<pthread_rwlock_destroy()>
+ function may fail if:
+
+ =over 4
+
+ =item [EBUSY]
+
+ The implementation has detected an attempt to destroy the
+ object referenced by I<rwlock> while it is locked.
+
+ =item [EINVAL]
+
+ The value specified by I<attr> is invalid.
+
+ =back
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 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.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<<pthread.h>>,
+ I<pthread_rwlock_rdlock()>,
+ I<pthread_rwlock_wrlock()>,
+ I<pthread_rwlockattr_init()>,
+ I<pthread_rwlock_unlock()>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_rwlock_rdlock,> B<pthread_rwlock_tryrdlock>
+ - lock a read-write lock object for reading
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_rwlock_rdlock(pthread_rwlock_t I<*rwlock>);
+ int pthread_rwlock_tryrdlock(pthread_rwlock_t I<*rwlock>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_rwlock_rdlock()>
+ function applies a read lock to the read-write lock referenced by
+ I<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
+ I<pthread_rwlock_rdlock()>
+ call) until it can acquire the lock.
+ Results are undefined if the calling thread holds
+ a write lock on I<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 I<rwlock>
+ (that is, successfully call the
+ I<pthread_rwlock_rdlock()>
+ function I<n> times). If so, the thread
+ must perform matching unlocks (that is, it must
+ call the
+ I<pthread_rwlock_unlock()>
+ function I<n> times).
+
+ The function
+ I<pthread_rwlock_tryrdlock()>
+ applies a read lock
+ as in the
+ I<pthread_rwlock_rdlock()>
+ function
+ with the exception that the function fails if any thread holds a
+ write lock on I<rwlock> or there are writers blocked
+ on I<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.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_rwlock_rdlock()>
+ function returns zero.
+ Otherwise, an error number is returned
+ to indicate the error.
+
+ The function
+ I<pthread_rwlock_tryrdlock()>
+ returns zero if the
+ lock for reading on the read-write lock object
+ referenced by I<rwlock> is acquired.
+ Otherwise an error number
+ is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_rwlock_tryrdlock()>
+ function will fail if:
+
+ =over 4
+
+ =item [EBUSY]
+
+ The read-write lock could not be acquired for reading because a
+ writer holds the
+ lock or was blocked on it.
+
+ =back
+
+ The
+ I<pthread_rwlock_rdlock()>
+ and
+ I<pthread_rwlock_tryrdlock()>
+ functions may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value specified by I<rwlock> does not refer to an initialised
+ read-write lock object.
+
+ =item [EDEADLK]
+
+ The current thread already owns the read-write lock for writing.
+
+ =item [EAGAIN]
+
+ The read lock could not be acquired because the maximum number of
+ read locks
+ for I<rwlock> has been exceeded.
+
+ =back
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 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 "locks" a read-write
+ lock that is about to be "unlocked" 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.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<<pthread.h>>,
+ I<pthread_rwlock_init()>,
+ I<pthread_rwlock_wrlock()>,
+ I<pthread_rwlockattr_init()>,
+ I<pthread_rwlock_unlock()>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_rwlock_rdlock,> B<pthread_rwlock_tryrdlock>
+ - lock a read-write lock object for reading
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_rwlock_rdlock(pthread_rwlock_t I<*rwlock>);
+ int pthread_rwlock_tryrdlock(pthread_rwlock_t I<*rwlock>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_rwlock_rdlock()>
+ function applies a read lock to the read-write lock referenced by
+ I<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
+ I<pthread_rwlock_rdlock()>
+ call) until it can acquire the lock.
+ Results are undefined if the calling thread holds
+ a write lock on I<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 I<rwlock>
+ (that is, successfully call the
+ I<pthread_rwlock_rdlock()>
+ function I<n> times). If so, the thread
+ must perform matching unlocks (that is, it must
+ call the
+ I<pthread_rwlock_unlock()>
+ function I<n> times).
+
+ The function
+ I<pthread_rwlock_tryrdlock()>
+ applies a read lock
+ as in the
+ I<pthread_rwlock_rdlock()>
+ function
+ with the exception that the function fails if any thread holds a
+ write lock on I<rwlock> or there are writers blocked
+ on I<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.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_rwlock_rdlock()>
+ function returns zero.
+ Otherwise, an error number is returned
+ to indicate the error.
+
+ The function
+ I<pthread_rwlock_tryrdlock()>
+ returns zero if the
+ lock for reading on the read-write lock object
+ referenced by I<rwlock> is acquired.
+ Otherwise an error number
+ is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_rwlock_tryrdlock()>
+ function will fail if:
+
+ =over 4
+
+ =item [EBUSY]
+
+ The read-write lock could not be acquired for reading because a
+ writer holds the
+ lock or was blocked on it.
+
+ =back
+
+ The
+ I<pthread_rwlock_rdlock()>
+ and
+ I<pthread_rwlock_tryrdlock()>
+ functions may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value specified by I<rwlock> does not refer to an initialised
+ read-write lock object.
+
+ =item [EDEADLK]
+
+ The current thread already owns the read-write lock for writing.
+
+ =item [EAGAIN]
+
+ The read lock could not be acquired because the maximum number of
+ read locks
+ for I<rwlock> has been exceeded.
+
+ =back
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 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 "locks" a read-write
+ lock that is about to be "unlocked" 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.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<<pthread.h>>,
+ I<pthread_rwlock_init()>,
+ I<pthread_rwlock_wrlock()>,
+ I<pthread_rwlockattr_init()>,
+ I<pthread_rwlock_unlock()>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_rwlock_wrlock,> B<pthread_rwlock_trywrlock>
+ - lock a read-write lock object for writing
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_rwlock_wrlock(pthread_rwlock_t I<*rwlock>);
+ int pthread_rwlock_trywrlock(pthread_rwlock_t I<*rwlock>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_rwlock_wrlock()>
+ function applies a write lock to
+ the read-write lock referenced by I<rwlock>. The
+ calling thread acquires the write lock if no other thread
+ (reader or writer) holds the read-write lock I<rwlock>.
+ Otherwise, the thread blocks (that is, does not return from the
+ I<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
+ I<pthread_rwlock_trywrlock()>
+ applies a write lock
+ like the
+ I<pthread_rwlock_wrlock()>
+ function, with the exception that the function fails if any
+ thread currently holds I<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.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_rwlock_wrlock()>
+ function returns zero.
+ Otherwise, an error number is returned
+ to indicate the error.
+
+ The function
+ I<pthread_rwlock_trywrlock()>
+ returns zero if the
+ lock for writing on the read-write lock object
+ referenced by I<rwlock> is acquired.
+ Otherwise an error number is
+ returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_rwlock_trywrlock()>
+ function will fail if:
+
+ =over 4
+
+ =item [EBUSY]
+
+ The read-write lock could not be acquired for writing because it
+ was already locked for reading or writing.
+
+ =back
+
+ The
+ I<pthread_rwlock_wrlock()>
+ and
+ I<pthread_rwlock_trywrlock()>
+ functions may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value specified by I<rwlock> does not refer to an initialised
+ read-write lock object.
+
+ =item [EDEADLK]
+
+ The current thread already owns the read-write lock for writing or
+ reading.
+
+ =back
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 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 "locks" a read-write
+ lock that is about to be "unlocked" 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.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<<pthread.h>>,
+ I<pthread_rwlock_init()>,
+ I<pthread_rwlock_unlock()>,
+ I<pthread_rwlockattr_init()>,
+ I<pthread_rwlock_rdlock()>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_rwlock_unlock> - unlock a read-write lock object
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_rwlock_unlock(pthread_rwlock_t I<*rwlock>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_rwlock_unlock()>
+ function is called to release a lock held on the read-write lock
+ object referenced by I<rwlock>.
+ Results are undefined if the read-write lock I<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
+ I<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 I<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.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_rwlock_unlock()>
+ function returns zero.
+ Otherwise, an error number is returned
+ to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_rwlock_unlock()>
+ function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value specified by I<rwlock> does not refer to an initialised
+ read-write lock object.
+
+ =item [EPERM]
+
+ The current thread does not own the read-write lock.
+
+ =back
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 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.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<<pthread.h>>,
+ I<pthread_rwlock_init()>,
+ I<pthread_rwlock_wrlock()>,
+ I<pthread_rwlockattr_init()>,
+ I<pthread_rwlock_rdlock()>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_rwlock_wrlock,> B<pthread_rwlock_trywrlock>
+ - lock a read-write lock object for writing
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_rwlock_wrlock(pthread_rwlock_t I<*rwlock>);
+ int pthread_rwlock_trywrlock(pthread_rwlock_t I<*rwlock>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_rwlock_wrlock()>
+ function applies a write lock to
+ the read-write lock referenced by I<rwlock>. The
+ calling thread acquires the write lock if no other thread
+ (reader or writer) holds the read-write lock I<rwlock>.
+ Otherwise, the thread blocks (that is, does not return from the
+ I<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
+ I<pthread_rwlock_trywrlock()>
+ applies a write lock
+ like the
+ I<pthread_rwlock_wrlock()>
+ function, with the exception that the function fails if any
+ thread currently holds I<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.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_rwlock_wrlock()>
+ function returns zero.
+ Otherwise, an error number is returned
+ to indicate the error.
+
+ The function
+ I<pthread_rwlock_trywrlock()>
+ returns zero if the
+ lock for writing on the read-write lock object
+ referenced by I<rwlock> is acquired.
+ Otherwise an error number is
+ returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_rwlock_trywrlock()>
+ function will fail if:
+
+ =over 4
+
+ =item [EBUSY]
+
+ The read-write lock could not be acquired for writing because it
+ was already locked for reading or writing.
+
+ =back
+
+ The
+ I<pthread_rwlock_wrlock()>
+ and
+ I<pthread_rwlock_trywrlock()>
+ functions may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value specified by I<rwlock> does not refer to an initialised
+ read-write lock object.
+
+ =item [EDEADLK]
+
+ The current thread already owns the read-write lock for writing or
+ reading.
+
+ =back
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 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 "locks" a read-write
+ lock that is about to be "unlocked" 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.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<<pthread.h>>,
+ I<pthread_rwlock_init()>,
+ I<pthread_rwlock_unlock()>,
+ I<pthread_rwlockattr_init()>,
+ I<pthread_rwlock_rdlock()>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_rwlockattr_init,> B<pthread_rwlockattr_destroy>
+ - initialise and destroy read-write lock attributes object
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_rwlockattr_init(pthread_rwlockattr_t I<*attr>);
+ int pthread_rwlockattr_destroy(pthread_rwlockattr_t I<*attr>);
+
+ =head1 DESCRIPTION
+
+ The function
+ I<pthread_rwlockattr_init()>
+ initialises a read-write
+ lock attributes object I<attr> with the default
+ value for all of the attributes defined by the implementation.
+
+ Results are undefined if
+ I<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
+ I<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
+ I<pthread_rwlockattr_init()>.
+ An implementation may cause
+ I<pthread_rwlockattr_destroy()>
+ to set the object
+ referenced by attr to an invalid value.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_rwlockattr_init()>
+ and
+ I<pthread_rwlockattr_destroy()>
+ functions return zero.
+ Otherwise, an error number is returned to
+ indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_rwlockattr_init()>
+ function will fail if:
+
+ =over 4
+
+ =item [ENOMEM]
+
+ Insufficient memory exists to initialise the read-write
+ lock attributes object.
+
+ =back
+
+ The
+ I<pthread_rwlockattr_destroy()>
+ function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value specified by I<attr> is invalid.
+
+ =back
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 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.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<<pthread.h>>,
+ I<pthread_rwlock_init()>,
+ I<pthread_rwlock_unlock()>,
+ I<pthread_rwlock_wrlock()>,
+ I<pthread_rwlock_rdlock()>,
+ I<pthread_rwlockattr_getpshared()>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_rwlockattr_getpshared,> B<pthread_rwlockattr_setpshared>
+ - get and set process-shared attribute of read-write lock
+ attributes object
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_rwlockattr_getpshared(const pthread_rwlockattr_t I<*attr>,
+ int I<*pshared>);
+ int pthread_rwlockattr_setpshared(pthread_rwlockattr_t I<*attr>,
+ int I<pshared>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<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
+ I<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
+ I<process-shared>
+ attribute is PTHREAD_PROCESS_PRIVATE.
+
+ The
+ I<pthread_rwlockattr_getpshared()>
+ function obtains the value of the
+ I<process-shared>
+ attribute from the initialised attributes object referenced by I<attr>.
+ The
+ I<pthread_rwlockattr_setpshared()>
+ function is used to set the
+ I<process-shared>
+ attribute in an initialised attributes object referenced by attr.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_rwlockattr_setpshared()>
+ function returns zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ Upon successful completion, the
+ I<pthread_rwlockattr_getpshared()>
+ returns zero and stores the value of the
+ I<process-shared>
+ attribute of I<attr> into the object referenced by the
+ I<pshared> parameter. Otherwise an error number is
+ returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_rwlockattr_getpshared()>
+ and
+ I<pthread_rwlockattr_setpshared()>
+ functions may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value specified by I<attr> is invalid.
+
+ =back
+
+ The
+ I<pthread_rwlockattr_setpshared()>
+ function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The new value specified for the attribute is outside the range
+ of legal values for
+ that attribute.
+
+ =back
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 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.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<<pthread.h>>,
+ I<pthread_rwlock_init()>,
+ I<pthread_rwlock_unlock()>,
+ I<pthread_rwlock_wrlock()>,
+ I<pthread_rwlock_rdlock()>,
+ I<pthread_rwlockattr_init()>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_rwlockattr_init,> B<pthread_rwlockattr_destroy>
+ - initialise and destroy read-write lock attributes object
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_rwlockattr_init(pthread_rwlockattr_t I<*attr>);
+ int pthread_rwlockattr_destroy(pthread_rwlockattr_t I<*attr>);
+
+ =head1 DESCRIPTION
+
+ The function
+ I<pthread_rwlockattr_init()>
+ initialises a read-write
+ lock attributes object I<attr> with the default
+ value for all of the attributes defined by the implementation.
+
+ Results are undefined if
+ I<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
+ I<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
+ I<pthread_rwlockattr_init()>.
+ An implementation may cause
+ I<pthread_rwlockattr_destroy()>
+ to set the object
+ referenced by attr to an invalid value.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_rwlockattr_init()>
+ and
+ I<pthread_rwlockattr_destroy()>
+ functions return zero.
+ Otherwise, an error number is returned to
+ indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_rwlockattr_init()>
+ function will fail if:
+
+ =over 4
+
+ =item [ENOMEM]
+
+ Insufficient memory exists to initialise the read-write
+ lock attributes object.
+
+ =back
+
+ The
+ I<pthread_rwlockattr_destroy()>
+ function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value specified by I<attr> is invalid.
+
+ =back
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 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.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<<pthread.h>>,
+ I<pthread_rwlock_init()>,
+ I<pthread_rwlock_unlock()>,
+ I<pthread_rwlock_wrlock()>,
+ I<pthread_rwlock_rdlock()>,
+ I<pthread_rwlockattr_getpshared()>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_rwlockattr_getpshared,> B<pthread_rwlockattr_setpshared>
+ - get and set process-shared attribute of read-write lock
+ attributes object
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_rwlockattr_getpshared(const pthread_rwlockattr_t I<*attr>,
+ int I<*pshared>);
+ int pthread_rwlockattr_setpshared(pthread_rwlockattr_t I<*attr>,
+ int I<pshared>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<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
+ I<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
+ I<process-shared>
+ attribute is PTHREAD_PROCESS_PRIVATE.
+
+ The
+ I<pthread_rwlockattr_getpshared()>
+ function obtains the value of the
+ I<process-shared>
+ attribute from the initialised attributes object referenced by I<attr>.
+ The
+ I<pthread_rwlockattr_setpshared()>
+ function is used to set the
+ I<process-shared>
+ attribute in an initialised attributes object referenced by attr.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_rwlockattr_setpshared()>
+ function returns zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ Upon successful completion, the
+ I<pthread_rwlockattr_getpshared()>
+ returns zero and stores the value of the
+ I<process-shared>
+ attribute of I<attr> into the object referenced by the
+ I<pshared> parameter. Otherwise an error number is
+ returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_rwlockattr_getpshared()>
+ and
+ I<pthread_rwlockattr_setpshared()>
+ functions may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value specified by I<attr> is invalid.
+
+ =back
+
+ The
+ I<pthread_rwlockattr_setpshared()>
+ function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The new value specified for the attribute is outside the range
+ of legal values for
+ that attribute.
+
+ =back
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 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.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<<pthread.h>>,
+ I<pthread_rwlock_init()>,
+ I<pthread_rwlock_unlock()>,
+ I<pthread_rwlock_wrlock()>,
+ I<pthread_rwlock_rdlock()>,
+ I<pthread_rwlockattr_init()>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_self> - get calling thread's ID
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ pthread_t pthread_self(void);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_self()>
+ function returns the thread ID of the calling thread.
+
+ =head1 RETURN VALUE
+
+ See DESCRIPTION above.
+
+ =head1 ERRORS
+
+ No errors are defined.
+
+ The
+ I<pthread_self()>
+ function will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_create()>,
+ I<pthread_equal()>,
+ I<<pthread.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_setcancelstate,> B<pthread_setcanceltype,> B<pthread_testcancel>
+ - set cancelability state
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_setcancelstate(int I<state>, int *I<oldstate>);
+ int pthread_setcanceltype(int I<type>, int *I<oldtype>);
+ void pthread_testcancel(void);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_setcancelstate()>
+ function atomically both sets the calling thread's cancelability
+ state to the indicated
+ I<state>
+ and returns the previous cancelability state
+ at the location referenced by I<oldstate>.
+ Legal values for
+ I<state>
+ are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DISABLE.
+
+ The
+ I<pthread_setcanceltype()>
+ function atomically both sets the calling thread's cancelability
+ type to the indicated
+ I<type>
+ and returns the previous cancelability type
+ at the location referenced by I<oldtype>.
+ Legal values for
+ I<type>
+ are PTHREAD_CANCEL_DEFERRED and PTHREAD_CANCEL_ASYNCHRONOUS.
+
+ The cancelability state and type of any newly
+ created threads, including the thread in which
+ I<main()>
+ was first invoked,
+ are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DEFERRED
+ respectively.
+
+ The
+ I<pthread_testcancel()>
+ function creates a cancellation point in the calling thread.
+ The
+ I<pthread_testcancel()>
+ function has no effect if cancelability is disabled.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_setcancelstate()>
+ and
+ I<pthread_setcanceltype()>
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_setcancelstate()>
+ function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The specified state is not
+ PTHREAD_CANCEL_ENABLE or PTHREAD_CANCEL_DISABLE.
+
+ =back
+
+ The
+ I<pthread_setcanceltype()>
+ function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The specified type is not PTHREAD_CANCEL_DEFERRED
+ or PTHREAD_CANCEL_ASYNCHRONOUS.
+
+ =back
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_cancel()>,
+ I<<pthread.h>>.
+
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_setcancelstate,> B<pthread_setcanceltype,> B<pthread_testcancel>
+ - set cancelability state
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_setcancelstate(int I<state>, int *I<oldstate>);
+ int pthread_setcanceltype(int I<type>, int *I<oldtype>);
+ void pthread_testcancel(void);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_setcancelstate()>
+ function atomically both sets the calling thread's cancelability
+ state to the indicated
+ I<state>
+ and returns the previous cancelability state
+ at the location referenced by I<oldstate>.
+ Legal values for
+ I<state>
+ are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DISABLE.
+
+ The
+ I<pthread_setcanceltype()>
+ function atomically both sets the calling thread's cancelability
+ type to the indicated
+ I<type>
+ and returns the previous cancelability type
+ at the location referenced by I<oldtype>.
+ Legal values for
+ I<type>
+ are PTHREAD_CANCEL_DEFERRED and PTHREAD_CANCEL_ASYNCHRONOUS.
+
+ The cancelability state and type of any newly
+ created threads, including the thread in which
+ I<main()>
+ was first invoked,
+ are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DEFERRED
+ respectively.
+
+ The
+ I<pthread_testcancel()>
+ function creates a cancellation point in the calling thread.
+ The
+ I<pthread_testcancel()>
+ function has no effect if cancelability is disabled.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_setcancelstate()>
+ and
+ I<pthread_setcanceltype()>
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_setcancelstate()>
+ function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The specified state is not
+ PTHREAD_CANCEL_ENABLE or PTHREAD_CANCEL_DISABLE.
+
+ =back
+
+ The
+ I<pthread_setcanceltype()>
+ function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The specified type is not PTHREAD_CANCEL_DEFERRED
+ or PTHREAD_CANCEL_ASYNCHRONOUS.
+
+ =back
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_cancel()>,
+ I<<pthread.h>>.
+
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_setconcurrency> - get or set level of concurrency
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_setconcurrency(int I<new_level>);
+
+ =head1 DESCRIPTION
+
+ Refer to
+ I<pthread_getconcurrency()>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_getschedparam,> B<pthread_setschedparam>
+ - dynamic thread scheduling parameters access
+ (B<REALTIME THREADS>)
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_getschedparam(pthread_t I<thread>, int *I<policy>,
+ struct sched_param *I<param>);
+ int pthread_setschedparam(pthread_t I<thread>, int I<policy>,
+ const struct sched_param *I<param>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_getschedparam()>
+ and
+ I<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
+ B<sched_param>
+ structure is the priority
+ I<sched_priority>.
+ For SCHED_OTHER,
+ the affected scheduling parameters are implementation-dependent.
+
+ The
+ I<pthread_getschedparam()>
+ function retrieves the scheduling policy and scheduling parameters
+ for the thread whose thread ID is given by
+ I<thread>
+ and stores those values in
+ I<policy>
+ and
+ I<param>,
+ respectively.
+ The priority value returned from
+ I<pthread_getschedparam()>
+ is the value specified by the most recent
+ I<pthread_setschedparam()>
+ or
+ I<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
+ I<pthread_setschedparam()>
+ function sets the scheduling policy
+ and associated scheduling parameters for the thread whose
+ thread ID is given by
+ I<thread>
+ to the policy and associated parameters provided in
+ I<policy>
+ and
+ I<param>,
+ respectively.
+
+ The
+ I<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,
+ I<priority.>
+
+ If the
+ I<pthread_setschedparam()>
+ function fails, no scheduling parameters will be changed
+ for the target thread.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_getschedparam()>
+ and
+ I<pthread_setschedparam()>
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_getschedparam()>
+ and
+ I<pthread_setschedparam()>
+ functions will fail if:
+
+ =over 4
+
+ =item [ENOSYS]
+
+ The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the
+ implementation does not support the function.
+
+ =back
+
+ The
+ I<pthread_getschedparam()>
+ function may fail if:
+
+ =over 4
+
+ =item [ESRCH]
+
+ The value specified by
+ I<thread>
+ does not refer to a existing thread.
+
+ =back
+
+ The
+ I<pthread_setschedparam()>
+ function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The value specified by
+ I<policy>
+ or one of the scheduling parameters associated with
+ the scheduling policy
+ I<policy>
+ is invalid.
+
+ =item [ENOTSUP]
+
+ An attempt was made to set the policy or scheduling parameters to
+ an unsupported value.
+
+ =item [EPERM]
+
+ The caller does not have the appropriate permission to set
+ either the scheduling parameters or the scheduling policy of the
+ specified thread.
+
+ =item [EPERM]
+
+ The implementation does not allow the application to modify
+ one of the parameters to the value specified.
+
+ =item [ESRCH]
+
+ The value specified by
+ I<thread>
+ does not refer to a existing thread.
+
+ =back
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<sched_setparam()>,
+ I<sched_getparam()>,
+ I<sched_setscheduler()>,
+ I<sched_getscheduler()>,
+ I<<pthread.h>>,
+ I<<sched.h>>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_setspecific,> B<pthread_getspecific> - thread-specific data management
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_setspecific(pthread_key_t I<key>, const void *I<value>);
+ void *pthread_getspecific(pthread_key_t I<key>);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_setspecific()>
+ function associates a thread-specific
+ I<value>
+ with a
+ I<key>
+ obtained via a previous call to
+ I<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
+ I<pthread_getspecific()>
+ function returns the value currently bound to the specified
+ I<key>
+ on behalf of the calling thread.
+
+ The effect of calling
+ I<pthread_setspecific()>
+ or
+ I<pthread_getspecific()>
+ with a
+ I<key>
+ value not obtained from
+ I<pthread_key_create()>
+ or after
+ I<key>
+ has been deleted with
+ I<pthread_key_delete()>
+ is undefined.
+
+ Both
+ I<pthread_setspecific()>
+ and
+ I<pthread_getspecific()>
+ may be called from a thread-specific data destructor function.
+ However, calling
+ I<pthread_setspecific()>
+ from a destructor may result in lost storage or infinite loops.
+
+ Both functions may be implemented as macros.
+
+ =head1 RETURN VALUE
+
+ The function
+ I<pthread_getspecific()>
+ returns the thread-specific data value
+ associated with the given
+ I<key>.
+ If no thread-specific data value is associated with
+ I<key>,
+ then the value NULL is returned.
+
+ If successful, the
+ I<pthread_setspecific()>
+ function returns zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_setspecific()>
+ function will fail if:
+
+ =over 4
+
+ =item [ENOMEM]
+
+ Insufficient memory exists to associate the value with the key.
+
+ =back
+
+ The
+ I<pthread_setspecific()>
+ function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The key value is invalid.
+
+ =back
+
+ No errors are returned from
+ I<pthread_getspecific()>.
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_key_create()>,
+ I<<pthread.h>>.
+
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_sigmask> - examine and change blocked signals
+
+ =head1 SYNOPSIS
+
+ #include <signal.h>
+
+ int pthread_sigmask(int I<how>, const sigset_t *I<set>, sigset_t *I<oset>);
+
+ =head1 DESCRIPTION
+
+ Refer to
+ I<sigprocmask()>.
+
+ =head1 ______________________________________________________________________
+
+ =head1 NAME
+
+ B<pthread_setcancelstate,> B<pthread_setcanceltype,> B<pthread_testcancel>
+ - set cancelability state
+
+ =head1 SYNOPSIS
+
+ #include <pthread.h>
+
+ int pthread_setcancelstate(int I<state>, int *I<oldstate>);
+ int pthread_setcanceltype(int I<type>, int *I<oldtype>);
+ void pthread_testcancel(void);
+
+ =head1 DESCRIPTION
+
+ The
+ I<pthread_setcancelstate()>
+ function atomically both sets the calling thread's cancelability
+ state to the indicated
+ I<state>
+ and returns the previous cancelability state
+ at the location referenced by I<oldstate>.
+ Legal values for
+ I<state>
+ are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DISABLE.
+
+ The
+ I<pthread_setcanceltype()>
+ function atomically both sets the calling thread's cancelability
+ type to the indicated
+ I<type>
+ and returns the previous cancelability type
+ at the location referenced by I<oldtype>.
+ Legal values for
+ I<type>
+ are PTHREAD_CANCEL_DEFERRED and PTHREAD_CANCEL_ASYNCHRONOUS.
+
+ The cancelability state and type of any newly
+ created threads, including the thread in which
+ I<main()>
+ was first invoked,
+ are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DEFERRED
+ respectively.
+
+ The
+ I<pthread_testcancel()>
+ function creates a cancellation point in the calling thread.
+ The
+ I<pthread_testcancel()>
+ function has no effect if cancelability is disabled.
+
+ =head1 RETURN VALUE
+
+ If successful, the
+ I<pthread_setcancelstate()>
+ and
+ I<pthread_setcanceltype()>
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+
+ =head1 ERRORS
+
+ The
+ I<pthread_setcancelstate()>
+ function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The specified state is not
+ PTHREAD_CANCEL_ENABLE or PTHREAD_CANCEL_DISABLE.
+
+ =back
+
+ The
+ I<pthread_setcanceltype()>
+ function may fail if:
+
+ =over 4
+
+ =item [EINVAL]
+
+ The specified type is not PTHREAD_CANCEL_DEFERRED
+ or PTHREAD_CANCEL_ASYNCHRONOUS.
+
+ =back
+
+ These functions will not return an error code of [EINTR].
+
+ =head1 EXAMPLES
+
+ None.
+
+ =head1 APPLICATION USAGE
+
+ None.
+
+ =head1 FUTURE DIRECTIONS
+
+ None.
+
+ =head1 SEE ALSO
+
+ I<pthread_cancel()>,
+ I<<pthread.h>>.
+
+ =cut
+
|
