USCTLSEMA(3P)                                                    USCTLSEMA(3P)


NAME
     usctlsema - semaphore control operations

C SYNOPSIS
     #include <ulocks.h>

     int usctlsema (usema_t *sema, int cmd [, void *arg ]);

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


     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


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