putmsg(2)                           CLIX                           putmsg(2)



  NAME

    putmsg - Sends a message on a stream

  LIBRARY

    Standard C Library (libc.a)

  SYNOPSIS

    #include <stropts.h>

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

  PARAMETERS

    fd        Specifies a file descriptor that references an open STREAMS
              device.

    ctlptr    Points to a structure that contains the control part of the
              message.

    dataptr   Points to a structure that contains the data part of the
              message.

    flags     Specifies the priority of the message.

  DESCRIPTION

    The putmsg() function creates a message (see the intro() function)  from
    user specified buffers 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.

    The fd parameter specifies a file descriptor referencing an open stream.
    The ctlptr and dataptr parameters each point to a strbuf structure
    containing the following members:

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

    The ctlptr parameter 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



  2/94 - Intergraph Corporation                                              1

  putmsg(2)                           CLIX                           putmsg(2)



    the len member indicates the number of bytes to be sent.  The maxlen
    member is not used in putmsg().  (See the getmsg() function.)  In a
    similar manner, dataptr specifies the data, if any, to be included in the
    message.  The value of 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
    member 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 will be sent if either dataptr (ctlptr) is NULL or the
    len member 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 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 condition.  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.

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

  EXAMPLES

    To send a high priority message:

    if (putmsg(fd, ctlptr, dataptr, RS_HIPRI) == -1)
         perror("Putmsg failed");


  RETURN VALUES

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

  ERRORS

    The putmsg() function fails if one or more of the following are true:

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

    [EAGAIN]   Buffers could not be allocated for the message that was to be



  2                                              Intergraph Corporation - 2/94

  putmsg(2)                           CLIX                           putmsg(2)



               created.

    [EBADF]    The value of fd does not represent a valid file descriptor open
               for writing.

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

    [EINTR]    A signal was caught during the putmsg() function.

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

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

  RELATED INFORMATION

    Functions:  intro(2), read(2), getmsg(2), poll(2), write(2)

    AT&T UNIX System V STREAMS Primer, AT&T UNIX System V STREAMS Programmer's
    Guide
















  2/94 - Intergraph Corporation                                              3