unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

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

GETMSG(2)                     System Calls Manual                    GETMSG(2)



NAME
       getmsg - get next message from a stream

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

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

DESCRIPTION
       getmsg()  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  mes-
       sage  are placed into separate buffers, as described below.  The seman-
       tics of each part is defined by the STREAMS module that  generated  the
       message.

       fd  specifies a file descriptor referencing an open stream.  ctlptr and
       dataptr each point to a strbuf structure that  contains  the  following
       members:

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

       where  buf  points to a buffer in which the data or control information
       is to be placed, and maxlen indicates the maximum number of bytes  this
       buffer  can  hold.  On return, len contains the number of bytes of data
       or control information actually received, or is 0 if there is  a  zero-
       length control or data part, or is -1 if no data or control information
       is present in the message.  flags  may  be  set  to  the  values  0  or
       RS_HIPRI and is used as described below.

       ctlptr is used to hold the control part from the message and dataptr is
       used to hold the data part from the message.  If ctlptr (or dataptr) is
       a NULL pointer or the maxlen field is -1, the control (or data) part of
       the message is not processed and is left on the stream head read  queue
       and  len  is set to -1.  If the maxlen field 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 field 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 field in ctlptr or dataptr is less than, respectively, the  con-
       trol  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.  If information is retrieved from  a  priority  message,
       flags is set to RS_HIPRI on return.

       By  default, getmsg() processes the first priority or non-priority mes-
       sage available on the stream head read queue.  However, a  process  may
       choose to retrieve only priority messages by setting flags to RS_HIPRI.
       In this case, getmsg() will only process the next message if  it  is  a
       priority message.

       If  O_NDELAY  has not been set, getmsg() blocks until a message, of the
       type(s) specified by flags (priority or either), is  available  on  the
       stream  head read queue.  If O_NDELAY has been set and a message of the
       specified type(s) 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() will continue to  operate  normally,  as  described
       above,  until the stream head read queue is empty.  Thereafter, it will
       return 0 in the len fields of ctlptr and dataptr.

RETURN VALUES
       getmsg() returns a non-negative value on success:

              0                        A full message was read successfully.

              MORECTL                  More control information is waiting for
                                       retrieval.   Subsequent  getmsg() calls
                                       will retrieve the rest of the message.

              MOREDATA                 More data are  waiting  for  retrieval.
                                       Subsequent getmsg() calls will retrieve
                                       the rest of the message.

              MORECTL | MOREDATA       Both types of information remain.

       On failure, getmsg() returns -1 and sets errno to indicate the error.

ERRORS
       EAGAIN         The O_NDELAY flag is set, and no messages are available.

       EBADF          fd is not a valid file descriptor open for reading.

       EBADMSG        The queued message to be read is not valid for getmsg().

       EFAULT         ctlptr, dataptr, or flags points to a  location  outside
                      the allocated address space.

       EINTR          A signal was caught during the getmsg() system call.

       EINVAL         An illegal value was specified in flags.

                      The  stream  referenced  by  fd is linked under a multi-
                      plexor.

       ENOSTR         A stream is not associated with fd.

       A getmsg() 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.

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



                                21 January 1990                      GETMSG(2)