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 36The semaphore referenced by 37.Fa sem 38is locked. When calling 39.Fn sem_wait , 40if the semaphore's value is zero, the calling thread will block until 41the lock is acquired or until the call is interrupted by a 42signal. Alternatively, the 43.Fn sem_trywait 44function will fail if the semaphore is already locked, rather than 45blocking on the semaphore. 46.Pp 47If successful (the lock was acquired), 48.Fn sem_wait 49and 50.Fn sem_trywait 51will return 0. Otherwise, -1 is returned and 52.Va errno 53is set, and the state of the semaphore is unchanged. 54.Sh ERRORS 55.Fn sem_wait 56and 57.Fn sem_trywait 58succeed unless: 59.Bl -tag -width Er 60.It Bq Er EAGAIN 61The semaphore is already locked. 62.It Bq Er EDEADLK 63A deadlock was detected. 64.It Bq Er EINTR 65The call was interrupted by a signal. 66.It Bq Er EINVAL 67.Fa sem 68is not a valid semaphore descriptor. 69.El 70.Sh NOTES 71Applications may encounter a priority inversion while using 72semaphores. When a thread is waiting on a semaphore which is about to 73be posted by a lower-priority thread and the lower-priority thread is 74preempted by another thread (of medium priority), a priority inversion 75has occured, and the higher-priority thread will be blocked for an 76unlimited time period. Programmers using the realtime functionality 77of 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 86and 87.Fn sem_trywait 88are specified in the POSIX Realtime Extension (1003.1b-1993/1003.1i-1995). 89