Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
getmsg(2)			 System	Calls			     getmsg(2)

NAME
       getmsg, getpmsg - get next message off a	stream

SYNOPSIS
       #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 *bandp, int *flagsp);

DESCRIPTION
       The  getmsg()  function	retrieves  the contents	of a message (see  in-
       tro(2)) located at  the stream head read	queue from a STREAMS file, and
       places  the  contents  into  user specified buffer(s). The message must
       contain either a	data part, a control part, or both. The	data and  con-
       trol  parts  of	the  message are placed	into separate buffers,	as de-
       scribed below. The semantics of each part is  defined  by  the  STREAMS
       module that generated  the message.

       The   getpmsg() function	behaved	like getmsg(), but provides finer con-
       trol over the priority of the messages received.	 Except	 where	noted,
       all information pertaining to getmsg() also pertains to getpmsg().

       The  fildes  argument  specifies	 a file	descriptor referencing an open
       stream.	The ctlptr and dataptr arguments each point to a strbuf	struc-
       ture, which contains the	following members:

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

       The buf member points to	a buffer into which the	data or	control	infor-
       mation is to be placed, and the maxlen  member  indicates  the  maximum
       number  of  bytes  this buffer can hold.	On return, the len member con-
       tains the number	of bytes of data or control information	 actually  re-
       ceived;	0  if there is a zero-length control or	data part; or -1 if no
       data or control information is present in the message. The flagsp argu-
       ment  should point to an	integer	that indicates the type	of message the
       user is able to receive,	as described below.

       The ctlptr argument holds the control part from	the  message  and  the
       dataptr	argument   holds the data part from the	message. If ctlptr (or
       dataptr)	is NULL	or the maxlen member is	-1,   the  control  (or	 data)
       part  of	 the  message  is not processed	and is left on the stream head
       read queue. If ctlptr (or dataptr) is not NULL and there	is  no	corre-
       sponding	control	(or data) part of the messages on the stream head read
       queue, 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 zero 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,  respectively, 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 non-zero return value is provided, as described below under
       RETURN VALUES.

       By  default,  getmsg()  processes  the  first  available	message	on the
       stream head read	queue. A user may, however, choose  to	retrieve  only
       high  priority messages by setting  the integer pointed to by flagsp to
       RS_HIPRI. In this case, getmsg()	processes the next message only	if  it
       is a high priority message.

       If  the	integer	pointed	to by flagsp is	0, getmsg() retrieves any mes-
       sage available on the stream head read queue. 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 to 0 otherwise.

       For getpmsg(), the flagsp argument points to a bitmask with the follow-
       ing 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 user may choose to retrieve only high-prior-
       ity messages 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	it is a	high-priority  message.	 In  a
       similar manner, a user may choose to retrieve a message from a particu-
       lar 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 user just	 wants
       to  get	the  first  message  off  the queue, the integer pointed to by
       flagsp should be	set to MSG_ANY and the integer	pointed	 to  by	 bandp
       should be set to	0. On return, if the message retrieved was a high-pri-
       ority 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.	Other-
       wise, 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_NDELAY and O_NONBLOCK are clear, getmsg() blocks until  a  message
       of  the	type  specified	by flagsp is available on the stream head read
       queue. If O_NDELAY or O_NONBLOCK	has been set  and  a  message  of  the
       specified  type	is  not	 present on the	read queue, getmsg() fails and
       sets errno to EAGAIN.

       If a hangup occurs on the stream	from which  messages  are  to  be  re-
       trieved,	 getmsg()  continues  to operate normally, as described	above,
       until the  stream head read queue is empty.  Thereafter,	it  returns  0
       in the len member of ctlptr and	dataptr.

RETURN VALUES
       Upon  successful	completion, a non-negative value is returned. A	return
       value of	0 indicates that a full	message	was read successfully.	A  re-
       turn  value of MORECTL indicates	that more control information is wait-
       ing for retrieval. A return value of MOREDATA indicates that more  data
       are  waiting for	retrieval.  A return value of MORECTL |	MOREDATA indi-
       cates that both types of	information remain. Subsequent getmsg()	 calls
       retrieve	the remainder of the message.  However,	if a message of	higher
       priority	has been received by the stream	head read queue, the next call
       to  getmsg() will retrieve that higher priority message before retriev-
       ing the remainder of the	previously received partial message.

ERRORS
       The getmsg() and	getpmsg() functions will fail if:

       EAGAIN
	     The O_NDELAY or O_NONBLOCK	flag is	set and	no messages are	avail-
	     able.

       EBADF The fildes	argument is not	a valid	file descriptor	open for read-
	     ing.

       EBADMSG
	     Queued message to be read is not valid for	getmsg.

       EFAULT
	     The ctlptr, dataptr, bandp, or flagsp argument points to an ille-
	     gal address.

       EINTR A signal was caught during	the execution of the getmsg function.

       EINVAL
	     An	 illegal  value	 was specified in flagsp, or the stream	refer-
	     enced by fildes is	linked under a multiplexor.

       ENOSTR
	     A stream is not associated	with fildes.

       The getmsg() function can also fail if a	STREAMS	error message had been
       received	 at the	stream head before the call to getmsg(). The error re-
       turned is the value contained in	the STREAMS error message.

SEE ALSO
       intro(2), poll(2), putmsg(2), read(2), write(2)

       STREAMS Programming Guide

SunOS 5.9			  29 Jul 1991			     getmsg(2)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=getmsg&sektion=2&manpath=SunOS+5.9>

home | help