getmsg(2)                                                         getmsg(2)




 NAME    [Toc]    [Back]
      getmsg, getpmsg - receive next message from a STREAMS file

 SYNOPSIS    [Toc]    [Back]
      #include <stropts.h>

      int getmsg(
           int fildes,
           struct strbuf *ctlptr,
           struct strbuf *dataptr,
           int *flagsp
      );

      int getpmsg(
           int fildes,
           struct strbuf *ctlptr,
           struct strbuf *dataptr,
           int *band,
           int *flagsp
      );

 DESCRIPTION    [Toc]    [Back]
      The getmsg() function retrieves the contents of a message located at
      the head of the stream head read queue associated with a STREAMS file
      and places the contents into one or more buffers.  The message
      contains either a data part, a control part, or both.  The data and
      control parts of the message are placed into separate buffers, as
      described below.  The semantics of each part is defined by the
      originator of the message.

      The getpmsg() function does the same thing as getmsg(), but provides
      finer control over the priority of the messages received.  Except
      where noted, all requirements on getmsg() also pertain to getpmsg().

      The fildes argument specifies a file descriptor referencing a
      STREAMS-based file.

      The ctlptr and dataptr arguments each point to a strbuf structure, in
      which the buf member points to a buffer in which the data or control
      information is to be placed, and the maxlen member indicates the
      maximum number of bytes this buffer can hold.  On return, the len
      member contains the number of bytes of data or control information
      actually received.  The len member is set to 0 if there is a zerolength
 control or data part and len is set to -1 if no data or control
      information is present in the message.

      When getmsg() is called, flagsp should point to an integer that
      indicates the type of message the process is able to receive.  This is
      described further below.





 Hewlett-Packard Company            - 1 -   HP-UX 11i Version 2: August 2003






 getmsg(2)                                                         getmsg(2)




      The ctlptr argument is used to hold the control part of the message,
      and dataptr is used to hold the data part of the message.  If ctlptr
      (or dataptr) is a null pointer or the maxlen members is -1, the
      control (or data) part of the message is not processed and is left on
      the stream head read queue, and if the ctlptr (or dataptr) is not a
      null pointer, len is set to -1.  If the maxlen member is set to 0 and
      there is a zero-length control (or data) part, that zero-length part
      is removed from the read queue and len is set to 0.  If the maxlen
      member is set to 0 and there are more than 0 bytes of control (or
      data) information, that information is left on the read queue and len
      is set to 0.  If the maxlen member in ctlptr (or dataptr) is less than
      the control (or data) part of the message, maxlen bytes are retrieved.
      In this case, the remainder of the message is left on the stream head
      read queue and a on-zero return value is provided.

      By default, getmsg() processes the first available message on the
      stream head read queue.  However, a process may choose to retrieve
      only high-priority messages by setting the integer pointed to by
      flagsp to RS_HIPRI.  In this case, getmsg() will only process the next
      message if it is a high-priority message.  When the integer pointed to
      by flagsp is 0, any message will be retrieved.  In this case, on
      return, the integer pointed to by flagsp will be set to RS_HIPRI if a
      high-priority message was retrieved, or 0 otherwise.

      For getpmsg(), the flags are different.  The flagsp argument points to
      a bitmask with the following mutually-exclusive flags defined.
      MSG_HIPRI, MSG_BAND, and MSG_ANY.  Like getmsg(), getpmsg() processes
      the first available message on the stream head read queue.  A process
      may choose to retrieve only high-priority message by setting the
      integer pointed to by flagsp to MSG_HIPRI and the integer pointed to
      by bandp to 0.  In this case, getpmsg() will only process the next
      message if is a high-priority message.  In a similar manner, a process
      may choose to retrieve a message from a particular priority band by
      setting the integer pointed to by flagsp to MSG_BAND and the integer
      pointed to by bandp to the priority band of interest.  In this case,
      getpmsg() will only process the next message if it is in a priority
      band equal to, or greater than, the integer pointed to by bandp, or if
      it is a high-priority message.  If a process just wants to get the
      first message off the queue, the integer pointed to by bandp should be
      set to 0.  On return, if the message retrieved was a high-priority
      message, the integer pointed to by flagsp will be set to MSG_HIPRI and
      the integer pointed to by bandp will be set to 0.  Otherwise, the
      integer pointed to by flagsp will be set to MSG_BAND and the integer
      pointed to by bandp will be set to the priority band of the message.

      If O_NONBLOCK is not set, getmsg() and getpmsg() will not block until
      a message of the type specified by flagsp is available at the front of
      the stream head read queue.  If O_NONBLOCK is set and a message of the
      specified type is not present at the front of the read queue, getmsg()
      and getpmsg() fail and set errno to [EAGAIN].




 Hewlett-Packard Company            - 2 -   HP-UX 11i Version 2: August 2003






 getmsg(2)                                                         getmsg(2)




      If a hangup occurs on the stream from which messages are to be
      retrieved, getmsg() and getpmsg() continue to operate normally, as
      described above, until the stream head read queue is empty.
      Thereafter, they return 0 in the len members of ctlptr and dataptr.

 RETURN VALUE    [Toc]    [Back]
      Upon successful completion, getmsg() and getpmsg() return a nonnegative
 value.  A value of 0 indicates that a full message was read
      successfully.  A return value of MORECTL indicates that more control
      information is waiting for retrieval.  A return value of MOREDATA
      indicates that more data is waiting for retrieval.  A return value of
      the bitwise logical OR of MORECTL and MOREDATA indicates that both
      types of information remain.  Subsequent getmsg() and getpmsg() calls
      retrieve the remainder of the message.  However, if a message of
      higher priority has come in on the stream head read queue, the next
      call to getmsg() or getpmsg() retrieves that higher-priority message
      before retrieving the remainder of the previously-received partial
      message.

      Upon failure, getmsg() and getpmsg() return -1 and set errno to
      indicate the error.

 ERRORS    [Toc]    [Back]
      The getmsg() and getpmsg() functions will fail if:

           [EAGAIN]       The O_NONBLOCK flag is set and no messages are
                          available.

           [EBADF]        The fildes argument is not a valid file descriptor
                          open for reading.

           [EBADMSG]      The queued message to be read is not valid for
                          getmsg() or getpmsg() or a pending file descriptor
                          is at the stream head.

           [EINTR]        A signal was caught during getmsg() or getpmsg().

           [EINVAL]       An illegal value was specified by flagsp, or the
                          stream or multiplexor referenced by fildes is
                          linked (directly or indirectly) downstream from a
                          multiplexor.

           [ENOSTR]       A stream is not associated with fildes.

 SEE ALSO    [Toc]    [Back]
      poll(2), putmsg(2), read(2), write(2), thread_safety(5), streamio(7),
      <stropts.h>.


 Hewlett-Packard Company            - 3 -   HP-UX 11i Version 2: August 2003