NAME
sem_init — initialize an unnamed POSIX semaphore
SYNOPSIS
#include <sys/semaphore.h>
int sem_init(sem_t *sem, int pshared, unsigned int value);
DESCRIPTION
sem_init()
is used to initialize an unnamed semaphore. A successful call to
sem_init()
will create a new unnamed semaphore referred to by
sem,
if one does not exist,
initialize the unnamed semaphore descriptor, referred to by
sem,
to the non-negative value specified by
value.
If the unnamed semaphore
already exists, i.e. created by a previous call to
sem_init(),
it is
re-initialized only if its current value is
equal to its initial value (set by the last successful call to
sem_init()).
If so, the initial value of the
unnamed semaphore is re-initialized to the value argument. Otherwise,
the call fails.
The argument
pshared
specifies if the unnamed semaphore is sharable
with other processes. If
pshared
is equal to 0, the unnamed semaphore is not shared with other processes.
If
pshared
is non-zero, the
unnamed semaphore is sharable with any processes that can access
sem.
The access mode specified for the unnamed semaphore allows read and
write permissions to all processes.
If the calling process may attach to the shared
sem_t
structure,
it is assumed it may operate on the semaphore.
To use this function, link in the realtime library by specifying
-lrt
on the compiler or linker command line.
EXAMPLES
The following call to
sem_init()
will create a new unnamed semaphore referred to by
sem,
if one does not exist,
initialize the unnamed semaphore descriptor, referred to by
sem,
to the non-negative value specified by
value.
sem_init(sem, pshared, value);
RETURN VALUE
If the semaphore was created and initialized,
sem_init()
returns 0 to the caller.
If the semaphore could not be created/initialized, the call returns -1 and sets
errno
to indicate the error.
ERRORS
sem_init()
fails and does not perform the requested operation
if any of the following conditions are encountered:
- [EPERM]
The calling process does not have the privileges necessary to initialize the
semaphore.
- [EBUSY]
There are threads currently blocked on the semaphore or
there are outstanding locks held on the semaphore.
- [EINVAL]
The argument
value
is greater than
{_POSIX_SEM_VALUE_MAX}.
- [ENOSPC]
There are insufficient resources to perform the operation or
the upper limit on the number of semaphores is reached.
STANDARDS CONFORMANCE
sem_init(): POSIX
Printable version
