📄 getmsg.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-2003 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, 2003 Edition<br>Copyright © 2001-2003 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 queueassociated with a STREAMS file and place the contents into one or more buffers. The message contains either a data part, a controlpart, or both. The data and control parts of the message shall be placed into separate buffers, as described below. The semanticsof 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 ofthe 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 toa buffer in which the data or control information is to be placed, and the <i>maxlen</i> member indicates the maximum number ofbytes this buffer can hold. On return, the <i>len</i> member shall contain the number of bytes of data or control informationactually 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 beset 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 ableto 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 ofthe 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) partof 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 readqueue 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 onthe 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 maychoose 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 toRS_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 followingmutually-exclusive flags defined: MSG_HIPRI, MSG_BAND, and MSG_ANY. Like <i>getmsg</i>(), <i>getpmsg</i>() shall process the firstavailable message on the STREAM head read queue. A process may choose to retrieve only high-priority messages by setting theinteger 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 amessage from a particular priority band by setting the integer pointed to by <i>flagsp</i> to MSG_BAND and the integer pointed toby <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 apriority band equal to, or greater than, the integer pointed to by <i>bandp</i>, or if it is a high-priority message. If a processwants to get the first message off the queue, the integer pointed to by <i>flagsp</i> should be set to MSG_ANY and the integerpointed to by <i>bandp</i> should be set to 0. On return, if the message retrieved was a high-priority message, the integer pointedto 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 integerpointed 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 bandof 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 isnot 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 tooperate 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 thata full message was read successfully. A return value of MORECTL indicates that more control information is waiting for retrieval. Areturn value of MOREDATA indicates that more data is waiting for retrieval. A return value of the bitwise-logical OR of MORECTL andMOREDATA indicates that both types of information remain. Subsequent <i>getmsg</i>() and <i>getpmsg</i>() calls shall retrieve theremainder 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 previousmessage.</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 messageof band 0. Subsequent <i>getmsg</i>() and <i>getpmsg</i>() calls shall retrieve the remainder of the message. If, however, apriority message arrives or already exists on the STREAM head, the subsequent call to <i>getmsg</i>() or <i>getpmsg</i>() shallretrieve 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 theSTREAM 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 (directlyor 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 thecall. In this case, the value of <i>errno</i> does not reflect the result of <i>getmsg</i>() or <i>getpmsg</i>() but reflects theprior 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 bufferspointed 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 readqueue.</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 BaseDefinitions 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 theISO/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>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -