putmsg(S)                      6 January 1993                      putmsg(S)


 Name

    putmsg - send a message on a stream

 Syntax


    cc  . . .  -lc


    #include <stropts.h>

    int putmsg (fd, ctlptr, dataptr, flags)
    int fd;
    struct strbuf *ctlptr;
    struct strbuf *dataptr;
    int flags;


 Description

    The putmsg system call creates a message from user-specified buffer(s)
    and sends the message to a STREAMS file.  The message may contain either
    a data part, a control part or both.  The data and control parts to be
    sent are distinguished by placement in separate buffers, as described
    below.  The semantics of each part is defined by the STREAMS module that
    receives the message.

    fd specifies a file descriptor referencing an open stream.  ctlptr and
    dataptr each point to a strbuf structure which contains the following
    members:

               int maxlen;     /* not used  */
               int len;        /* length of data  */
               char *buf;      /* ptr to buffer  */

    ctlptr points to the structure describing the control part, if any, to be
    included in the message.  The buf field in the strbuf structure points to
    the buffer where the control information resides, and the len field indi-
    cates the number of bytes to be sent.  The maxlen field is not used in
    putmsg (see getmsg(S)).  In a similar manner, dataptr specifies the data,
    if any, to be included in the message.  flags may be set to the values 0
    or RSHIPRI and is used as described below.

    To send the data part of a message, dataptr must be non-NULL and the len
    field of dataptr must have a value of 0 or greater.  To send the control
    part of a message, the corresponding values must be set for ctlptr.  No
    data (control) part is sent if either dataptr (ctlptr) is NULL or the len
    field of dataptr (ctlptr) is set to -1.

    If a control part is specified, and flags is set to RSHIPRI, a priority
    message is sent.  If flags is set to 0, a non-priority message is sent.
    If no control part is specified, and flags is set to RSHIPRI, putmsg
    fails and sets errno to EINVAL.  If no control part and no data part are
    specified, and flags is set to 0, no message is sent, and 0 is returned.

    For non-priority messages, putmsg blocks if the stream write queue is
    full due to internal flow control conditions.  For priority messages,
    putmsg does not block on this condition.  For non-priority messages,
    putmsg does not block when the write queue is full and ONONBLOCK is set.
    Instead, it fails and sets errno to EAGAIN.

    The putmsg system call also blocks, unless prevented by lack of internal
    resources, waiting for the availability of message blocks in the stream,
    regardless of priority or whether ONONBLOCK has been specified.  No par-
    tial message is sent.

    The putmsg system call fails if one or more of the following is true:


    [EAGAIN]       1. A non-priority message was specified, the ONONBLOCK
                   flag is set, and the  stream write queue is full due to
                   internal flow control conditions.

                   2. Buffers could not be allocated for the message that was
                   to be created.

    [EBADF]        fd is not a valid file descriptor open for writing.

    [EFAULT]       ctlptr or dataptr points outside the allocated address
                   space.

    [EINTR]        A signal was caught during the putmsg system call.

    [EINVAL]       1. An undefined value was specified in flags, or flags is
                   set to RSHIPRI and no control part was supplied.

                   2. The stream referenced by fd is linked below a multi-
                   plexer.

    [ENOSTR]       A stream is not associated with fd.

    [ENXIO]        A hangup condition was generated downstream for the speci-
                   fied stream.

    [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.

    A putmsg also fails if a STREAMS error message had been processed by the
    stream head before the call to putmsg.  The error returned is the value
    contained in the STREAMS error message.

 Diagnostics

    Upon successful completion, a value of 0 is returned.  Otherwise, a value
    of -1 is returned and errno is set to indicate the error.

 See also

    getmsg(S), poll(S), read(S), write(S)

 Standards conformance

    putmsg is conformant with:
    AT&T SVID Issue 2.