sem_mode(3C)							  sem_mode(3C)

NAME    [Toc]    [Back]

     sem_mode -	set the	operation mode of a POSIX unnamed semaphore

C SYNOPSIS    [Toc]    [Back]

     #include <semaphore.h>

     int sem_mode (sem_t *sem<b>, int cmd<b>[, arg<b>]);

DESCRIPTION    [Toc]    [Back]

     sem_mode is used to change	the operation mode of the specified POSIX
     unnamed semaphore sem. Changing a semaphore's default operation mode
     allows applications to enable two levels of debug tracing,	and apply
     retry spinning.

     Semaphore types other than	POSIX unnamed semaphores are not supported by
     this function.

     sem_mode is an IRIX extension to the POSIX	interfaces and is not part of
     the IEEE 1003.1b Standard.

     The operation mode	is selected by setting cmd to one of the following:

     SEM_MODE_TRACEINIT
	  Initialize statistical tracing for sem, passing a pointer to a
	  user-allocated trace structure of type sem_trace_t as	arg.  When
	  debug	or meter tracing is enabled, the collected data	is stored in
	  the trace structure. Upon initialization, the	contents of the
	  structure is cleared.

	  The trace structure must reside in memory accessible to all
	  threads/processes accessing sem, to allow them to update the traced
	  data.	 If the	semaphore is being shared across process boundarys,
	  the trace structure must be located at the same virtual address for
	  all processes.

	  The application may access the contents of the trace structure at
	  any time.

	  Note:	Tracing	is not supported for non-shared	unnamed	semaphores,
	  used by pthread applications.

     SEM_MODE_METERON
	  Enable metered tracing for sem.  Once	a trace	structure for sem has
	  been initialized, metered tracing can	be enabled.  Enabling this
	  level	of tracing causes metered information to be accumulated	and
	  stored in the	following trace	structure fields (as operations
	  occur):

	       sem_waits: number of sem_wait operations

	       sem_waithits: number of times a thread/process called sem_wait
	       without having to block



									Page 1






sem_mode(3C)							  sem_mode(3C)



	       sem_posts: number of sem_post operations

	       sem_posthits: number of times a thread/process called sem_post
	       without having to wakeup	a waiting thread/process

	       sem_waiters: number of threads/processes	currently waiting on
	       the semaphore

	       sem_maxwaiters: maximum number of threads/processes that	can
	       block on	a semaphore at any given time

     SEM_MODE_METEROFF
	  Disable metered tracing for sem, leaving the contents	of the trace
	  structure intact for future analysis.

     SEM_MODE_METERRESET
	  Clear	the metered contents of	the trace structure of semaphore sem.

     SEM_MODE_DEBUGON
	  Enable debug tracing for sem.	 Once a	trace structure	for sem	has
	  been initialized, debug tracing can be enabled.  Enabling this level
	  of tracing causes ownership and access information to	be tracked and
	  stored in the	following trace	structure fields:

	       sem_owner_pid: process ID of the	semaphore's current owner

	       sem_owner_tid: pthread ID of the	semaphore's current owner

	       sem_owner_pc: program counter of	the semaphore owner

	       sem_last_pid: process ID	of the last process to perform a
	       semaphore operation on sem

	       sem_last_tid: pthread ID	of the last pthread to perform a
	       semaphore operation on sem

	       sem_last_pc: program counter of the last	thread/process to to
	       perform a semaphore operation on	sem

     SEM_MODE_DEBUGOFF
	  Disable debug	tracing	for sem, leaving the contents of the trace
	  structure intact for future analysis.

     SEM_MODE_DEBUGRESET
	  Clear	the debug ownership contents of	the trace structure of
	  semaphore sem.

     SEM_MODE_SPINSET
	  Apply	a retry	count arg to hold-off blocking in sem_wait(3C) when
	  the semaphore	sem is not immediately available.  The default POSIX
	  semaphore sem_wait algorithm attempts	to acquire a semaphore once,
	  and blocks the caller	if the semaphore isn't available.  Applying a



									Page 2






sem_mode(3C)							  sem_mode(3C)



	  retry	count causes sem_wait to retry semaphore acquisition arg times
	  (spinning) before blocking.  Retry counts remain in effect until the
	  application again sets the retry count to 0.

	  Note:	This operation mode is ignored on uni-processor	systems.

     sem_mode will fail	if the following is true:

     [EINVAL]	 Invalid parameter.

SEE ALSO    [Toc]    [Back]

     sem_init(3C), sem_post(3C), sem_wait(3C), sem_print(3C)

DIAGNOSTICS    [Toc]    [Back]

     Upon successful completion, a value of 0 is returned to the calling
     process. Otherwise, a value of -1 is returned and errno is	set to
     indicate the error.


									PPPPaaaaggggeeee 3333