ioctl.html

IEEE 1003.1-2003, Single Unix Specification v3

<dt>I_CANPUT</dt>

<dd>Checks if a certain band is writable. <i>arg</i> is set to the priority band in question. The return value shall be 0 if the
band is flow-controlled, 1 if the band is writable, or -1 on error. 

<p>The <i>ioctl</i>() function with the I_CANPUT command shall fail if:</p>

<dl compact>
<dt>[EINVAL]</dt>

<dd>Invalid <i>arg</i> value.</dd>
</dl>
</dd>

<dt>I_SETCLTIME</dt>

<dd>This request allows the process to set the time the STREAM head shall delay when a STREAM is closing and there is data on the
write queues. Before closing each module or driver, if there is data on its write queue, the STREAM head shall delay for the
specified amount of time to allow the data to drain. If, after the delay, data is still present, it shall be flushed. The
<i>arg</i> argument is a pointer to an integer specifying the number of milliseconds to delay, rounded up to the nearest valid
value. If I_SETCLTIME is not performed on a STREAM, an implementation-defined default timeout interval is used. 

<p>The <i>ioctl</i>() function with the I_SETCLTIME command shall fail if:</p>

<dl compact>
<dt>[EINVAL]</dt>

<dd>Invalid <i>arg</i> value.</dd>
</dl>
</dd>

<dt>I_GETCLTIME</dt>

<dd>Returns the close time delay in the integer pointed to by <i>arg</i>.</dd>
</dl>

<h5><a name="tag_03_282_03_01"></a>Multiplexed STREAMS Configurations</h5>

<p>The following commands are used for connecting and disconnecting multiplexed STREAMS configurations. These commands use an
implementation-defined default timeout interval.</p>

<dl compact>
<dt>I_LINK</dt>

<dd>Connects two STREAMs, where <i>fildes</i> is the file descriptor of the STREAM connected to the multiplexing driver, and
<i>arg</i> is the file descriptor of the STREAM connected to another driver. The STREAM designated by <i>arg</i> is connected below
the multiplexing driver. I_LINK requires the multiplexing driver to send an acknowledgement message to the STREAM head regarding
the connection. This call shall return a multiplexer ID number (an identifier used to disconnect the multiplexer; see I_UNLINK) on
success, and -1 on failure. 

<p>The <i>ioctl</i>() function with the I_LINK command shall fail if:</p>

<dl compact>
<dt>[ENXIO]</dt>

<dd>Hangup received on <i>fildes</i>.</dd>

<dt>[ETIME]</dt>

<dd>Timeout before acknowledgement message was received at STREAM head.</dd>

<dt>[EAGAIN] or [ENOSR]</dt>

<dd><br>
Unable to allocate STREAMS storage to perform the I_LINK.</dd>

<dt>[EBADF]</dt>

<dd>The <i>arg</i> argument is not a valid, open file descriptor.</dd>

<dt>[EINVAL]</dt>

<dd>The <i>fildes</i> argument does not support multiplexing; or <i>arg</i> is not a STREAM or is already connected downstream from
a multiplexer; or the specified I_LINK operation would connect the STREAM head in more than one place in the multiplexed
STREAM.</dd>
</dl>

<p>An I_LINK can also fail while waiting for the multiplexing driver to acknowledge the request, if a message indicating an error
or a hangup is received at the STREAM head of <i>fildes</i>. In addition, an error code can be returned in the positive or negative
acknowledgement message. For these cases, I_LINK fails with <i>errno</i> set to the value in the message.</p>
</dd>

<dt>I_UNLINK</dt>

<dd>Disconnects the two STREAMs specified by <i>fildes</i> and <i>arg</i>. <i>fildes</i> is the file descriptor of the STREAM
connected to the multiplexing driver. The <i>arg</i> argument is the multiplexer ID number that was returned by the I_LINK
<i>ioctl</i>() command when a STREAM was connected downstream from the multiplexing driver. If <i>arg</i> is MUXID_ALL, then all
STREAMs that were connected to <i>fildes</i> shall be disconnected. As in I_LINK, this command requires acknowledgement. 

<p>The <i>ioctl</i>() function with the I_UNLINK command shall fail if:</p>

<dl compact>
<dt>[ENXIO]</dt>

<dd>Hangup received on <i>fildes</i>.</dd>

<dt>[ETIME]</dt>

<dd>Timeout before acknowledgement message was received at STREAM head.</dd>

<dt>[EAGAIN] or [ENOSR]</dt>

<dd><br>
Unable to allocate buffers for the acknowledgement message.</dd>

<dt>[EINVAL]</dt>

<dd>Invalid multiplexer ID number.</dd>
</dl>

<p>An I_UNLINK can also fail while waiting for the multiplexing driver to acknowledge the request if a message indicating an error
or a hangup is received at the STREAM head of <i>fildes</i>. In addition, an error code can be returned in the positive or negative
acknowledgement message. For these cases, I_UNLINK shall fail with <i>errno</i> set to the value in the message.</p>
</dd>

<dt>I_PLINK</dt>

<dd>Creates a <i>persistent connection</i> between two STREAMs, where <i>fildes</i> is the file descriptor of the STREAM connected
to the multiplexing driver, and <i>arg</i> is the file descriptor of the STREAM connected to another driver. This call shall create
a persistent connection which can exist even if the file descriptor <i>fildes</i> associated with the upper STREAM to the
multiplexing driver is closed. The STREAM designated by <i>arg</i> gets connected via a persistent connection below the
multiplexing driver. I_PLINK requires the multiplexing driver to send an acknowledgement message to the STREAM head. This call
shall return a multiplexer ID number (an identifier that may be used to disconnect the multiplexer; see I_PUNLINK) on success, and
-1 on failure. 

<p>The <i>ioctl</i>() function with the I_PLINK command shall fail if:</p>

<dl compact>
<dt>[ENXIO]</dt>

<dd>Hangup received on <i>fildes</i>.</dd>

<dt>[ETIME]</dt>

<dd>Timeout before acknowledgement message was received at STREAM head.</dd>

<dt>[EAGAIN] or [ENOSR]</dt>

<dd><br>
Unable to allocate STREAMS storage to perform the I_PLINK.</dd>

<dt>[EBADF]</dt>

<dd>The <i>arg</i> argument is not a valid, open file descriptor.</dd>

<dt>[EINVAL]</dt>

<dd>The <i>fildes</i> argument does not support multiplexing; or <i>arg</i> is not a STREAM or is already connected downstream from
a multiplexer; or the specified I_PLINK operation would connect the STREAM head in more than one place in the multiplexed
STREAM.</dd>
</dl>

<p>An I_PLINK can also fail while waiting for the multiplexing driver to acknowledge the request, if a message indicating an error
or a hangup is received at the STREAM head of <i>fildes</i>. In addition, an error code can be returned in the positive or negative
acknowledgement message. For these cases, I_PLINK shall fail with <i>errno</i> set to the value in the message.</p>
</dd>

<dt>I_PUNLINK</dt>

<dd>Disconnects the two STREAMs specified by <i>fildes</i> and <i>arg</i> from a persistent connection. The <i>fildes</i> argument
is the file descriptor of the STREAM connected to the multiplexing driver. The <i>arg</i> argument is the multiplexer ID number
that was returned by the I_PLINK <i>ioctl</i>() command when a STREAM was connected downstream from the multiplexing driver. If
<i>arg</i> is MUXID_ALL, then all STREAMs which are persistent connections to <i>fildes</i> shall be disconnected. As in I_PLINK,
this command requires the multiplexing driver to acknowledge the request. 

<p>The <i>ioctl</i>() function with the I_PUNLINK command shall fail if:</p>

<dl compact>
<dt>[ENXIO]</dt>

<dd>Hangup received on <i>fildes</i>.</dd>

<dt>[ETIME]</dt>

<dd>Timeout before acknowledgement message was received at STREAM head.</dd>

<dt>[EAGAIN] or [ENOSR]</dt>

<dd><br>
Unable to allocate buffers for the acknowledgement message.</dd>

<dt>[EINVAL]</dt>

<dd>Invalid multiplexer ID number.</dd>
</dl>

<p>An I_PUNLINK can also fail while waiting for the multiplexing driver to acknowledge the request if a message indicating an error
or a hangup is received at the STREAM head of <i>fildes</i>. In addition, an error code can be returned in the positive or negative
acknowledgement message. For these cases, I_PUNLINK shall fail with <i>errno</i> set to the value in the message.</p>
</dd>
</dl>
</blockquote>

<h4><a name="tag_03_282_04"></a>RETURN VALUE</h4>

<blockquote>
<p>Upon successful completion, <i>ioctl</i>() shall return a value other than -1 that depends upon the STREAMS device control
function. Otherwise, it shall return -1 and set <i>errno</i> to indicate the error.</p>
</blockquote>

<h4><a name="tag_03_282_05"></a>ERRORS</h4>

<blockquote>
<p>Under the following general conditions, <i>ioctl</i>() shall fail if:</p>

<dl compact>
<dt>[EBADF]</dt>

<dd>The <i>fildes</i> argument is not a valid open file descriptor.</dd>

<dt>[EINTR]</dt>

<dd>A signal was caught during the <i>ioctl</i>() operation.</dd>

<dt>[EINVAL]</dt>

<dd>The STREAM or multiplexer referenced by <i>fildes</i> is linked (directly or indirectly) downstream from a multiplexer.</dd>
</dl>

<p>If an underlying device driver detects an error, then <i>ioctl</i>() shall fail if:</p>

<dl compact>
<dt>[EINVAL]</dt>

<dd>The <i>request</i> or <i>arg</i> argument is not valid for this device.</dd>

<dt>[EIO]</dt>

<dd>Some physical I/O error has occurred.</dd>

<dt>[ENOTTY]</dt>

<dd>The <i>fildes</i> argument is not associated with a STREAMS device that accepts control functions.</dd>

<dt>[ENXIO]</dt>

<dd>The <i>request</i> and <i>arg</i> arguments are valid for this device driver, but the service requested cannot be performed on
this particular sub-device.</dd>

<dt>[ENODEV]</dt>

<dd>The <i>fildes</i> argument refers to a valid STREAMS device, but the corresponding device driver does not support the
<i>ioctl</i>() function.</dd>
</dl>

<p>If a STREAM is connected downstream from a multiplexer, any <i>ioctl</i>() command except I_UNLINK and I_PUNLINK shall set
<i>errno</i> to [EINVAL].</p>
</blockquote>

<hr>
<div class="box"><em>The following sections are informative.</em></div>

<h4><a name="tag_03_282_06"></a>EXAMPLES</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_03_282_07"></a>APPLICATION USAGE</h4>

<blockquote>
<p>The implementation-defined timeout interval for STREAMS has historically been 15 seconds.</p>
</blockquote>

<h4><a name="tag_03_282_08"></a>RATIONALE</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_03_282_09"></a>FUTURE DIRECTIONS</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_03_282_10"></a>SEE ALSO</h4>

<blockquote>
<p><a href="xsh_chap02_06.html#tag_02_06"><i>STREAMS</i></a> , <a href="close.html"><i>close</i>()</a> , <a href=
"fcntl.html"><i>fcntl</i>()</a> , <a href="getmsg.html"><i>getmsg</i>()</a> , <a href="open.html"><i>open</i>()</a> , <a href=
"pipe.html"><i>pipe</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="sigaction.html"><i>sigaction</i>()</a> , <a href="write.html"><i>write</i>()</a> , the
Base Definitions volume of IEEE&nbsp;Std&nbsp;1003.1-2001, <a href="../basedefs/stropts.h.html"><i>&lt;stropts.h&gt;</i></a></p>
</blockquote>

<h4><a name="tag_03_282_11"></a>CHANGE HISTORY</h4>

<blockquote>
<p>First released in Issue 4, Version 2.</p>
</blockquote>

<h4><a name="tag_03_282_12"></a>Issue 5</h4>

<blockquote>
<p>Moved from X/OPEN UNIX extension to BASE.</p>
</blockquote>

<h4><a name="tag_03_282_13"></a>Issue 6</h4>

<blockquote>
<p>The Open Group Corrigendum U028/4 is applied, correcting text in the I_FDINSERT [EINVAL] case to refer to <i>ctlbuf</i>.</p>

<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 &quot;must&quot; 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 &reg; is a registered Trademark of The Open Group.<br>
POSIX &reg; 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>