linuxthreads/man/sem_init.man

   1 .TH SEMAPHORES 3 LinuxThreads
   2
   3 .XREF sem_wait
   4 .XREF sem_trywait
   5 .XREF sem_post
   6 .XREF sem_getvalue
   7 .XREF sem_destroy
   8
   9 .SH NAME
  10 sem_init, sem_wait, sem_trywait, sem_post, sem_getvalue, sem_destroy \- operations on semaphores
  11
  12 .SH SYNOPSIS
  13 #include <semaphore.h>
  14
  15 int sem_init(sem_t *sem, int pshared, unsigned int value);
  16
  17 int sem_wait(sem_t * sem);
  18
  19 int sem_trywait(sem_t * sem);
  20
  21 int sem_post(sem_t * sem);
  22
  23 int sem_getvalue(sem_t * sem, int * sval);
  24
  25 int sem_destroy(sem_t * sem);
  26
  27 .SH DESCRIPTION
  28 This manual page documents POSIX 1003.1b semaphores, not to be
  29 confused with SystemV semaphores as described in !ipc!(5), !semctl!(2)
  30 and !semop!(2).
  31
  32 Semaphores are counters for resources shared between threads. The
  33 basic operations on semaphores are: increment the counter atomically,
  34 and wait until the counter is non-null and decrement it atomically.
  35
  36 !sem_init! initializes the semaphore object pointed to by |sem|. The
  37 count associated with the semaphore is set initially to |value|. The
  38 |pshared| argument indicates whether the semaphore is local to the
  39 current process (|pshared| is zero) or is to be shared between several
  40 processes (|pshared| is not zero). LinuxThreads currently does not
  41 support process-shared semaphores, thus !sem_init! always returns with
  42 error !ENOSYS! if |pshared| is not zero.
  43
  44 !sem_wait! suspends the calling thread until the semaphore pointed to
  45 by |sem| has non-zero count. It then atomically decreases the
  46 semaphore count.
  47
  48 !sem_trywait! is a non-blocking variant of !sem_wait!. If the
  49 semaphore pointed to by |sem| has non-zero count, the count is
  50 atomically decreased and !sem_trywait! immediately returns 0.
  51 If the semaphore count is zero, !sem_trywait! immediately returns with
  52 error !EAGAIN!.
  53
  54 !sem_post! atomically increases the count of the semaphore pointed to
  55 by |sem|. This function never blocks and can safely be used in
  56 asynchronous signal handlers.
  57
  58 !sem_getvalue! stores in the location pointed to by |sval| the current
  59 count of the semaphore |sem|.
  60
  61 !sem_destroy! destroys a semaphore object, freeing the resources it
  62 might hold. No threads should be waiting on the semaphore at the time
  63 !sem_destroy! is called. In the LinuxThreads implementation, no
  64 resources are associated with semaphore objects, thus !sem_destroy!
  65 actually does nothing except checking that no thread is waiting on the
  66 semaphore.
  67
  68 .SH CANCELLATION
  69
  70 !sem_wait! is a cancellation point.
  71
  72 .SH "ASYNC-SIGNAL SAFETY"
  73
  74 On processors supporting atomic compare-and-swap (Intel 486, Pentium
  75 and later, Alpha, PowerPC, MIPS II, Motorola 68k), the !sem_post!
  76 function is async-signal safe and can therefore be
  77 called from signal handlers. This is the only thread synchronization
  78 function provided by POSIX threads that is async-signal safe.
  79
  80 On the Intel 386 and the Sparc, the current LinuxThreads
  81 implementation of !sem_post! is not async-signal safe by lack of the
  82 required atomic operations.
  83
  84 .SH "RETURN VALUE"
  85
  86 The !sem_wait! and !sem_getvalue! functions always return 0.
  87 All other semaphore functions return 0 on success and -1 on error, in
  88 addition to writing an error code in !errno!.
  89
  90 .SH ERRORS
  91
  92 The !sem_init! function sets !errno! to the following codes on error:
  93 .RS
  94 .TP
  95 !EINVAL!
  96 |value| exceeds the maximal counter value !SEM_VALUE_MAX!
  97 .TP
  98 !ENOSYS!
  99 |pshared| is not zero
 100 .RE
 101
 102 The !sem_trywait! function sets !errno! to the following error code on error:
 103 .RS
 104 .TP
 105 !EAGAIN!
 106 the semaphore count is currently 0
 107 .RE
 108
 109 The !sem_post! function sets !errno! to the following error code on error:
 110 .RS
 111 .TP
 112 !ERANGE!
 113 after incrementation, the semaphore value would exceed !SEM_VALUE_MAX!
 114 (the semaphore count is left unchanged in this case)
 115 .RE
 116
 117 The !sem_destroy! function sets !errno! to the following error code on error:
 118 .RS
 119 .TP
 120 !EBUSY!
 121 some threads are currently blocked waiting on the semaphore.
 122 .RE
 123
 124 .SH AUTHOR
 125 Xavier Leroy <Xavier.Leroy@inria.fr>
 126
 127 .SH "SEE ALSO"
 128 !pthread_mutex_init!(3),
 129 !pthread_cond_init!(3),
 130 !pthread_cancel!(3),
 131 !ipc!(5).
 132