Quick ?s
Cheat Sheets
Man Pages
The Lynx
Software
PTHREADS(7)		   Linux Programmers Manual		  PTHREADS(7)



NAME
       pthreads - POSIX threads

DESCRIPTION
       POSIX.1	specifies  a  set  of interfaces (functions, header files) for
       threaded programming commonly known as POSIX threads, or  Pthreads.   A
       single process can contain multiple threads, all of which are executing
       the same program.  These threads share the same global memory (data and
       heap  segments),  but  each  thread  has its own stack (automatic vari
       ables).

       POSIX.1 also requires that threads share a range  of  other  attributes
       (i.e., these attributes are process-wide rather than per-thread):

       -  process ID

       -  parent process ID

       -  process group ID and session ID

       -  controlling terminal

       -  user and group IDs

       -  open file descriptors

       -  record locks (see fcntl(2))

       -  signal dispositions

       -  file mode creation mask (umask(2))

       -  current directory (chdir(2)) and root directory (chroot(2))

       -  interval timers (setitimer(2)) and POSIX timers (timer_create(3))

       -  nice value (setpriority(2))

       -  resource limits (setrlimit(2))

       -  measurements of the consumption of CPU time (times(2)) and resources
	  (getrusage(2))

       As well as the stack, POSIX.1 specifies that various  other  attributes
       are distinct for each thread, including:

       -  thread ID (the pthread_t data type)

       -  signal mask (pthread_sigmask(3))

       -  the errno variable

       -  alternate signal stack (sigaltstack(2))

       -  real-time  scheduling policy and priority (sched_setscheduler(2) and
	  sched_setparam(2))

       The following Linux-specific features are also per-thread:

       -  capabilities (see capabilities(7))

       -  CPU affinity (sched_setaffinity(2))

   Thread-safe functions
       A thread-safe function is one that can be safely (i.e., it will deliver
       the  same  results  regardless  of  whether it is) called from multiple
       threads at the same time.

       POSIX.1-2001 requires that all  functions  specified  in  the  standard
       shall be thread-safe, except for the following functions:

	   asctime()
	   basename()
	   catgets()
	   crypt()
	   ctermid() if passed a non-NULL argument
	   ctime()
	   dbm_clearerr()
	   dbm_close()
	   dbm_delete()
	   dbm_error()
	   dbm_fetch()
	   dbm_firstkey()
	   dbm_nextkey()
	   dbm_open()
	   dbm_store()
	   dirname()
	   dlerror()
	   drand48()
	   ecvt()
	   encrypt()
	   endgrent()
	   endpwent()
	   endutxent()
	   fcvt()
	   ftw()
	   gcvt()
	   getc_unlocked()
	   getchar_unlocked()
	   getdate()
	   getenv()
	   getgrent()
	   getgrgid()
	   getgrnam()
	   gethostbyaddr()
	   gethostbyname()
	   gethostent()
	   getlogin()
	   getnetbyaddr()
	   getnetbyname()
	   getnetent()
	   getopt()
	   getprotobyname()
	   getprotobynumber()
	   getprotoent()
	   getpwent()
	   getpwnam()
	   getpwuid()
	   getservbyname()
	   getservbyport()
	   getservent()
	   getutxent()
	   getutxid()
	   getutxline()
	   gmtime()
	   hcreate()
	   hdestroy()
	   hsearch()
	   inet_ntoa()
	   l64a()
	   lgamma()
	   lgammaf()
	   lgammal()
	   localeconv()
	   localtime()
	   lrand48()
	   mrand48()
	   nftw()
	   nl_langinfo()
	   ptsname()
	   putc_unlocked()
	   putchar_unlocked()
	   putenv()
	   pututxline()
	   rand()
	   readdir()
	   setenv()
	   setgrent()
	   setkey()
	   setpwent()
	   setutxent()
	   strerror()
	   strtok()
	   tmpnam() if passed a non-NULL argument
	   ttyname()
	   unsetenv()
	   wcrtomb() if its final argument is NULL
	   wcsrtombs() if its final argument is NULL
	   wcstombs()
	   wctomb()

   Compiling on Linux
       On  Linux,  programs that use the Pthreads API should be compiled using
       cc -pthread.

   Linux Implementations of POSIX Threads
       Over time, two threading implementations have been provided by the  GNU
       C library on Linux:

       LinuxThreads
	      This  is the original Pthreads implementation.  Since glibc 2.4,
	      this implementation is no longer supported.

       NPTL (Native POSIX Threads Library)
	      This is the modern Pthreads implementation.  By comparison  with
	      LinuxThreads,  NPTL  provides closer conformance to the require
	      ments of the POSIX.1 specification and better  performance  when
	      creating	large  numbers	of  threads.   NPTL is available since
	      glibc 2.3.2, and requires features that are present in the Linux
	      2.6 kernel.

       Both  of  these	are  so-called	1:1 implementations, meaning that each
       thread maps to a kernel scheduling entity.  Both threading  implementa
       tions  employ the Linux clone(2) system call.  In NPTL, thread synchro
       nization primitives (mutexes, thread  joining,  etc.)  are  implemented
       using the Linux futex(2) system call.

   LinuxThreads
       The notable features of this implementation are the following:

       -  In  addition	to the main (initial) thread, and the threads that the
	  program creates using pthread_create(3), the implementation  creates
	  a  "manager" thread.	This thread handles thread creation and termi
	  nation.  (Problems  can  result  if  this  thread  is  inadvertently
	  killed.)

       -  Signals are used internally by the implementation.  On Linux 2.2 and
	  later, the first three real-time signals are used.  On  older  Linux
	  kernels,  SIGUSR1 and SIGUSR2 are used.  Applications must avoid the
	  use of whichever set of signals is employed by the implementation.

       -  Threads do not share process IDs.  (In effect, LinuxThreads  threads
	  are  implemented  as	processes  which  share  more information than
	  usual, but which do not share a common  process  ID.)   LinuxThreads
	  threads  (including the manager thread) are visible as separate pro
	  cesses using ps(1).

       The LinuxThreads implementation deviates from the POSIX.1 specification
       in a number of ways, including the following:

       -  Calls to getpid(2) return a different value in each thread.

       -  Calls to getppid(2) in threads other than the main thread return the
	  process ID of  the  manager  thread;	instead  getppid(2)  in  these
	  threads  should  return  the	same  value  as getppid(2) in the main
	  thread.

       -  When one thread creates a  new  child  process  using  fork(2),  any
	  thread  should be able to wait(2) on the child.  However, the imple
	  mentation only allows the thread that created the child  to  wait(2)
	  on it.

       -  When	a thread calls execve(2), all other threads are terminated (as
	  required by POSIX.1).  However, the resulting process has  the  same
	  PID as the thread that called execve(2): it should have the same PID
	  as the main thread.

       -  Threads do not share user and group IDs.  This can  cause  complica
	  tions  with  set-user-ID programs and can cause failures in Pthreads
	  functions if an application changes its credentials using seteuid(2)
	  or similar.

       -  Threads do not share a common session ID and process group ID.

       -  Threads do not share record locks created using fcntl(2).

       -  The  information returned by times(2) and getrusage(2) is per-thread
	  rather than process-wide.

       -  Threads do not share semaphore undo values (see semop(2)).

       -  Threads do not share interval timers.

       -  Threads do not share a common nice value.

       -  POSIX.1 distinguishes the notions of signals that  are  directed  to
	  the  process	as a whole and signals that are directed to individual
	  threads.  According to  POSIX.1,  a  process-directed  signal  (sent
	  using kill(2), for example) should be handled by a single, arbitrar
	  ily selected thread within the process.  LinuxThreads does not  sup
	  port	the  notion  of  process-directed signals: signals may only be
	  sent to specific threads.

       -  Threads have distinct alternate signal stack settings.   However,  a
	  new  threads	alternate  signal  stack settings are copied from the
	  thread that created it, so  that  the  threads  initially  share  an
	  alternate  signal  stack.  (A new thread should start with no alter
	  nate signal stack defined.  If two threads handle signals  on  their
	  shared  alternate  signal stack at the same time, unpredictable pro
	  gram failures are likely to occur.)

   NPTL
       With NPTL, all of the threads in a  process  are  placed  in  the  same
       thread  group; all members of a thread groups share the same PID.  NPTL
       does not employ a manager thread.  NPTL makes internal use of the first
       two real-time signals; these signals cannot be used in applications.

       NPTL still has at least one non-conformance with POSIX.1:

       -  Threads do not share a common nice value.

       Some NPTL non-conformances only occur with older kernels:

       -  The  information returned by times(2) and getrusage(2) is per-thread
	  rather than process-wide (fixed in kernel 2.6.9).

       -  Threads do not share resource limits (fixed in kernel 2.6.10).

       -  Threads do not share interval timers (fixed in kernel 2.6.12).

       -  Only the main thread is permitted to start a new session using  set
	  sid(2) (fixed in kernel 2.6.16).

       -  Only the main thread is permitted to make the process into a process
	  group leader using setpgid(2) (fixed in kernel 2.6.16).

       -  Threads have distinct alternate signal stack settings.   However,  a
	  new  threads	alternate  signal  stack settings are copied from the
	  thread that created it, so  that  the  threads  initially  share  an
	  alternate signal stack (fixed in kernel 2.6.16).

       Note the following further points about the NPTL implementation:

       -  If  the  stack  size	soft  resource	limit  (see the description of
	  RLIMIT_STACK in setrlimit(2)) is set to a value  other  than	unlim
	  ited,  then  this  value  defines  the  default  stack  size for new
	  threads.  To be effective, this limit must be set before the program
	  is  executed,  perhaps  using  the  ulimit -s shell built-in command
	  (limit stacksize in the C shell).

   Determining the Threading Implementation
       Since glibc 2.3.2, the getconf(1) command can be used to determine  the
       systems threading implementation, for example:

	   bash$ getconf GNU_LIBPTHREAD_VERSION
	   NPTL 2.3.4

       With  older  glibc  versions, a command such as the following should be
       sufficient to determine the default threading implementation:

	   bash$ $( ldd /bin/ls | grep libc.so | awk '{print $3}' ) | \
			   egrep -i 'threads|nptl'
		   Native POSIX Threads Library by Ulrich Drepper et al

   Selecting the Threading Implementation: LD_ASSUME_KERNEL
       On systems with a glibc that supports both LinuxThreads and NPTL (i.e.,
       glibc  2.3.x), the LD_ASSUME_KERNEL environment variable can be used to
       override the dynamic linkers default choice of  threading  implementa
       tion.  This variable tells the dynamic linker to assume that it is run
       ning on top of a particular kernel version.   By  specifying  a	kernel
       version	that  does  not  provide  the support required by NPTL, we can
       force the use of LinuxThreads.  (The most likely reason for doing  this
       is  to  run  a (broken) application that depends on some non-conformant
       behavior in LinuxThreads.)  For example:

	   bash$ $( LD_ASSUME_KERNEL=2.2.5 ldd /bin/ls | grep libc.so | \
			   awk '{print $3}' ) | egrep -i 'threads|ntpl'
		   linuxthreads-0.10 by Xavier Leroy

SEE ALSO
       clone(2), futex(2), gettid(2), futex(7),
       and various Pthreads  manual  pages,  for  example:  pthread_atfork(3),
       pthread_cleanup_push(3),  pthread_cond_signal(3), pthread_cond_wait(3),
       pthread_create(3),	  pthread_detach(3),	     pthread_equal(3),
       pthread_exit(3), 	pthread_key_create(3),	      pthread_kill(3),
       pthread_mutex_lock(3),	 pthread_mutex_unlock(3),     pthread_once(3),
       pthread_setcancelstate(3),   pthread_setcanceltype(3),  pthread_setspe
       cific(3), pthread_sigmask(3), and pthread_testcancel(3)

COLOPHON
       This page is part of release 3.05 of the Linux  man-pages  project.   A
       description  of	the project, and information about reporting bugs, can
       be found at http://www.kernel.org/doc/man-pages/.



Linux				  2008-05-29			   PTHREADS(7)




Yals.net is © 1999-2009 Crescendo Communications
Sharing tech info on the web for more than a decade!
This page was generated Thu Apr 30 17:05:31 2009