1/* Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007
2   Free Software Foundation, Inc.
3   This file is part of the GNU C Library.
4
5   The GNU C Library is free software; you can redistribute it and/or
6   modify it under the terms of the GNU Lesser General Public
7   License as published by the Free Software Foundation; either
8   version 2.1 of the License, or (at your option) any later version.
9
10   The GNU C Library is distributed in the hope that it will be useful,
11   but WITHOUT ANY WARRANTY; without even the implied warranty of
12   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13   Lesser General Public License for more details.
14
15   You should have received a copy of the GNU Lesser General Public
16   License along with the GNU C Library; if not, write to the Free
17   Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
18   02111-1307 USA.  */
19
20#ifndef _PTHREAD_H
21#define _PTHREAD_H	1
22
23#include <features.h>
24#include <endian.h>
25#include <sched.h>
26#include <time.h>
27
28#define __need_sigset_t
29#include <signal.h>
30#include <bits/pthreadtypes.h>
31#include <bits/setjmp.h>
32#include <bits/wordsize.h>
33
34
35/* Detach state.  */
36enum
37{
38  PTHREAD_CREATE_JOINABLE,
39#define PTHREAD_CREATE_JOINABLE	PTHREAD_CREATE_JOINABLE
40  PTHREAD_CREATE_DETACHED
41#define PTHREAD_CREATE_DETACHED	PTHREAD_CREATE_DETACHED
42};
43
44
45/* Mutex types.  */
46enum
47{
48  PTHREAD_MUTEX_TIMED_NP,
49  PTHREAD_MUTEX_RECURSIVE_NP,
50  PTHREAD_MUTEX_ERRORCHECK_NP,
51  PTHREAD_MUTEX_ADAPTIVE_NP
52#ifdef __USE_UNIX98
53  ,
54  PTHREAD_MUTEX_NORMAL = PTHREAD_MUTEX_TIMED_NP,
55  PTHREAD_MUTEX_RECURSIVE = PTHREAD_MUTEX_RECURSIVE_NP,
56  PTHREAD_MUTEX_ERRORCHECK = PTHREAD_MUTEX_ERRORCHECK_NP,
57  PTHREAD_MUTEX_DEFAULT = PTHREAD_MUTEX_NORMAL
58#endif
59#ifdef __USE_GNU
60  /* For compatibility.  */
61  , PTHREAD_MUTEX_FAST_NP = PTHREAD_MUTEX_TIMED_NP
62#endif
63};
64
65
66#ifdef __USE_GNU
67/* Robust mutex or not flags.  */
68enum
69{
70  PTHREAD_MUTEX_STALLED_NP,
71  PTHREAD_MUTEX_ROBUST_NP
72};
73#endif
74
75
76#ifdef __USE_UNIX98
77/* Mutex protocols.  */
78enum
79{
80  PTHREAD_PRIO_NONE,
81  PTHREAD_PRIO_INHERIT,
82  PTHREAD_PRIO_PROTECT
83};
84#endif
85
86
87/* Mutex initializers.  */
88#if __WORDSIZE == 64
89# define PTHREAD_MUTEX_INITIALIZER \
90  { { 0, 0, 0, 0, 0, 0, { 0, 0 } } }
91# ifdef __USE_GNU
92#  define PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP \
93  { { 0, 0, 0, 0, PTHREAD_MUTEX_RECURSIVE_NP, 0, { 0, 0 } } }
94#  define PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP \
95  { { 0, 0, 0, 0, PTHREAD_MUTEX_ERRORCHECK_NP, 0, { 0, 0 } } }
96#  define PTHREAD_ADAPTIVE_MUTEX_INITIALIZER_NP \
97  { { 0, 0, 0, 0, PTHREAD_MUTEX_ADAPTIVE_NP, 0, { 0, 0 } } }
98# endif
99#else
100# define PTHREAD_MUTEX_INITIALIZER \
101  { { 0, 0, 0, 0, 0, { 0 } } }
102# ifdef __USE_GNU
103#  define PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP \
104  { { 0, 0, 0, PTHREAD_MUTEX_RECURSIVE_NP, 0, { 0 } } }
105#  define PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP \
106  { { 0, 0, 0, PTHREAD_MUTEX_ERRORCHECK_NP, 0, { 0 } } }
107#  define PTHREAD_ADAPTIVE_MUTEX_INITIALIZER_NP \
108  { { 0, 0, 0, PTHREAD_MUTEX_ADAPTIVE_NP, 0, { 0 } } }
109# endif
110#endif
111
112
113/* Read-write lock types.  */
114#if defined __USE_UNIX98 || defined __USE_XOPEN2K
115enum
116{
117  PTHREAD_RWLOCK_PREFER_READER_NP,
118  PTHREAD_RWLOCK_PREFER_WRITER_NP,
119  PTHREAD_RWLOCK_PREFER_WRITER_NONRECURSIVE_NP,
120  PTHREAD_RWLOCK_DEFAULT_NP = PTHREAD_RWLOCK_PREFER_READER_NP
121};
122
123/* Read-write lock initializers.  */
124# define PTHREAD_RWLOCK_INITIALIZER \
125  { { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 } }
126# ifdef __USE_GNU
127#  if __WORDSIZE == 64
128#   define PTHREAD_RWLOCK_WRITER_NONRECURSIVE_INITIALIZER_NP \
129  { { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,					      \
130      PTHREAD_RWLOCK_PREFER_WRITER_NONRECURSIVE_NP } }
131#  else
132#   if __BYTE_ORDER == __LITTLE_ENDIAN
133#    define PTHREAD_RWLOCK_WRITER_NONRECURSIVE_INITIALIZER_NP \
134  { { 0, 0, 0, 0, 0, 0, PTHREAD_RWLOCK_PREFER_WRITER_NONRECURSIVE_NP, \
135      0, 0, 0, 0 } }
136#   else
137#    define PTHREAD_RWLOCK_WRITER_NONRECURSIVE_INITIALIZER_NP \
138  { { 0, 0, 0, 0, 0, 0, 0, 0, 0, PTHREAD_RWLOCK_PREFER_WRITER_NONRECURSIVE_NP,\
139      0 } }
140#   endif
141#  endif
142# endif
143#endif  /* Unix98 or XOpen2K */
144
145
146/* Scheduler inheritance.  */
147enum
148{
149  PTHREAD_INHERIT_SCHED,
150#define PTHREAD_INHERIT_SCHED   PTHREAD_INHERIT_SCHED
151  PTHREAD_EXPLICIT_SCHED
152#define PTHREAD_EXPLICIT_SCHED  PTHREAD_EXPLICIT_SCHED
153};
154
155
156/* Scope handling.  */
157enum
158{
159  PTHREAD_SCOPE_SYSTEM,
160#define PTHREAD_SCOPE_SYSTEM    PTHREAD_SCOPE_SYSTEM
161  PTHREAD_SCOPE_PROCESS
162#define PTHREAD_SCOPE_PROCESS   PTHREAD_SCOPE_PROCESS
163};
164
165
166/* Process shared or private flag.  */
167enum
168{
169  PTHREAD_PROCESS_PRIVATE,
170#define PTHREAD_PROCESS_PRIVATE PTHREAD_PROCESS_PRIVATE
171  PTHREAD_PROCESS_SHARED
172#define PTHREAD_PROCESS_SHARED  PTHREAD_PROCESS_SHARED
173};
174
175
176
177/* Conditional variable handling.  */
178#define PTHREAD_COND_INITIALIZER { { 0, 0, 0, 0, 0, (void *) 0, 0, 0 } }
179
180
181/* Cleanup buffers */
182struct _pthread_cleanup_buffer
183{
184  void (*__routine) (void *);             /* Function to call.  */
185  void *__arg;                            /* Its argument.  */
186  int __canceltype;                       /* Saved cancellation type. */
187  struct _pthread_cleanup_buffer *__prev; /* Chaining of cleanup functions.  */
188};
189
190/* Cancellation */
191enum
192{
193  PTHREAD_CANCEL_ENABLE,
194#define PTHREAD_CANCEL_ENABLE   PTHREAD_CANCEL_ENABLE
195  PTHREAD_CANCEL_DISABLE
196#define PTHREAD_CANCEL_DISABLE  PTHREAD_CANCEL_DISABLE
197};
198enum
199{
200  PTHREAD_CANCEL_DEFERRED,
201#define PTHREAD_CANCEL_DEFERRED	PTHREAD_CANCEL_DEFERRED
202  PTHREAD_CANCEL_ASYNCHRONOUS
203#define PTHREAD_CANCEL_ASYNCHRONOUS	PTHREAD_CANCEL_ASYNCHRONOUS
204};
205#define PTHREAD_CANCELED ((void *) -1)
206
207
208/* Single execution handling.  */
209#define PTHREAD_ONCE_INIT 0
210
211
212#ifdef __USE_XOPEN2K
213/* Value returned by 'pthread_barrier_wait' for one of the threads after
214   the required number of threads have called this function.
215   -1 is distinct from 0 and all errno constants */
216# define PTHREAD_BARRIER_SERIAL_THREAD -1
217#endif
218
219
220__BEGIN_DECLS
221
222/* Create a new thread, starting with execution of START-ROUTINE
223   getting passed ARG.  Creation attributed come from ATTR.  The new
224   handle is stored in *NEWTHREAD.  */
225extern int pthread_create (pthread_t *__restrict __newthread,
226			   __const pthread_attr_t *__restrict __attr,
227			   void *(*__start_routine) (void *),
228			   void *__restrict __arg) __THROW __nonnull ((1, 3));
229
230/* Terminate calling thread.
231
232   The registered cleanup handlers are called via exception handling
233   so we cannot mark this function with __THROW.*/
234extern void pthread_exit (void *__retval) __attribute__ ((__noreturn__));
235
236/* Make calling thread wait for termination of the thread TH.  The
237   exit status of the thread is stored in *THREAD_RETURN, if THREAD_RETURN
238   is not NULL.
239
240   This function is a cancellation point and therefore not marked with
241   __THROW.  */
242extern int pthread_join (pthread_t __th, void **__thread_return);
243
244#ifdef __USE_GNU
245/* Check whether thread TH has terminated.  If yes return the status of
246   the thread in *THREAD_RETURN, if THREAD_RETURN is not NULL.  */
247extern int pthread_tryjoin_np (pthread_t __th, void **__thread_return) __THROW;
248
249/* Make calling thread wait for termination of the thread TH, but only
250   until TIMEOUT.  The exit status of the thread is stored in
251   *THREAD_RETURN, if THREAD_RETURN is not NULL.
252
253   This function is a cancellation point and therefore not marked with
254   __THROW.  */
255extern int pthread_timedjoin_np (pthread_t __th, void **__thread_return,
256				 __const struct timespec *__abstime);
257#endif
258
259/* Indicate that the thread TH is never to be joined with PTHREAD_JOIN.
260   The resources of TH will therefore be freed immediately when it
261   terminates, instead of waiting for another thread to perform PTHREAD_JOIN
262   on it.  */
263extern int pthread_detach (pthread_t __th) __THROW;
264
265
266/* Obtain the identifier of the current thread.  */
267extern pthread_t pthread_self (void) __THROW __attribute__ ((__const__));
268
269/* Compare two thread identifiers.  */
270extern int pthread_equal (pthread_t __thread1, pthread_t __thread2) __THROW;
271
272
273/* Thread attribute handling.  */
274
275/* Initialize thread attribute *ATTR with default attributes
276   (detachstate is PTHREAD_JOINABLE, scheduling policy is SCHED_OTHER,
277    no user-provided stack).  */
278extern int pthread_attr_init (pthread_attr_t *__attr) __THROW __nonnull ((1));
279
280/* Destroy thread attribute *ATTR.  */
281extern int pthread_attr_destroy (pthread_attr_t *__attr)
282     __THROW __nonnull ((1));
283
284/* Get detach state attribute.  */
285extern int pthread_attr_getdetachstate (__const pthread_attr_t *__attr,
286					int *__detachstate)
287     __THROW __nonnull ((1, 2));
288
289/* Set detach state attribute.  */
290extern int pthread_attr_setdetachstate (pthread_attr_t *__attr,
291					int __detachstate)
292     __THROW __nonnull ((1));
293
294
295/* Get the size of the guard area created for stack overflow protection.  */
296extern int pthread_attr_getguardsize (__const pthread_attr_t *__attr,
297				      size_t *__guardsize)
298     __THROW __nonnull ((1, 2));
299
300/* Set the size of the guard area created for stack overflow protection.  */
301extern int pthread_attr_setguardsize (pthread_attr_t *__attr,
302				      size_t __guardsize)
303     __THROW __nonnull ((1));
304
305
306/* Return in *PARAM the scheduling parameters of *ATTR.  */
307extern int pthread_attr_getschedparam (__const pthread_attr_t *__restrict
308				       __attr,
309				       struct sched_param *__restrict __param)
310     __THROW __nonnull ((1, 2));
311
312/* Set scheduling parameters (priority, etc) in *ATTR according to PARAM.  */
313extern int pthread_attr_setschedparam (pthread_attr_t *__restrict __attr,
314				       __const struct sched_param *__restrict
315				       __param) __THROW __nonnull ((1, 2));
316
317/* Return in *POLICY the scheduling policy of *ATTR.  */
318extern int pthread_attr_getschedpolicy (__const pthread_attr_t *__restrict
319					__attr, int *__restrict __policy)
320     __THROW __nonnull ((1, 2));
321
322/* Set scheduling policy in *ATTR according to POLICY.  */
323extern int pthread_attr_setschedpolicy (pthread_attr_t *__attr, int __policy)
324     __THROW __nonnull ((1));
325
326/* Return in *INHERIT the scheduling inheritance mode of *ATTR.  */
327extern int pthread_attr_getinheritsched (__const pthread_attr_t *__restrict
328					 __attr, int *__restrict __inherit)
329     __THROW __nonnull ((1, 2));
330
331/* Set scheduling inheritance mode in *ATTR according to INHERIT.  */
332extern int pthread_attr_setinheritsched (pthread_attr_t *__attr,
333					 int __inherit)
334     __THROW __nonnull ((1));
335
336
337/* Return in *SCOPE the scheduling contention scope of *ATTR.  */
338extern int pthread_attr_getscope (__const pthread_attr_t *__restrict __attr,
339				  int *__restrict __scope)
340     __THROW __nonnull ((1, 2));
341
342/* Set scheduling contention scope in *ATTR according to SCOPE.  */
343extern int pthread_attr_setscope (pthread_attr_t *__attr, int __scope)
344     __THROW __nonnull ((1));
345
346/* Return the previously set address for the stack.  */
347extern int pthread_attr_getstackaddr (__const pthread_attr_t *__restrict
348				      __attr, void **__restrict __stackaddr)
349     __THROW __nonnull ((1, 2)) __attribute_deprecated__;
350
351/* Set the starting address of the stack of the thread to be created.
352   Depending on whether the stack grows up or down the value must either
353   be higher or lower than all the address in the memory block.  The
354   minimal size of the block must be PTHREAD_STACK_MIN.  */
355extern int pthread_attr_setstackaddr (pthread_attr_t *__attr,
356				      void *__stackaddr)
357     __THROW __nonnull ((1)) __attribute_deprecated__;
358
359/* Return the currently used minimal stack size.  */
360extern int pthread_attr_getstacksize (__const pthread_attr_t *__restrict
361				      __attr, size_t *__restrict __stacksize)
362     __THROW __nonnull ((1, 2));
363
364/* Add information about the minimum stack size needed for the thread
365   to be started.  This size must never be less than PTHREAD_STACK_MIN
366   and must also not exceed the system limits.  */
367extern int pthread_attr_setstacksize (pthread_attr_t *__attr,
368				      size_t __stacksize)
369     __THROW __nonnull ((1));
370
371#ifdef __USE_XOPEN2K
372/* Return the previously set address for the stack.  */
373extern int pthread_attr_getstack (__const pthread_attr_t *__restrict __attr,
374				  void **__restrict __stackaddr,
375				  size_t *__restrict __stacksize)
376     __THROW __nonnull ((1, 2, 3));
377
378/* The following two interfaces are intended to replace the last two.  They
379   require setting the address as well as the size since only setting the
380   address will make the implementation on some architectures impossible.  */
381extern int pthread_attr_setstack (pthread_attr_t *__attr, void *__stackaddr,
382				  size_t __stacksize) __THROW __nonnull ((1));
383#endif
384
385#ifdef __USE_GNU
386/* Thread created with attribute ATTR will be limited to run only on
387   the processors represented in CPUSET.  */
388extern int pthread_attr_setaffinity_np (pthread_attr_t *__attr,
389					size_t __cpusetsize,
390					__const cpu_set_t *__cpuset)
391     __THROW __nonnull ((1, 3));
392
393/* Get bit set in CPUSET representing the processors threads created with
394   ATTR can run on.  */
395extern int pthread_attr_getaffinity_np (__const pthread_attr_t *__attr,
396					size_t __cpusetsize,
397					cpu_set_t *__cpuset)
398     __THROW __nonnull ((1, 3));
399
400
401/* Initialize thread attribute *ATTR with attributes corresponding to the
402   already running thread TH.  It shall be called on unitialized ATTR
403   and destroyed with pthread_attr_destroy when no longer needed.  */
404extern int pthread_getattr_np (pthread_t __th, pthread_attr_t *__attr)
405     __THROW __nonnull ((2));
406#endif
407
408
409/* Functions for scheduling control.  */
410
411/* Set the scheduling parameters for TARGET_THREAD according to POLICY
412   and *PARAM.  */
413extern int pthread_setschedparam (pthread_t __target_thread, int __policy,
414				  __const struct sched_param *__param)
415     __THROW __nonnull ((3));
416
417/* Return in *POLICY and *PARAM the scheduling parameters for TARGET_THREAD. */
418extern int pthread_getschedparam (pthread_t __target_thread,
419				  int *__restrict __policy,
420				  struct sched_param *__restrict __param)
421     __THROW __nonnull ((2, 3));
422
423/* Set the scheduling priority for TARGET_THREAD.  */
424extern int pthread_setschedprio (pthread_t __target_thread, int __prio)
425     __THROW;
426
427
428#ifdef __USE_UNIX98
429/* Determine level of concurrency.  */
430extern int pthread_getconcurrency (void) __THROW;
431
432/* Set new concurrency level to LEVEL.  */
433extern int pthread_setconcurrency (int __level) __THROW;
434#endif
435
436#ifdef __USE_GNU
437/* Yield the processor to another thread or process.
438   This function is similar to the POSIX `sched_yield' function but
439   might be differently implemented in the case of a m-on-n thread
440   implementation.  */
441extern int pthread_yield (void) __THROW;
442
443
444/* Limit specified thread TH to run only on the processors represented
445   in CPUSET.  */
446extern int pthread_setaffinity_np (pthread_t __th, size_t __cpusetsize,
447				   __const cpu_set_t *__cpuset)
448     __THROW __nonnull ((3));
449
450/* Get bit set in CPUSET representing the processors TH can run on.  */
451extern int pthread_getaffinity_np (pthread_t __th, size_t __cpusetsize,
452				   cpu_set_t *__cpuset)
453     __THROW __nonnull ((3));
454#endif
455
456
457/* Functions for handling initialization.  */
458
459/* Guarantee that the initialization function INIT_ROUTINE will be called
460   only once, even if pthread_once is executed several times with the
461   same ONCE_CONTROL argument. ONCE_CONTROL must point to a static or
462   extern variable initialized to PTHREAD_ONCE_INIT.
463
464   The initialization functions might throw exception which is why
465   this function is not marked with __THROW.  */
466extern int pthread_once (pthread_once_t *__once_control,
467			 void (*__init_routine) (void)) __nonnull ((1, 2));
468
469
470/* Functions for handling cancellation.
471
472   Note that these functions are explicitly not marked to not throw an
473   exception in C++ code.  If cancellation is implemented by unwinding
474   this is necessary to have the compiler generate the unwind information.  */
475
476/* Set cancelability state of current thread to STATE, returning old
477   state in *OLDSTATE if OLDSTATE is not NULL.  */
478extern int pthread_setcancelstate (int __state, int *__oldstate);
479
480/* Set cancellation state of current thread to TYPE, returning the old
481   type in *OLDTYPE if OLDTYPE is not NULL.  */
482extern int pthread_setcanceltype (int __type, int *__oldtype);
483
484/* Cancel THREAD immediately or at the next possibility.  */
485extern int pthread_cancel (pthread_t __th);
486
487/* Test for pending cancellation for the current thread and terminate
488   the thread as per pthread_exit(PTHREAD_CANCELED) if it has been
489   cancelled.  */
490extern void pthread_testcancel (void);
491
492
493/* Cancellation handling with integration into exception handling.  */
494
495typedef struct
496{
497  struct
498  {
499    __jmp_buf __cancel_jmp_buf;
500    int __mask_was_saved;
501  } __cancel_jmp_buf[1];
502  void *__pad[4];
503} __pthread_unwind_buf_t __attribute__ ((__aligned__));
504
505/* No special attributes by default.  */
506#ifndef __cleanup_fct_attribute
507# define __cleanup_fct_attribute
508#endif
509
510
511/* Structure to hold the cleanup handler information.  */
512struct __pthread_cleanup_frame
513{
514  void (*__cancel_routine) (void *);
515  void *__cancel_arg;
516  int __do_it;
517  int __cancel_type;
518};
519
520#if defined __GNUC__ && defined __EXCEPTIONS
521# ifdef __cplusplus
522/* Class to handle cancellation handler invocation.  */
523class __pthread_cleanup_class
524{
525  void (*__cancel_routine) (void *);
526  void *__cancel_arg;
527  int __do_it;
528  int __cancel_type;
529
530 public:
531  __pthread_cleanup_class (void (*__fct) (void *), void *__arg)
532    : __cancel_routine (__fct), __cancel_arg (__arg), __do_it (1) { }
533  ~__pthread_cleanup_class () { if (__do_it) __cancel_routine (__cancel_arg); }
534  void __setdoit (int __newval) { __do_it = __newval; }
535  void __defer () { pthread_setcanceltype (PTHREAD_CANCEL_DEFERRED,
536					   &__cancel_type); }
537  void __restore () const { pthread_setcanceltype (__cancel_type, 0); }
538};
539
540/* Install a cleanup handler: ROUTINE will be called with arguments ARG
541   when the thread is canceled or calls pthread_exit.  ROUTINE will also
542   be called with arguments ARG when the matching pthread_cleanup_pop
543   is executed with non-zero EXECUTE argument.
544
545   pthread_cleanup_push and pthread_cleanup_pop are macros and must always
546   be used in matching pairs at the same nesting level of braces.  */
547#  define pthread_cleanup_push(routine, arg) \
548  do {									      \
549    __pthread_cleanup_class __clframe (routine, arg)
550
551/* Remove a cleanup handler installed by the matching pthread_cleanup_push.
552   If EXECUTE is non-zero, the handler function is called. */
553#  define pthread_cleanup_pop(execute) \
554    __clframe.__setdoit (execute);					      \
555  } while (0)
556
557#  ifdef __USE_GNU
558/* Install a cleanup handler as pthread_cleanup_push does, but also
559   saves the current cancellation type and sets it to deferred
560   cancellation.  */
561#   define pthread_cleanup_push_defer_np(routine, arg) \
562  do {									      \
563    __pthread_cleanup_class __clframe (routine, arg);			      \
564    __clframe.__defer ()
565
566/* Remove a cleanup handler as pthread_cleanup_pop does, but also
567   restores the cancellation type that was in effect when the matching
568   pthread_cleanup_push_defer was called.  */
569#   define pthread_cleanup_pop_restore_np(execute) \
570    __clframe.__restore ();						      \
571    __clframe.__setdoit (execute);					      \
572  } while (0)
573#  endif
574# else
575/* Function called to call the cleanup handler.  As an extern inline
576   function the compiler is free to decide inlining the change when
577   needed or fall back on the copy which must exist somewhere
578   else.  */
579__extern_inline void
580__pthread_cleanup_routine (struct __pthread_cleanup_frame *__frame)
581{
582  if (__frame->__do_it)
583    __frame->__cancel_routine (__frame->__cancel_arg);
584}
585
586/* Install a cleanup handler: ROUTINE will be called with arguments ARG
587   when the thread is canceled or calls pthread_exit.  ROUTINE will also
588   be called with arguments ARG when the matching pthread_cleanup_pop
589   is executed with non-zero EXECUTE argument.
590
591   pthread_cleanup_push and pthread_cleanup_pop are macros and must always
592   be used in matching pairs at the same nesting level of braces.  */
593#  define pthread_cleanup_push(routine, arg) \
594  do {									      \
595    struct __pthread_cleanup_frame __clframe				      \
596      __attribute__ ((__cleanup__ (__pthread_cleanup_routine)))		      \
597      = { .__cancel_routine = (routine), .__cancel_arg = (arg),	 	      \
598	  .__do_it = 1 };
599
600/* Remove a cleanup handler installed by the matching pthread_cleanup_push.
601   If EXECUTE is non-zero, the handler function is called. */
602#  define pthread_cleanup_pop(execute) \
603    __clframe.__do_it = (execute);					      \
604  } while (0)
605
606#  ifdef __USE_GNU
607/* Install a cleanup handler as pthread_cleanup_push does, but also
608   saves the current cancellation type and sets it to deferred
609   cancellation.  */
610#   define pthread_cleanup_push_defer_np(routine, arg) \
611  do {									      \
612    struct __pthread_cleanup_frame __clframe				      \
613      __attribute__ ((__cleanup__ (__pthread_cleanup_routine)))		      \
614      = { .__cancel_routine = (routine), .__cancel_arg = (arg),		      \
615	  .__do_it = 1 };						      \
616    (void) pthread_setcanceltype (PTHREAD_CANCEL_DEFERRED,		      \
617				  &__clframe.__cancel_type)
618
619/* Remove a cleanup handler as pthread_cleanup_pop does, but also
620   restores the cancellation type that was in effect when the matching
621   pthread_cleanup_push_defer was called.  */
622#   define pthread_cleanup_pop_restore_np(execute) \
623    (void) pthread_setcanceltype (__clframe.__cancel_type, NULL);	      \
624    __clframe.__do_it = (execute);					      \
625  } while (0)
626#  endif
627# endif
628#else
629/* Install a cleanup handler: ROUTINE will be called with arguments ARG
630   when the thread is canceled or calls pthread_exit.  ROUTINE will also
631   be called with arguments ARG when the matching pthread_cleanup_pop
632   is executed with non-zero EXECUTE argument.
633
634   pthread_cleanup_push and pthread_cleanup_pop are macros and must always
635   be used in matching pairs at the same nesting level of braces.  */
636# define pthread_cleanup_push(routine, arg) \
637  do {									      \
638    __pthread_unwind_buf_t __cancel_buf;				      \
639    void (*__cancel_routine) (void *) = (routine);			      \
640    void *__cancel_arg = (arg);						      \
641    int not_first_call = __sigsetjmp ((struct __jmp_buf_tag *)		      \
642				      __cancel_buf.__cancel_jmp_buf, 0);      \
643    if (__builtin_expect (not_first_call, 0))				      \
644      {									      \
645	__cancel_routine (__cancel_arg);				      \
646	__pthread_unwind_next (&__cancel_buf);				      \
647	/* NOTREACHED */						      \
648      }									      \
649									      \
650    __pthread_register_cancel (&__cancel_buf);				      \
651    do {
652extern void __pthread_register_cancel (__pthread_unwind_buf_t *__buf)
653     __cleanup_fct_attribute;
654
655/* Remove a cleanup handler installed by the matching pthread_cleanup_push.
656   If EXECUTE is non-zero, the handler function is called. */
657# define pthread_cleanup_pop(execute) \
658    } while (0);							      \
659    __pthread_unregister_cancel (&__cancel_buf);			      \
660    if (execute)							      \
661      __cancel_routine (__cancel_arg);					      \
662  } while (0)
663extern void __pthread_unregister_cancel (__pthread_unwind_buf_t *__buf)
664  __cleanup_fct_attribute;
665
666# ifdef __USE_GNU
667/* Install a cleanup handler as pthread_cleanup_push does, but also
668   saves the current cancellation type and sets it to deferred
669   cancellation.  */
670#  define pthread_cleanup_push_defer_np(routine, arg) \
671  do {									      \
672    __pthread_unwind_buf_t __cancel_buf;				      \
673    void (*__cancel_routine) (void *) = (routine);			      \
674    void *__cancel_arg = (arg);						      \
675    int not_first_call = __sigsetjmp ((struct __jmp_buf_tag *)		      \
676				      __cancel_buf.__cancel_jmp_buf, 0);      \
677    if (__builtin_expect (not_first_call, 0))				      \
678      {									      \
679	__cancel_routine (__cancel_arg);				      \
680	__pthread_unwind_next (&__cancel_buf);				      \
681	/* NOTREACHED */						      \
682      }									      \
683									      \
684    __pthread_register_cancel_defer (&__cancel_buf);			      \
685    do {
686extern void __pthread_register_cancel_defer (__pthread_unwind_buf_t *__buf)
687     __cleanup_fct_attribute;
688
689/* Remove a cleanup handler as pthread_cleanup_pop does, but also
690   restores the cancellation type that was in effect when the matching
691   pthread_cleanup_push_defer was called.  */
692#  define pthread_cleanup_pop_restore_np(execute) \
693    } while (0);							      \
694    __pthread_unregister_cancel_restore (&__cancel_buf);		      \
695    if (execute)							      \
696      __cancel_routine (__cancel_arg);					      \
697  } while (0)
698extern void __pthread_unregister_cancel_restore (__pthread_unwind_buf_t *__buf)
699  __cleanup_fct_attribute;
700# endif
701
702/* Internal interface to initiate cleanup.  */
703extern void __pthread_unwind_next (__pthread_unwind_buf_t *__buf)
704     __cleanup_fct_attribute __attribute__ ((__noreturn__))
705# ifndef SHARED
706     __attribute__ ((__weak__))
707# endif
708     ;
709#endif
710
711/* Function used in the macros.  */
712struct __jmp_buf_tag;
713extern int __sigsetjmp (struct __jmp_buf_tag *__env, int __savemask) __THROW;
714
715
716/* Mutex handling.  */
717
718/* Initialize a mutex.  */
719extern int pthread_mutex_init (pthread_mutex_t *__mutex,
720			       __const pthread_mutexattr_t *__mutexattr)
721     __THROW __nonnull ((1));
722
723/* Destroy a mutex.  */
724extern int pthread_mutex_destroy (pthread_mutex_t *__mutex)
725     __THROW __nonnull ((1));
726
727/* Try locking a mutex.  */
728extern int pthread_mutex_trylock (pthread_mutex_t *__mutex)
729     __THROW __nonnull ((1));
730
731/* Lock a mutex.  */
732extern int pthread_mutex_lock (pthread_mutex_t *__mutex)
733     __THROW __nonnull ((1));
734
735#ifdef __USE_XOPEN2K
736/* Wait until lock becomes available, or specified time passes. */
737extern int pthread_mutex_timedlock (pthread_mutex_t *__restrict __mutex,
738                                    __const struct timespec *__restrict
739                                    __abstime) __THROW __nonnull ((1, 2));
740#endif
741
742/* Unlock a mutex.  */
743extern int pthread_mutex_unlock (pthread_mutex_t *__mutex)
744     __THROW __nonnull ((1));
745
746
747#ifdef __USE_UNIX98
748/* Get the priority ceiling of MUTEX.  */
749extern int pthread_mutex_getprioceiling (__const pthread_mutex_t *
750					 __restrict __mutex,
751					 int *__restrict __prioceiling)
752     __THROW __nonnull ((1, 2));
753
754/* Set the priority ceiling of MUTEX to PRIOCEILING, return old
755   priority ceiling value in *OLD_CEILING.  */
756extern int pthread_mutex_setprioceiling (pthread_mutex_t *__restrict __mutex,
757					 int __prioceiling,
758					 int *__restrict __old_ceiling)
759     __THROW __nonnull ((1, 3));
760#endif
761
762
763#ifdef __USE_GNU
764/* Declare the state protected by MUTEX as consistent.  */
765extern int pthread_mutex_consistent_np (pthread_mutex_t *__mutex)
766     __THROW __nonnull ((1));
767#endif
768
769
770/* Functions for handling mutex attributes.  */
771
772/* Initialize mutex attribute object ATTR with default attributes
773   (kind is PTHREAD_MUTEX_TIMED_NP).  */
774extern int pthread_mutexattr_init (pthread_mutexattr_t *__attr)
775     __THROW __nonnull ((1));
776
777/* Destroy mutex attribute object ATTR.  */
778extern int pthread_mutexattr_destroy (pthread_mutexattr_t *__attr)
779     __THROW __nonnull ((1));
780
781/* Get the process-shared flag of the mutex attribute ATTR.  */
782extern int pthread_mutexattr_getpshared (__const pthread_mutexattr_t *
783					 __restrict __attr,
784					 int *__restrict __pshared)
785     __THROW __nonnull ((1, 2));
786
787/* Set the process-shared flag of the mutex attribute ATTR.  */
788extern int pthread_mutexattr_setpshared (pthread_mutexattr_t *__attr,
789					 int __pshared)
790     __THROW __nonnull ((1));
791
792#ifdef __USE_UNIX98
793/* Return in *KIND the mutex kind attribute in *ATTR.  */
794extern int pthread_mutexattr_gettype (__const pthread_mutexattr_t *__restrict
795				      __attr, int *__restrict __kind)
796     __THROW __nonnull ((1, 2));
797
798/* Set the mutex kind attribute in *ATTR to KIND (either PTHREAD_MUTEX_NORMAL,
799   PTHREAD_MUTEX_RECURSIVE, PTHREAD_MUTEX_ERRORCHECK, or
800   PTHREAD_MUTEX_DEFAULT).  */
801extern int pthread_mutexattr_settype (pthread_mutexattr_t *__attr, int __kind)
802     __THROW __nonnull ((1));
803
804/* Return in *PROTOCOL the mutex protocol attribute in *ATTR.  */
805extern int pthread_mutexattr_getprotocol (__const pthread_mutexattr_t *
806					  __restrict __attr,
807					  int *__restrict __protocol)
808     __THROW __nonnull ((1, 2));
809
810/* Set the mutex protocol attribute in *ATTR to PROTOCOL (either
811   PTHREAD_PRIO_NONE, PTHREAD_PRIO_INHERIT, or PTHREAD_PRIO_PROTECT).  */
812extern int pthread_mutexattr_setprotocol (pthread_mutexattr_t *__attr,
813					  int __protocol)
814     __THROW __nonnull ((1));
815
816/* Return in *PRIOCEILING the mutex prioceiling attribute in *ATTR.  */
817extern int pthread_mutexattr_getprioceiling (__const pthread_mutexattr_t *
818					     __restrict __attr,
819					     int *__restrict __prioceiling)
820     __THROW __nonnull ((1, 2));
821
822/* Set the mutex prioceiling attribute in *ATTR to PRIOCEILING.  */
823extern int pthread_mutexattr_setprioceiling (pthread_mutexattr_t *__attr,
824					     int __prioceiling)
825     __THROW __nonnull ((1));
826#endif
827
828#ifdef __USE_GNU
829/* Get the robustness flag of the mutex attribute ATTR.  */
830extern int pthread_mutexattr_getrobust_np (__const pthread_mutexattr_t *__attr,
831					   int *__robustness)
832     __THROW __nonnull ((1, 2));
833
834/* Set the robustness flag of the mutex attribute ATTR.  */
835extern int pthread_mutexattr_setrobust_np (pthread_mutexattr_t *__attr,
836					   int __robustness)
837     __THROW __nonnull ((1));
838#endif
839
840
841#if defined __USE_UNIX98 || defined __USE_XOPEN2K
842/* Functions for handling read-write locks.  */
843
844/* Initialize read-write lock RWLOCK using attributes ATTR, or use
845   the default values if later is NULL.  */
846extern int pthread_rwlock_init (pthread_rwlock_t *__restrict __rwlock,
847				__const pthread_rwlockattr_t *__restrict
848				__attr) __THROW __nonnull ((1));
849
850/* Destroy read-write lock RWLOCK.  */
851extern int pthread_rwlock_destroy (pthread_rwlock_t *__rwlock)
852     __THROW __nonnull ((1));
853
854/* Acquire read lock for RWLOCK.  */
855extern int pthread_rwlock_rdlock (pthread_rwlock_t *__rwlock)
856     __THROW __nonnull ((1));
857
858/* Try to acquire read lock for RWLOCK.  */
859extern int pthread_rwlock_tryrdlock (pthread_rwlock_t *__rwlock)
860  __THROW __nonnull ((1));
861
862# ifdef __USE_XOPEN2K
863/* Try to acquire read lock for RWLOCK or return after specfied time.  */
864extern int pthread_rwlock_timedrdlock (pthread_rwlock_t *__restrict __rwlock,
865				       __const struct timespec *__restrict
866				       __abstime) __THROW __nonnull ((1, 2));
867# endif
868
869/* Acquire write lock for RWLOCK.  */
870extern int pthread_rwlock_wrlock (pthread_rwlock_t *__rwlock)
871     __THROW __nonnull ((1));
872
873/* Try to acquire write lock for RWLOCK.  */
874extern int pthread_rwlock_trywrlock (pthread_rwlock_t *__rwlock)
875     __THROW __nonnull ((1));
876
877# ifdef __USE_XOPEN2K
878/* Try to acquire write lock for RWLOCK or return after specfied time.  */
879extern int pthread_rwlock_timedwrlock (pthread_rwlock_t *__restrict __rwlock,
880				       __const struct timespec *__restrict
881				       __abstime) __THROW __nonnull ((1, 2));
882# endif
883
884/* Unlock RWLOCK.  */
885extern int pthread_rwlock_unlock (pthread_rwlock_t *__rwlock)
886     __THROW __nonnull ((1));
887
888
889/* Functions for handling read-write lock attributes.  */
890
891/* Initialize attribute object ATTR with default values.  */
892extern int pthread_rwlockattr_init (pthread_rwlockattr_t *__attr)
893     __THROW __nonnull ((1));
894
895/* Destroy attribute object ATTR.  */
896extern int pthread_rwlockattr_destroy (pthread_rwlockattr_t *__attr)
897     __THROW __nonnull ((1));
898
899/* Return current setting of process-shared attribute of ATTR in PSHARED.  */
900extern int pthread_rwlockattr_getpshared (__const pthread_rwlockattr_t *
901					  __restrict __attr,
902					  int *__restrict __pshared)
903     __THROW __nonnull ((1, 2));
904
905/* Set process-shared attribute of ATTR to PSHARED.  */
906extern int pthread_rwlockattr_setpshared (pthread_rwlockattr_t *__attr,
907					  int __pshared)
908     __THROW __nonnull ((1));
909
910/* Return current setting of reader/writer preference.  */
911extern int pthread_rwlockattr_getkind_np (__const pthread_rwlockattr_t *
912					  __restrict __attr,
913					  int *__restrict __pref)
914     __THROW __nonnull ((1, 2));
915
916/* Set reader/write preference.  */
917extern int pthread_rwlockattr_setkind_np (pthread_rwlockattr_t *__attr,
918					  int __pref) __THROW __nonnull ((1));
919#endif
920
921
922/* Functions for handling conditional variables.  */
923
924/* Initialize condition variable COND using attributes ATTR, or use
925   the default values if later is NULL.  */
926extern int pthread_cond_init (pthread_cond_t *__restrict __cond,
927			      __const pthread_condattr_t *__restrict
928			      __cond_attr) __THROW __nonnull ((1));
929
930/* Destroy condition variable COND.  */
931extern int pthread_cond_destroy (pthread_cond_t *__cond)
932     __THROW __nonnull ((1));
933
934/* Wake up one thread waiting for condition variable COND.  */
935extern int pthread_cond_signal (pthread_cond_t *__cond)
936     __THROW __nonnull ((1));
937
938/* Wake up all threads waiting for condition variables COND.  */
939extern int pthread_cond_broadcast (pthread_cond_t *__cond)
940     __THROW __nonnull ((1));
941
942/* Wait for condition variable COND to be signaled or broadcast.
943   MUTEX is assumed to be locked before.
944
945   This function is a cancellation point and therefore not marked with
946   __THROW.  */
947extern int pthread_cond_wait (pthread_cond_t *__restrict __cond,
948			      pthread_mutex_t *__restrict __mutex)
949     __nonnull ((1, 2));
950
951/* Wait for condition variable COND to be signaled or broadcast until
952   ABSTIME.  MUTEX is assumed to be locked before.  ABSTIME is an
953   absolute time specification; zero is the beginning of the epoch
954   (00:00:00 GMT, January 1, 1970).
955
956   This function is a cancellation point and therefore not marked with
957   __THROW.  */
958extern int pthread_cond_timedwait (pthread_cond_t *__restrict __cond,
959				   pthread_mutex_t *__restrict __mutex,
960				   __const struct timespec *__restrict
961				   __abstime) __nonnull ((1, 2, 3));
962
963/* Functions for handling condition variable attributes.  */
964
965/* Initialize condition variable attribute ATTR.  */
966extern int pthread_condattr_init (pthread_condattr_t *__attr)
967     __THROW __nonnull ((1));
968
969/* Destroy condition variable attribute ATTR.  */
970extern int pthread_condattr_destroy (pthread_condattr_t *__attr)
971     __THROW __nonnull ((1));
972
973/* Get the process-shared flag of the condition variable attribute ATTR.  */
974extern int pthread_condattr_getpshared (__const pthread_condattr_t *
975                                        __restrict __attr,
976                                        int *__restrict __pshared)
977     __THROW __nonnull ((1, 2));
978
979/* Set the process-shared flag of the condition variable attribute ATTR.  */
980extern int pthread_condattr_setpshared (pthread_condattr_t *__attr,
981                                        int __pshared) __THROW __nonnull ((1));
982
983#ifdef __USE_XOPEN2K
984/* Get the clock selected for the conditon variable attribute ATTR.  */
985extern int pthread_condattr_getclock (__const pthread_condattr_t *
986				      __restrict __attr,
987				      __clockid_t *__restrict __clock_id)
988     __THROW __nonnull ((1, 2));
989
990/* Set the clock selected for the conditon variable attribute ATTR.  */
991extern int pthread_condattr_setclock (pthread_condattr_t *__attr,
992				      __clockid_t __clock_id)
993     __THROW __nonnull ((1));
994#endif
995
996
997#ifdef __USE_XOPEN2K
998/* Functions to handle spinlocks.  */
999
1000/* Initialize the spinlock LOCK.  If PSHARED is nonzero the spinlock can
1001   be shared between different processes.  */
1002extern int pthread_spin_init (pthread_spinlock_t *__lock, int __pshared)
1003     __THROW __nonnull ((1));
1004
1005/* Destroy the spinlock LOCK.  */
1006extern int pthread_spin_destroy (pthread_spinlock_t *__lock)
1007     __THROW __nonnull ((1));
1008
1009/* Wait until spinlock LOCK is retrieved.  */
1010extern int pthread_spin_lock (pthread_spinlock_t *__lock)
1011     __THROW __nonnull ((1));
1012
1013/* Try to lock spinlock LOCK.  */
1014extern int pthread_spin_trylock (pthread_spinlock_t *__lock)
1015     __THROW __nonnull ((1));
1016
1017/* Release spinlock LOCK.  */
1018extern int pthread_spin_unlock (pthread_spinlock_t *__lock)
1019     __THROW __nonnull ((1));
1020
1021
1022/* Functions to handle barriers.  */
1023
1024/* Initialize BARRIER with the attributes in ATTR.  The barrier is
1025   opened when COUNT waiters arrived.  */
1026extern int pthread_barrier_init (pthread_barrier_t *__restrict __barrier,
1027				 __const pthread_barrierattr_t *__restrict
1028				 __attr, unsigned int __count)
1029     __THROW __nonnull ((1));
1030
1031/* Destroy a previously dynamically initialized barrier BARRIER.  */
1032extern int pthread_barrier_destroy (pthread_barrier_t *__barrier)
1033     __THROW __nonnull ((1));
1034
1035/* Wait on barrier BARRIER.  */
1036extern int pthread_barrier_wait (pthread_barrier_t *__barrier)
1037     __THROW __nonnull ((1));
1038
1039
1040/* Initialize barrier attribute ATTR.  */
1041extern int pthread_barrierattr_init (pthread_barrierattr_t *__attr)
1042     __THROW __nonnull ((1));
1043
1044/* Destroy previously dynamically initialized barrier attribute ATTR.  */
1045extern int pthread_barrierattr_destroy (pthread_barrierattr_t *__attr)
1046     __THROW __nonnull ((1));
1047
1048/* Get the process-shared flag of the barrier attribute ATTR.  */
1049extern int pthread_barrierattr_getpshared (__const pthread_barrierattr_t *
1050					   __restrict __attr,
1051					   int *__restrict __pshared)
1052     __THROW __nonnull ((1, 2));
1053
1054/* Set the process-shared flag of the barrier attribute ATTR.  */
1055extern int pthread_barrierattr_setpshared (pthread_barrierattr_t *__attr,
1056                                           int __pshared)
1057     __THROW __nonnull ((1));
1058#endif
1059
1060
1061/* Functions for handling thread-specific data.  */
1062
1063/* Create a key value identifying a location in the thread-specific
1064   data area.  Each thread maintains a distinct thread-specific data
1065   area.  DESTR_FUNCTION, if non-NULL, is called with the value
1066   associated to that key when the key is destroyed.
1067   DESTR_FUNCTION is not called if the value associated is NULL when
1068   the key is destroyed.  */
1069extern int pthread_key_create (pthread_key_t *__key,
1070			       void (*__destr_function) (void *))
1071     __THROW __nonnull ((1));
1072
1073/* Destroy KEY.  */
1074extern int pthread_key_delete (pthread_key_t __key) __THROW;
1075
1076/* Return current value of the thread-specific data slot identified by KEY.  */
1077extern void *pthread_getspecific (pthread_key_t __key) __THROW;
1078
1079/* Store POINTER in the thread-specific data slot identified by KEY. */
1080extern int pthread_setspecific (pthread_key_t __key,
1081				__const void *__pointer) __THROW ;
1082
1083
1084#ifdef __USE_XOPEN2K
1085/* Get ID of CPU-time clock for thread THREAD_ID.  */
1086extern int pthread_getcpuclockid (pthread_t __thread_id,
1087				  __clockid_t *__clock_id)
1088     __THROW __nonnull ((2));
1089#endif
1090
1091
1092/* Install handlers to be called when a new process is created with FORK.
1093   The PREPARE handler is called in the parent process just before performing
1094   FORK. The PARENT handler is called in the parent process just after FORK.
1095   The CHILD handler is called in the child process.  Each of the three
1096   handlers can be NULL, meaning that no handler needs to be called at that
1097   point.
1098   PTHREAD_ATFORK can be called several times, in which case the PREPARE
1099   handlers are called in LIFO order (last added with PTHREAD_ATFORK,
1100   first called before FORK), and the PARENT and CHILD handlers are called
1101   in FIFO (first added, first called).  */
1102
1103extern int pthread_atfork (void (*__prepare) (void),
1104			   void (*__parent) (void),
1105			   void (*__child) (void)) __THROW;
1106
1107
1108#ifdef __USE_EXTERN_INLINES
1109/* Optimizations.  */
1110__extern_inline int
1111__NTH (pthread_equal (pthread_t __thread1, pthread_t __thread2))
1112{
1113  return __thread1 == __thread2;
1114}
1115#endif
1116
1117__END_DECLS
1118
1119#endif	/* pthread.h */
1120