USNEWSEMA(3P)							 USNEWSEMA(3P)

NAME    [Toc]    [Back]

     usnewsema - allocate and initialize a semaphore

C SYNOPSIS    [Toc]    [Back]

     #include <ulocks.h>

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

DESCRIPTION    [Toc]    [Back]

     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    [Toc]    [Back]

     amalloc(3P), uscpsema(3P),	usconfig(3P), usctlsema(3P), usdumpsema(3P),
     usfreesema(3P), usfreepollsema(3P), usinit(3P), usnewpollsema(3P),
     usvsema(3P).

DIAGNOSTICS    [Toc]    [Back]

     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.


									PPPPaaaaggggeeee 1111