mmssggccttll() -- General Function (libc)

Message control 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/mmssgg.hh>
iinntt mmssggccttll(_i_d, _c_o_m_m_a_n_d, _b_u_f_f_e_r)
iinntt _i_d; iinntt _c_o_m_m_a_n_d; ssttrruucctt mmssqqiidd_ddss *_b_u_f_f_e_r;

The function mmssggccttll()  controls the COHERENT's system's messaging facility.
This facility permits processes to pass messages from one another.

Each message queue is controlled by  a structure of type mmssqqiidd_ddss, which is
defined in header file <ssyyss/mmssgg.hh>.  This structure points to the first and
last messages in  the queue, gives the size of  the queue and the number of
messages  in the  queue, and  names  who can  manipulate it  and how.   The
messages themselves  consist of  a linked list  of structures of  type mmssgg,
which  is also  defined  in mmssgg.hh.  When  the function  mmssggggeett() creates  a
message  queue,  it assigns  to  that queue  an  identification number  and
returns that  number to the calling process.  For  details on this process,
see the Lexicon entry for mmssggggeett().

_i_d identifies  the message queue  to be manipulated.  This  value must have
been returned by a call to mmssggggeett().

_c_o_m_m_a_n_d names  the operation that  you want mmssggccttll()  to perform.  mmssggccttll()
recognizes the following _c_o_m_m_a_n_ds:

IIPPCC_SSTTAATT  Copy  the  message-queue  structure  identified  by _i_d  into  the
          structure  pointed to  by _b_u_f_f_e_r.  This  command lets  you gather
          information about  a message queue  without actually manipulating
          the queue.

IIPPCC_SSEETT   This  command sets  permissions for  this queue.   It does  so by
          copying  fields  mmssgg_ppeerrmm.uuiidd,  mmssgg_ppeerrmm.ggiidd, mmssgg_ppeerrmm.mmooddee  (low
          nine bits only),  and mmssgg_qqbbyytteess from the message-queue structure
          point  to  by _b_u_f_f_e_r  to  structure identified  by  _i_d. Only  the
          superuser rroooott  and the  user who  owns the process  that created
          structure  _i_d  can  execute  this  _c_o_m_m_a_n_d.  Note that  only  the
          superuser can  raise the value  of field mmssgg_qqbbyytteess,  which gives
          the size of space occupied by the queue, in bytes.

IIPPCC_RRMMIIDD  Remove  the structure  identified by _i_d,  and destroy  its queue.
          Only the  superuser rroooott and  the user who owns  the process that
          created structure _i_d do this.

If  any of  the following  conditions occur, mmssggccttll()  returns -1  and sets
eerrrroorr to the value in parentheses:

-> _i_d is not a valid message-queue identifier (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).

-> _c_o_m_m_a_n_d  equals IIPPCC_SSTTAATT,  but the  owner of  the calling  process lacks
   permission to execute this command (EEAACCCCEESS).

-> _c_o_m_m_a_n_d equals IIPPCC_RRMMIIDD or IIPPCC_SSEETT, but the owner of the calling process
   lacks permission to execute the command (EEPPEERRMM).

-> A process  owned by someone  other than the superuser  rroooott attempted to
   increase field mmssgg_qqbbyytteess (EEPPEERRMM).

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

If all went well, mmssggccttll() returns zero.

_E_x_a_m_p_l_e
For an example of this function, see the Lexicon entry for mmssggggeett().

_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/mmssgg.hh

_S_e_e _A_l_s_o
lliibbcc, mmssggggeett(), mmssggrrccvv(), mmssggssnndd()

_N_o_t_e_s
For  information on  other methods of  interprocess communication,  see the
Lexicon entries for sseemmccttll(), sshhmmccttll(), and lliibbssoocckkeett.
