sys.subproj/sem_wait.2

   1 .\"     $Darwin$
   2 .\"
   3 .\" Wilfredo Sanchez, wsanchez@apple.com
   4 .\" Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
   5 .\"
   6 .\" @APPLE_LICENSE_HEADER_START@
   7 .\"
   8 .\" The contents of this file constitute Original Code as defined in and
   9 .\" are subject to the Apple Public Source License Version 1.1 (the
  10 .\" "License").  You may not use this file except in compliance with the
  11 .\" License.  Please obtain a copy of the License at
  12 .\" http://www.apple.com/publicsource and read it before using this file.
  13 .\"
  14 .\" This Original Code and all software distributed under the License are
  15 .\" distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  16 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  17 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  18 .\" FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  19 .\" License for the specific language governing rights and limitations
  20 .\" under the License.
  21 .\"
  22 .\" @APPLE_LICENSE_HEADER_END@
  23 .\"
  24 .Dd June 8, 2000
  25 .Dt SEM_WAIT 2
  26 .Os Darwin
  27 .Sh NAME
  28 .Nm sem_wait, sem_trywait
  29 .Nd lock a semaphore
  30 .Sh SYNOPSIS
  31 .Fd #include <semaphore.h>
  32 .Ft int
  33 .Fn sem_wait "sem_t *sem"
  34 .Ft int
  35 .Fn sem_trywait "sem_t *sem"
  36 .Sh DESCRIPTION
  37 The semaphore referenced by
  38 .Fa sem
  39 is locked.  When calling
  40 .Fn sem_wait ,
  41 if the semaphore's value is zero, the calling thread will block until
  42 the lock is aquired or until the call is interrupted by a
  43 signal. Alternatively, the
  44 .Fn sem_trywait
  45 function will fail if the semaphore is already locked, rather than
  46 blocking on the semaphore.
  47 .Pp
  48 If successful (the lock was aquired),
  49 .Fn sem_wait
  50 and
  51 .Fn sem_trywait
  52 will return 0.  Otherwise, -1 is returned and
  53 .Va errno
  54 is set, and the state of the semaphore is unchanged.
  55 .Sh ERRORS
  56 .Fn sem_wait
  57 and
  58 .Fn sem_trywait
  59 succeed unless:
  60 .Bl -tag -width Er
  61 .It Bq Er EAGAIN
  62 The semaphore is already locked.
  63 .It Bq Er EINVAL
  64 .Fa sem
  65 is not a valid semaphore descriptor.
  66 .It Bq Er EDEADLK
  67 A deadlock was detected.
  68 .It Bq Er EINTR
  69 The call was interrupted by a signal.
  70 .El
  71 .Sh NOTES
  72 Applications may encounter a priority inversion while using
  73 semaphores.  When a thread is waiting on a semaphore which is about to
  74 be posted by a lower-priority thread and the lower-priority thread is
  75 preempted by another thread (of medium priority), a priority inversion
  76 has occured, and the higher-priority thread will be blocked for an
  77 unlimited time period.  Programmers using the realtime functionality
  78 of the system should take care to avoid priority inversions.
  79 .Sh SEE ALSO
  80 .Xr semctl 2 ,
  81 .Xr semget 2 ,
  82 .Xr semop 2 ,
  83 .Xr sem_open 2 ,
  84 .Xr sem_post 2
  85 .Sh HISTORY
  86 .Fn sem_wait
  87 and
  88 .Fn sem_trywait
  89 are specified in the POSIX Realtime Extension (1003.1b-1993/1003.1i-1995).