📄 msgrcv.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>msgrcv</title></head><body bgcolor="white"><script type="text/javascript" language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> <a name="msgrcv"></a> <a name="tag_03_395"></a><!-- msgrcv --> <!--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_395_01"></a>NAME</h4><blockquote>msgrcv - XSI message receive operation</blockquote><h4><a name="tag_03_395_02"></a>SYNOPSIS</h4><blockquote class="synopsis"><div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> #include <<a href="../basedefs/sys/msg.h.html">sys/msg.h</a>><br><br> ssize_t msgrcv(int</tt> <i>msqid</i><tt>, void *</tt><i>msgp</i><tt>, size_t</tt> <i>msgsz</i><tt>, long</tt><i>msgtyp</i><tt>,<br> int</tt> <i>msgflg</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_395_03"></a>DESCRIPTION</h4><blockquote><p>The <i>msgrcv</i>() function operates on XSI message queues (see the Base Definitions volume of IEEE Std 1003.1-2001,<a href="../basedefs/xbd_chap03.html#tag_03_224">Section 3.224, Message Queue</a>). It is unspecified whether this functioninteroperates with the realtime interprocess communication facilities defined in <a href="xsh_chap02_08.html#tag_02_08"><i>Realtime</i></a> .</p><p>The <i>msgrcv</i>() function shall read a message from the queue associated with the message queue identifier specified by<i>msqid</i> and place it in the user-defined buffer pointed to by <i>msgp</i>.</p><p>The application shall ensure that the argument <i>msgp</i> points to a user-defined buffer that contains first a field of type<b>long</b> specifying the type of the message, and then a data portion that holds the data bytes of the message. The structurebelow is an example of what this user-defined buffer might look like:</p><pre><tt>struct mymsg { long mtype; /* Message type. */ char mtext[1]; /* Message text. */}</tt></pre><p>The structure member <i>mtype</i> is the received message's type as specified by the sending process.</p><p>The structure member <i>mtext</i> is the text of the message.</p><p>The argument <i>msgsz</i> specifies the size in bytes of <i>mtext</i>. The received message shall be truncated to <i>msgsz</i>bytes if it is larger than <i>msgsz</i> and (<i>msgflg</i> & MSG_NOERROR) is non-zero. The truncated part of the message shallbe lost and no indication of the truncation shall be given to the calling process.</p><p>If the value of <i>msgsz</i> is greater than {SSIZE_MAX}, the result is implementation-defined.</p><p>The argument <i>msgtyp</i> specifies the type of message requested as follows:</p><ul><li><p>If <i>msgtyp</i> is 0, the first message on the queue shall be received.</p></li><li><p>If <i>msgtyp</i> is greater than 0, the first message of type <i>msgtyp</i> shall be received.</p></li><li><p>If <i>msgtyp</i> is less than 0, the first message of the lowest type that is less than or equal to the absolute value of<i>msgtyp</i> shall be received.</p></li></ul><p>The argument <i>msgflg</i> specifies the action to be taken if a message of the desired type is not on the queue. These are asfollows:</p><ul><li><p>If (<i>msgflg</i> & IPC_NOWAIT) is non-zero, the calling thread shall return immediately with a return value of -1 and<i>errno</i> set to [ENOMSG].</p></li><li><p>If (<i>msgflg</i> & IPC_NOWAIT) is 0, the calling thread shall suspend execution until one of the following occurs:</p><ul><li><p>A message of the desired type is placed on the queue.</p></li><li><p>The message queue identifier <i>msqid</i> is removed from the system; when this occurs, <i>errno</i> shall be set equal to[EIDRM] and -1 shall be returned.</p></li><li><p>The calling thread receives a signal that is to be caught; in this case a message is not received and the calling thread resumesexecution in the manner prescribed in <a href="sigaction.html"><i>sigaction</i>()</a> .</p></li></ul></li></ul><p>Upon successful completion, the following actions are taken with respect to the data structure associated with <i>msqid</i>:</p><ul><li><p><b>msg_qnum</b> shall be decremented by 1.</p></li><li><p><b>msg_lrpid</b> shall be set equal to the process ID of the calling process.</p></li><li><p><b>msg_rtime</b> shall be set equal to the current time.</p></li></ul></blockquote><h4><a name="tag_03_395_04"></a>RETURN VALUE</h4><blockquote><p>Upon successful completion, <i>msgrcv</i>() shall return a value equal to the number of bytes actually placed into the buffer<i>mtext</i>. Otherwise, no message shall be received, <i>msgrcv</i>() shall return (<b>ssize_t</b>)-1, and <i>errno</i> shall beset to indicate the error.</p></blockquote><h4><a name="tag_03_395_05"></a>ERRORS</h4><blockquote><p>The <i>msgrcv</i>() function shall fail if:</p><dl compact><dt>[E2BIG]</dt><dd>The value of <i>mtext</i> is greater than <i>msgsz</i> and (<i>msgflg</i> & MSG_NOERROR) is 0.</dd><dt>[EACCES]</dt><dd>Operation permission is denied to the calling process; see <a href="xsh_chap02_07.html#tag_02_07"><i>XSI InterprocessCommunication</i></a> .</dd><dt>[EIDRM]</dt><dd>The message queue identifier <i>msqid</i> is removed from the system.</dd><dt>[EINTR]</dt><dd>The <i>msgrcv</i>() function was interrupted by a signal.</dd><dt>[EINVAL]</dt><dd><i>msqid</i> is not a valid message queue identifier.</dd><dt>[ENOMSG]</dt><dd>The queue does not contain a message of the desired type and (<i>msgflg</i> & IPC_NOWAIT) is non-zero.</dd></dl></blockquote><hr><div class="box"><em>The following sections are informative.</em></div><h4><a name="tag_03_395_06"></a>EXAMPLES</h4><blockquote><h5><a name="tag_03_395_06_01"></a>Receiving a Message</h5><p>The following example receives the first message on the queue (based on the value of the <i>msgtyp</i> argument, 0). The queueis identified by the <i>msqid</i> argument (assuming that the value has previously been set). This call specifies that an errorshould be reported if no message is available, but not if the message is too large. The message size is calculated directly usingthe <i>sizeof</i> operator.</p><pre><tt>#include <sys/msg.h>...int result;int msqid;struct message { long type; char text[20];} msg;long msgtyp = 0;...result = msgrcv(msqid, (void *) &msg, sizeof(msg.text), msgtyp, MSG_NOERROR | IPC_NOWAIT);</tt></pre></blockquote><h4><a name="tag_03_395_07"></a>APPLICATION USAGE</h4><blockquote><p>The POSIX Realtime Extension defines alternative interfaces for interprocess communication (IPC). Application developers whoneed to use IPC should design their applications so that modules using the IPC routines described in <a href="xsh_chap02_07.html#tag_02_07"><i>XSI Interprocess Communication</i></a> can be easily modified to use the alternativeinterfaces.</p></blockquote><h4><a name="tag_03_395_08"></a>RATIONALE</h4><blockquote><p>None.</p></blockquote><h4><a name="tag_03_395_09"></a>FUTURE DIRECTIONS</h4><blockquote><p>None.</p></blockquote><h4><a name="tag_03_395_10"></a>SEE ALSO</h4><blockquote><p><a href="xsh_chap02_07.html#tag_02_07"><i>XSI Interprocess Communication</i></a> , <a href="xsh_chap02_08.html#tag_02_08"><i>Realtime</i></a> , <a href="mq_close.html"><i>mq_close</i>()</a> , <a href="mq_getattr.html"><i>mq_getattr</i>()</a> , <a href="mq_notify.html"><i>mq_notify</i>()</a> , <a href="mq_open.html"><i>mq_open</i>()</a> , <a href="mq_receive.html"><i>mq_receive</i>()</a> , <a href="mq_send.html"><i>mq_send</i>()</a> , <a href="mq_setattr.html"><i>mq_setattr</i>()</a> , <a href="mq_unlink.html"><i>mq_unlink</i>()</a> , <a href="msgctl.html"><i>msgctl</i>()</a> , <a href="msgget.html"><i>msgget</i>()</a> ,<a href="msgsnd.html"><i>msgsnd</i>()</a> , <a href="sigaction.html"><i>sigaction</i>()</a> , the Base Definitions volume ofIEEE Std 1003.1-2001, <a href="../basedefs/sys/msg.h.html"><i><sys/msg.h></i></a></p></blockquote><h4><a name="tag_03_395_11"></a>CHANGE HISTORY</h4><blockquote><p>First released in Issue 2. Derived from Issue 2 of the SVID.</p></blockquote><h4><a name="tag_03_395_12"></a>Issue 5</h4><blockquote><p>The type of the return value is changed from <b>int</b> to <b>ssize_t</b>, and a warning is added to the DESCRIPTION aboutvalues of <i>msgsz</i> larger the {SSIZE_MAX}.</p><p>The note about use of POSIX Realtime Extension IPC routines has been moved from FUTURE DIRECTIONS to the APPLICATION USAGEsection.</p></blockquote><h4><a name="tag_03_395_13"></a>Issue 6</h4><blockquote><p>The DESCRIPTION is updated to avoid use of the term "must" for application requirements.</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 + -