 |
Index for
Section 2 |
|
 |
Alphabetical
listing for G |
|
 |
Bottom of
page |
|
getmsg(2)
NAME
getmsg, getpmsg - Receive the next message from a Stream
SYNOPSIS
#include <stropts.h>
int getmsg(
int fd,
struct strbuf *ctlptr,
struct strbuf *dataptr,
int *flags );
int getpmsg(
int fd,
struct strbuf *ctlptr,
struct strbuf *dataptr,
int *band,
int *flags );
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry standards
as follows:
getmsg(), getpmsg(): XSH4.2, XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
fd Specifies a file descriptor that references an open Stream.
ctlptr
Points to a strbuf structure that holds the control part of the
message. This strbuf structure is described in the DESCRIPTION section.
dataptr
Points to a strbuf structure that holds the data part of the message.
This strbuf structure is described in the DESCRIPTION section.
band
Points to an integer that indicates the priority band of the message
that the user is able to retrieve.
flags
Points to an integer that indicates the type of message the user is
able to retrieve.
DESCRIPTION
The getmsg() and getpmsg() functions retrieve the contents of messages.
These messages are located at the Stream head read queue associated with a
STREAMS file. Messages must contain a control part or a data part, or both.
The control and data parts of the message are placed into separate user-
specified buffers, pointed at by ctlptr and dataptr respectively. The open
Stream specifies the format and semantics of the message's control and data
parts. The getpmsg() function provides better control over the priority of
the messages received. Except where specified, all information about the
getmsg() function also applies to the getpmsg() function. The semantics of
both the control and data parts of the message is defined by the STREAMS
module that created the message.
The ctlptr and dataptr parameters each point to a strbuf structure that
contains three members. This structure is defined in <sys/stropts.h> as:
struct strbuf {
int maxlen; /* maximum buffer length */
int len; /* length of data */
char *buf /* ptr to buffer */
};
The members are:
maxlen Specifies the maximum number of bytes buf can hold.
buf Points to the buffer where the control or data information is to
reside.
len On return, contains the number of bytes of control or data
information that has actually been received. The len parameter is
set to 0 (zero) if there is a zero-length data or control part;
otherwise, len is set to -1 if no control or data information is
contained in the message.
The members of this structure are also affected by the following.
· If the maxlen field is set to 0 (zero), and the control or data part
is of zero-length, that zero-length part is deleted from the read
queue of the Stream head, and len is set to 0 (zero).
· If the maxlen field is set to 0 (zero), and if the size of the control
or data part is greater than 0 (zero), that part remains on the read
queue and len is set to 0 (zero).
· If the maxlen field for either the ctlptr or dataptr structure is less
than the size of the control or data part of the message, maxlen bytes
are retrieved and the rest of the message remains on the Stream head
read queue. A nonzero value is then returned.
· If the maxlen member is -1, or if ctlptr or dataptr parameter is a
null pointer, the getmsg() function does not process the control or
the data part of the message. The unprocessed part(s) then remains on
the Stream head queue.
· If ctlptr or dataptr is not a null pointer, and if the read queue at
the Stream head has no corresponding message control or data part, len
is set to -1.
One of the major differences between the getmsg() and getpmsg() functions,
in addition to the band parameter, is how the flags parameter is used to
collect messages. The getmsg() function processes messages as follows:
· By default, the getmsg() function processes the first message that is
available on the Stream head queue.
· If you set the flags parameter to 0 (zero), any message will be
retrieved. On return, the integer pointed to by the flags parameter
will be set to RS_HIPRI if a high-priority message was retrieved;
otherwise, a value of 0 (zero) is returned.
· If you set the flags parameter to RS_HIPRI, the getmsg() function
retrieves only the high-priority messages. The getmsg() function then
only processes the next message if it is a high-priority message.
The getpmsg() function flags parameter points to a bitmask with the
mutually-exclusive options MSG_HIPRI, MSG_BAND, and MSG_ANY defined. The
getpmsg() function processes messages as follows:
· By default, the getpmsg() function processes the first available
message on the Stream head read queue.
· If you set the integer pointed at by the flags parameter to MSG_HIPRI,
and set the integer pointed to by the band parameter to 0 (zero), the
getpmsg() function retrieves only high-priority messages. The
getpmsg() function then only processes the next message if it is a
high-priority message.
· If you set the integer pointed to by the flags parameter to MSG_BAND,
and set the integer pointed to by the band parameter to the desired
priority band, the getpmsg() function retrieves a message from that
band. The getpmsg() function then only processes the next message if
it is in a high-priority message, or if its priority band is at least
equal to the integer pointed to by band.
· If you set the integer pointed to by the flags parameter to MSG_ANY,
and set the integer pointed to by the band parameter to 0 (zero), the
getpmsg() function retrieves only the first message off the queue.
When the getpmsg() function returns, it then sets the flags and band
parameters according to the type of message that was retrieved. If the
message was not a high-priority one, the integer pointed to by the
flags parameter is set to MSG_BAND and the integer pointed to by band
is set to the band of the message. If the message was a high-priority
one, the integer pointed to by the flags is set to MSG_HIPRI and the
integer pointed to by band will be set to 0 (zero).
If the O_NDELAY or O_NONBLOCK flags are set and a message of the specified
type is not present at the front of the read queue, the getmsg() function
fails. If the O_NDELAY or O_NONBLOCK options are not set for the read()
operation, the getmsg() function blocks until a message is available at the
front of the Stream head read queue. This message's type is specified by
flags.
[Tru64 UNIX] Current industry standards do not define the O_NDELAY option.
It is included in the preceding paragraphs for System V compatibility.
If the Stream from which the messages are being retrieved experiences a
hangup, the getmsg() function does not fail. Instead, it will continues as
usual until the read queue of the Stream head is empty. Subsequent calls
will return a value of 0 (zero) in the len fields for the ctlptr and
dataptr structures.
RETURN VALUES
Upon successful completion, the getmsg() and getmsg() functions return
nonnegative values, as follows:
0 (zero)
Indicates that a full message was successfully read.
MORECTL
Indicates that more control information is waiting for retrieval.
MOREDATA
Indicates that more data is waiting for retrieval.
MORECTL | MOREDATA
Indicates that both types of information remain. Later calls to
getmsg() then retrieve the rest of the message. Note, however, that
higher-priority messages, although they may arrive later on the queue,
take a higher precedence. In other words, if a message comes in later
on the read queue, the next call to the getmsg() function retrieves
that higher-priority message first. The rest of the earlier partial
message is retrieved afterwards.
Upon failure, the getmsg() function returns a value of -1, and sets errno
to indicate an error.
ERRORS
Both the getmsg() and getpmsg() functions fail if a STREAMS error message
is delivered to the Stream head read queue before the call. In this
instance, the STREAMS error message contains the value of the returned
error.
In addition, if any of the following conditions occurs, the getmsg()
function sets errno to the corresponding value:
[EAGAIN]
The O_NDELAY or O_NONBLOCK flag is set, and no messages are currently
available.
[Tru64 UNIX] Current industry standards do not define the O_NDELAY
flag. It is included in the preceding paragraph for System V
compatibility.
[EFAULT]
An illegal address has been specified in ctlptr or dataptr.
[EBADF]
The fd parameter is not a valid file descriptor open for reading.
[EBADMSG]
The message on the read queue is not a control or data message, or a
file descriptor is pending at the Stream head.
[EINTR]
The getmsg() or getpmsg() function was interrupted by a signal that was
caught.
[EINVAL]
An illegal value was specified by the flags parameter, or the Stream
referenced by fd is linked under a multiplexor.
[ENOSTR]
A Stream is not associated with the fd parameter.
SEE ALSO
Functions: poll(2), putmsg(2), read(2), write(2)
Interfaces: streamio(7)
Standards: standards(5)
Network Programmer's Guide
|
Index for
Section 2 |
|
|
Alphabetical
listing for G |
|
 |
Top of
page |
|