linuxthreads.texi

用于嵌入式Linux系统的标准C的库函数

mask is set to @var{newmask}. If @var{how} is @code{SIG_BLOCK}, the
signals specified to @var{newmask} are added to the current signal mask.
If @var{how} is @code{SIG_UNBLOCK}, the signals specified to
@var{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 @code{sigaction}, are shared
between all threads.

The @code{pthread_sigmask} function returns 0 on success, and one of the
following error codes on error:
@table @code
@item EINVAL
@var{how} is not one of @code{SIG_SETMASK}, @code{SIG_BLOCK}, or @code{SIG_UNBLOCK}

@item EFAULT
@var{newmask} or @var{oldmask} point to invalid addresses
@end table
@end deftypefun

@comment pthread.h
@comment POSIX
@deftypefun int pthread_kill (pthread_t @var{thread}, int @var{signo})
@code{pthread_kill} sends signal number @var{signo} to the thread
@var{thread}.  The signal is delivered and handled as described in
@ref{Signal Handling}.

@code{pthread_kill} returns 0 on success, one of the following error codes
on error:
@table @code
@item EINVAL
@var{signo} is not a valid signal number

@item ESRCH
The thread @var{thread} does not exist (e.g. it has already terminated)
@end table
@end deftypefun

@comment pthread.h
@comment POSIX
@deftypefun int sigwait (const sigset_t *@var{set}, int *@var{sig})
@code{sigwait} suspends the calling thread until one of the signals in
@var{set} is delivered to the calling thread. It then stores the number
of the signal received in the location pointed to by @var{sig} and
returns. The signals in @var{set} must be blocked and not ignored on
entrance to @code{sigwait}. If the delivered signal has a signal handler
function attached, that function is @emph{not} called.

@code{sigwait} is a cancellation point.  It always returns 0.
@end deftypefun

For @code{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 @code{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 @code{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 @code{sigwait} on that
signal, it will not be restarted.

The LinuxThreads implementation of @code{sigwait} installs dummy signal
handlers for the signals in @var{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).

@node Threads and Fork
@section Threads and Fork

It's not intuitively obvious what should happen when a multi-threaded POSIX
process calls @code{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 @code{fork} function. Moreover, you need to be aware of
interaction between @code{fork} and some library features like
@code{pthread_once} and stdio streams.

When @code{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 @code{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 @code{fork},
threads in the parent process other than the one calling @code{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 @code{fork}. For this purpose, the POSIX
interface provides the special function @code{pthread_atfork} for installing
pointers to handler functions which are called from within @code{fork}.

@comment pthread.h
@comment POSIX
@deftypefun int pthread_atfork (void (*@var{prepare})(void), void (*@var{parent})(void), void (*@var{child})(void))

@code{pthread_atfork} registers handler functions to be called just
before and just after a new process is created with @code{fork}. The
@var{prepare} handler will be called from the parent process, just
before the new process is created. The @var{parent} handler will be
called from the parent process, just before @code{fork} returns. The
@var{child} handler will be called from the child process, just before
@code{fork} returns.

@code{pthread_atfork} returns 0 on success and a non-zero error code on
error.

One or more of the three handlers @var{prepare}, @var{parent} and
@var{child} can be given as @code{NULL}, meaning that no handler needs
to be called at the corresponding point.

@code{pthread_atfork} can be called several times to install several
sets of handlers. At @code{fork} time, the @var{prepare} handlers are
called in LIFO order (last added with @code{pthread_atfork}, first
called before @code{fork}), while the @var{parent} and @var{child}
handlers are called in FIFO order (first added, first called).

If there is insufficient memory available to register the handlers,
@code{pthread_atfork} fails and returns @code{ENOMEM}.  Otherwise it
returns 0.

The functions @code{fork} and @code{pthread_atfork} must not be regarded as
reentrant from the context of the handlers.  That is to say, if a
@code{pthread_atfork} handler invoked from within @code{fork} calls
@code{pthread_atfork} or @code{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 @code{exec} to load a new
pocess image.

@end deftypefun

To understand the purpose of @code{pthread_atfork}, recall that
@code{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 @code{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 @code{pthread_atfork} as follows: have the
@var{prepare} handler lock the mutexes (in locking order), and the
@var{parent} handler unlock the mutexes. The @var{child} handler should reset
the mutexes using @code{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 @code{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.

@node Streams and Fork
@section 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 @code{fork} so that the child receives an intact copy of the list.
This allows the @code{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
@code{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 @code{fork} is called.
Otherwise an inconsistent copy of the stream object be produced. An easy way to
ensure this is to use @code{flockfile} to lock the stream prior to calling
@code{fork} and then unlock it with @code{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 @code{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 @code{stdout}, strangely interleaved output may result regardless of
the explicit use of @code{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.

@node Miscellaneous Thread Functions
@section Miscellaneous Thread Functions

@comment pthread.h
@comment POSIX
@deftypefun {pthread_t} pthread_self (@var{void})
@code{pthread_self} returns the thread identifier for the calling thread.
@end deftypefun

@comment pthread.h
@comment POSIX
@deftypefun int pthread_equal (pthread_t thread1, pthread_t thread2)
@code{pthread_equal} determines if two thread identifiers refer to the same
thread.

A non-zero value is returned if @var{thread1} and @var{thread2} refer to
the same thread. Otherwise, 0 is returned.
@end deftypefun

@comment pthread.h
@comment POSIX
@deftypefun int pthread_detach (pthread_t @var{th})
@code{pthread_detach} puts the thread @var{th} in the detached
state. This guarantees that the memory resources consumed by @var{th}
will be freed immediately when @var{th} terminates. However, this
prevents other threads from synchronizing on the termination of @var{th}
using @code{pthread_join}.

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

After @code{pthread_detach} completes, subsequent attempts to perform
@code{pthread_join} on @var{th} will fail. If another thread is already
joining the thread @var{th} at the time @code{pthread_detach} is called,
@code{pthread_detach} does nothing and leaves @var{th} in the joinable
state.

On success, 0 is returned. On error, one of the following codes is
returned:
@table @code
@item ESRCH
No thread could be found corresponding to that specified by @var{th}
@item EINVAL
The thread @var{th} is already in the detached state
@end table
@end deftypefun

@comment pthread.h
@comment GNU
@deftypefun void pthread_kill_other_threads_np (@var{void})
@code{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 @code{exec} functions,
e.g. @code{execve}.

Termination of the other threads is not performed through
@code{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 @code{exec*} in one of the
threads should automatically terminate all other threads in the program.
This behavior is not yet implemented in LinuxThreads.  Calling
@code{pthread_kill_other_threads_np} before @code{exec*} achieves much
of the same behavior, except that if @code{exec*} ultimately fails, then
all other threads are already killed.
@end deftypefun

@comment pthread.h
@comment POSIX
@deftypefun int pthread_once (pthread_once_t *once_@var{control}, void (*@var{init_routine}) (void))

The purpose of @code{pthread_once} is to ensure that a piece of
initialization code is executed at most once. The @var{once_control}
argument points to a static or extern variable statically initialized
to @code{PTHREAD_ONCE_INIT}.

The first time @code{pthread_once} is called with a given
@var{once_control} argument, it calls @var{init_routine} with no
argument and changes the value of the @var{once_control} variable to
record that initialization has been performed. Subsequent calls to
@code{pthread_once} with the same @code{once_control} argument do
nothing.

If a thread is cancelled while executing @var{init_routine}
the state of the @var{once_control} variable is reset so that
a