.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "SEM_INIT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" sem_init 
.SH NAME
sem_init \- initialize an unnamed semaphore (\fBREALTIME\fP)
.SH SYNOPSIS
.LP
\fB#include <semaphore.h>
.br
.sp
int sem_init(sem_t *\fP\fIsem\fP\fB, int\fP \fIpshared\fP\fB, unsigned\fP
\fIvalue\fP\fB); \fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
The \fIsem_init\fP() function shall initialize the unnamed semaphore
referred to by \fIsem\fP. The value of the initialized
semaphore shall be \fIvalue\fP. Following a successful call to \fIsem_init\fP(),
the semaphore may be used in subsequent calls to
\fIsem_wait\fP(), \fIsem_trywait\fP(), \fIsem_post\fP(), and \fIsem_destroy\fP().
This
semaphore shall remain usable until the semaphore is destroyed.
.LP
If the \fIpshared\fP argument has a non-zero value, then the semaphore
is shared between processes; in this case, any process
that can access the semaphore \fIsem\fP can use \fIsem\fP for performing
\fIsem_wait\fP(), \fIsem_trywait\fP(), \fIsem_post\fP(), and \fIsem_destroy\fP()
operations.
.LP
Only \fIsem\fP itself may be used for performing synchronization.
The result of referring to copies of \fIsem\fP in calls to
\fIsem_wait\fP(), \fIsem_trywait\fP(), \fIsem_post\fP(), and \fIsem_destroy\fP()
is
undefined.
.LP
If the \fIpshared\fP argument is zero, then the semaphore is shared
between threads of the process; any thread in this process
can use \fIsem\fP for performing \fIsem_wait\fP(), \fIsem_trywait\fP(),
\fIsem_post\fP(), and \fIsem_destroy\fP() operations. The use of the
semaphore by threads other than those created
in the same process is undefined.
.LP
Attempting to initialize an already initialized semaphore results
in undefined behavior.
.SH RETURN VALUE
.LP
Upon successful completion, the \fIsem_init\fP() function shall initialize
the semaphore in \fIsem\fP. Otherwise, it shall
return -1 and set \fIerrno\fP to indicate the error.
.SH ERRORS
.LP
The \fIsem_init\fP() function shall fail if:
.TP 7
.B EINVAL
The \fIvalue\fP argument exceeds {SEM_VALUE_MAX}.
.TP 7
.B ENOSPC
A resource required to initialize the semaphore has been exhausted,
or the limit on semaphores ( {SEM_NSEMS_MAX}) has been
reached.
.TP 7
.B EPERM
The process lacks the appropriate privileges to initialize the semaphore.
.sp
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
The \fIsem_init\fP() function is part of the Semaphores option and
need not be available on all implementations.
.SH RATIONALE
.LP
Although this volume of IEEE\ Std\ 1003.1-2001 fails to specify a
successful return value, it is likely that a later
version may require the implementation to return a value of zero if
the call to \fIsem_init\fP() is successful.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIsem_destroy\fP() , \fIsem_post\fP() , \fIsem_timedwait\fP() , \fIsem_trywait\fP()
, \fIsem_wait\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
\fI<semaphore.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .