sem_mode(3C)

NAME
     sem_mode - set the operation mode of a POSIX unnamed semaphore

C SYNOPSIS
     #include <semaphore.h>
     int sem_mode (sem_t *sem, int cmd[, arg]);

DESCRIPTION
     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
               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
          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
     sem_init(3C), sem_post(3C), sem_wait(3C), sem_print(3C)

DIAGNOSTICS
     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.