unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

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 *restrict ctlptr, struct strbuf
       *restrict dataptr, int *restrict flagsp);

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

DESCRIPTION
       The  getmsg()  function  retrieves  the  contents  of  a  message  (see
       intro(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
       described 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
       received; 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
       retrieved, 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
       return value of MORECTL indicates  that  more  control  information  is
       waiting  for  retrieval. A return value of MOREDATA indicates that more
       data are waiting for retrieval. A return value of  MORECTL  |  MOREDATA
       indicates  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
       retrieving 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 available.



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



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



       EFAULT          The  ctlptr,  dataptr, bandp, or flagsp argument points
                       to an illegal address.



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



       EINVAL          An illegal value was specified in flagsp, or the stream
                       referenced 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
       returned is the value contained in the STREAMS error message.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:


       tab()    allbox;    cw(2.750000i)|     cw(2.750000i)     lw(2.750000i)|
       lw(2.750000i).   ATTRIBUTE TYPEATTRIBUTE VALUE Interface StabilityStan-
       dard


SEE ALSO
       intro(2), poll(2), putmsg(2), read(2), write(2),  attributes(5),  stan-
       dards(5)

       STREAMS Programming Guide




SunOS 5.10                        1 Nov 2001                         getmsg(2)