200 lines
7.9 KiB
Groff
200 lines
7.9 KiB
Groff
'\"macro stdmacro
|
|
.if n .pH g2.getmsg @(#)getmsg 41.4 of 5/26/91
|
|
.\" Copyright 1991 UNIX System Laboratories, Inc.
|
|
.\" Copyright 1989, 1990 AT&T
|
|
.nr X
|
|
.if \nX=0 .ds x} getmsg 2 "" "\&"
|
|
.if \nX=1 .ds x} getmsg 2 ""
|
|
.if \nX=2 .ds x} getmsg 2 "" "\&"
|
|
.if \nX=3 .ds x} getmsg "" "" "\&"
|
|
.if \nX=4 .ds x} getmsg "NS_OS" "EXTENSION" " "
|
|
.TH \*(x}
|
|
.SH NAME
|
|
\f4getmsg\f1 \- get next message off a stream
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.na
|
|
\f4#include <stropts.h>\fP
|
|
.HP
|
|
\f4int getmsg(int fd, struct strbuf *ctlptr,
|
|
struct strbuf *dataptr, int *flagsp);\fP
|
|
.HP
|
|
\f4int getpmsg(int fd, struct strbuf *ctlptr,
|
|
struct strbuf *dataptr, int *bandp, int *flagsp);\fP
|
|
.fi
|
|
.ad
|
|
.SH DESCRIPTION
|
|
\f4getmsg\fP retrieves the contents of a message [see \f4intro\fP(2)] located at
|
|
the stream head read queue from a \s-1STREAMS\s0 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 \s-1STREAMS\s0 module that generated
|
|
the message.
|
|
.P
|
|
The function \f4getpmsg\f1 does the same thing as \f4getmsg\fP,
|
|
but provides finer control over the priority of the messages received.
|
|
Except where noted, all information pertaining to \f4getmsg\fP also
|
|
pertains to \f4getpmsg\fP.
|
|
.P
|
|
\f2fd\f1 specifies a file descriptor referencing an open stream.
|
|
\f2ctlptr\f1 and \f2dataptr\f1 each point to a \f4strbuf\f1 structure,
|
|
which contains the following members:
|
|
.P
|
|
.RS
|
|
.nf
|
|
.ft 4
|
|
int maxlen; /* maximum buffer length */
|
|
int len; /* length of data */
|
|
char *buf; /* ptr to buffer */
|
|
.ft 1
|
|
.fi
|
|
.RE
|
|
.P
|
|
\f4buf\f1 points to a buffer in which the data or control information is to
|
|
be placed, and \f4maxlen\f1 indicates the maximum number of bytes
|
|
this buffer can hold.
|
|
On return, \f4len\f1 contains the number of bytes of data or control information
|
|
actually received,
|
|
or 0 if there is a zero-length control or data part,
|
|
or -1 if no data or control information is present in the message.
|
|
\f2flagsp\f1 should point to an integer that indicates the type of message the
|
|
user is able to receive.
|
|
This is described later.
|
|
.PP
|
|
\f2ctlptr\f1 is used to hold the control part from the message and \f2dataptr\f1
|
|
is used to hold the data part from the message.
|
|
If \f2ctlptr\f1 (or \f2dataptr\f1) is \f4NULL\fP or the \f4maxlen\f1 field is \-1,
|
|
the control (or data) part of the message is not processed and is left on the
|
|
stream head read queue.
|
|
If \f2ctlptr\f1 (or \f2dataptr\f1) is not \f4NULL\fP and there is no
|
|
corresponding control (or data) part of the messages on the stream head
|
|
read queue,
|
|
\f4len\f1 is set to \-1.
|
|
If the \f4maxlen\f1 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 \f4len\f1 is set to 0.
|
|
If the \f4maxlen\f1 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 \f4len\f1 is set to 0.
|
|
If the \f4maxlen\f1 field in \f2ctlptr\f1 or \f2dataptr\f1 is less than,
|
|
respectively, the control or data part of the message, \f4maxlen\f1 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
|
|
\s-1DIAGNOSTICS\s0.
|
|
.PP
|
|
By default, \f4getmsg\fP processes the first available message on the
|
|
stream head read queue.
|
|
However, a user may choose to retrieve only high priority messages by setting
|
|
the integer pointed by \f2flagsp\f1 to \f4RS_HIPRI\fP.
|
|
In this case, \f4getmsg\fP processes the next message only if it is a high
|
|
priority message.
|
|
If the integer pointed by \f2flagsp\f1 is 0, \f4getmsg\fP retrieves any message
|
|
available on the stream head read queue.
|
|
In this case, on return, the integer pointed to by \f2flagsp\fP will be set to
|
|
\f4RS_HIPRI\fP if a high priority message was retrieved, or 0 otherwise.
|
|
.PP
|
|
For \f4getpmsg\f1, the flags are different.
|
|
\f2flagsp\f1 points to a bitmask with the following
|
|
mutually-exclusive flags defined:
|
|
\f4MSG_HIPRI, MSG_BAND\f1, and \f4MSG_ANY\f1.
|
|
Like \f4getmsg\f1,
|
|
\f4getpmsg\f1 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 \f2flagsp\f1 to \f4MSG_HIPRI\f1
|
|
and the integer pointed to by \f2bandp\f1 to 0.
|
|
In this case, \f4getpmsg\f1 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 \f2flagsp\f1 to \f4MSG_BAND\f1 and the integer
|
|
pointed to by \f2bandp\f1 to the priority band of interest.
|
|
In this case, \f4getpmsg\f1 will only process the next message if it is in
|
|
a priority band equal to, or greater than, the integer pointed to
|
|
by \f2bandp\f1, 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 \f2flagsp\f1 should be set to \f4MSG_ANY\f1
|
|
and the integer pointed to by \f2bandp\f1 should be set to 0.
|
|
On return, if the message retrieved was a high-priority message,
|
|
the integer pointed to by \f2flagsp\f1 will
|
|
be set to \f4MSG_HIPRI\f1 and the integer pointed to by \f2bandp\f1 will
|
|
be set to 0.
|
|
Otherwise, the integer pointed to by \f2flagsp\f1 will
|
|
be set to \f4MSG_BAND\f1 and the integer pointed to by \f2bandp\f1 will
|
|
be set to the priority band of the message.
|
|
.PP
|
|
If \f4O_NDELAY\fP and \f4O_NONBLOCK\fP are clear, \f4getmsg\fP blocks until a message
|
|
of the type specified by \f2flagsp\f1 is available on the stream head read
|
|
queue.
|
|
If \f4O_NDELAY\fP or \f4O_NONBLOCK\fP has been set and a message of the specified
|
|
type
|
|
is not present on the read queue, \f4getmsg\fP fails
|
|
and sets \f4errno\f1 to \f4EAGAIN\fP.
|
|
.P
|
|
If a hangup occurs on the stream from which messages are to be retrieved,
|
|
\f4getmsg\fP continues to operate normally, as described above, until the
|
|
stream head read queue is empty.
|
|
Thereafter, it returns 0 in the \f4len\f1 fields of \f2ctlptr\f1 and
|
|
\f2dataptr\f1.
|
|
.P
|
|
\f4getmsg\fP or \f4getpmsg\f1 will fail if one or more of the following are true:
|
|
.TP 15
|
|
\f4EAGAIN\fP
|
|
The \f4O_NDELAY\fP or \f4O_NONBLOCK\fP flag is set, and no messages are available.
|
|
.TP
|
|
\f4EBADF\fP
|
|
\f2fd\f1 is not a valid file descriptor open for reading.
|
|
.TP
|
|
\f4EBADMSG\fP
|
|
Queued message to be read is not valid for \f4getmsg\fP.
|
|
.TP
|
|
\f4EFAULT\fP
|
|
\f2ctlptr\f1, \f2dataptr\f1, \f2bandp\fP, or \f2flagsp\f1 points to a location
|
|
outside the allocated address space.
|
|
.TP
|
|
\f4EINTR\fP
|
|
A signal was caught during the \f4getmsg\fP system call.
|
|
.TP
|
|
\f4EINVAL\fP
|
|
An illegal value was specified in \f2flagsp\f1,
|
|
or the stream referenced by \f2fd\f1 is linked under a multiplexor.
|
|
.TP
|
|
\f4ENOSTR\fP
|
|
A stream is not associated with \f2fd\f1.
|
|
.TP
|
|
\f4EIO\fP
|
|
\f2fildes\fP points to an open device that is in the process of
|
|
closing.
|
|
.TP
|
|
\f4EACCES\fP
|
|
\f2fildes\fP points to a dynamic device and read permission on the
|
|
device is denied.
|
|
.PP
|
|
\f4getmsg\fP can also fail if a \s-1STREAMS\s0 error message had been received
|
|
at the stream head before the call to \f4getmsg\fP.
|
|
The error returned is the value contained in the \s-1STREAMS\s0 error message.
|
|
.SH "SEE ALSO"
|
|
.nf
|
|
\f4intro\fP(2), \f4poll\fP(2), \f4putmsg\fP(2), \f4read\fP(2), \f4write\fP(2)
|
|
.fi
|
|
.SH DIAGNOSTICS
|
|
Upon successful completion, a non-negative value is returned.
|
|
A value of 0 indicates that a full message was read successfully.
|
|
A return value of
|
|
\f4MORECTL\fP
|
|
indicates that more control information is waiting for retrieval.
|
|
A return value of
|
|
\f4MOREDATA\fP
|
|
indicates that more data is waiting for retrieval.
|
|
A return value of \f4MORECTL | MOREDATA\fP
|
|
indicates that both types of information remain.
|
|
Subsequent \f4getmsg\fP calls retrieve the remainder of the message.
|
|
However, if a message of higher priority has come in on the stream head read
|
|
queue, the next call to
|
|
\f4getmsg\f1 will retrieve
|
|
that higher priority message before retrieving the remainder of the
|
|
previously received partial message.
|
|
.Ee
|