unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



getmsg(2)							    getmsg(2)



NAME

  getmsg, getpmsg - Receives the next message from a Stream

LIBRARY

  Standard C Library (libc)

SYNOPSIS

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

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

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

STANDARDS

  Interfaces documented	on this	reference page conform to industry standards
  as follows:

  getmsg(), getpmsg(): XSH4.2

  Refer	to the standards(5) reference page for more information	about indus-
  try standards	and associated tags.

PARAMETERS

  fd	    Specifies a	file descriptor	that references	an open	Stream.

  ctlptr    Points to a	strbuf structure that holds the	control	part of	the
	    message. This strbuf structure is described	in the DESCRIPTION
	    section.

  dataptr   Points to a	strbuf structure that holds the	data part of the mes-
	    sage. This strbuf structure	is described in	the DESCRIPTION	sec-
	    tion.

  band	    Points to an integer that indicates	the priority band of the mes-
	    sage that the user is able to retrieve.

  flags	    Points to an integer that indicates	the type of message the	user
	    is able to retrieve.

DESCRIPTION

  The getmsg() and getpmsg() functions retrieve	the contents of	messages.
  These	messages are located at	the Stream head	read queue associated with a
  STREAMS file.	 Messages must contain a control part or a data	part, or
  both.	 The control and data parts of the message are placed into separate
  user-specified buffers, pointed at by	ctlptr and dataptr respectively.  The
  open Stream specifies	the format and semantics of the	message's control and
  data parts.  The getpmsg() function provides better control over the prior-
  ity of the messages received.	 Except	where specified, all information
  about	the getmsg() function also applies to the getpmsg() function.

  The ctlptr and dataptr parameters each point to a strbuf structure that
  contains three members.  This	structure is defined in	<&lt;sys/stropts.h>&gt;	as:

       struct strbuf {
	   int maxlen; /* maximum buffer length	*/
	   int len;    /* length of data */
	   char	*buf   /* ptr to buffer	*/
       };

  The members are:

  maxlen    Specifies the maximum number of bytes buf can hold.

  buf	    Points to the buffer where the control or data information is to
	    reside.

  len	    On return, contains	the number of bytes of control or data infor-
	    mation that	has actually been received.  The len parameter is set
	    to 0 (zero)	if there is a zero-length data or control part;	oth-
	    erwise, len	is set to -1 if	no control or data information is
	    contained in the message.

  The members of this structure	are also affected by the following.

    +  If the maxlen field is set to 0 (zero), and the control or data part
       is of zero-length, that zero-length part	is deleted from	the read
       queue of	the Stream head, and len is set	to 0 (zero).

    +  If the maxlen field is set to 0 (zero), and if the size of the control
       or data part is greater than 0 (zero), that part	remains	on the read
       queue and len is	set to 0 (zero).

    +  If the maxlen field for either the ctlptr or dataptr structure is less
       than the	size of	the control or data part of the	message, maxlen	bytes
       are retrieved and the rest of the message remains on the	Stream head
       read queue.   A nonzero value is	then returned.

    +  If the maxlen member is -1, or if ctlptr	or dataptr parameter is	a
       null pointer, the getmsg() function does	not process the	control	or
       the data	part of	the message.  The unprocessed part(s) then remains on
       the Stream head queue.

    +  If ctlptr or dataptr is not a null pointer, and if the read queue at
       the Stream head has no corresponding message control or data part, len
       is set to -1.

  One of the major differences between the getmsg() and	getpmsg() functions,
  in addition to the band parameter, is	how the	flags parameter	is used	to
  collect messages.  The getmsg() function processes messages as follows:

    +  By default, the getmsg()	function processes the first message that is
       available on the	Stream head queue.

    +  If you set the flags parameter to 0 (zero), any message will be
       retrieved.  On return, the integer pointed to by	the flags parameter
       will be set to RS_HIPRI if a high-priority message was retrieved; oth-
       erwise, a value of 0 (zero) is returned.

    +  If you set the flags parameter to RS_HIPRI, the getmsg()	function
       retrieves only the high-priority	messages.  The getmsg()	function then
       only processes the next message if it is	a high-priority	message.

  The getpmsg()	function flags parameter points	to a bitmask with the
  mutually-exclusive flags MSG_HIPRI, MSG_BAND,	and MSG_ANY defined.  The
  getpmsg() function processes messages	as follows:

    +  By default, the getpmsg() function processes the	first available	mes-
       sage on the Stream head read queue.

    +  If you set the integer pointed at by the	flags parameter	to MSG_HIPRI,
       and set the integer pointed to by the band parameter to 0 (zero), the
       getpmsg() function retrieves only high-priority messages.  The
       getpmsg() function then only processes the next message if it is	a
       high-priority message.

    +  If you set the integer pointed to by the	flags parameter	to MSG_BAND,
       and set the integer pointed to by the band parameter to the desired
       priority	band, the getpmsg() function retrieves a message from that
       band.  The getpmsg() function then only processes the next message if
       it is in	a high-priority	message, or if its priority band is at least
       equal to	the integer pointed to by band.

    +  If you set the integer pointed to by the	flags parameter	to MSG_ANY,
       and set the integer pointed to by the band parameter to 0 (zero), the
       getpmsg() function retrieves only the first message off the queue.
       When the	getpmsg() function returns, it then sets the flags and band
       parameters according to the type	of message that	was retrieved.	If
       the message was not a high-priority one,	the integer pointed to by the
       flags parameter is set to MSG_BAND and the integer pointed to by	band
       is set to the band of the message.  If the message was a	high-priority
       one, the	integer	pointed	to by the flags	is set to MSG_HIPRI and	the
       integer pointed to by band will be set to 0 (zero).

  If the O_NDELAY or O_NONBLOCK	flags are set and a message of the specified
  type is not present at the front of the read queue, the getmsg() function
  fails.  If the O_NDELAY or O_NONBLOCK	flags are not set for the read()
  operation, the getmsg() function blocks until	a message is available at the
  front	of the Stream head read	queue.	This message's type is specified by
  flags.

  [Tru64 UNIX]	Current	industry standards do not define the O_NDELAY flag.
  It is	included in the	preceding paragraphs for System	V compatibility.

  If the Stream	from which the messages	are being retrieved experiences	a
  hangup, the getmsg() function	does not fail.	Instead, it will continues as
  usual	until the read queue of	the Stream head	is empty.  Subsequent calls
  will return a	value of 0 (zero) in the len fields for	the ctlptr and
  dataptr structures.

RETURN VALUES

  Upon successful completion, the getmsg() and getmsg()	functions return non-
  negative values, as follows:

  0 (zero)  Indicates that a full message was successfully read.

  MORECTL   Indicates that more	control	information is waiting for retrieval.

  MOREDATA  Indicates that more	data is	waiting	for retrieval.

  MORECTL | MOREDATA
	    Indicates that both	types of information remain.  Later calls to
	    getmsg() then retrieve the rest of the message.  Note, however,
	    that higher-priority messages, although they may arrive later on
	    the	queue, take a higher precedence.  In other words, if a mes-
	    sage comes in later	on the read queue, the next call to the
	    getmsg() function retrieves	that higher-priority message first.
	    The	rest of	the earlier partial message is retrieved afterwards.

  Upon failure,	the getmsg() function returns a	value of -1, and sets errno
  to indicate an error.

ERRORS

  Both the getmsg() and	getpmsg() functions fail if a STREAMS error message
  is delivered to the Stream head read queue before the	call.  In this
  instance, the	STREAMS	error message contains the value of the	returned
  error.

  In addition, if any of the following conditions occurs, the getmsg() func-
  tion sets errno to the corresponding value:

  [EAGAIN]  The	O_NDELAY or O_NONBLOCK flag is set, and	no messages are
	    currently available.

	    [Tru64 UNIX]  Current industry standards do	not define the
	    O_NDELAY flag.  It is included in the preceding paragraph for
	    System V compatibility.

  [EFAULT]  An illegal address has been	specified in ctlptr or dataptr.

  [EBADF]   The	fd parameter is	not a valid file descriptor open for reading.

  [EBADMSG] The	message	on the read queue is not a control or data message,
	    or a file descriptor is pending at the Stream head.

  [EINTR]   The	getmsg() or getpmsg() function was interrupted by a signal
	    that was caught.

  [EINVAL]  An illegal value was specified by the flags	parameter, or the
	    Stream referenced by fd is linked under a multiplexor.

  [ENOSTR]  A Stream is	not associated with the	fd parameter.

RELATED	INFORMATION

  Functions: poll(2), putmsg(2), read(2), write(2)

  Interfaces: streamio(7)

  Standards: standards(5)