|
|
|
#include <stropts.h>
int getmsg(fd, ctlptr, dataptr, flags) int fd; struct strbuf *ctlptr; struct strbuf *dataptr; int *flags;
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 message are placed into separate buffers, as described below. The semantics 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 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. 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 message 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.
getmsg() returns a non-negative value on success:
On failure, getmsg() returns -1 and sets errno to indicate the error.
The stream referenced by fd is linked under a multiplexor.
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.
|
|
|
Created by unroff & hp-tools. © somebody (See intro for details). All Rights Reserved. Last modified 11/5/97