# putmsg

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           putmsg, putpmsg — send a message on a STREAM (**STREAMS**)
    


## SYNOPSIS



           #include <stropts.h>
    
           int putmsg(int _fildes_ , const struct strbuf *_ctlptr_ ,
               const struct strbuf *_dataptr_ , int _flags_);
           int putpmsg(int _fildes_ , const struct strbuf *_ctlptr_ ,
               const struct strbuf *_dataptr_ , int _band_ , int _flags_);
    


## DESCRIPTION



           The _putmsg_() function shall create a message from a process
           buffer(s) and send the message to a STREAMS file. The message may
           contain either a data part, a control part, or both. The data and
           control parts are distinguished by placement in separate buffers,
           as described below. The semantics of each part are defined by the
           STREAMS module that receives the message.
    
           The _putpmsg_() function is equivalent to _putmsg_(), except that the
           process can send messages in different priority bands.  Except
           where noted, all requirements on _putmsg_() also pertain to
           _putpmsg_().
    
           The _fildes_ argument specifies a file descriptor referencing an
           open STREAM. The _ctlptr_ and _dataptr_ arguments each point to a
           **strbuf** structure.
    
           The _ctlptr_ argument points to the structure describing the control
           part, if any, to be included in the message. The _buf_ member in the
           **strbuf** structure points to the buffer where the control
           information resides, and the _len_ member indicates the number of
           bytes to be sent. The _maxlen_ member is not used by _putmsg_().  In a
           similar manner, the argument _dataptr_ specifies the data, if any,
           to be included in the message. The _flags_ argument indicates what
           type of message should be sent and is described further below.
    
           To send the data part of a message, the application shall ensure
           that _dataptr_ is not a null pointer and the _len_ member of _dataptr_
           is 0 or greater. To send the control part of a message, the
           application shall ensure that the corresponding values are set for
           _ctlptr_.  No data (control) part shall be sent if either
           _dataptr_(_ctlptr_) is a null pointer or the _len_ member of
           _dataptr_(_ctlptr_) is set to -1.
    
           For _putmsg_(), if a control part is specified and _flags_ is set to
           RS_HIPRI, a high priority message shall be sent. If no control
           part is specified, and _flags_ is set to RS_HIPRI, _putmsg_() shall
           fail and set _errno_ to **[EINVAL]**.  If _flags_ is set to 0, a normal
           message (priority band equal to 0) shall be sent.  If a control
           part and data part are not specified and _flags_ is set to 0, no
           message shall be sent and 0 shall be returned.
    
           For _putpmsg_(), the flags are different. The _flags_ argument is a
           bitmask with the following mutually-exclusive flags defined:
           MSG_HIPRI and MSG_BAND. If _flags_ is set to 0, _putpmsg_() shall fail
           and set _errno_ to **[EINVAL]**.  If a control part is specified and
           _flags_ is set to MSG_HIPRI and _band_ is set to 0, a high-priority
           message shall be sent. If _flags_ is set to MSG_HIPRI and either no
           control part is specified or _band_ is set to a non-zero value,
           _putpmsg_() shall fail and set _errno_ to **[EINVAL]**.  If _flags_ is set
           to MSG_BAND, then a message shall be sent in the priority band
           specified by _band_.  If a control part and data part are not
           specified and _flags_ is set to MSG_BAND, no message shall be sent
           and 0 shall be returned.
    
           The _putmsg_() function shall block if the STREAM write queue is
           full due to internal flow control conditions, with the following
           exceptions:
    
            *  For high-priority messages, _putmsg_() shall not block on this
               condition and continues processing the message.
    
            *  For other messages, _putmsg_() shall not block but shall fail
               when the write queue is full and O_NONBLOCK is set.
    
           The _putmsg_() function shall also block, unless prevented by lack
           of internal resources, while waiting for the availability of
           message blocks in the STREAM, regardless of priority or whether
           O_NONBLOCK has been specified. No partial message shall be sent.
    


## RETURN VALUE



           Upon successful completion, _putmsg_() and _putpmsg_() shall return 0;
           otherwise, they shall return -1 and set _errno_ to indicate the
           error.
    


## ERRORS



           The _putmsg_() and _putpmsg_() functions shall fail if:
    
           **EAGAIN** A non-priority message was specified, the O_NONBLOCK flag
                  is set, and the STREAM write queue is full due to internal
                  flow control conditions; or buffers could not be allocated
                  for the message that was to be created.
    
           **EBADF** _fildes_ is not a valid file descriptor open for writing.
    
           **EINTR** A signal was caught during _putmsg_().
    
           **EINVAL** An undefined value is specified in _flags_ , or _flags_ is set
                  to RS_HIPRI or MSG_HIPRI and no control part is supplied,
                  or the STREAM or multiplexer referenced by _fildes_ is linked
                  (directly or indirectly) downstream from a multiplexer, or
                  _flags_ is set to MSG_HIPRI and _band_ is non-zero (for
                  _putpmsg_() only).
    
           **ENOSR** Buffers could not be allocated for the message that was to
                  be created due to insufficient STREAMS memory resources.
    
           **ENOSTR** A STREAM is not associated with _fildes_.
    
           **ENXIO** A hangup condition was generated downstream for the
                  specified STREAM.
    
           **EPIPE** or **EIO**
                  The _fildes_ argument refers to a STREAMS-based pipe and the
                  other end of the pipe is closed. A SIGPIPE signal is
                  generated for the calling thread.
    
           **ERANGE** The size of the data part of the message does not fall
                  within the range specified by the maximum and minimum
                  packet sizes of the topmost STREAM module. This value is
                  also returned if the control part of the message is larger
                  than the maximum configured size of the control part of a
                  message, or if the data part of a message is larger than
                  the maximum configured size of the data part of a message.
    
           In addition, _putmsg_() and _putpmsg_() shall fail if the STREAM head
           had processed an asynchronous error before the call. In this case,
           the value of _errno_ does not reflect the result of _putmsg_() or
           _putpmsg_(), but reflects the prior error.
    
           _The following sections are informative._
    


## EXAMPLES



       **Sending a High-Priority Message**
           The value of _fd_ is assumed to refer to an open STREAMS file. This
           call to _putmsg_() does the following:
    
            1. Creates a high-priority message with a control part and a data
               part, using the buffers pointed to by _ctrlbuf_ and _databuf_ ,
               respectively.
    
            2. Sends the message to the STREAMS file identified by _fd_.
    
               #include <stropts.h>
               #include <string.h>
               ...
               int fd;
               char *ctrlbuf = "This is the control part";
               char *databuf = "This is the data part";
               struct strbuf ctrl;
               struct strbuf data;
               int ret;
    
               ctrl.buf = ctrlbuf;
               ctrl.len = strlen(ctrlbuf);
    
               data.buf = databuf;
               data.len = strlen(databuf);
    
               ret = putmsg(fd, &ctrl, &data, MSG_HIPRI);
    
       **Using putpmsg()**
           This example has the same effect as the previous example. In this
           example, however, the _putpmsg_() function creates and sends the
           message to the STREAMS file.
    
               #include <stropts.h>
               #include <string.h>
               ...
               int fd;
               char *ctrlbuf = "This is the control part";
               char *databuf = "This is the data part";
               struct strbuf ctrl;
               struct strbuf data;
               int ret;
    
               ctrl.buf = ctrlbuf;
               ctrl.len = strlen(ctrlbuf);
    
               data.buf = databuf;
               data.len = strlen(databuf);
    
               ret = putpmsg(fd, &ctrl, &data, 0, MSG_HIPRI);
    


## APPLICATION USAGE



           None.
    


## RATIONALE



           None.
    


## FUTURE DIRECTIONS



           The _putmsg_() and _putpmsg_() functions may be removed in a future
           version.
    


* * *