📄 getmsg.html
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"><html><head><!-- Copyright 1997 The Open Group, All Rights Reserved --><title>getmsg</title></head><body bgcolor=white><center><font size=2>The Single UNIX ® Specification, Version 2<br>Copyright © 1997 The Open Group</font></center><hr size=2 noshade><h4><a name = "tag_000_005_608"> </a>NAME</h4><blockquote>getmsg, getpmsg - receive next message from a STREAMS file</blockquote><h4><a name = "tag_000_005_609"> </a>SYNOPSIS</h4><blockquote><pre><code>#include <<a href="stropts.h.html">stropts.h</a>>int getmsg(int <i>fildes</i>, struct strbuf *<i>ctlptr</i>, struct strbuf *<i>dataptr</i>, int *<i>flagsp</i>);int getpmsg(int <i>fildes</i>, struct strbuf *<i>ctlptr</i>, struct strbuf *<i>dataptr</i>, int *<i>bandp</i>, int *<i>flagsp</i>);</code></pre></blockquote><h4><a name = "tag_000_005_610"> </a>DESCRIPTION</h4><blockquote>The<i>getmsg()</i>function retrieves the contents of a message located at the head of the STREAMhead read queue associated with a STREAMS file and places the contents intoone or more buffers. The message contains either a data part, a controlpart, or both. The data and control parts of the message are placed intoseparate buffers, as described below. The semantics of each part is definedby the originator of the message.<p>The<i><a href="getpmsg.html">getpmsg()</a></i>function does the same thing as<i>getmsg()</i>,but provides finer control over the priority of the messages received.Except where noted, all requirements on<i>getmsg()</i>also pertain to<i><a href="getpmsg.html">getpmsg()</a></i>.<p>The <i>fildes</i> argument specifies a file descriptor referencing aSTREAMS-based file.<p>The <i>ctlptr</i> and <i>dataptr</i> arguments each point to a <b>strbuf</b>structure, in which the <b>buf</b> member points to a buffer in which the dataor control information is to be placed, and the <b>maxlen</b> member indicatesthe maximum number of bytes this buffer can hold. On return, the <b>len</b>member contains the number of bytes of data or control information actuallyreceived. The <b>len</b> member is set to 0 if there is a zero-length controlor data part and <b>len</b> is set to -1 if no data or control informationis present in the message.<p>When<i>getmsg()</i>is called, <i>flagsp</i> should point to an integer that indicates the type ofmessage the process is able to receive. This is described further below.<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 <b>maxlen</b> member is -1, thecontrol (or data) part of the message is not processed and is left on theSTREAM head read queue, and if the <i>ctlptr</i> (or <i>dataptr</i>) is not anull pointer, <b>len</b> is set to -1. If the <b>maxlen</b> member is set to0 and there is a zero-length control (or data) part, that zero-length part isremoved from the read queue and <b>len</b> is set to 0. If the <b>maxlen</b>member is set to 0 and there are more than 0 bytes of control (or data)information, that information is left on the read queue and <b>len</b> is setto 0. If the <b>maxlen</b> member in <i>ctlptr</i> (or <i>dataptr</i>) is lessthan the control (or data) part of the message, <b>maxlen</b> bytes areretrieved. In this case, the remainder of the message is left on the STREAMhead read queue and a non-zero return value is provided.<p>By default,<i>getmsg()</i>processes the first available message on the STREAM head read queue. However,a process may choose to retrieve only high-priority messages by setting theinteger pointed to by <i>flagsp</i> to RS_HIPRI. In this case,<i>getmsg()</i>will only process the next message if it is a high-priority message. Whenthe integer pointed to by <i>flagsp</i> is 0, any message will be retrieved.In this case, on return, the integer pointed to by <i>flagsp</i> will be set toRS_HIPRI if a high-priority message was retrieved, or 0 otherwise.<p>For<i><a href="getpmsg.html">getpmsg()</a></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><a href="getpmsg.html">getpmsg()</a></i>processes the first available message on the STREAM head read queue. Aprocess 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><a href="getpmsg.html">getpmsg()</a></i>will only process the next message if it is a high-priority message. In asimilar manner, a process may choose to retrieve a message from a particularpriority band by setting the integer pointed to by <i>flagsp</i> to MSG_BANDand the integer pointed to by <i>bandp</i> to the priority band of interest.In this case,<i><a href="getpmsg.html">getpmsg()</a></i>will only process the next message if it is ina priority band equal to, or greater than, the integer pointed toby <i>bandp</i>, or if it is a high-priority message.If a process just wants to get the first message off the queue,the integer pointed to by <i>flagsp</i> should be set to MSG_ANYand 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> willbe set to MSG_HIPRI and the integer pointed to by <i>bandp</i> will be set to0. Otherwise, the integer pointed to by <i>flagsp</i> will be set to MSG_BANDand the integer pointed to by <i>bandp</i> will be set to the priority band ofthe message.<p>If O_NONBLOCK is not set,<i>getmsg()</i>and<i><a href="getpmsg.html">getpmsg()</a></i>will block until a message of the type specified by <i>flagsp</i> is availableat the front of the STREAM head read queue. If O_NONBLOCK is set and amessage of the specified type is not present at the front of the read queue,<i>getmsg()</i>and<i><a href="getpmsg.html">getpmsg()</a></i>fail and set <i>errno</i> to [EAGAIN].<p>If a hangup occurs on the STREAM from which messages are to be retrieved,<i>getmsg()</i>and<i><a href="getpmsg.html">getpmsg()</a></i>continue to operate normally, as described above, until the STREAM head readqueue is empty. Thereafter, they return 0 in the <i>len</i> members of<i>ctlptr</i> and <i>dataptr</i>.</blockquote><h4><a name = "tag_000_005_611"> </a>RETURN VALUE</h4><blockquote>Upon successful completion,<i>getmsg()</i>and<i><a href="getpmsg.html">getpmsg()</a></i>return a non-negative value. A value of 0 indicates that a full message wasread successfully. A return value of MORECTL indicates that more controlinformation is waiting for retrieval. A return value of MOREDATA indicatesthat more data is waiting for retrieval. A return value of the bitwiselogical OR of MORECTL and MOREDATA indicates that both types of informationremain. Subsequent<i>getmsg()</i>and<i><a href="getpmsg.html">getpmsg()</a></i>calls retrieve the remainder of the message. However, if a message of higherpriority has come in on the STREAM head read queue, the next call to<i>getmsg()</i>or<i><a href="getpmsg.html">getpmsg()</a></i>retrieves that higher-priority message before retrieving the remainder of theprevious message.<p>If the high priority control part of the message is consumed, themessage will be placed back on the queue as a normal message of band 0.Subsequent<i>getmsg()</i>and<i><a href="getpmsg.html">getpmsg()</a></i>calls retrieve the remainder of the message.If, however, a priority message arrives or already exists on theSTREAM head, the subsequent call to<i>getmsg()</i>or<i><a href="getpmsg.html">getpmsg()</a></i>retrieves the higher-priority message before retrieving the remainderof the message that was put back.<p>Upon failure,<i>getmsg()</i>and<i><a href="getpmsg.html">getpmsg()</a></i>return -1 and set <i>errno</i> to indicate the error.</blockquote><h4><a name = "tag_000_005_612"> </a>ERRORS</h4><blockquote>The<i>getmsg()</i>and<i><a href="getpmsg.html">getpmsg()</a></i>functions will fail if:<dl compact><dt>[EAGAIN]<dd>The O_NONBLOCK flag is set and no messages are available.<dt>[EBADF]<dd>The <i>fildes</i> argument is not a valid file descriptor open for reading.<dt>[EBADMSG]<dd>The queued message to be read is not valid for<i>getmsg()</i>or<i><a href="getpmsg.html">getpmsg()</a></i>or a pending file descriptor is at the STREAM head.<dt>[EINTR]<dd>A signal was caught during<i>getmsg()</i>or<i><a href="getpmsg.html">getpmsg()</a></i>.<dt>[EINVAL]<dd>An illegal value was specified by <i>flagsp</i>, or the STREAM or multiplexerreferenced by <i>fildes</i> is linked (directly or indirectly) downstream froma multiplexer.<dt>[ENOSTR]<dd>A STREAM is not associated with <i>fildes</i>.</dl><p>In addition,<i>getmsg()</i>and<i><a href="getpmsg.html">getpmsg()</a></i>will 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><a href="getpmsg.html">getpmsg()</a></i>but reflects the prior error.</blockquote><h4><a name = "tag_000_005_613"> </a>EXAMPLES</h4><blockquote>None.</blockquote><h4><a name = "tag_000_005_614"> </a>APPLICATION USAGE</h4><blockquote>None.</blockquote><h4><a name = "tag_000_005_615"> </a>FUTURE DIRECTIONS</h4><blockquote>None.</blockquote><h4><a name = "tag_000_005_616"> </a>SEE ALSO</h4><blockquote><i><a href="poll.html">poll()</a></i>,<i><a href="putmsg.html">putmsg()</a></i>,<i><a href="read.html">read()</a></i>,<i><a href="write.html">write()</a></i>,<i><a href="stropts.h.html"><stropts.h></a></i>,<a href="STREAMS.html">STREAMS overview</a>.<br></blockquote><hr size=2 noshade><center><font size=2>UNIX ® is a registered Trademark of The Open Group.<br>Copyright © 1997 The Open Group<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]</font></center><hr size=2 noshade></body></html>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -