287 lines
13 KiB
HTML
287 lines
13 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
|
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
|
<title>getmsg</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="getmsg"></a> <a name="tag_03_231"></a><!-- getmsg -->
|
|
<!--header start-->
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001<br>
|
|
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
|
|
|
<!--header end-->
|
|
<hr size="2" noshade>
|
|
<h4><a name="tag_03_231_01"></a>NAME</h4>
|
|
|
|
<blockquote>getmsg, getpmsg - receive next message from a STREAMS file (<b>STREAMS</b>)</blockquote>
|
|
|
|
<h4><a name="tag_03_231_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSR')">XSR</a>]</sup> <img src="../images/opt-start.gif" alt=
|
|
"[Option Start]" border="0"> #include <<a href="../basedefs/stropts.h.html">stropts.h</a>><br>
|
|
<br>
|
|
int getmsg(int</tt> <i>fildes</i><tt>, struct strbuf *restrict</tt> <i>ctlptr</i><tt>,<br>
|
|
struct strbuf *restrict</tt> <i>dataptr</i><tt>, int *restrict</tt> <i>flagsp</i><tt>);<br>
|
|
int getpmsg(int</tt> <i>fildes</i><tt>, struct strbuf *restrict</tt> <i>ctlptr</i><tt>,<br>
|
|
struct strbuf *restrict</tt> <i>dataptr</i><tt>, int *restrict</tt> <i>bandp</i><tt>,<br>
|
|
int *restrict</tt> <i>flagsp</i><tt>); <img src="../images/opt-end.gif" alt="[Option End]"
|
|
border="0"></tt></code></div>
|
|
|
|
<tt><br>
|
|
</tt></blockquote>
|
|
|
|
<h4><a name="tag_03_231_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>getmsg</i>() function shall retrieve the contents of a message located at the head of the STREAM head read queue
|
|
associated with a STREAMS file and place the contents into one or more buffers. The message contains either a data part, a control
|
|
part, or both. The data and control parts of the message shall be placed into separate buffers, as described below. The semantics
|
|
of each part are defined by the originator of the message.</p>
|
|
|
|
<p>The <i>getpmsg</i>() function shall be equivalent to <i>getmsg</i>(), except that it provides finer control over the priority of
|
|
the messages received. Except where noted, all requirements on <i>getmsg</i>() also pertain to <i>getpmsg</i>().</p>
|
|
|
|
<p>The <i>fildes</i> argument specifies a file descriptor referencing a STREAMS-based file.</p>
|
|
|
|
<p>The <i>ctlptr</i> and <i>dataptr</i> arguments each point to a <b>strbuf</b> structure, in which the <i>buf</i> member points to
|
|
a buffer in which the data or control information is to be placed, and the <i>maxlen</i> member indicates the maximum number of
|
|
bytes this buffer can hold. On return, the <i>len</i> member shall contain the number of bytes of data or control information
|
|
actually received. The <i>len</i> member shall be set to 0 if there is a zero-length control or data part and <i>len</i> shall be
|
|
set to -1 if no data or control information is present in the message.</p>
|
|
|
|
<p>When <i>getmsg</i>() is called, <i>flagsp</i> should point to an integer that indicates the type of message the process is able
|
|
to receive. This is described further below.</p>
|
|
|
|
<p>The <i>ctlptr</i> argument is used to hold the control part of the message, and <i>dataptr</i> is used to hold the data part of
|
|
the message. If <i>ctlptr</i> (or <i>dataptr</i>) is a null pointer or the <i>maxlen</i> member is -1, the control (or data) part
|
|
of the message shall not be processed and shall be left on the STREAM head read queue, and if the <i>ctlptr</i> (or <i>dataptr</i>)
|
|
is not a null pointer, <i>len</i> shall be set to -1. If the <i>maxlen</i> member is set to 0 and there is a zero-length control
|
|
(or data) part, that zero-length part shall be removed from the read queue and <i>len</i> shall be set to 0. If the <i>maxlen</i>
|
|
member is set to 0 and there are more than 0 bytes of control (or data) information, that information shall be left on the read
|
|
queue and <i>len</i> shall be set to 0. If the <i>maxlen</i> member in <i>ctlptr</i> (or <i>dataptr</i>) is less than the control
|
|
(or data) part of the message, <i>maxlen</i> bytes shall be retrieved. In this case, the remainder of the message shall be left on
|
|
the STREAM head read queue and a non-zero return value shall be provided.</p>
|
|
|
|
<p>By default, <i>getmsg</i>() shall process the first available message on the STREAM head read queue. However, a process may
|
|
choose to retrieve only high-priority messages by setting the integer pointed to by <i>flagsp</i> to RS_HIPRI. In this case,
|
|
<i>getmsg</i>() shall only process the next message if it is a high-priority message. When the integer pointed to by <i>flagsp</i>
|
|
is 0, any available message shall be retrieved. In this case, on return, the integer pointed to by <i>flagsp</i> shall be set to
|
|
RS_HIPRI if a high-priority message was retrieved, or 0 otherwise.</p>
|
|
|
|
<p>For <i>getpmsg</i>(), the flags are different. The <i>flagsp</i> argument points to a bitmask with the following
|
|
mutually-exclusive flags defined: MSG_HIPRI, MSG_BAND, and MSG_ANY. Like <i>getmsg</i>(), <i>getpmsg</i>() shall process the first
|
|
available message on the STREAM head read queue. A process may choose to retrieve only high-priority messages by setting the
|
|
integer pointed to by <i>flagsp</i> to MSG_HIPRI and the integer pointed to by <i>bandp</i> to 0. In this case, <i>getpmsg</i>()
|
|
shall only process the next message if it is a high-priority message. In a similar manner, a process may choose to retrieve a
|
|
message from a particular priority band by setting the integer pointed to by <i>flagsp</i> to MSG_BAND and the integer pointed to
|
|
by <i>bandp</i> to the priority band of interest. In this case, <i>getpmsg</i>() shall only process the next message if it is in a
|
|
priority band equal to, or greater than, the integer pointed to by <i>bandp</i>, or if it is a high-priority message. If a process
|
|
wants to get the first message off the queue, the integer pointed to by <i>flagsp</i> should be set to MSG_ANY and the integer
|
|
pointed to by <i>bandp</i> should be set to 0. On return, if the message retrieved was a high-priority message, the integer pointed
|
|
to by <i>flagsp</i> shall be set to MSG_HIPRI and the integer pointed to by <i>bandp</i> shall be set to 0. Otherwise, the integer
|
|
pointed to by <i>flagsp</i> shall be set to MSG_BAND and the integer pointed to by <i>bandp</i> shall be set to the priority band
|
|
of the message.</p>
|
|
|
|
<p>If O_NONBLOCK is not set, <i>getmsg</i>() and <i>getpmsg</i>() shall block until a message of the type specified by
|
|
<i>flagsp</i> is available at the front of the STREAM head read queue. If O_NONBLOCK is set and a message of the specified type is
|
|
not present at the front of the read queue, <i>getmsg</i>() and <i>getpmsg</i>() shall fail and set <i>errno</i> to [EAGAIN].</p>
|
|
|
|
<p>If a hangup occurs on the STREAM from which messages are retrieved, <i>getmsg</i>() and <i>getpmsg</i>() shall continue to
|
|
operate normally, as described above, until the STREAM head read queue is empty. Thereafter, they shall return 0 in the <i>len</i>
|
|
members of <i>ctlptr</i> and <i>dataptr</i>.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_231_04"></a>RETURN VALUE</h4>
|
|
|
|
<blockquote>
|
|
<p>Upon successful completion, <i>getmsg</i>() and <i>getpmsg</i>() shall return a non-negative value. 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. A
|
|
return value of MOREDATA indicates that more data is waiting for retrieval. A return value of the bitwise-logical OR of MORECTL and
|
|
MOREDATA indicates that both types of information remain. Subsequent <i>getmsg</i>() and <i>getpmsg</i>() calls shall 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
|
|
<i>getmsg</i>() or <i>getpmsg</i>() shall retrieve that higher-priority message before retrieving the remainder of the previous
|
|
message.</p>
|
|
|
|
<p>If the high priority control part of the message is consumed, the message shall be placed back on the queue as a normal message
|
|
of band 0. Subsequent <i>getmsg</i>() and <i>getpmsg</i>() calls shall retrieve the remainder of the message. If, however, a
|
|
priority message arrives or already exists on the STREAM head, the subsequent call to <i>getmsg</i>() or <i>getpmsg</i>() shall
|
|
retrieve the higher-priority message before retrieving the remainder of the message that was put back.</p>
|
|
|
|
<p>Upon failure, <i>getmsg</i>() and <i>getpmsg</i>() shall return -1 and set <i>errno</i> to indicate the error.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_231_05"></a>ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>getmsg</i>() and <i>getpmsg</i>() functions shall fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EAGAIN]</dt>
|
|
|
|
<dd>The O_NONBLOCK flag is set and no messages are available.</dd>
|
|
|
|
<dt>[EBADF]</dt>
|
|
|
|
<dd>The <i>fildes</i> argument is not a valid file descriptor open for reading.</dd>
|
|
|
|
<dt>[EBADMSG]</dt>
|
|
|
|
<dd>The queued message to be read is not valid for <i>getmsg</i>() or <i>getpmsg</i>() or a pending file descriptor is at the
|
|
STREAM head.</dd>
|
|
|
|
<dt>[EINTR]</dt>
|
|
|
|
<dd>A signal was caught during <i>getmsg</i>() or <i>getpmsg</i>().</dd>
|
|
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd>An illegal value was specified by <i>flagsp</i>, or the STREAM or multiplexer referenced by <i>fildes</i> is linked (directly
|
|
or indirectly) downstream from a multiplexer.</dd>
|
|
|
|
<dt>[ENOSTR]</dt>
|
|
|
|
<dd>A STREAM is not associated with <i>fildes</i>.</dd>
|
|
</dl>
|
|
|
|
<p>In addition, <i>getmsg</i>() and <i>getpmsg</i>() shall fail if the STREAM head had processed an asynchronous error before the
|
|
call. In this case, the value of <i>errno</i> does not reflect the result of <i>getmsg</i>() or <i>getpmsg</i>() but reflects the
|
|
prior error.</p>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_03_231_06"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<h5><a name="tag_03_231_06_01"></a>Getting Any Message</h5>
|
|
|
|
<p>In the following example, the value of <i>fd</i> is assumed to refer to an open STREAMS file. The call to <i>getmsg</i>()
|
|
retrieves any available message on the associated STREAM-head read queue, returning control and data information to the buffers
|
|
pointed to by <i>ctrlbuf</i> and <i>databuf</i>, respectively.</p>
|
|
|
|
<pre>
|
|
<tt>#include <stropts.h>
|
|
...
|
|
int fd;
|
|
char ctrlbuf[128];
|
|
char databuf[512];
|
|
struct strbuf ctrl;
|
|
struct strbuf data;
|
|
int flags = 0;
|
|
int ret;
|
|
<br>
|
|
ctrl.buf = ctrlbuf;
|
|
ctrl.maxlen = sizeof(ctrlbuf);
|
|
<br>
|
|
data.buf = databuf;
|
|
data.maxlen = sizeof(databuf);
|
|
<br>
|
|
ret = getmsg (fd, &ctrl, &data, &flags);
|
|
</tt>
|
|
</pre>
|
|
|
|
<h5><a name="tag_03_231_06_02"></a>Getting the First Message off the Queue</h5>
|
|
|
|
<p>In the following example, the call to <i>getpmsg</i>() retrieves the first available message on the associated STREAM-head read
|
|
queue.</p>
|
|
|
|
<pre>
|
|
<tt>#include <stropts.h>
|
|
...
|
|
<br>
|
|
int fd;
|
|
char ctrlbuf[128];
|
|
char databuf[512];
|
|
struct strbuf ctrl;
|
|
struct strbuf data;
|
|
int band = 0;
|
|
int flags = MSG_ANY;
|
|
int ret;
|
|
<br>
|
|
ctrl.buf = ctrlbuf;
|
|
ctrl.maxlen = sizeof(ctrlbuf);
|
|
<br>
|
|
data.buf = databuf;
|
|
data.maxlen = sizeof(databuf);
|
|
<br>
|
|
ret = getpmsg (fd, &ctrl, &data, &band, &flags);
|
|
</tt>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_231_07"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_231_08"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_231_09"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_231_10"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="xsh_chap02_06.html#tag_02_06"><i>STREAMS</i></a> , <a href="poll.html"><i>poll</i>()</a> , <a href=
|
|
"putmsg.html"><i>putmsg</i>()</a> , <a href="read.html"><i>read</i>()</a> , <a href="write.html"><i>write</i>()</a> , the Base
|
|
Definitions volume of IEEE Std 1003.1-2001, <a href="../basedefs/stropts.h.html"><i><stropts.h></i></a></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_231_11"></a>CHANGE HISTORY</h4>
|
|
|
|
<blockquote>
|
|
<p>First released in Issue 4, Version 2.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_231_12"></a>Issue 5</h4>
|
|
|
|
<blockquote>
|
|
<p>Moved from X/OPEN UNIX extension to BASE.</p>
|
|
|
|
<p>A paragraph regarding "high-priority control parts of messages" is added to the RETURN VALUE section.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_231_13"></a>Issue 6</h4>
|
|
|
|
<blockquote>
|
|
<p>This function is marked as part of the XSI STREAMS Option Group.</p>
|
|
|
|
<p>The <b>restrict</b> keyword is added to the <i>getmsg</i>() and <i>getpmsg</i>() prototypes for alignment with the
|
|
ISO/IEC 9899:1999 standard.</p>
|
|
</blockquote>
|
|
|
|
<div class="box"><em>End of informative text.</em></div>
|
|
|
|
<hr>
|
|
<hr size="2" noshade>
|
|
<center><font size="2"><!--footer start-->
|
|
UNIX ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® is a registered Trademark of The IEEE.<br>
|
|
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
|
|
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
|
|
]</font></center>
|
|
|
|
<!--footer end-->
|
|
<hr size="2" noshade>
|
|
</body>
|
|
</html>
|
|
|