ossp-pkg/pth/pthread.pod
##
## GNU Pth - The GNU Portable Threads
## Copyright (c) 1999-2007 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
