USNEWSEMA(3P)USNEWSEMA(3P)NAMEusnewsema - allocate and initialize a semaphore
C SYNOPSIS
#include <ulocks.h>
usema_t *usnewsema (usptr_t *handle, int val);
DESCRIPTIONusnewsema allocates a semaphore and initializes its count to the value
specified by val. Initially, metering and debugging are off (and can be
turned on through a call to usctlsema(3P)) and the history logging
mechanism is set according to the global setting (see usconfig(3P)). The
semaphore is allocated from the shared arena designated by handle as
returned from usinit(3P). A semaphore allocated via usnewsema is a
blocking semaphore - if the semaphore is unavailable, the caller will
block. A pollable semaphore may be allocated via usnewpollsema(3P).
A val of 0 implies no available resources, and the first process that
attempts a 'P' operation (via uspsema(3P)) will block. This can be
viewed as a synchronizing semaphore, since the goal is to always have a
process block until another has completed an operation that the first
process requires. Positive values for val can be used for tracking a
collection of resources. The simplest case of a value of 1 implements
the common mutual exclusion semaphore, where one and only one process
will be permitted through a semaphore at a time. Values greater than one
imply that up to val resources may be simultaneously used, but requests
for more than val resources cause the calling process to block until a
resource comes free (by a process holding a resource performing a
usvsema(3P)).
usnewsema will fail if one or more of the following is true:
[ENOMEM] There is no memory available in the arena to allocate the
semaphore structure (see usconfig(3P)).
[EINVAL] val is less than zero or greater than 30000.
SEE ALSOamalloc(3P), uscpsema(3P), usconfig(3P), usctlsema(3P), usdumpsema(3P),
usfreesema(3P), usfreepollsema(3P), usinit(3P), usnewpollsema(3P),
usvsema(3P).
DIAGNOSTICS
Upon successful completion, a value of pointer to a usema_t structure is
returned. Otherwise, a value of NULL is returned and errno is set to
indicate the error.
Page 1
