| |
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 control information is present in the message. The flagsp argument 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 corresponding 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 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 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-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.
|
