This is libc.info, produced by makeinfo version 4.0 from libc.texinfo.

INFO-DIR-SECTION GNU libraries
START-INFO-DIR-ENTRY
* Libc: (libc).                 C library.
END-INFO-DIR-ENTRY

   This file documents the GNU C library.

   This is Edition 0.09 DRAFT, last updated 28 Aug 1999, of `The GNU C
Library Reference Manual', for Version 2.2 Beta.

   Copyright (C) 1993, '94, '95, '96, '97, '98, '99 Free Software
Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU Library General Public License" is
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the text of the translation of the section
entitled "GNU Library General Public License" must be approved for
accuracy by the Foundation.


File: libc.info,  Node: Condition Variables,  Next: POSIX Semaphores,  Prev: Mutexes,  Up: POSIX Threads

Condition Variables
===================

   A condition (short for "condition variable") is a synchronization
device that allows threads to suspend execution until some predicate on
shared data is satisfied. The basic operations on conditions are: signal
the condition (when the predicate becomes true), and wait for the
condition, suspending the thread execution until another thread signals
the condition.

   A condition variable must always be associated with a mutex, to avoid
the race condition where a thread prepares to wait on a condition
variable and another thread signals the condition just before the first
thread actually waits on it.

 - Function: int pthread_cond_init (pthread_cond_t *COND,
          pthread_condattr_t *cond_ATTR)
     `pthread_cond_init' initializes the condition variable COND, using
     the condition attributes specified in COND_ATTR, or default
     attributes if COND_ATTR is `NULL'. The LinuxThreads implementation
     supports no attributes for conditions, hence the COND_ATTR
     parameter is actually ignored.

     Variables of type `pthread_cond_t' can also be initialized
     statically, using the constant `PTHREAD_COND_INITIALIZER'.

     This function always returns 0.

 - Function: int pthread_cond_signal (pthread_cond_t *COND)
     `pthread_cond_signal' restarts one of the threads that are waiting
     on the condition variable COND. If no threads are waiting on COND,
     nothing happens. If several threads are waiting on COND, exactly
     one is restarted, but it is not specified which.

     This function always returns 0.

 - Function: int pthread_cond_broadcast (pthread_cond_t *COND)
     `pthread_cond_broadcast' restarts all the threads that are waiting
     on the condition variable COND. Nothing happens if no threads are
     waiting on COND.

     This function always returns 0.

 - Function: int pthread_cond_wait (pthread_cond_t *COND,
          pthread_mutex_t *MUTEX)
     `pthread_cond_wait' atomically unlocks the MUTEX (as per
     `pthread_unlock_mutex') and waits for the condition variable COND
     to be signaled. The thread execution is suspended and does not
     consume any CPU time until the condition variable is signaled. The
     MUTEX must be locked by the calling thread on entrance to
     `pthread_cond_wait'. Before returning to the calling thread,
     `pthread_cond_wait' re-acquires MUTEX (as per
     `pthread_lock_mutex').

     Unlocking the mutex and suspending on the condition variable is
     done atomically. Thus, if all threads always acquire the mutex
     before signaling the condition, this guarantees that the condition
     cannot be signaled (and thus ignored) between the time a thread
     locks the mutex and the time it waits on the condition variable.

     This function always returns 0.

 - Function: int pthread_cond_timedwait (pthread_cond_t *COND,
          pthread_mutex_t *MUTEX, const struct timespec *ABSTIME)
     `pthread_cond_timedwait' atomically unlocks MUTEX and waits on
     COND, as `pthread_cond_wait' does, but it also bounds the duration
     of the wait. If COND has not been signaled before time ABSTIME,
     the mutex MUTEX is re-acquired and `pthread_cond_timedwait'
     returns the error code `ETIMEDOUT'.  The wait can also be
     interrupted by a signal; in that case `pthread_cond_timedwait'
     returns `EINTR'.

     The ABSTIME parameter specifies an absolute time, with the same
     origin as `time' and `gettimeofday': an ABSTIME of 0 corresponds
     to 00:00:00 GMT, January 1, 1970.

 - Function: int pthread_cond_destroy (pthread_cond_t *COND)
     `pthread_cond_destroy' destroys the condition variable COND,
     freeing the resources it might hold.  If any threads are waiting
     on the condition variable, `pthread_cond_destroy' leaves COND
     untouched and returns `EBUSY'.  Otherwise it returns 0, and COND
     must not be used again until it is reinitialized.

     In the LinuxThreads implementation, no resources are associated
     with condition variables, so `pthread_cond_destroy' actually does
     nothing.

   `pthread_cond_wait' and `pthread_cond_timedwait' are cancellation
points. If a thread is cancelled while suspended in one of these
functions, the thread immediately resumes execution, relocks the mutex
specified by  MUTEX, and finally executes the cancellation.
Consequently, cleanup handlers are assured that MUTEX is locked when
they are called.

   It is not safe to call the condition variable functions from a signal
handler. In particular, calling `pthread_cond_signal' or
`pthread_cond_broadcast' from a signal handler may deadlock the calling
thread.

   Consider two shared variables X and Y, protected by the mutex MUT,
and a condition variable COND that is to be signaled whenever X becomes
greater than Y.

     int x,y;
     pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
     pthread_cond_t cond = PTHREAD_COND_INITIALIZER;

   Waiting until X is greater than Y is performed as follows:

     pthread_mutex_lock(&mut);
     while (x <= y) {
             pthread_cond_wait(&cond, &mut);
     }
     /* operate on x and y */
     pthread_mutex_unlock(&mut);

   Modifications on X and Y that may cause X to become greater than Y
should signal the condition if needed:

     pthread_mutex_lock(&mut);
     /* modify x and y */
     if (x > y) pthread_cond_broadcast(&cond);
     pthread_mutex_unlock(&mut);

   If it can be proved that at most one waiting thread needs to be waken
up (for instance, if there are only two threads communicating through X
and Y), `pthread_cond_signal' can be used as a slightly more efficient
alternative to `pthread_cond_broadcast'. In doubt, use
`pthread_cond_broadcast'.

   To wait for X to becomes greater than Y with a timeout of 5 seconds,
do:

     struct timeval now;
     struct timespec timeout;
     int retcode;
     
     pthread_mutex_lock(&mut);
     gettimeofday(&now);
     timeout.tv_sec = now.tv_sec + 5;
     timeout.tv_nsec = now.tv_usec * 1000;
     retcode = 0;
     while (x <= y && retcode != ETIMEDOUT) {
             retcode = pthread_cond_timedwait(&cond, &mut, &timeout);
     }
     if (retcode == ETIMEDOUT) {
             /* timeout occurred */
     } else {
             /* operate on x and y */
     }
     pthread_mutex_unlock(&mut);

   Condition attributes can be specified at condition creation time, by
passing a condition attribute object as second argument to
`pthread_cond_init'.  Passing `NULL' is equivalent to passing a
condition attribute object with all attributes set to their default
values.

   The LinuxThreads implementation supports no attributes for
conditions. The functions on condition attributes are included only for
compliance with the POSIX standard.

 - Function: int pthread_condattr_init (pthread_condattr_t *ATTR)
 - Function: int pthread_condattr_destroy (pthread_condattr_t *ATTR)
     `pthread_condattr_init' initializes the condition attribute object
     ATTR and fills it with default values for the attributes.
     `pthread_condattr_destroy' destroys the condition attribute object
     ATTR.

     Both functions do nothing in the LinuxThreads implementation.

     `pthread_condattr_init' and `pthread_condattr_destroy' always
     return 0.


File: libc.info,  Node: POSIX Semaphores,  Next: Thread-Specific Data,  Prev: Condition Variables,  Up: POSIX Threads

POSIX Semaphores
================

   Semaphores are counters for resources shared between threads. The
basic operations on semaphores are: increment the counter atomically,
and wait until the counter is non-null and decrement it atomically.

   Semaphores have a maximum value past which they cannot be
incremented.  The macro `SEM_VALUE_MAX' is defined to be this maximum
value.  In the GNU C library, `SEM_VALUE_MAX' is equal to `INT_MAX'
(*note Range of Type::), but it may be much smaller on other systems.

   The pthreads library implements POSIX 1003.1b semaphores.  These
should not be confused with System V semaphores (`ipc', `semctl' and
`semop').

   All the semaphore functions and macros are defined in `semaphore.h'.

 - Function: int sem_init (sem_t *SEM, int PSHARED, unsigned int VALUE)
     `sem_init' initializes the semaphore object pointed to by SEM. The
     count associated with the semaphore is set initially to VALUE. The
     PSHARED argument indicates whether the semaphore is local to the
     current process (PSHARED is zero) or is to be shared between
     several processes (PSHARED is not zero).

     On success `sem_init' returns 0.  On failure it returns -1 and sets
     ERRNO to one of the following values:

    `EINVAL'
          VALUE exceeds the maximal counter value `SEM_VALUE_MAX'

    `ENOSYS'
          PSHARED is not zero.  LinuxThreads currently does not support
          process-shared semaphores.  (This will eventually change.)

 - Function: int sem_destroy (sem_t * SEM)
     `sem_destroy' destroys a semaphore object, freeing the resources it
     might hold.  If any threads are waiting on the semaphore when
     `sem_destroy' is called, it fails and sets ERRNO to `EBUSY'.

     In the LinuxThreads implementation, no resources are associated
     with semaphore objects, thus `sem_destroy' actually does nothing
     except checking that no thread is waiting on the semaphore.  This
     will change when process-shared semaphores are implemented.

 - Function: int sem_wait (sem_t * SEM)
     `sem_wait' suspends the calling thread until the semaphore pointed
     to by SEM has non-zero count. It then atomically decreases the
     semaphore count.

     `sem_wait' is a cancellation point.  It always returns 0.

 - Function: int sem_trywait (sem_t * SEM)
     `sem_trywait' is a non-blocking variant of `sem_wait'. If the
     semaphore pointed to by SEM has non-zero count, the count is
     atomically decreased and `sem_trywait' immediately returns 0.  If
     the semaphore count is zero, `sem_trywait' immediately returns -1
     and sets errno to `EAGAIN'.

 - Function: int sem_post (sem_t * SEM)
     `sem_post' atomically increases the count of the semaphore pointed
     to by SEM. This function never blocks.

     On processors supporting atomic compare-and-swap (Intel 486,
     Pentium and later, Alpha, PowerPC, MIPS II, Motorola 68k,
     Ultrasparc), the `sem_post' function is can safely be called from
     signal handlers.  This is the only thread synchronization function
     provided by POSIX threads that is async-signal safe.  On the Intel
     386 and earlier Sparc chips, the current LinuxThreads
     implementation of `sem_post' is not async-signal safe, because the
     hardware does not support the required atomic operations.

     `sem_post' always succeeds and returns 0, unless the semaphore
     count would exceed `SEM_VALUE_MAX' after being incremented.  In
     that case `sem_post' returns -1 and sets ERRNO to `EINVAL'.  The
     semaphore count is left unchanged.

 - Function: int sem_getvalue (sem_t * SEM, int * SVAL)
     `sem_getvalue' stores in the location pointed to by SVAL the
     current count of the semaphore SEM.  It always returns 0.


File: libc.info,  Node: Thread-Specific Data,  Next: Threads and Signal Handling,  Prev: POSIX Semaphores,  Up: POSIX Threads

Thread-Specific Data
====================

   Programs often need global or static variables that have different
values in different threads. Since threads share one memory space, this
cannot be achieved with regular variables. Thread-specific data is the
POSIX threads answer to this need.

   Each thread possesses a private memory block, the thread-specific
data area, or TSD area for short. This area is indexed by TSD keys. The
TSD area associates values of type `void *' to TSD keys. TSD keys are
common to all threads, but the value associated with a given TSD key can
be different in each thread.

   For concreteness, the TSD areas can be viewed as arrays of `void *'
pointers, TSD keys as integer indices into these arrays, and the value
of a TSD key as the value of the corresponding array element in the
calling thread.

   When a thread is created, its TSD area initially associates `NULL'
with all keys.

 - Function: int pthread_key_create (pthread_key_t *KEY, void
          (*destr_function) (void *))
     `pthread_key_create' allocates a new TSD key. The key is stored in
     the location pointed to by KEY. There is a limit of
     `PTHREAD_KEYS_MAX' on the number of keys allocated at a given
     time. The value initially associated with the returned key is
     `NULL' in all currently executing threads.

     The DESTR_FUNCTION argument, if not `NULL', specifies a destructor
     function associated with the key. When a thread terminates via
     `pthread_exit' or by cancellation, DESTR_FUNCTION is called on the
     value associated with the key in that thread. The DESTR_FUNCTION
     is not called if a key is deleted with `pthread_key_delete' or a
     value is changed with `pthread_setspecific'.  The order in which
     destructor functions are called at thread termination time is
     unspecified.

     Before the destructor function is called, the `NULL' value is
     associated with the key in the current thread.  A destructor
     function might, however, re-associate non-`NULL' values to that
     key or some other key.  To deal with this, if after all the
     destructors have been called for all non-`NULL' values, there are
     still some non-`NULL' values with associated destructors, then the
     process is repeated.  The LinuxThreads implementation stops the
     process after `PTHREAD_DESTRUCTOR_ITERATIONS' iterations, even if
     some non-`NULL' values with associated descriptors remain.  Other
     implementations may loop indefinitely.

     `pthread_key_create' returns 0 unless `PTHREAD_KEYS_MAX' keys have
     already been allocated, in which case it fails and returns
     `EAGAIN'.

 - Function: int pthread_key_delete (pthread_key_t KEY)
     `pthread_key_delete' deallocates a TSD key. It does not check
     whether non-`NULL' values are associated with that key in the
     currently executing threads, nor call the destructor function
     associated with the key.

     If there is no such key KEY, it returns `EINVAL'.  Otherwise it
     returns 0.

 - Function: int pthread_setspecific (pthread_key_t KEY, const void
          *POINTER)
     `pthread_setspecific' changes the value associated with KEY in the
     calling thread, storing the given POINTER instead.

     If there is no such key KEY, it returns `EINVAL'.  Otherwise it
     returns 0.

 - Function: void * pthread_getspecific (pthread_key_t KEY)
     `pthread_getspecific' returns the value currently associated with
     KEY in the calling thread.

     If there is no such key KEY, it returns `NULL'.

   The following code fragment allocates a thread-specific array of 100
characters, with automatic reclaimation at thread exit:

     /* Key for the thread-specific buffer */
     static pthread_key_t buffer_key;
     
     /* Once-only initialisation of the key */
     static pthread_once_t buffer_key_once = PTHREAD_ONCE_INIT;
     
     /* Allocate the thread-specific buffer */
     void buffer_alloc(void)
     {
       pthread_once(&buffer_key_once, buffer_key_alloc);
       pthread_setspecific(buffer_key, malloc(100));
     }
     
     /* Return the thread-specific buffer */
     char * get_buffer(void)
     {
       return (char *) pthread_getspecific(buffer_key);
     }
     
     /* Allocate the key */
     static void buffer_key_alloc()
     {
       pthread_key_create(&buffer_key, buffer_destroy);
     }
     
     /* Free the thread-specific buffer */
     static void buffer_destroy(void * buf)
     {
       free(buf);
     }


File: libc.info,  Node: Threads and Signal Handling,  Next: Threads and Fork,  Prev: Thread-Specific Data,  Up: POSIX Threads

Threads and Signal Handling
===========================

 - Function: int pthread_sigmask (int HOW, const sigset_t *NEWMASK,
          sigset_t *OLDMASK)
     `pthread_sigmask' changes the signal mask for the calling thread as
     described by the HOW and NEWMASK arguments. If OLDMASK is not
     `NULL', the previous signal mask is stored in the location pointed
     to by OLDMASK.

     The meaning of the HOW and NEWMASK arguments is the same as for
     `sigprocmask'. If HOW is `SIG_SETMASK', the signal mask is set to
     NEWMASK. If HOW is `SIG_BLOCK', the signals specified to NEWMASK
     are added to the current signal mask.  If HOW is `SIG_UNBLOCK',
     the signals specified to NEWMASK are removed from the current
     signal mask.

     Recall that signal masks are set on a per-thread basis, but signal
     actions and signal handlers, as set with `sigaction', are shared
     between all threads.

     The `pthread_sigmask' function returns 0 on success, and one of the
     following error codes on error:
    `EINVAL'
          HOW is not one of `SIG_SETMASK', `SIG_BLOCK', or `SIG_UNBLOCK'

    `EFAULT'
          NEWMASK or OLDMASK point to invalid addresses

 - Function: int pthread_kill (pthread_t THREAD, int SIGNO)
     `pthread_kill' sends signal number SIGNO to the thread THREAD.
     The signal is delivered and handled as described in *Note Signal
     Handling::.

     `pthread_kill' returns 0 on success, one of the following error
     codes on error:
    `EINVAL'
          SIGNO is not a valid signal number

    `ESRCH'
          The thread THREAD does not exist (e.g. it has already
          terminated)

 - Function: int sigwait (const sigset_t *SET, int *SIG)
     `sigwait' suspends the calling thread until one of the signals in
     SET is delivered to the calling thread. It then stores the number
     of the signal received in the location pointed to by SIG and
     returns. The signals in SET must be blocked and not ignored on
     entrance to `sigwait'. If the delivered signal has a signal handler
     function attached, that function is _not_ called.

     `sigwait' is a cancellation point.  It always returns 0.

   For `sigwait' to work reliably, the signals being waited for must be
blocked in all threads, not only in the calling thread, since otherwise
the POSIX semantics for signal delivery do not guarantee that it's the
thread doing the `sigwait' that will receive the signal.  The best way
to achieve this is block those signals before any threads are created,
and never unblock them in the program other than by calling `sigwait'.

   Signal handling in LinuxThreads departs significantly from the POSIX
standard. According to the standard, "asynchronous" (external) signals
are addressed to the whole process (the collection of all threads),
which then delivers them to one particular thread. The thread that
actually receives the signal is any thread that does not currently block
the signal.

   In LinuxThreads, each thread is actually a kernel process with its
own PID, so external signals are always directed to one particular
thread.  If, for instance, another thread is blocked in `sigwait' on
that signal, it will not be restarted.

   The LinuxThreads implementation of `sigwait' installs dummy signal
handlers for the signals in SET for the duration of the wait. Since
signal handlers are shared between all threads, other threads must not
attach their own signal handlers to these signals, or alternatively
they should all block these signals (which is recommended anyway).


File: libc.info,  Node: Threads and Fork,  Next: Streams and Fork,  Prev: Threads and Signal Handling,  Up: POSIX Threads

Threads and Fork
================

   It's not intuitively obvious what should happen when a
multi-threaded POSIX process calls `fork'. Not only are the semantics
tricky, but you may need to write code that does the right thing at
fork time even if that code doesn't use the `fork' function. Moreover,
you need to be aware of interaction between `fork' and some library
features like `pthread_once' and stdio streams.

   When `fork' is called by one of the threads of a process, it creates
a new process which is copy of the  calling process. Effectively, in
addition to copying certain system objects, the function takes a
snapshot of the memory areas of the parent process, and creates
identical areas in the child.  To make matters more complicated, with
threads it's possible for two or more threads to concurrently call fork
to create two or more child processes.

   The child process has a copy of the address space of the parent, but
it does not inherit any of its threads. Execution of the child process
is carried out by a new thread which returns from `fork' function with
a return value of zero; it is the only thread in the child process.
Because threads are not inherited across fork, issues arise. At the
time of the call to `fork', threads in the parent process other than
the one calling `fork' may have been executing critical regions of
code.  As a result, the child process may get a copy of objects that
are not in a well-defined state.  This potential problem affects all
components of the program.

   Any program component which will continue being used in a child
process must correctly handle its state during `fork'. For this
purpose, the POSIX interface provides the special function
`pthread_atfork' for installing pointers to handler functions which are
called from within `fork'.

 - Function: int pthread_atfork (void (*PREPARE)(void), void
          (*PARENT)(void), void (*CHILD)(void))
     `pthread_atfork' registers handler functions to be called just
     before and just after a new process is created with `fork'. The
     PREPARE handler will be called from the parent process, just
     before the new process is created. The PARENT handler will be
     called from the parent process, just before `fork' returns. The
     CHILD handler will be called from the child process, just before
     `fork' returns.

     `pthread_atfork' returns 0 on success and a non-zero error code on
     error.

     One or more of the three handlers PREPARE, PARENT and CHILD can be
     given as `NULL', meaning that no handler needs to be called at the
     corresponding point.

     `pthread_atfork' can be called several times to install several
     sets of handlers. At `fork' time, the PREPARE handlers are called
     in LIFO order (last added with `pthread_atfork', first called
     before `fork'), while the PARENT and CHILD handlers are called in
     FIFO order (first added, first called).

     If there is insufficient memory available to register the handlers,
     `pthread_atfork' fails and returns `ENOMEM'.  Otherwise it returns
     0.

     The functions `fork' and `pthread_atfork' must not be regarded as
     reentrant from the context of the handlers.  That is to say, if a
     `pthread_atfork' handler invoked from within `fork' calls
     `pthread_atfork' or `fork', the behavior is undefined.

     Registering a triplet of handlers is an atomic operation with
     respect to fork.  If new handlers are registered at about the same
     time as a fork occurs, either all three handlers will be called,
     or none of them will be called.

     The handlers are inherited by the child process, and there is no
     way to remove them, short of using `exec' to load a new pocess
     image.


   To understand the purpose of `pthread_atfork', recall that `fork'
duplicates the whole memory space, including mutexes in their current
locking state, but only the calling thread: other threads are not
running in the child process. Thus, if a mutex is locked by a thread
other than the thread calling `fork', that mutex will remain locked
forever in the child process, possibly blocking the execution of the
child process. Or if some shared data, such as a linked list, was in the
middle of being updated by a thread in the parent process, the child
will get a copy of the incompletely updated data which it cannot use.

   To avoid this, install handlers with `pthread_atfork' as follows:
have the PREPARE handler lock the mutexes (in locking order), and the
PARENT handler unlock the mutexes. The CHILD handler should reset the
mutexes using `pthread_mutex_init', as well as any other
synchronization objects such as condition variables.

   Locking the global mutexes before the fork ensures that all other
threads are locked out of the critical regions of code protected by
those mutexes.  Thus when `fork' takes a snapshot of the parent's
address space, that snapshot will copy valid, stable data.  Resetting
the synchronization objects in the child process will ensure they are
properly cleansed of any artifacts from the threading subsystem of the
parent process. For example, a mutex may inherit a wait queue of
threads waiting for the lock; this wait queue makes no sense in the
child process. Initializing the mutex takes care of this.


File: libc.info,  Node: Streams and Fork,  Next: Miscellaneous Thread Functions,  Prev: Threads and Fork,  Up: POSIX Threads

Streams and Fork
================

   The GNU standard I/O library has an internal mutex which guards the
internal linked list of all standard C FILE objects. This mutex is
properly taken care of during `fork' so that the child receives an
intact copy of the list.  This allows the `fopen' function, and related
stream-creating functions, to work correctly in the child process,
since these functions need to insert into the list.

   However, the individual stream locks are not completely taken care
of.  Thus unless the multithreaded application takes special
precautions in its use of `fork', the child process might not be able
to safely use the streams that it inherited from the parent.   In
general, for any given open stream in the parent that is to be used by
the child process, the application must ensure that that stream is not
in use by another thread when `fork' is called.  Otherwise an
inconsistent copy of the stream object be produced. An easy way to
ensure this is to use `flockfile' to lock the stream prior to calling
`fork' and then unlock it with `funlockfile' inside the parent process,
provided that the parent's threads properly honor these locks.  Nothing
special needs to be done in the child process, since the library
internally resets all stream locks.

   Note that the stream locks are not shared between the parent and
child.  For example, even if you ensure that, say, the stream `stdout'
is properly treated and can be safely used in the child, the stream
locks do not provide an exclusion mechanism between the parent and
child. If both processes write to `stdout', strangely interleaved
output may result regardless of the explicit use of `flockfile' or
implicit locks.

   Also note that these provisions are a GNU extension; other systems
might not provide any way for streams to be used in the child of a
multithreaded process.  POSIX requires that such a child process
confines itself to calling only asynchronous safe functions, which
excludes much of the library, including standard I/O.


File: libc.info,  Node: Miscellaneous Thread Functions,  Prev: Streams and Fork,  Up: POSIX Threads

Miscellaneous Thread Functions
==============================

 - Function: pthread_t pthread_self (VOID)
     `pthread_self' returns the thread identifier for the calling
     thread.

 - Function: int pthread_equal (pthread_t thread1, pthread_t thread2)
     `pthread_equal' determines if two thread identifiers refer to the
     same thread.

     A non-zero value is returned if THREAD1 and THREAD2 refer to the
     same thread. Otherwise, 0 is returned.

 - Function: int pthread_detach (pthread_t TH)
     `pthread_detach' puts the thread TH in the detached state. This
     guarantees that the memory resources consumed by TH will be freed
     immediately when TH terminates. However, this prevents other
     threads from synchronizing on the termination of TH using
     `pthread_join'.

     A thread can be created initially in the detached state, using the
     `detachstate' attribute to `pthread_create'. In contrast,
     `pthread_detach' applies to threads created in the joinable state,
     and which need to be put in the detached state later.

     After `pthread_detach' completes, subsequent attempts to perform
     `pthread_join' on TH will fail. If another thread is already
     joining the thread TH at the time `pthread_detach' is called,
     `pthread_detach' does nothing and leaves TH in the joinable state.

     On success, 0 is returned. On error, one of the following codes is
     returned:
    `ESRCH'
          No thread could be found corresponding to that specified by TH

    `EINVAL'
          The thread TH is already in the detached state

 - Function: void pthread_kill_other_threads_np (VOID)
     `pthread_kill_other_threads_np' is a non-portable LinuxThreads
     extension.  It causes all threads in the program to terminate
     immediately, except the calling thread which proceeds normally. It
     is intended to be called just before a thread calls one of the
     `exec' functions, e.g. `execve'.

     Termination of the other threads is not performed through
     `pthread_cancel' and completely bypasses the cancellation
     mechanism. Hence, the current settings for cancellation state and
     cancellation type are ignored, and the cleanup handlers are not
     executed in the terminated threads.

     According to POSIX 1003.1c, a successful `exec*' in one of the
     threads should automatically terminate all other threads in the
     program.  This behavior is not yet implemented in LinuxThreads.
     Calling `pthread_kill_other_threads_np' before `exec*' achieves
     much of the same behavior, except that if `exec*' ultimately
     fails, then all other threads are already killed.

 - Function: int pthread_once (pthread_once_t *once_CONTROL, void
          (*INIT_ROUTINE) (void))
     The purpose of `pthread_once' is to ensure that a piece of
     initialization code is executed at most once. The ONCE_CONTROL
     argument points to a static or extern variable statically
     initialized to `PTHREAD_ONCE_INIT'.

     The first time `pthread_once' is called with a given ONCE_CONTROL
     argument, it calls INIT_ROUTINE with no argument and changes the
     value of the ONCE_CONTROL variable to record that initialization
     has been performed. Subsequent calls to `pthread_once' with the
     same `once_control' argument do nothing.

     If a thread is cancelled while executing INIT_ROUTINE the state of
     the ONCE_CONTROL variable is reset so that a future call to
     `pthread_once' will call the routine again.

     If the process forks while one or more threads are executing
     `pthread_once' initialization routines, the states of their
     respective ONCE_CONTROL variables will appear to be reset in the
     child process so that if the child calls `pthread_once', the
     routines will be executed.

     `pthread_once' always returns 0.

 - Function: int pthread_setschedparam (pthread_t target_THREAD, int
          POLICY, const struct sched_param *PARAM)
     `pthread_setschedparam' sets the scheduling parameters for the
     thread TARGET_THREAD as indicated by POLICY and PARAM. POLICY can
     be either `SCHED_OTHER' (regular, non-realtime scheduling),
     `SCHED_RR' (realtime, round-robin) or `SCHED_FIFO' (realtime,
     first-in first-out). PARAM specifies the scheduling priority for
     the two realtime policies.  See `sched_setpolicy' for more
     information on scheduling policies.

     The realtime scheduling policies `SCHED_RR' and `SCHED_FIFO' are
     available only to processes with superuser privileges.

     On success, `pthread_setschedparam' returns 0.  On error it returns
     one of the following codes:
    `EINVAL'
          POLICY is not one of `SCHED_OTHER', `SCHED_RR', `SCHED_FIFO',
          or the priority value specified by PARAM is not valid for the
          specified policy

    `EPERM'
          Realtime scheduling was requested but the calling process
          does not have sufficient privileges.

    `ESRCH'
          The TARGET_THREAD is invalid or has already terminated

    `EFAULT'
          PARAM points outside the process memory space

 - Function: int pthread_getschedparam (pthread_t target_THREAD, int
          *POLICY, struct sched_param *PARAM)
     `pthread_getschedparam' retrieves the scheduling policy and
     scheduling parameters for the thread TARGET_THREAD and stores them
     in the locations pointed to by POLICY and PARAM, respectively.

     `pthread_getschedparam' returns 0 on success, or one of the
     following error codes on failure:
    `ESRCH'
          The TARGET_THREAD is invalid or has already terminated.

    `EFAULT'
          POLICY or PARAM point outside the process memory space.


 - Function: int pthread_setconcurrency (int LEVEL)
     `pthread_setconcurrency' is unused in LinuxThreads due to the lack
     of a mapping of user threads to kernel threads.  It exists for
     source compatibility.  It does store the value LEVEL so that it
     can be returned by a subsequent call to `pthread_getconcurrency'.
     It takes no other action however.

 - Function: int pthread_getconcurrency ()
     `pthread_getconcurrency' is unused in LinuxThreads due to the lack
     of a mapping of user threads to kernel threads.  It exists for
     source compatibility.  However, it will return the value that was
     set by the last call to `pthread_setconcurrency'.


File: libc.info,  Node: Language Features,  Next: Library Summary,  Prev: POSIX Threads,  Up: Top

C Language Facilities in the Library
************************************

   Some of the facilities implemented by the C library really should be
thought of as parts of the C language itself.  These facilities ought to
be documented in the C Language Manual, not in the library manual; but
since we don't have the language manual yet, and documentation for these
features has been written, we are publishing it here.

* Menu:

* Consistency Checking::        Using `assert' to abort if
				 something ``impossible'' happens.
* Variadic Functions::          Defining functions with varying numbers
                                 of args.
* Null Pointer Constant::       The macro `NULL'.
* Important Data Types::        Data types for object sizes.
* Data Type Measurements::      Parameters of data type representations.


File: libc.info,  Node: Consistency Checking,  Next: Variadic Functions,  Up: Language Features

Explicitly Checking Internal Consistency
========================================

   When you're writing a program, it's often a good idea to put in
checks at strategic places for "impossible" errors or violations of
basic assumptions.  These kinds of checks are helpful in debugging
problems with the interfaces between different parts of the program,
for example.

   The `assert' macro, defined in the header file `assert.h', provides
a convenient way to abort the program while printing a message about
where in the program the error was detected.

   Once you think your program is debugged, you can disable the error
checks performed by the `assert' macro by recompiling with the macro
`NDEBUG' defined.  This means you don't actually have to change the
program source code to disable these checks.

   But disabling these consistency checks is undesirable unless they
make the program significantly slower.  All else being equal, more error
checking is good no matter who is running the program.  A wise user
would rather have a program crash, visibly, than have it return nonsense
without indicating anything might be wrong.

 - Macro: void assert (int EXPRESSION)
     Verify the programmer's belief that EXPRESSION is nonzero at this
     point in the program.

     If `NDEBUG' is not defined, `assert' tests the value of
     EXPRESSION.  If it is false (zero), `assert' aborts the program
     (*note Aborting a Program::) after printing a message of the form:

          `FILE':LINENUM: FUNCTION: Assertion `EXPRESSION' failed.

     on the standard error stream `stderr' (*note Standard Streams::).
     The filename and line number are taken from the C preprocessor
     macros `__FILE__' and `__LINE__' and specify where the call to
     `assert' was made.  When using the GNU C compiler, the name of the
     function which calls `assert' is taken from the built-in variable
     `__PRETTY_FUNCTION__'; with older compilers, the function name and
     following colon are omitted.

     If the preprocessor macro `NDEBUG' is defined before `assert.h' is
     included, the `assert' macro is defined to do absolutely nothing.

     *Warning:* Even the argument expression EXPRESSION is not
     evaluated if `NDEBUG' is in effect.  So never use `assert' with
     arguments that involve side effects.  For example, `assert (++i >
     0);' is a bad idea, because `i' will not be incremented if
     `NDEBUG' is defined.

   Sometimes the "impossible" condition you want to check for is an
error return from an operating system function.  Then it is useful to
display not only where the program crashes, but also what error was
returned.  The `assert_perror' macro makes this easy.

 - Macro: void assert_perror (int ERRNUM)
     Similar to `assert', but verifies that ERRNUM is zero.

     If `NDEBUG' is defined, `assert_perror' tests the value of ERRNUM.
     If it is nonzero, `assert_perror' aborts the program after
     printing a message of the form:

          `FILE':LINENUM: FUNCTION: ERROR TEXT

     on the standard error stream.  The file name, line number, and
     function name are as for `assert'.  The error text is the result of
     `strerror (ERRNUM)'.  *Note Error Messages::.

     Like `assert', if `NDEBUG' is defined before `assert.h' is
     included, the `assert_perror' macro does absolutely nothing.  It
     does not evaluate the argument, so ERRNUM should not have any side
     effects.  It is best for ERRNUM to be just a simple variable
     reference; often it will be `errno'.

     This macro is a GNU extension.

   *Usage note:* The `assert' facility is designed for detecting
_internal inconsistency_; it is not suitable for reporting invalid
input or improper usage by the _user_ of the program.

   The information in the diagnostic messages printed by the `assert'
and `assert_perror' macro is intended to help you, the programmer,
track down the cause of a bug, but is not really useful for telling a
user of your program why his or her input was invalid or why a command
could not be carried out.  What's more, your program should not abort
when given invalid input, as `assert' would do--it should exit with
nonzero status (*note Exit Status::) after printing its error messages,
or perhaps read another command or move on to the next input file.

   *Note Error Messages::, for information on printing error messages
for problems that _do not_ represent bugs in the program.


File: libc.info,  Node: Variadic Functions,  Next: Null Pointer Constant,  Prev: Consistency Checking,  Up: Language Features

Variadic Functions
==================

   ISO C defines a syntax for declaring a function to take a variable
number or type of arguments.  (Such functions are referred to as
"varargs functions" or "variadic functions".)  However, the language
itself provides no mechanism for such functions to access their
non-required arguments; instead, you use the variable arguments macros
defined in `stdarg.h'.

   This section describes how to declare variadic functions, how to
write them, and how to call them properly.

   *Compatibility Note:* Many older C dialects provide a similar, but
incompatible, mechanism for defining functions with variable numbers of
arguments, using `varargs.h'.

* Menu:

* Why Variadic::                Reasons for making functions take
                                 variable arguments.
* How Variadic::                How to define and call variadic functions.
* Variadic Example::            A complete example.


File: libc.info,  Node: Why Variadic,  Next: How Variadic,  Up: Variadic Functions

Why Variadic Functions are Used
-------------------------------

   Ordinary C functions take a fixed number of arguments.  When you
define a function, you specify the data type for each argument.  Every
call to the function should supply the expected number of arguments,
with types that can be converted to the specified ones.  Thus, if the
function `foo' is declared with `int foo (int, char *);' then you must
call it with two arguments, a number (any kind will do) and a string
pointer.

   But some functions perform operations that can meaningfully accept an
unlimited number of arguments.

   In some cases a function can handle any number of values by
operating on all of them as a block.  For example, consider a function
that allocates a one-dimensional array with `malloc' to hold a
specified set of values.  This operation makes sense for any number of
values, as long as the length of the array corresponds to that number.
Without facilities for variable arguments, you would have to define a
separate function for each possible array size.

   The library function `printf' (*note Formatted Output::) is an
example of another class of function where variable arguments are
useful.  This function prints its arguments (which can vary in type as
well as number) under the control of a format template string.

   These are good reasons to define a "variadic" function which can
handle as many arguments as the caller chooses to pass.

   Some functions such as `open' take a fixed set of arguments, but
occasionally ignore the last few.  Strict adherence to ISO C requires
these functions to be defined as variadic; in practice, however, the GNU
C compiler and most other C compilers let you define such a function to
take a fixed set of arguments--the most it can ever use--and then only
_declare_ the function as variadic (or not declare its arguments at
all!).


File: libc.info,  Node: How Variadic,  Next: Variadic Example,  Prev: Why Variadic,  Up: Variadic Functions

How Variadic Functions are Defined and Used
-------------------------------------------

   Defining and using a variadic function involves three steps:

   * _Define_ the function as variadic, using an ellipsis (`...') in
     the argument list, and using special macros to access the variable
     arguments.  *Note Receiving Arguments::.

   * _Declare_ the function as variadic, using a prototype with an
     ellipsis (`...'), in all the files which call it.  *Note Variadic
     Prototypes::.

   * _Call_ the function by writing the fixed arguments followed by the
     additional variable arguments.  *Note Calling Variadics::.

* Menu:

* Variadic Prototypes::  How to make a prototype for a function
			  with variable arguments.
* Receiving Arguments::  Steps you must follow to access the
			  optional argument values.
* How Many Arguments::   How to decide whether there are more arguments.
* Calling Variadics::    Things you need to know about calling
			  variable arguments functions.
* Argument Macros::      Detailed specification of the macros
        		  for accessing variable arguments.
* Old Varargs::		 The pre-ISO way of defining variadic functions.


File: libc.info,  Node: Variadic Prototypes,  Next: Receiving Arguments,  Up: How Variadic

Syntax for Variable Arguments
.............................

   A function that accepts a variable number of arguments must be
declared with a prototype that says so.   You write the fixed arguments
as usual, and then tack on `...' to indicate the possibility of
additional arguments.  The syntax of ISO C requires at least one fixed
argument before the `...'.  For example,

     int
     func (const char *a, int b, ...)
     {
       ...
     }

defines a function `func' which returns an `int' and takes two required
arguments, a `const char *' and an `int'.  These are followed by any
number of anonymous arguments.

   *Portability note:* For some C compilers, the last required argument
must not be declared `register' in the function definition.
Furthermore, this argument's type must be "self-promoting": that is,
the default promotions must not change its type.  This rules out array
and function types, as well as `float', `char' (whether signed or not)
and `short int' (whether signed or not).  This is actually an ISO C
requirement.


File: libc.info,  Node: Receiving Arguments,  Next: How Many Arguments,  Prev: Variadic Prototypes,  Up: How Variadic

Receiving the Argument Values
.............................

   Ordinary fixed arguments have individual names, and you can use these
names to access their values.  But optional arguments have no
names--nothing but `...'.  How can you access them?

   The only way to access them is sequentially, in the order they were
written, and you must use special macros from `stdarg.h' in the
following three step process:

  1. You initialize an argument pointer variable of type `va_list' using
     `va_start'.  The argument pointer when initialized points to the
     first optional argument.

  2. You access the optional arguments by successive calls to `va_arg'.
     The first call to `va_arg' gives you the first optional argument,
     the next call gives you the second, and so on.

     You can stop at any time if you wish to ignore any remaining
     optional arguments.  It is perfectly all right for a function to
     access fewer arguments than were supplied in the call, but you
     will get garbage values if you try to access too many arguments.

  3. You indicate that you are finished with the argument pointer
     variable by calling `va_end'.

     (In practice, with most C compilers, calling `va_end' does nothing.
     This is always true in the GNU C compiler.  But you might as well
     call `va_end' just in case your program is someday compiled with a
     peculiar compiler.)

   *Note Argument Macros::, for the full definitions of `va_start',
`va_arg' and `va_end'.

   Steps 1 and 3 must be performed in the function that accepts the
optional arguments.  However, you can pass the `va_list' variable as an
argument to another function and perform all or part of step 2 there.

   You can perform the entire sequence of three steps multiple times
within a single function invocation.  If you want to ignore the optional
arguments, you can do these steps zero times.

   You can have more than one argument pointer variable if you like.
You can initialize each variable with `va_start' when you wish, and
then you can fetch arguments with each argument pointer as you wish.
Each argument pointer variable will sequence through the same set of
argument values, but at its own pace.

   *Portability note:* With some compilers, once you pass an argument
pointer value to a subroutine, you must not keep using the same
argument pointer value after that subroutine returns.  For full
portability, you should just pass it to `va_end'.  This is actually an
ISO C requirement, but most ANSI C compilers work happily regardless.


File: libc.info,  Node: How Many Arguments,  Next: Calling Variadics,  Prev: Receiving Arguments,  Up: How Variadic

How Many Arguments Were Supplied
................................

   There is no general way for a function to determine the number and
type of the optional arguments it was called with.  So whoever designs
the function typically designs a convention for the caller to specify
the number and type of arguments.  It is up to you to define an
appropriate calling convention for each variadic function, and write
all calls accordingly.

   One kind of calling convention is to pass the number of optional
arguments as one of the fixed arguments.  This convention works provided
all of the optional arguments are of the same type.

   A similar alternative is to have one of the required arguments be a
bit mask, with a bit for each possible purpose for which an optional
argument might be supplied.  You would test the bits in a predefined
sequence; if the bit is set, fetch the value of the next argument,
otherwise use a default value.

   A required argument can be used as a pattern to specify both the
number and types of the optional arguments.  The format string argument
to `printf' is one example of this (*note Formatted Output Functions::).

   Another possibility is to pass an "end marker" value as the last
optional argument.  For example, for a function that manipulates an
arbitrary number of pointer arguments, a null pointer might indicate the
end of the argument list.  (This assumes that a null pointer isn't
otherwise meaningful to the function.)  The `execl' function works in
just this way; see *Note Executing a File::.

