getmsg(2) CLIX getmsg(2)
NAME
getmsg - Gets the next message off a stream
LIBRARY
Standard C Library (libc.a)
SYNOPSIS
#include <stropts.h>
int getmsg(
int fd ,
struct strbuf *ctlptr ,
struct strbuf *dataptr ,
int *flags );
PARAMETERS
fd Specifies a file descriptor that references an open STREAMS
device.
ctlptr Points to a structure that will contain the control part of the
message.
dataptr Points to a structure that will contain the data part of the
message.
flags Specifies the priority of a message.
DESCRIPTION
The getmsg() function retrieves the contents of a message (see the intro()
function) located at the stream head read queue from a STREAMS file, and
places the contents into user specified buffers. 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 fd parameter specifies a file descriptor referencing an open stream.
The ctlptr and dataptr parameters 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 */
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
2/94 - Intergraph Corporation 1
getmsg(2) CLIX getmsg(2)
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. The flags parameter may be set to the values 0 or RS_HIPRI and
is used as described below.
The ctlptr parameter 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 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 and
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, the control or data part of the
message, respectively, maxlen bytes are retrieved. In this case, the
remainder of the message is left on the stream head read queue and a
nonzero 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 user 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
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
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
members of ctlptr and dataptr.
EXAMPLES
To receive only the data part of a message:
if (getmsg(fd, NULL, dataptr, flags) == -1)
perror("Getmsg failed");
RETURN VALUES
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
MORECTL indicates that more control information is waiting for retrieval.
2 Intergraph Corporation - 2/94
getmsg(2) CLIX getmsg(2)
A return value of MOREDATA indicates that more data is waiting for
retrieval. A return value of MORECTL | MOREDATA indicates that both types
of information remain. Subsequent getmsg() calls will retrieve the
remainder of the message.
ERRORS
The getmsg() function fails if one or more of the following are true:
[EAGAIN] The O_NDELAY flag is set, and no messages are available.
[EBADF] The value of fd is not a valid file descriptor open for
reading.
[EBADMSG] Queued message to be read is not valid for getmsg().
[EFAULT] The ctlptr, dataptr, or flags pointer points to a location
outside the allocated address space.
[EINTR] A signal was caught during the getmsg() function.
[EINVAL] An illegal value was specified in flags, or the stream
referenced by fd is linked under a multiplexor.
[ENOSTR] A stream is not associated with fd.
A getmsg() function 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.
RELATED INFORMATION
Functions: intro(2), read(2), poll(2), putmsg(2), write(2)
AT&T UNIX System V STREAMS Primer, AT&T UNIX System V STREAMS Programmer's
Guide
2/94 - Intergraph Corporation 3