sem_mode(3C)sem_mode(3C)NAMEsem_mode - set the operation mode of a POSIX unnamed semaphore
C SYNOPSIS
#include <semaphore.h>
int sem_mode (sem_t *sem, int cmd[, arg]);
DESCRIPTIONsem_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 ALSOsem_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.
Page 3
