pthread.pod

Linux下的中文输入法

##
##  GNU Pth - The GNU Portable Threads
##  Copyright (c) 1999-2004 Ralf S. Engelschall <[e-mail]>
##
##  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 <[e-mail]>.
##
##  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
 [e-mail]
 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).