add directory Ref-docs
This commit is contained in:
gohigh
292
Ref-docs/POSIX/susv3/functions/putmsg.html
Normal file
292
Ref-docs/POSIX/susv3/functions/putmsg.html
Normal file
@@ -0,0 +1,292 @@
|
||||
<!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>putmsg</title>
|
||||
</head>
|
||||
<body bgcolor="white">
|
||||
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
||||
</script>
|
||||
|
||||
<basefont size="3"> <a name="putmsg"></a> <a name="tag_03_584"></a><!-- putmsg -->
|
||||
<!--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_584_01"></a>NAME</h4>
|
||||
|
||||
<blockquote>putmsg, putpmsg - send a message on a STREAM (<b>STREAMS</b>)</blockquote>
|
||||
|
||||
<h4><a name="tag_03_584_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 putmsg(int</tt> <i>fildes</i><tt>, const struct strbuf *</tt><i>ctlptr</i><tt>,<br>
|
||||
const struct strbuf *</tt><i>dataptr</i><tt>, int</tt> <i>flags</i><tt>);<br>
|
||||
int putpmsg(int</tt> <i>fildes</i><tt>, const struct strbuf *</tt><i>ctlptr</i><tt>,<br>
|
||||
const struct strbuf *</tt><i>dataptr</i><tt>, int</tt> <i>band</i><tt>, int</tt>
|
||||
<i>flags</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_584_03"></a>DESCRIPTION</h4>
|
||||
|
||||
<blockquote>
|
||||
<p>The <i>putmsg</i>() function shall create a message from a process buffer(s) and send the message to a STREAMS file. The message
|
||||
may contain either a data part, a control part, or both. The data and control parts are distinguished by placement in separate
|
||||
buffers, as described below. The semantics of each part are defined by the STREAMS module that receives the message.</p>
|
||||
|
||||
<p>The <i>putpmsg</i>() function is equivalent to <i>putmsg</i>(), except that the process can send messages in different priority
|
||||
bands. Except where noted, all requirements on <i>putmsg</i>() also pertain to <i>putpmsg</i>().</p>
|
||||
|
||||
<p>The <i>fildes</i> argument specifies a file descriptor referencing an open STREAM. The <i>ctlptr</i> and <i>dataptr</i>
|
||||
arguments each point to a <b>strbuf</b> structure.</p>
|
||||
|
||||
<p>The <i>ctlptr</i> argument points to the structure describing the control part, if any, to be included in the message. The
|
||||
<i>buf</i> member in the <b>strbuf</b> structure points to the buffer where the control information resides, and the <i>len</i>
|
||||
member indicates the number of bytes to be sent. The <i>maxlen</i> member is not used by <i>putmsg</i>(). In a similar manner, the
|
||||
argument <i>dataptr</i> specifies the data, if any, to be included in the message. The <i>flags</i> argument indicates what type of
|
||||
message should be sent and is described further below.</p>
|
||||
|
||||
<p>To send the data part of a message, the application shall ensure that <i>dataptr</i> is not a null pointer and the <i>len</i>
|
||||
member of <i>dataptr</i> is 0 or greater. To send the control part of a message, the application shall ensure that the
|
||||
corresponding values are set for <i>ctlptr</i>. No data (control) part shall be sent if either <i>dataptr</i>( <i>ctlptr</i>) is a
|
||||
null pointer or the <i>len</i> member of <i>dataptr</i>( <i>ctlptr</i>) is set to -1.</p>
|
||||
|
||||
<p>For <i>putmsg</i>(), if a control part is specified and <i>flags</i> is set to RS_HIPRI, a high priority message shall be sent.
|
||||
If no control part is specified, and <i>flags</i> is set to RS_HIPRI, <i>putmsg</i>() shall fail and set <i>errno</i> to [EINVAL].
|
||||
If <i>flags</i> is set to 0, a normal message (priority band equal to 0) shall be sent. If a control part and data part are not
|
||||
specified and <i>flags</i> is set to 0, no message shall be sent and 0 shall be returned.</p>
|
||||
|
||||
<p>For <i>putpmsg</i>(), the flags are different. The <i>flags</i> argument is a bitmask with the following mutually-exclusive
|
||||
flags defined: MSG_HIPRI and MSG_BAND. If <i>flags</i> is set to 0, <i>putpmsg</i>() shall fail and set <i>errno</i> to [EINVAL].
|
||||
If a control part is specified and <i>flags</i> is set to MSG_HIPRI and <i>band</i> is set to 0, a high-priority message shall be
|
||||
sent. If <i>flags</i> is set to MSG_HIPRI and either no control part is specified or <i>band</i> is set to a non-zero value,
|
||||
<i>putpmsg</i>() shall fail and set <i>errno</i> to [EINVAL]. If <i>flags</i> is set to MSG_BAND, then a message shall be sent in
|
||||
the priority band specified by <i>band</i>. If a control part and data part are not specified and <i>flags</i> is set to MSG_BAND,
|
||||
no message shall be sent and 0 shall be returned.</p>
|
||||
|
||||
<p>The <i>putmsg</i>() function shall block if the STREAM write queue is full due to internal flow control conditions, with the
|
||||
following exceptions:</p>
|
||||
|
||||
<ul>
|
||||
<li>
|
||||
<p>For high-priority messages, <i>putmsg</i>() shall not block on this condition and continues processing the message.</p>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<p>For other messages, <i>putmsg</i>() shall not block but shall fail when the write queue is full and O_NONBLOCK is set.</p>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<p>The <i>putmsg</i>() function shall also block, unless prevented by lack of internal resources, while waiting for the
|
||||
availability of message blocks in the STREAM, regardless of priority or whether O_NONBLOCK has been specified. No partial message
|
||||
shall be sent.</p>
|
||||
</blockquote>
|
||||
|
||||
<h4><a name="tag_03_584_04"></a>RETURN VALUE</h4>
|
||||
|
||||
<blockquote>
|
||||
<p>Upon successful completion, <i>putmsg</i>() and <i>putpmsg</i>() shall return 0; otherwise, they shall return -1 and set
|
||||
<i>errno</i> to indicate the error.</p>
|
||||
</blockquote>
|
||||
|
||||
<h4><a name="tag_03_584_05"></a>ERRORS</h4>
|
||||
|
||||
<blockquote>
|
||||
<p>The <i>putmsg</i>() and <i>putpmsg</i>() functions shall fail if:</p>
|
||||
|
||||
<dl compact>
|
||||
<dt>[EAGAIN]</dt>
|
||||
|
||||
<dd>A non-priority message was specified, the O_NONBLOCK flag is set, and the STREAM write queue is full due to internal flow
|
||||
control conditions; or buffers could not be allocated for the message that was to be created.</dd>
|
||||
|
||||
<dt>[EBADF]</dt>
|
||||
|
||||
<dd><i>fildes</i> is not a valid file descriptor open for writing.</dd>
|
||||
|
||||
<dt>[EINTR]</dt>
|
||||
|
||||
<dd>A signal was caught during <i>putmsg</i>().</dd>
|
||||
|
||||
<dt>[EINVAL]</dt>
|
||||
|
||||
<dd>An undefined value is specified in <i>flags</i>, or <i>flags</i> is set to RS_HIPRI or MSG_HIPRI and no control part is
|
||||
supplied, or the STREAM or multiplexer referenced by <i>fildes</i> is linked (directly or indirectly) downstream from a
|
||||
multiplexer, or <i>flags</i> is set to MSG_HIPRI and <i>band</i> is non-zero (for <i>putpmsg</i>() only).</dd>
|
||||
|
||||
<dt>[ENOSR]</dt>
|
||||
|
||||
<dd>Buffers could not be allocated for the message that was to be created due to insufficient STREAMS memory resources.</dd>
|
||||
|
||||
<dt>[ENOSTR]</dt>
|
||||
|
||||
<dd>A STREAM is not associated with <i>fildes</i>.</dd>
|
||||
|
||||
<dt>[ENXIO]</dt>
|
||||
|
||||
<dd>A hangup condition was generated downstream for the specified STREAM.</dd>
|
||||
|
||||
<dt>[EPIPE] or [EIO]</dt>
|
||||
|
||||
<dd>The <i>fildes</i> argument refers to a STREAMS-based pipe and the other end of the pipe is closed. A SIGPIPE signal is
|
||||
generated for the calling thread.</dd>
|
||||
|
||||
<dt>[ERANGE]</dt>
|
||||
|
||||
<dd>The size of the data part of the message does not fall within the range specified by the maximum and minimum packet sizes of
|
||||
the topmost STREAM module. This value is also returned if the control part of the message is larger than the maximum configured
|
||||
size of the control part of a message, or if the data part of a message is larger than the maximum configured size of the data part
|
||||
of a message.</dd>
|
||||
</dl>
|
||||
|
||||
<p>In addition, <i>putmsg</i>() and <i>putpmsg</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>putmsg</i>() or <i>putpmsg</i>(), but reflects the
|
||||
prior error.<br>
|
||||
</p>
|
||||
</blockquote>
|
||||
|
||||
<hr>
|
||||
<div class="box"><em>The following sections are informative.</em></div>
|
||||
|
||||
<h4><a name="tag_03_584_06"></a>EXAMPLES</h4>
|
||||
|
||||
<blockquote>
|
||||
<h5><a name="tag_03_584_06_01"></a>Sending a High-Priority Message</h5>
|
||||
|
||||
<p>The value of <i>fd</i> is assumed to refer to an open STREAMS file. This call to <i>putmsg</i>() does the following:</p>
|
||||
|
||||
<ol>
|
||||
<li>
|
||||
<p>Creates a high-priority message with a control part and a data part, using the buffers pointed to by <i>ctrlbuf</i> and
|
||||
<i>databuf</i>, respectively.</p>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<p>Sends the message to the STREAMS file identified by <i>fd</i>.</p>
|
||||
</li>
|
||||
</ol>
|
||||
|
||||
<pre>
|
||||
<tt>#include <stropts.h>
|
||||
#include <string.h>
|
||||
...
|
||||
int fd;
|
||||
char *ctrlbuf = "This is the control part";
|
||||
char *databuf = "This is the data part";
|
||||
struct strbuf ctrl;
|
||||
struct strbuf data;
|
||||
int ret;
|
||||
<br>
|
||||
ctrl.buf = ctrlbuf;
|
||||
ctrl.len = strlen(ctrlbuf);
|
||||
<br>
|
||||
data.buf = databuf;
|
||||
data.len = strlen(databuf);
|
||||
<br>
|
||||
ret = putmsg(fd, &ctrl, &data, MSG_HIPRI);
|
||||
</tt>
|
||||
</pre>
|
||||
|
||||
<h5><a name="tag_03_584_06_02"></a>Using putpmsg()</h5>
|
||||
|
||||
<p>This example has the same effect as the previous example. In this example, however, the <i>putpmsg</i>() function creates and
|
||||
sends the message to the STREAMS file.</p>
|
||||
|
||||
<pre>
|
||||
<tt>#include <stropts.h>
|
||||
#include <string.h>
|
||||
...
|
||||
int fd;
|
||||
char *ctrlbuf = "This is the control part";
|
||||
char *databuf = "This is the data part";
|
||||
struct strbuf ctrl;
|
||||
struct strbuf data;
|
||||
int ret;
|
||||
<br>
|
||||
ctrl.buf = ctrlbuf;
|
||||
ctrl.len = strlen(ctrlbuf);
|
||||
<br>
|
||||
data.buf = databuf;
|
||||
data.len = strlen(databuf);
|
||||
<br>
|
||||
ret = putpmsg(fd, &ctrl, &data, 0, MSG_HIPRI);
|
||||
</tt>
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<h4><a name="tag_03_584_07"></a>APPLICATION USAGE</h4>
|
||||
|
||||
<blockquote>
|
||||
<p>None.</p>
|
||||
</blockquote>
|
||||
|
||||
<h4><a name="tag_03_584_08"></a>RATIONALE</h4>
|
||||
|
||||
<blockquote>
|
||||
<p>None.</p>
|
||||
</blockquote>
|
||||
|
||||
<h4><a name="tag_03_584_09"></a>FUTURE DIRECTIONS</h4>
|
||||
|
||||
<blockquote>
|
||||
<p>None.</p>
|
||||
</blockquote>
|
||||
|
||||
<h4><a name="tag_03_584_10"></a>SEE ALSO</h4>
|
||||
|
||||
<blockquote>
|
||||
<p><a href="xsh_chap02_06.html#tag_02_06"><i>STREAMS</i></a> , <a href="getmsg.html"><i>getmsg</i>()</a> , <a href=
|
||||
"poll.html"><i>poll</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_584_11"></a>CHANGE HISTORY</h4>
|
||||
|
||||
<blockquote>
|
||||
<p>First released in Issue 4, Version 2.</p>
|
||||
</blockquote>
|
||||
|
||||
<h4><a name="tag_03_584_12"></a>Issue 5</h4>
|
||||
|
||||
<blockquote>
|
||||
<p>Moved from X/OPEN UNIX extension to BASE.</p>
|
||||
|
||||
<p>The following text is removed from the DESCRIPTION: "The STREAM head guarantees that the control part of a message generated by
|
||||
<i>putmsg</i>() is at least 64 bytes in length".</p>
|
||||
</blockquote>
|
||||
|
||||
<h4><a name="tag_03_584_13"></a>Issue 6</h4>
|
||||
|
||||
<blockquote>
|
||||
<p>This function is marked as part of the XSI STREAMS Option Group.</p>
|
||||
|
||||
<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>
|
||||
|
||||
Reference in New Issue
Block a user