ppuuttmmssgg() -- System Call (libc)

Place a message onto a stream
#iinncclluuddee <ssttrrooppttss.hh>
int putmsg (_f_d, _c_t_l_p_t_r, _d_a_t_a_p_t_r, _f_l_a_g_s)
iinntt _f_d, _f_l_a_g_s; ccoonnsstt ssttrruucctt ssttrrbbuuff *_c_t_l_p_t_r, *_d_a_t_a_p_t_r;

ppuuttmmssgg()  creates a  message from user-specified  buffer (or  buffers), and
sends the message to a STREAMS file.  The message can contain either a data
part, a control  part, or both.  The data and  control parts to be sent are
distinguished by being placed in separate buffers, as described below.  The
semantics of each part are defined  by the STREAMS module that receives the
message.

_f_d  gives a  file descriptor  that identifies an  open stream.   _c_t_l_p_t_r and
_d_a_t_a_p_t_r  each point  to a  structure  of tyupe  ssttrrbbuuff, which  contains the
following members:

    int len;    /* Length of data */
    void *buf;  /* Pointer to buffer */

_c_t_l_p_t_r points to the structure that  describes the control part (if any) to
be included  in the message: bbuuff  points to the buffer  wherein the control
information resides, and lleenn gives the number of bytes to be sent.

Likewise,  _d_a_t_a_p_t_r  specifies the  data  (if  any) to  be  included in  the
message.  _f_l_a_g_s gives the message's type; it is described in detail below.

To send the data part of a message, _d_a_t_a_p_t_r must not be NULL, and the value
of _d_a_t_a_p_t_r.lleenn  must be no less  than zero.  To send the  control part of a
message, the corresponding values must be set for _c_t_l_p_t_r. ppuuttmmssgg() does not
send  the  data  portion of  the  message  if _d_a_t_a_p_t_r  is  set  to NULL  or
_d_a_t_a_p_t_r.lleenn equals -1; likewise, ppuuttmmssgg() does not send the control portion
of the message if _c_t_l_p_t_r is NULL or _c_t_r_l_p_t_r.lleenn equals -1.

If a control part is specified  and _f_l_a_g_s equals RRSS_HHIIPPRRII, ppuuttmmssgg() sends a
high-priority message.   If no control  part is specified  and _f_l_a_g_s equals
RRSS_HHIIPPRRII, ppuuttmmssgg() fails and sets eerrrrnnoo to EEIINNVVAALL. If _f_l_a_g_s is set to zero,
ppuuttmmssgg() sends  a message of normal priority.  If  neither the control part
nor the data part is specified, and if flags is set to zero, ppuuttmmssgg() sends
no message and returns zero.

The stream head guarantees that the  control part of a message generated by
ppuuttmmssgg() is at least 64 bytes long.

ppuuttmmssgg() usually  blocks if the  stream head's write  queue is full  due to
internal  flow-control conditions.   For  high-priority messages,  ppuuttmmssgg()
does not  block on this  condition.  For other messages,  ppuuttmmssgg() does not
block when  the write  queue is  full and you  have set  the mode on  _f_d to
OO_NNDDEELLAAYY  or  OO_NNOONNBBLLOOCCKK.  ppuuttmmssgg() never  sends  a  partial message.   For
details on OO_NNDDEELLAAYY and OO_NNOONNBBLLOOCCKK, see the Lexicon entry for ooppeenn().

Upon  successful  completion, ppuuttmmssgg()  returns  zero.   If something  goes
wrong,  ppuuttmmssgg()  returns  -1  and  sets  eerrrrnnoo to  an  appropriate  value.
ppuuttmmssgg() fails if any of the following conditions is true:

-> A non-priority message was specified, the mode on _f_d was set to OO_NNDDEELLAAYY
   or OO_NNOONNBBLLOOCCKK, and the stream-write  queue is full due to internal flow-
   control conditions.  ppuuttmmssgg() sets eerrrrnnoo to EEAAGGAAIINN.

-> _f_d is not a valid file descriptor.  ppuuttmmssgg() sets eerrrrnnoo to EEBBAADDFF.

-> _c_t_l_p_t_r or  _d_a_t_a_p_t_r contains an illegal address.   ppuuttmmssgg() sets eerrrrnnoo to
   EEFFAAUULLTT.

-> Your  application  caught  a signal  while  it  was executing  ppuuttmmssgg().
   ppuuttmmssgg() sets eerrrrnnoo to EEIINNTTRR.

-> _f_l_a_g_s contains an undefined value, or you set _f_l_a_g_s RRSS_HHIIPPRRII but did not
   supply a control part.  ppuuttmmssgg() sets eerrrrnnoo to EEIINNVVAALL.

-> The stream  referenced by  _f_d is  linked below a  multiplexor.  ppuuttmmssgg()
   sets eerrrrnnoo to EEIINNVVAALL.

-> ppuuttmmssgg() could not  allocate buffers for the message it  was to send due
   to insufficient STREAMS memory resources.  ppuuttmmssgg() sets eerrrrnnoo to EENNOOSSRR.

-> _f_d does not identify a stream.  ppuuttmmssgg() sets eerrrrnnoo to EENNOOSSTTRR.

-> A hangup condition was generated downstream for the specified stream, or
   the other end of the pipe is closed.  ppuuttmmssgg() sets eerrrrnnoo to EENNXXIIOO.

-> The size  of the message's  data portion does  not fall within  range of
   legal packet sizes set by  topmost stream module, or its control portion
   exceeds the maximum configured size.  ppuuttmmssgg() sets eerrrrnnoo to EERRAANNGGEE.

ppuuttmmssgg() also  fails if a STREAMS  error message had been  processed by the
stream head before the call to ppuuttmmssgg() was executed.  ppuuttmmssgg() returns the
the value contained in the STREAMS error message.

_S_e_e _A_l_s_o
ggeettmmssgg(), lliibbcc, SSTTRREEAAMMSS
