[apple/libc.git] / sys / sem_wait.2

.\"	$Darwin$
.\"
.\" Copyright (c) 2000-2002 Apple Computer, Inc. All rights reserved.
.\"
.\" @APPLE_LICENSE_HEADER_START@
.\" 
.\" The contents of this file constitute Original Code as defined in and
.\" are subject to the Apple Public Source License Version 1.1 (the
.\" "License").  You may not use this file except in compliance with the
.\" License.  Please obtain a copy of the License at
.\" http://www.apple.com/publicsource and read it before using this file.
.\" 
.\" This Original Code and all software distributed under the License are
.\" distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
.\" FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
.\" License for the specific language governing rights and limitations
.\" under the License.
.\" 
.\" @APPLE_LICENSE_HEADER_END@
.\"
.Dd June 8, 2000
.Dt SEM_WAIT 2
.Os Darwin
.Sh NAME
.Nm sem_trywait, sem_wait
.Nd lock a semaphore
.Sh SYNOPSIS
.Fd #include <semaphore.h>
.Ft int
.Fn sem_trywait "sem_t *sem"
.Ft int
.Fn sem_wait    "sem_t *sem"
.Sh DESCRIPTION
The semaphore referenced by
.Fa sem
is locked.  When calling
.Fn sem_wait ,
if the semaphore's value is zero, the calling thread will block until
the lock is acquired or until the call is interrupted by a
signal. Alternatively, the
.Fn sem_trywait
function will fail if the semaphore is already locked, rather than
blocking on the semaphore.
.Pp
If successful (the lock was acquired),
.Fn sem_wait
and
.Fn sem_trywait
will return 0.  Otherwise, -1 is returned and
.Va errno
is set, and the state of the semaphore is unchanged.
.Sh ERRORS
.Fn sem_wait
and
.Fn sem_trywait
succeed unless:
.Bl -tag -width Er
.It Bq Er EAGAIN
The semaphore is already locked.
.It Bq Er EDEADLK
A deadlock was detected.
.It Bq Er EINTR
The call was interrupted by a signal.
.It Bq Er EINVAL
.Fa sem
is not a valid semaphore descriptor.
.El
.Sh NOTES
Applications may encounter a priority inversion while using
semaphores.  When a thread is waiting on a semaphore which is about to
be posted by a lower-priority thread and the lower-priority thread is
preempted by another thread (of medium priority), a priority inversion
has occured, and the higher-priority thread will be blocked for an
unlimited time period.  Programmers using the realtime functionality
of the system should take care to avoid priority inversions.
.Sh SEE ALSO
.Xr sem_open 2 ,
.Xr sem_post 2 ,
.Xr semctl 2 ,
.Xr semget 2 ,
.Xr semop 2
.Sh HISTORY
.Fn sem_wait
and
.Fn sem_trywait
are specified in the POSIX Realtime Extension (1003.1b-1993/1003.1i-1995).
Commit	Line	Data
e9ce8d39 A	1	.\" $Darwin$
e9ce8d39 A	2	.\"
5b2abdfb	3	.\" Copyright (c) 2000-2002 Apple Computer, Inc. All rights reserved.
e9ce8d39 A	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
224c7076	27	.Nm sem_trywait, sem_wait
e9ce8d39 A	28	.Nd lock a semaphore
	29	.Sh SYNOPSIS
	30	.Fd #include <semaphore.h>
	31	.Ft int
e9ce8d39	32	.Fn sem_trywait "sem_t *sem"
224c7076 A	33	.Ft int
224c7076 A	34	.Fn sem_wait "sem_t *sem"
e9ce8d39 A	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
224c7076	41	the lock is acquired or until the call is interrupted by a
e9ce8d39 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
224c7076	47	If successful (the lock was acquired),
e9ce8d39 A	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.
e9ce8d39 A	62	.It Bq Er EDEADLK
	63	A deadlock was detected.
	64	.It Bq Er EINTR
	65	The call was interrupted by a signal.
224c7076 A	66	.It Bq Er EINVAL
	67	.Fa sem
	68	is not a valid semaphore descriptor.
e9ce8d39 A	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
224c7076 A	79	.Xr sem_open 2 ,
224c7076 A	80	.Xr sem_post 2 ,
e9ce8d39 A	81	.Xr semctl 2 ,
e9ce8d39 A	82	.Xr semget 2 ,
224c7076	83	.Xr semop 2
e9ce8d39 A	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).