USCTLLOCK(3P)                                                    USCTLLOCK(3P)


NAME
     usctllock - lock control operations

C SYNOPSIS
     #include <ulocks.h>

     int usctllock (ulock_t lock, int cmd, ...);

DESCRIPTION
     usctllock 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.


     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 ALSO
     usconfig(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