'\" te
.\"  Copyright (c) 1997, Sun Microsystems, Inc.  All Rights Reserved
.TH _lwp_sema_wait 2 "8 May 1998" "SunOS 5.11" "System Calls"
.SH NAME
_lwp_sema_wait, _lwp_sema_trywait, _lwp_sema_init, _lwp_sema_post \- semaphore operations
.SH SYNOPSIS
.LP
.nf
#include <sys/lwp.h>

\fBint\fR \fB_lwp_sema_wait\fR(\fBlwp_sema_t *\fR\fIsema\fR);
.fi

.LP
.nf
\fBint\fR \fB_lwp_sema_trywait\fR(\fBlwp_sema_t *\fR\fIsema\fR);
.fi

.LP
.nf
\fBint\fR \fB_lwp_sema_init\fR(\fBlwp_sema_t *\fR\fIsema\fR, \fBint\fR \fIcount\fR);
.fi

.LP
.nf
\fBint\fR \fB_lwp_sema_post\fR(\fBlwp_sema_t *\fR\fIsema\fR);
.fi

.SH DESCRIPTION
.sp
.LP
Conceptually, a semaphore is an non-negative integer count that is atomically incremented and decremented. Typically this represents the number of resources available. The \fB_lwp_sema_init()\fR function initializes the count, \fB_lwp_sema_post()\fR atomically increments the count, and \fB_lwp_sema_wait()\fR waits for the count to become greater than 0 and then atomically decrements it.
.sp
.LP
LWP semaphores must be initialized before use.  The \fB_lwp_sema_init()\fR function initializes the count associated with the LWP semaphore pointed to by \fIsema\fR to \fIcount\fR.
.sp
.LP
The \fB_lwp_sema_wait()\fR function blocks the calling LWP until the semaphore count becomes greater than 0 and then atomically decrements it.
.sp
.LP
The \fB_lwp_sema_trywait()\fR function atomically decrements the count if it is greater than zero. Otherwise it returns an error.
.sp
.LP
The \fB_lwp_sema_post()\fR function atomically increments the semaphore count. If there are any LWPs blocked on the semaphore, one is unblocked.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fB0\fR is returned. A non-zero value indicates an error.
.SH ERRORS
.sp
.LP
The \fB_lwp_sema_init()\fR, \fB_lwp_sema_trywait()\fR, \fB_lwp_sema_wait()\fR, and \fB_lwp_sema_post()\fR functions will fail if:
.sp
.ne 2
.mk
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
.rt  
The \fIsema\fR argument points to an invalid semaphore.
.RE

.sp
.ne 2
.mk
.na
\fB\fBEFAULT\fR\fR
.ad
.RS 10n
.rt  
The \fIsema\fR argument points to an illegal address.
.RE

.sp
.LP
The  \fB_lwp_sema_wait()\fR function will fail if:
.sp
.ne 2
.mk
.na
\fB\fBEINTR\fR\fR
.ad
.RS 9n
.rt  
The function execution was interrupted by a signal or \fBfork\fR(2).
.RE

.sp
.LP
The  \fB_lwp_sema_trywait()\fR function will fail if:
.sp
.ne 2
.mk
.na
\fB\fBEBUSY\fR\fR
.ad
.RS 9n
.rt  
The function was called on a semaphore with a zero count.
.RE

.sp
.LP
The  \fB_lwp_sema_post()\fR function will fail if:
.sp
.ne 2
.mk
.na
\fB\fBEOVERFLOW\fR\fR
.ad
.RS 13n
.rt  
The value of the \fIsema\fR argument exceeds \fBSEM_VALUE_MAX\fR.
.RE

.SH SEE ALSO
.sp
.LP
\fBfork\fR(2)