USCTLSEMA(3P)USCTLSEMA(3P)NAMEusctlsema - semaphore control operations
C SYNOPSIS
#include <ulocks.h>
int usctlsema (usema_t *sema, int cmd [, void *arg ]);
DESCRIPTIONusctlsema provides a variety of semaphore control operations as specified
by cmd. The following cmds are available:
CS_METERON Enable metering for the semaphore specified by sema. The
metering information gathered consists of the number of
uspsema and uscpsema calls, the number of times the
semaphore could immediately be acquired, the number of
usvsema calls, the number of times usvsema was called and
no process was queued waiting, the current number of
processes waiting on the semaphore, and the maximum number
of processes ever waiting on the semaphore. All metering
is stored in a semameter_t structure defined in the header
file <ulocks.h> and described below.
CS_METEROFF Disable metering for the semaphore specified by sema.
CS_METERFETCH Fills the structure pointed to by arg with the metering
data associated with sema.
CS_METERRESET Reinitializes the semameter_t structure associated with
sema to all 0.
CS_DEBUGON Enable debug monitoring for the semaphore specified by
sema. The debugging information maintained consists of
the process id of the owner of the semaphore, and the
address in the owner process where the call to the
semaphore operation was made, the process id of the last
process to operate on the semaphore, and the address in
the last process where the call to the semaphore operation
was made. The pid is set to -1 if no one owns the
semaphore. All debug info is stored in a semadebug_t
structure defined in the header file <ulocks.h> and
described below.
CS_DEBUGOFF Disable debugging for the semaphore specified by sema.
CS_DEBUGFETCH Fills the structure pointed to by arg with the debugging
data associated with sema.
CS_DEBUGRESET Reinitializes the elements of the semadebug_t structure
associated with sema to values of -1.
Page 1
USCTLSEMA(3P)USCTLSEMA(3P)
CS_HISTON Enable history logging for the semaphore specified by
sema. A global history is maintained that consists of a
record of each transaction on semaphores in hist_t
structures defined in the header file <ulocks.h>. This is
discussed further in usconfig(3P), which is used to
retrieve history of semaphore transactions.
CS_HISTOFF Disable history for the semaphore specified by sema.
CS_RECURSIVEON Enables recursive acquires of the semaphore specified by
sema. Normally, an attempt to recursively acquire a
mutual exclusion semaphore, (one initialized with a value
of 1), will result in the calling process deadlocking.
This option will cause a count to be incremented each time
the current owner acquires the semaphore (including
uscpsema(3P)). A matched number of usvsema(3P) calls will
release the semaphore. This option can be used only with
mutual exclusion semaphores and must be specified when the
semaphore is currently free. Note that the recursive
semaphore option is not supported for pthread applications
intending to share the semaphore across process
boundaries. However, pthread application threads may use
recursive semaphores when semaphore access is restricted
to a single process.
CS_RECURSIVEOFF
Disable recursive acquires of the semaphore specified by
sema.
Declarations of the function and cmds, the hist_t structure, the
semameter_t structure, and the semadebug_t structure, are in the
<ulocks.h> header file.
The structure declaration of semameter_t is:
typedef struct semameter_s {
int sm_phits; /* number of immediate psemas*/
int sm_psemas; /* number of psema attempts */
int sm_vsemas; /* number of vsema attempts */
int sm_vnowait; /* number of vsemas with no one
waiting */
int sm_nwait; /* number of threads waiting on the
semaphore */
int sm_maxnwait; /* maximum number of threads waiting
on the semaphore */
} semameter_t;
The structure declaration of semadebug_t is:
typedef struct semadebug_s {
int sd_owner_pid /* the process that owns the semaphore */
char * sd_owner_pc; /* the address of last psema for
Page 2
USCTLSEMA(3P)USCTLSEMA(3P)
process that owns the semaphore */
int sd_last_pid; /* the process that last did a p or v sema */
char * sd_last_pc; /* the address of the last routine to operate
on the semaphore */
} semadebug_t;
usctlsema will fail if one or more of the following are true:
[EINVAL] cmd is not a valid command.
[EINVAL] cmd is equal to CS_METERFETCH and metering in not
currently enabled.
[EINVAL] cmd is equal to CS_DEBUGFETCH and debugging is not
currently enabled.
[ENOMEM] cmd is equal to CS_METERON or CS_DEBUGON and there was not
enough memory in the arena.
SEE ALSOusconfig(3P), uscpsema(3P), usdumpsema(3P), usinitsema(3P),
usnewsema(3P), uspsema(3P), usvsema(3P).
DIAGNOSTICS
Upon successful completion, a value of 0 is returned. Otherwise, a value
of -1 is returned and errno is set to indicate the error.
Page 3
