USNEWPOLLSEMA(3P)                                            USNEWPOLLSEMA(3P)


NAME
     usnewpollsema - allocate and initialize a pollable semaphore

C SYNOPSIS
     #include <ulocks.h>

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

DESCRIPTION
     usnewpollsema 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).  Pollable semaphores never block the caller.
     If the semaphore is unavailable when uspsema(3P) is called, the caller is
     queued to receive the semaphore and returns immediately.  To actually
     acquire the semaphore the caller must issue a poll(2) or select(2) on the
     file descriptor associated with the semaphore.  A file descriptor is
     allocated via usopenpollsema(3P).  The POLLIN event should be used with
     poll(2).  The semaphore file descriptor should be passed in as a read
     descriptor for select(2).

     A val of 0 implies no available resources, and the first process that
     attempts a 'P' operation (via uspsema(3P)) will return 0.  This can be
     viewed as a synchronizing semaphore, since the goal is to always have a
     process wait 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 wait until a
     resource comes free (by a process holding a resource performing a
     usvsema(3P)).

     Pollable semaphores may be used with all the other semaphore routines.
     They must be freed using usfreepollsema(3P).

     usnewpollsema will fail if one or more of the following are true:

     [ENOMEM]       There is no memory available in the arena to allocate the
                    semaphore structure (see usconfig(3P)).  Pollable
                    semaphores take more memory than non-pollable semaphores
                    since a file descriptor per user must be saved.

     [EINVAL]       val is less than zero or greater than 30000.

SEE ALSO
     poll(2), select(2), amalloc(3P), uscpsema(3P), usconfig(3P),
     usctlsema(3P), usdumpsema(3P), usclosepollsema(3P), usfreesema(3P),
     usfreepollsema(3P), usinit(3P), usnewsema(3P), usopenpollsema(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 2