getmsg() -- System Call (libc)

Get the next message from a stream
#include <stropts.h>
int getmsg (fd, ctlptr, dataptr, flagsp)
int fd; struct strbuf *ctlptr, dataptr; int *flagsp;

getmsg() retrieves  a message from a  STREAMS file, and writes  it into the
buffer or buffers that you specify.   The message must contain a data part,
a control part, or both.  getmsg() writes each part into its own buffer, as
described below.  The STREAMS module that generated the message defines the
semantics of each part.

fd gives  the file descriptor  that references the stream  whose message is
being  retrieved.  ctlptr  and dataptr  each point to  a structure  of type
strbuf, which contains the following members:

    int maxlen; Maximum buffer length
    int len;    Length of data
    void  *buf; Pointer to buffer

ctlptr holds  the message's control  part, and dataptr its  data part.  buf
points to  the buffer into which  the data or control  information is to be
written, and maxlen gives the maximum  number of bytes the buffer can hold.
getmsg()  initializes  len  to the  number  of  bytes  of  data or  control
information that  it actually wrote  into buf. It  sets len to  zero if the
part in question has a length of zero; and it sets len to -1 if the message
does not contain the part in question.

flagsp points  to an integer  that indicates the  type of messages  you can
receive; this is discussed in detail below.

getmsg() has special behaviors, corresponding to the settings of ctlptr and
dataptr, and of the structures to which they point:

-> If either  ctlptr or dataptr is  NULL, or if maxlen  equals -1, getmsg()
   does not process the corresponding  part of the message.  The message is
   left on the stream head's read queue.

-> If  ctlptr or  dataptr is  not  NULL, but  the message  does not  have a
   corresponding part, getmsg() sets len to -1.

-> If maxlen equals  zero and there is a zero-length  control or data part,
   getmsg() removes  the zero-length part from the read  queue and sets len
   to zero  If maxlen  equals zero  and the corresponding  section contains
   more than zero bytes of information, getmsg() leaves that information on
   the read queue and sets len to zero.

-> If maxlen is  less than than the corresponding part  of the message (the
   control  part  for  ctlptr and  the  data  part  for dataptr),  getmsg()
   retrieves maxlen  bytes.  It leaves the remainder of  the message on the
   stream  head's  read queue  and  returns and  a  non-zero return  value.
   Details are given below.

Flags

The following summarizes what flags are available, and what they mean.

-> By default, getmsg() processes the first available message on the stream
   head's read  queue.  However,  you can choose  to retrieve only  a high-
   priority message: just insert  RS_HIPRI into the integer to which flagsp
   points.  In this case, getmsg() processes the next message only if it is
   a high-priority message.

-> If the  integer to which  flagsp points equals  zero, getmsg() retrieves
   any message available on the stream head's read queue.  In this case, if
   getmsg() retrieves  a high-priority message,  it sets to  the integer to
   which  flagsp points  to RS_HIPRI;  if  the message  does not  have high
   priority, it sets that integer to zero.

-> If  flags O_NDELAY  and O_NONBLOCK  are not  set as  part of  the global
   settings for fd (for details, see the Lexicon entry for open()),
   getmsg() blocks  execution of your  program until a message  of the type
   specified by  flagsp is available  on the stream head's  read queue.  If
   either  O_NDELAY  or  O_NONBLOCK has  been  set  and  a  message of  the
   specified type is  not at the top of the  queue, getmsg() fails and sets
   errno to EAGAIN.

If a hangup  occurs on the stream from which  messages are to be retrieved,
getmsg() operates  normally until  the stream  head's read queue  is empty.
Thereafter, it returns zero in the len fields of both ctlptr and dataptr.

Return Values

If all  goes well, getmsg()  returns a non-negative  value.  Zero indicates
that a full message was read successfully.

MORECTL and MOREDATA  indicate, respectively, that more control information
or more  data are awaiting retrieval; whereas  MORECTL | MOREDATA indicates
that more of both types information remain in the queue, to be retrieved by
subsequent calls to getmsg(). However,  if a message of higher priority has
come into the stream head's read queue, the next call to getmsg() retrieves
that  higher-priority  message  and  the  information  remaining  from  the
partially retrieved message remains on the queue.

Errors

getmsg() fails if any of the following conditions are true:

-> Either of  the flags  O_NDELAY or  O_NONBLOCK is set  but no  message is
   available.  getmsg() sets errno to EAGAIN.

-> fd is not a valid file descriptor.  getmsg() sets errno to EBADF.

-> The next  message in the read  queue is not valie  for getmsg() to read.
   getmsg() sets errno to EBADMSG.

-> ctlptr, dataptr,  or flagsp contains an  illegal address.  getmsg() sets
   errno to EFAULT.

-> A signal  was caught as getmsg() was executing.   getmsg() sets errno to
   EINTR.

-> flagsp holds  an unrecognized value,  or the stream referenced  by fd is
   linked under a multiplexor.  getmsg() sets errno to EINVAL.

-> fd does not describe a stream.  getmsg() sets errno to ENOSTR.

getmsg() also  fails if the stream header receives  a STREAMS error message
before getmsg() tries  to read it.  getmsg() then returns  the value in the
STREAMS error message.

See Also

libc,
putmsg(),
STREAMS,
stropts.h

© 2012 by Stephen A. Ness