USNEWSEMA(3P)                                                    USNEWSEMA(3P)


NAME
     usnewsema - allocate and initialize a semaphore

C SYNOPSIS
     #include <ulocks.h>

     usema_t *usnewsema (usptr_t *handle, int val);

DESCRIPTION
     usnewsema 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 ALSO
     amalloc(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