diff options
Diffstat (limited to 'man7/pthreads.7')
| -rw-r--r-- | man7/pthreads.7 | 175 |
1 files changed, 94 insertions, 81 deletions
diff --git a/man7/pthreads.7 b/man7/pthreads.7 index 81d0db0e1..98743742e 100644 --- a/man7/pthreads.7 +++ b/man7/pthreads.7 @@ -29,34 +29,43 @@ user and group IDs open file descriptors .IP \[bu] record locks (see -.BR fcntl (2)) +.MR fcntl 2 ) .IP \[bu] signal dispositions .IP \[bu] file mode creation mask -.RB ( umask (2)) +\%(\c +.MR umask 2 ) .IP \[bu] current directory -.RB ( chdir (2)) +\%(\c +.MR chdir 2 ) and root directory -.RB ( chroot (2)) +\%(\c +.MR chroot 2 ) .IP \[bu] interval timers -.RB ( setitimer (2)) +\%(\c +.MR setitimer 2 ) and POSIX timers -.RB ( timer_create (2)) +\%(\c +.MR timer_create 2 ) .IP \[bu] nice value -.RB ( setpriority (2)) +\%(\c +.MR setpriority 2 ) .IP \[bu] resource limits -.RB ( setrlimit (2)) +\%(\c +.MR setrlimit 2 ) .IP \[bu] measurements of the consumption of CPU time -.RB ( times (2)) +\%(\c +.MR times 2 ) and resources -.RB ( getrusage (2)) +\%(\c +.MR getrusage 2 ) .P As well as the stack, POSIX.1 specifies that various other attributes are distinct for each thread, including: @@ -66,25 +75,29 @@ thread ID (the data type) .IP \[bu] signal mask -.RB ( pthread_sigmask (3)) +\%(\c +.MR pthread_sigmask 3 ) .IP \[bu] the .I errno variable .IP \[bu] alternate signal stack -.RB ( sigaltstack (2)) +\%(\c +.MR sigaltstack 2 ) .IP \[bu] real-time scheduling policy and priority -.RB ( sched (7)) +\%(\c +.MR sched 7 ) .P The following Linux-specific features are also per-thread: .IP \[bu] 3 capabilities (see -.BR capabilities (7)) +.MR capabilities 7 ) .IP \[bu] CPU affinity -.RB ( sched_setaffinity (2)) +\%(\c +.MR sched_setaffinity 2 ) .SS Pthreads function return values Most pthreads functions return 0 on success, and an error number on failure. The error numbers that can be returned have the same meaning as @@ -101,9 +114,9 @@ Each of the threads in a process has a unique thread identifier (stored in the type .IR pthread_t ). This identifier is returned to the caller of -.BR pthread_create (3), +.MR pthread_create 3 , and a thread can obtain its own thread identifier using -.BR pthread_self (3). +.MR pthread_self 3 . .P Thread IDs are guaranteed to be unique only within a process. (In all pthreads functions that accept a thread ID as an argument, @@ -223,7 +236,7 @@ wctomb() .SS Async-cancel-safe functions An async-cancel-safe function is one that can be safely called in an application where asynchronous cancelability is enabled (see -.BR pthread_setcancelstate (3)). +.MR pthread_setcancelstate 3 ). .P Only the following functions are required to be async-cancel-safe by POSIX.1-2001 and POSIX.1-2008: @@ -673,18 +686,18 @@ 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 implementations employ the Linux -.BR clone (2) +.MR clone 2 system call. In NPTL, thread synchronization primitives (mutexes, thread joining, and so on) are implemented using the Linux -.BR futex (2) +.MR futex 2 system call. .SS LinuxThreads The notable features of this implementation are the following: .IP \[bu] 3 In addition to the main (initial) thread, and the threads that the program creates using -.BR pthread_create (3), +.MR pthread_create 3 , the implementation creates a "manager" thread. This thread handles thread creation and termination. (Problems can result if this thread is inadvertently killed.) @@ -692,7 +705,7 @@ This thread handles thread creation and termination. Signals are used internally by the implementation. On Linux 2.2 and later, the first three real-time signals are used (see also -.BR signal (7)). +.MR signal 7 ). On older Linux kernels, .B SIGUSR1 and @@ -706,61 +719,61 @@ Threads do not share process IDs. more information than usual, but which do not share a common process ID.) LinuxThreads threads (including the manager thread) are visible as separate processes using -.BR ps (1). +.MR ps 1 . .P The LinuxThreads implementation deviates from the POSIX.1 specification in a number of ways, including the following: .IP \[bu] 3 Calls to -.BR getpid (2) +.MR getpid 2 return a different value in each thread. .IP \[bu] Calls to -.BR getppid (2) +.MR getppid 2 in threads other than the main thread return the process ID of the manager thread; instead -.BR getppid (2) +.MR getppid 2 in these threads should return the same value as -.BR getppid (2) +.MR getppid 2 in the main thread. .IP \[bu] When one thread creates a new child process using -.BR fork (2), +.MR fork 2 , any thread should be able to -.BR wait (2) +.MR wait 2 on the child. However, the implementation allows only the thread that created the child to -.BR wait (2) +.MR wait 2 on it. .IP \[bu] When a thread calls -.BR execve (2), +.MR 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 -.BR execve (2): +.MR execve 2 : it should have the same PID as the main thread. .IP \[bu] Threads do not share user and group IDs. This can cause complications with set-user-ID programs and can cause failures in Pthreads functions if an application changes its credentials using -.BR seteuid (2) +.MR seteuid 2 or similar. .IP \[bu] Threads do not share a common session ID and process group ID. .IP \[bu] Threads do not share record locks created using -.BR fcntl (2). +.MR fcntl 2 . .IP \[bu] The information returned by -.BR times (2) +.MR times 2 and -.BR getrusage (2) +.MR getrusage 2 is per-thread rather than process-wide. .IP \[bu] Threads do not share semaphore undo values (see -.BR semop (2)). +.MR semop 2 ). .IP \[bu] Threads do not share interval timers. .IP \[bu] @@ -770,7 +783,7 @@ 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 -.BR kill (2), +.MR kill 2 , for example) should be handled by a single, arbitrarily selected thread within the process. LinuxThreads does not support the notion of process-directed signals: @@ -793,7 +806,7 @@ 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. See -.BR nptl (7) +.MR nptl 7 for further details. .P NPTL still has at least one nonconformance with POSIX.1: @@ -808,9 +821,9 @@ Threads do not share a common nice value. Some NPTL nonconformances occur only with older kernels: .IP \[bu] 3 The information returned by -.BR times (2) +.MR times 2 and -.BR getrusage (2) +.MR getrusage 2 is per-thread rather than process-wide (fixed in Linux 2.6.9). .IP \[bu] Threads do not share resource limits (fixed in Linux 2.6.10). @@ -818,12 +831,12 @@ Threads do not share resource limits (fixed in Linux 2.6.10). Threads do not share interval timers (fixed in Linux 2.6.12). .IP \[bu] Only the main thread is permitted to start a new session using -.BR setsid (2) +.MR setsid 2 (fixed in Linux 2.6.16). .IP \[bu] Only the main thread is permitted to make the process into a process group leader using -.BR setpgid (2) +.MR setpgid 2 (fixed in Linux 2.6.16). .IP \[bu] Threads have distinct alternate signal stack settings. @@ -837,7 +850,7 @@ Note the following further points about the NPTL implementation: If the stack size soft resource limit (see the description of .B RLIMIT_STACK in -.BR setrlimit (2)) +.MR setrlimit 2 ) is set to a value other than .IR unlimited , then this value defines the default stack size for new threads. @@ -849,7 +862,7 @@ shell built-in command in the C shell). .SS Determining the threading implementation Since glibc 2.3.2, the -.BR getconf (1) +.MR getconf 1 command can be used to determine the system's threading implementation, for example: .P @@ -896,42 +909,42 @@ bash$ $( LD_ASSUME_KERNEL=2.2.5 ldd /bin/ls | grep libc.so | \e .SH SEE ALSO .ad l .nh -.BR clone (2), -.BR fork (2), -.BR futex (2), -.BR gettid (2), -.BR proc (5), -.BR attributes (7), -.BR futex (7), -.BR nptl (7), -.BR sigevent (3type), -.BR signal (7) +.MR clone 2 , +.MR fork 2 , +.MR futex 2 , +.MR gettid 2 , +.MR proc 5 , +.MR attributes 7 , +.MR futex 7 , +.MR nptl 7 , +.MR sigevent 3type , +.MR signal 7 .P Various Pthreads manual pages, for example: -.BR pthread_atfork (3), -.BR pthread_attr_init (3), -.BR pthread_cancel (3), -.BR pthread_cleanup_push (3), -.BR pthread_cond_signal (3), -.BR pthread_cond_wait (3), -.BR pthread_create (3), -.BR pthread_detach (3), -.BR pthread_equal (3), -.BR pthread_exit (3), -.BR pthread_key_create (3), -.BR pthread_kill (3), -.BR pthread_mutex_lock (3), -.BR pthread_mutex_unlock (3), -.BR pthread_mutexattr_destroy (3), -.BR pthread_mutexattr_init (3), -.BR pthread_once (3), -.BR pthread_spin_init (3), -.BR pthread_spin_lock (3), -.BR pthread_rwlockattr_setkind_np (3), -.BR pthread_setcancelstate (3), -.BR pthread_setcanceltype (3), -.BR pthread_setspecific (3), -.BR pthread_sigmask (3), -.BR pthread_sigqueue (3), +.MR pthread_atfork 3 , +.MR pthread_attr_init 3 , +.MR pthread_cancel 3 , +.MR pthread_cleanup_push 3 , +.MR pthread_cond_signal 3 , +.MR pthread_cond_wait 3 , +.MR pthread_create 3 , +.MR pthread_detach 3 , +.MR pthread_equal 3 , +.MR pthread_exit 3 , +.MR pthread_key_create 3 , +.MR pthread_kill 3 , +.MR pthread_mutex_lock 3 , +.MR pthread_mutex_unlock 3 , +.MR pthread_mutexattr_destroy 3 , +.MR pthread_mutexattr_init 3 , +.MR pthread_once 3 , +.MR pthread_spin_init 3 , +.MR pthread_spin_lock 3 , +.MR pthread_rwlockattr_setkind_np 3 , +.MR pthread_setcancelstate 3 , +.MR pthread_setcanceltype 3 , +.MR pthread_setspecific 3 , +.MR pthread_sigmask 3 , +.MR pthread_sigqueue 3 , and -.BR pthread_testcancel (3) +.MR pthread_testcancel 3 |