getpmsg(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   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  control  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  control  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 structure, 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  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; 0 if there is
     a zero-length control or data part; or -1 if no data or con-
     trol 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 mes-
     sage. If ctlptr (or dataptr) is NULL or the maxlen member is
     -1,   the  control (or data) part of the message is not pro-
     cessed and is left on the stream head read queue. If  ctlptr
     (or  dataptr) is not NULL and there is no corresponding con-
     trol (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,  max-
     len 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 message 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  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
     user may choose to retrieve only high-priority  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 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 user just wants to get the first mes-
     sage 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-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_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  wait-
     ing  for  retrieval.   A  return value of MORECTL | MOREDATA
     indicates that both types of information remain.  Subsequent
     getmsg()  calls retrieve the remainder of the message.  How-
     ever, 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 multi-
           plexor.

     ENOSTR
           A stream is not associated with fildes.

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


SEE ALSO

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

     STREAMS Programming Guide


Man(1) output converted with man2html