man3p/sem_wait.3p

   1 .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
   2 .TH "SEM_TRYWAIT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
   3 .\" sem_trywait
   4 .SH NAME
   5 sem_trywait, sem_wait \- lock a semaphore (\fBREALTIME\fP)
   6 .SH SYNOPSIS
   7 .LP
   8 \fB#include <semaphore.h>
   9 .br
  10 .sp
  11 int sem_trywait(sem_t *\fP\fIsem\fP\fB);
  12 .br
  13 int sem_wait(sem_t *\fP\fIsem\fP\fB); \fP
  14 \fB
  15 .br
  16 \fP
  17 .SH DESCRIPTION
  18 .LP
  19 The \fIsem_trywait\fP() function shall lock the semaphore referenced
  20 by \fIsem\fP only if the semaphore is currently not
  21 locked; that is, if the semaphore value is currently positive. Otherwise,
  22 it shall not lock the semaphore.
  23 .LP
  24 The \fIsem_wait\fP() function shall lock the semaphore referenced
  25 by \fIsem\fP by performing a semaphore lock operation on
  26 that semaphore. If the semaphore value is currently zero, then the
  27 calling thread shall not return from the call to
  28 \fIsem_wait\fP() until it either locks the semaphore or the call is
  29 interrupted by a signal.
  30 .LP
  31 Upon successful return, the state of the semaphore shall be locked
  32 and shall remain locked until the \fIsem_post\fP() function is executed
  33 and returns successfully.
  34 .LP
  35 The \fIsem_wait\fP() function is interruptible by the delivery of
  36 a signal.
  37 .SH RETURN VALUE
  38 .LP
  39 The \fIsem_trywait\fP() and \fIsem_wait\fP() functions shall return
  40 zero if the calling process successfully performed the
  41 semaphore lock operation on the semaphore designated by \fIsem\fP.
  42 If the call was unsuccessful, the state of the semaphore shall
  43 be unchanged, and the function shall return a value of -1 and set
  44 \fIerrno\fP to indicate the error.
  45 .SH ERRORS
  46 .LP
  47 The \fIsem_trywait\fP() and \fIsem_wait\fP() functions shall fail
  48 if:
  49 .TP 7
  50 .B EAGAIN
  51 The semaphore was already locked, so it cannot be immediately locked
  52 by the \fIsem_trywait\fP() operation (
  53 \fIsem_trywait\fP() only).
  54 .TP 7
  55 .B EINVAL
  56 The \fIsem\fP argument does not refer to a valid semaphore.
  57 .sp
  58 .LP
  59 The \fIsem_trywait\fP() and \fIsem_wait\fP() functions may fail if:
  60 .TP 7
  61 .B EDEADLK
  62 A deadlock condition was detected.
  63 .TP 7
  64 .B EINTR
  65 A signal interrupted this function.
  66 .sp
  67 .LP
  68 \fIThe following sections are informative.\fP
  69 .SH EXAMPLES
  70 .LP
  71 None.
  72 .SH APPLICATION USAGE
  73 .LP
  74 Applications using these functions may be subject to priority inversion,
  75 as discussed in the Base Definitions volume of
  76 IEEE\ Std\ 1003.1-2001, Section 3.285, Priority Inversion.
  77 .LP
  78 The \fIsem_trywait\fP() and \fIsem_wait\fP() functions are part of
  79 the Semaphores option and need not be provided on all
  80 implementations.
  81 .SH RATIONALE
  82 .LP
  83 None.
  84 .SH FUTURE DIRECTIONS
  85 .LP
  86 None.
  87 .SH SEE ALSO
  88 .LP
  89 \fIsemctl\fP() , \fIsemget\fP() , \fIsemop\fP()
  90 , \fIsem_post\fP() , \fIsem_timedwait\fP() , the Base Definitions
  91 volume of IEEE\ Std\ 1003.1-2001, \fI<semaphore.h>\fP
  92 .SH COPYRIGHT
  93 Portions of this text are reprinted and reproduced in electronic form
  94 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
  95 -- Portable Operating System Interface (POSIX), The Open Group Base
  96 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
  97 Electrical and Electronics Engineers, Inc and The Open Group. In the
  98 event of any discrepancy between this version and the original IEEE and
  99 The Open Group Standard, the original IEEE and The Open Group Standard
 100 is the referee document. The original Standard can be obtained online at
 101 http://www.opengroup.org/unix/online.html .