sseemmccttll() -- General Function (libc)

Control semaphore operations
#iinncclluuddee <ssyyss/ttyyppeess.hh>
#iinncclluuddee <ssyyss/iippcc.hh>
#iinncclluuddee <ssyyss/sseemm.hh>
iinntt sseemmccttll(_i_d, _n_u_m_b_e_r, _c_o_m_m_a_n_d, _a_r_g)
iinntt _i_d, _c_o_m_m_a_n_d, _n_u_m_b_e_r;
uunniioonn sseemmuunn {
        iinntt _v_a_l_u_e;
        ssttrruucctt sseemmiidd_ddss *_b_u_f_f_e_r;
        uunnssiiggnneedd sshhoorrtt _a_r_r_a_y[];
} _a_r_g;

The function sseemmccttll() controls the COHERENT system's semaphore facility.

A set  of semaphores  consists of  a copy of  structure sseemmiidd_ddss,  which is
defined in  header file  <ssyyss/sseemm.hh>. This structure  points to the  set of
semaphores, notes how many semaphores are in the set, and gives information
on who can manipulate it, and how.  The semaphores themselves consist of an
array of structures  of type sseemm, which is also  defined in sseemm.hh. When the
function sseemmggeett()  creates a set of  semaphores, it assigns to  that set an
identification number and returns  that number to the calling process.  For
details on this process, see the Lexicon entry for sseemmggeett()

_i_d identifies  the set  of semaphores to  be manipulated.  This  value must
have been  returned by a call  to sseemmggeett(). _n_u_m_b_e_r gives  the offset within
the set  identified by _i_d of  the semaphore that interests  you.  _a_r_g gives
information to  be passed to, or received from,  the semaphore in question.
_c_o_m_m_a_n_d names the operation that you want sseemmccttll() to perform.

The  following   _c_o_m_m_a_n_ds  manipulate  semaphore  _n_u_m_b_e_r   within  the  set
identified by _i_d:

GGEETTVVAALL    Return the  value of sseemmvvaall, which is the  field in structure sseemm
          that gives the address of the semaphore's text map.

SSEETTVVAALL    Set sseemmvvaall to _a_r_g._v_a_l_u_e.  If an ``adjust value'' had been created
          for this  semaphore (by changing  or setting a  semaphore through
          sseemmoopp() with the flag SSEEMM_UUNNDDOO set), it is erased.

GGEETTPPIIDD    Return  the value  of  sseemmppiidd, which  is  the field  in sseemm  that
          identifies the last process to have manipulated this semaphore.

GGEETTNNCCNNTT   Return the value of  sseemmnnccnntt, which gives the number of processes
          that await an increase in field sseemm.sseemmvvaall.

GGEETTZZCCNNTT   Return the value of  sseemmzzccnntt, which gives the number of processes
          that are waiting for the value of sseemm.sseemmvvaall to become zero.

The following _c_o_m_m_a_n_ds return or set field sseemmvvaall within every semaphore in
the set identified by _i_d:

GGEETTAALLLL    Write every sseemmvvaall into _a_r_g._a_r_r_a_y.

SSEETTAALLLL    Initialize  every  sseemmvvaall   to  the  corresponding  value  within
          _a_r_g._a_r_r_a_y.  All ``adjust values'' for this semaphores are erased.

sseemmccttll() also recognizes the following _c_o_m_m_a_n_ds:

IIPPCC_SSTTAATT  Copy the value of each semaphore in the set identified by _i_d into
          the structure pointed to by _a_r_g._b_u_f_f_e_r.

IIPPCC_SSEETT   Copy  fields sseemm_ppeerrmm.uuiidd,  sseemm_ppeerrmm.ggiidd, and  sseemm_ppeerrmm.mmooddee (low
          nine bits  only) from the  iippcc_ppeerrmm associated with  _i_d into that
          pointed to _a_r_g._b_u_f_f_e_r. Only  the superuser rroooott or the user whose
          effective  user ID  matches the  value of field  uuiidd in  the data
          structure identified by _i_d can invoke this command.

IIPPCC_RRMMIIDD  Destroy the  sseemmiidd_ddss structure identified by  _i_d, plus its array
          of  semaphores.   Only  the  superuser  rroooott  or the  user  whose
          effective user ID matches the  value of field uuiidd can invoke this
          command.

sseemmccttll() fails if one or more of the following is true:

-> _i_d  is  not a  valid  semaphore identifier.   sseemmccttll()  sets the  global
   variable eerrrrnnoo to EEIINNVVAALL.

-> _n_u_m_b_e_r is  less than zero  or greater than field  sseemm_nnsseemmss in structure
   sseemmiidd_ddss, which gives the number  of semaphores in the set identified by
   _i_d (EEIINNVVAALL).

-> _c_o_m_m_a_n_d is not a valid command (EEIINNVVAALL).

-> The calling process is denied operation permission (EEAACCCCEESS).

-> _c_o_m_m_a_n_d is SSEETTVVAALL or SSEETTAALLLL, but the value of sseemmvvaall exceeds the system-
   imposed maximum (EERRAANNGGEE).

-> _c_o_m_m_a_n_d is IIPPCC_RRMMIIDD or IIPPCC_SSEETT, but the calling process is owned neither
   by  rroooott  nor by  the  user  who created  the  set  of semaphores  being
   manipulated (EEPPEERRMM).

-> _a_r_g._b_u_f_f_e_r points to an illegal address (EEFFAAUULLTT).

sseemmccttll() returns  the following values upon  successful completion of their
following commands:

     _C_o_m_m_a_n_d   _R_e_t_u_r_n _V_a_l_u_e
     GGEETTVVAALL    Value of sseemmvvaall
     GGEETTPPIIDD    Value of sseemmppiidd
     GGEETTNNCCNNTT   Value of sseemmnnccnntt
     GGEETTZZCCNNTT   Value of sseemmzzccnntt

For  all  other  commands, sseemmccttll()  returns  zero  to indicate  successful
completion.

If it  could not  execute a command  successfully, sseemmccttll() returns  -1 and
sets eerrrrnnoo to an appropriate value.

_F_i_l_e_s
/uussrr/iinncclluuddee/ssyyss/iippcc.hh
/uussrr/iinncclluuddee/ssyyss/sseemm.hh

_S_e_e _A_l_s_o
lliibbcc, sseemmggeett(), sseemmoopp()

_N_o_t_e_s
For  information on  other methods of  interprocess communication,  see the
Lexicon entries for mmssggccttll() and sshhmmccttll().
