USCTLLOCK(3P)USCTLLOCK(3P)NAMEusctllock - lock control operations
C SYNOPSIS
#include <ulocks.h>
int usctllock (ulock_t lock, int cmd, ...);
DESCRIPTIONusctllock provides a variety of lock control operations as specified by
cmd. Metering and debugging information is available only for locks
allocated from an arena with a lock type of either US_DEBUG or
US_DEBUGPLUS (see usconfig(3P)). Some cmds take a third argument
referred to below as arg. The following cmds are available:
CL_METERFETCH Fills the lockmeter_t structure pointed to by arg with the
metering data associated with lock.
CL_METERRESET Reinitializes the lockmeter_t structure associated with
lock to all values of -1.
CL_DEBUGFETCH Fills the lockdebug_t structure pointed to by arg with the
debugging data associated with lock. See usconfig(3P) for
a explanation of the data returned.
CL_DEBUGRESET Reinitializes the elements of the lockdebug_t structure
associated with lock to values of -1.
Declarations of the function and cmds, the lockmeter_t structure, and the
lockdebug_t structure, are in the <ulocks.h> header file.
The structure declaration of lockmeter_t is:
typedef struct {
int lm_spins; /* times the lock request spun out */
int lm_tries; /* times the lock was requested */
int lm_hits; /* times the lock was acquired */
} lockmeter_t;
lm_tries is incremented each time ussetlock, uscsetlock or uswsetlock is
called. lm_hits is incremented each time the lock is acquired. lm_spins
is incremented each time an attempt is made to acquire a lock, the lock
is busy, and the number of spins to attempt to acquire the lock is
exhausted. For uswsetlock, lm_spins is incremented once for every time
spins is exhausted and the processor is (potentially) yielded. For
uscsetlock, lm_spins will be incremented a maximum of once per call.
Additionally, lm_tries and lm_spins may be slightly wrong if uscsetlock
is called and fails, since these statistics will be updated without
actually holding any lock.
Page 1
USCTLLOCK(3P)USCTLLOCK(3P)
The structure declaration of lockdebug_t is:
typedef struct {
int ld_owner_pid; /* the process that owns the lock */
} lockdebug_t;
An invalid lock may yield unpredictable results.
usctllock will fail if one or more of the following are true:
[EINVAL] cmd is not a valid command.
[EINVAL] cmd is equal to CL_METERFETCH and metering is not
currently enabled for the given lock.
[EINVAL] cmd is equal to CL_DEBUGFETCH and debugging is not
currently enabled for the given lock.
SEE ALSOusconfig(3P), usinitlock(3P), usnewlock(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 2
