putmsg() -- System Call (libc)

Place a message onto a stream
#include <stropts.h>
int putmsg (fd, ctlptr, dataptr, flags)
int fd, flags; const struct strbuf *ctlptr, *dataptr;

putmsg()  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.

fd  gives a  file descriptor  that identifies an  open stream.   ctlptr and
dataptr  each point  to a  structure  of tyupe  strbuf, which  contains the
following members:

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

ctlptr points to the structure that  describes the control part (if any) to
be included  in the message: buf  points to the buffer  wherein the control
information resides, and len gives the number of bytes to be sent.

Likewise,  dataptr  specifies the  data  (if  any) to  be  included in  the
message.  flags gives the message's type; it is described in detail below.

To send the data part of a message, dataptr must not be NULL, and the value
of dataptr.len  must be no less  than zero.  To send the  control part of a
message, the corresponding values must be set for ctlptr. putmsg() does not
send  the  data  portion of  the  message  if dataptr  is  set  to NULL  or
dataptr.len equals -1; likewise, putmsg() does not send the control portion
of the message if ctlptr is NULL or ctrlptr.len equals -1.

If a control part is specified  and flags equals RS_HIPRI, putmsg() sends a
high-priority message.   If no control  part is specified  and flags equals
RS_HIPRI, putmsg() fails and sets errno to EINVAL. If flags is set to zero,
putmsg() sends  a message of normal priority.  If  neither the control part
nor the data part is specified, and if flags is set to zero, putmsg() sends
no message and returns zero.

The stream head guarantees that the  control part of a message generated by
putmsg() is at least 64 bytes long.

putmsg() usually  blocks if the  stream head's write  queue is full  due to
internal  flow-control conditions.   For  high-priority messages,  putmsg()
does not  block on this  condition.  For other messages,  putmsg() does not
block when  the write  queue is  full and you  have set  the mode on  fd to
O_NDELAY  or  O_NONBLOCK.  putmsg() never  sends  a  partial message.   For
details on O_NDELAY and O_NONBLOCK, see the Lexicon entry for open().

Upon  successful  completion, putmsg()  returns  zero.   If something  goes
wrong,  putmsg()  returns  -1  and  sets  errno to  an  appropriate  value.
putmsg() fails if any of the following conditions is true:

-> A non-priority message was specified, the mode on fd was set to O_NDELAY
   or O_NONBLOCK, and the stream-write  queue is full due to internal flow-
   control conditions.  putmsg() sets errno to EAGAIN.

-> fd is not a valid file descriptor.  putmsg() sets errno to EBADF.

-> ctlptr or  dataptr contains an illegal address.   putmsg() sets errno to
   EFAULT.

-> Your  application  caught  a signal  while  it  was executing  putmsg().
   putmsg() sets errno to EINTR.

-> flags contains an undefined value, or you set flags RS_HIPRI but did not
   supply a control part.  putmsg() sets errno to EINVAL.

-> The stream  referenced by  fd is  linked below a  multiplexor.  putmsg()
   sets errno to EINVAL.

-> putmsg() could not  allocate buffers for the message it  was to send due
   to insufficient STREAMS memory resources.  putmsg() sets errno to ENOSR.

-> fd does not identify a stream.  putmsg() sets errno to ENOSTR.

-> A hangup condition was generated downstream for the specified stream, or
   the other end of the pipe is closed.  putmsg() sets errno to ENXIO.

-> 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.  putmsg() sets errno to ERANGE.

putmsg() also  fails if a STREAMS  error message had been  processed by the
stream head before the call to putmsg() was executed.  putmsg() returns the
the value contained in the STREAMS error message.

See Also

getmsg(),
libc,
STREAMS

© 2012 by Stephen A. Ness