PUTMSG(2-SVR3)      RISC/os Reference Manual       PUTMSG(2-SVR3)



NAME
     putmsg - send a message on a stream

SYNOPSIS
     #include <stropts.h>

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

DESCRIPTION
     putmsg creates a message [see intro(2)] from user specified
     buffer(s) and sends the message to a STREAMS file.  The mes-
     sage 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 indicates the number
     of bytes to be sent.  The maxlen field is not used in putmsg
     [see getmsg(2)].  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 RS_HIPRI 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 (con-
     trol) part will be 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
     RS_HIPRI, 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 RS_HIPRI, 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,



                        Printed 11/19/92                   Page 1

PUTMSG(2-SVR3)      RISC/os Reference Manual       PUTMSG(2-SVR3)



     and 0 is returned.

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

     putmsg also blocks, unless prevented by lack of internal
     resources, waiting for the availability of message blocks in
     the stream, regardless of priority or whether O_NDELAY has
     been specified.  No partial message is sent.

ERRORS
     putmsg fails if one or more of the following are true:

     [EAGAIN]                 A non-priority message was speci-
                              fied, the O_NDELAY flag is set and
                              the  stream write queue is full due
                              to internal flow control condi-
                              tions.

     [EAGAIN]                 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]                 An undefined value was specified in
                              flags, or flags is set to RS_HIPRI
                              and no control part was supplied.

     [EINVAL]                 The stream referenced by fd is
                              linked below a multiplexor.

     [ENOSTR]                 A stream is not associated with fd.

     [ENXIO]                  A hangup condition was generated
                              downstream for the specified
                              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



 Page 2                 Printed 11/19/92

PUTMSG(2-SVR3)      RISC/os Reference Manual       PUTMSG(2-SVR3)



                              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 pro-
     cessed by the stream head before the call to putmsg.  The
     error returned is the value contained in the STREAMS error
     message.

SEE ALSO
     intro(2), read(2), getmsg(2), poll(2), write(2).
     STREAMS Primer.
     STREAMS Programmer's Guide.

DIAGNOSTICS
     Upon successful completion, a value of 0 is returned.  Oth-
     erwise, a value of -1 is returned and errno is set to indi-
     cate the error.
































                        Printed 11/19/92                   Page 3