unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 getmsg(2)							   getmsg(2)




 NAME
      getmsg, getpmsg - receive next message from a STREAMS file

 SYNOPSIS
      #include <&lt&lt&lt;stropts.h>&gt&gt&gt;

      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
      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 zero-
      length 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 Release 11i: November 2000






 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 Release 11i: November 2000






 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.

 MULTITHREAD USAGE
      The getmsg() and getpmsg() functions are safe to be called by
      multithreaded applications, and they are thread-safe for both POSIX
      Threads and DCE User Threads.  The getmsg() and getpmsg() functions
      have cancellation points. They are async-signal safe and fork-safe.
      They are not async-cancel safe.

 RETURN VALUE
      Upon successful completion, getmsg() and getpmsg() return a non-
      negative 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
      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.





 Hewlett-Packard Company	    - 3 -   HP-UX Release 11i: November 2000






 getmsg(2)							   getmsg(2)




 SEE ALSO
      poll(2), putmsg(2), read(2), write(2), <stropts.h>, streamio(7).




















































 Hewlett-Packard Company	    - 4 -   HP-UX Release 11i: November 2000