bsd/man/man2/sem_wait.2

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