ioctl.html

unix 下的C开发手册,还用详细的例程。

</dl>
<p>
<dt>I_CKBAND<dd>
Check if the message of a given priority band exists on the STREAM head read
queue.  This returns 1 if a message of the given priority exists, 0 if no
such message exists, or -1 on error.  <i>arg</i> should be of type <b>int</b>.
<p>
The
<i>ioctl()</i>
function with the I_CKBAND command will fail if:
<dl compact>

<dt>[EINVAL]<dd>
Invalid <i>arg</i> value.

</dl>
<p>
<dt>I_GETBAND<dd>
Return the priority band of the first message on the STREAM head read queue in
the integer referenced by <i>arg</i>.
<p>
The
<i>ioctl()</i>
function with the I_GETBAND command will fail if:
<dl compact>

<dt>[ENODATA]<dd>
No message on the STREAM head read queue.

</dl>
<p>
<dt>I_CANPUT<dd>
Check if a certain band is writable.  <i>arg</i> is set to the priority band in
question.  The return value is 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 will fail if:
<dl compact>

<dt>[EINVAL]<dd>
Invalid <i>arg</i> value.

</dl>
<p>
<dt>I_SETCLTIME<dd>
This request allows the process to set the time the STREAM head will 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 will delay for the specified amount of time to allow the data to
drain.  If, after the delay, data is still present, they will 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-dependent default timeout
interval is used.
<p>
The
<i>ioctl()</i>
function with the I_SETCLTIME command will fail if:
<dl compact>

<dt>[EINVAL]<dd>
Invalid <i>arg</i> value.

</dl>
<p>
<dt>I_GETCLTIME<dd>
This request returns the close time delay in the integer pointed to by
<i>arg</i>.
<p>
</dl>
<h5><a name = "tag_000_006_010_001">&nbsp;</a>Multiplexed STREAMS Configurations</h5>
<p>
The following four commands are used for connecting and disconnecting
multiplexed STREAMS configurations.
These commands use an implementation-dependent default timeout interval.
<dl compact>

<dt>I_LINK<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>
gets 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 returns a multiplexer ID number
(an identifier used to disconnect the multiplexer; see I_UNLINK) on success,
and -1 on failure.

The
<i>ioctl()</i>
function with the I_LINK command will fail if:
<dl compact>

<dt>[ENXIO]<dd>
Hangup received on <i>fildes</i>.

<dt>[ETIME]<dd>
Time out before acknowledgement message was received at STREAM head.

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

Unable to allocate STREAMS storage to perform the I_LINK.

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

<dt>[EINVAL]<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.

</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>
<dt>I_UNLINK<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> are disconnected.  As in I_LINK, this command requires
acknowledgement.
<p>
The
<i>ioctl()</i>
function with the I_UNLINK command will fail if:
<dl compact>

<dt>[ENXIO]<dd>
Hangup received on <i>fildes</i>.

<dt>[ETIME]<dd>
Time out before acknowledgement message was received at STREAM head.

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

Unable to allocate buffers for the acknowledgement message.

<dt>[EINVAL]<dd>
Invalid multiplexer ID number.

</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 fails with <i>errno</i> set
to the value in the message.
<p>
<dt>I_PLINK<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 creates 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 returns 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 will fail if:
<dl compact>

<dt>[ENXIO]<dd>
Hangup received on <i>fildes</i>.

<dt>[ETIME]<dd>
Time out before acknowledgement message was received at STREAM head.

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

Unable to allocate STREAMS storage to perform the I_PLINK.

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

<dt>[EINVAL]<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.

</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 fails with <i>errno</i> set
to the value in the message.
<p>
<dt>I_PUNLINK<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> are 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 will fail if:
<dl compact>

<dt>[ENXIO]<dd>
Hangup received on <i>fildes</i>.

<dt>[ETIME]<dd>
Time out before acknowledgement message was received at STREAM head.

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

Unable to allocate buffers for the acknowledgement message.

<dt>[EINVAL]<dd>
Invalid multiplexer ID number.

</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 fails with <i>errno</i> set to the value in the message.
<p>
</dl>
</blockquote><h4><a name = "tag_000_006_011">&nbsp;</a>RETURN VALUE</h4><blockquote>
Upon successful completion,
<i>ioctl()</i>
returns a value other than -1 that depends upon the STREAMS device control
function.  Otherwise, it returns -1 and sets <i>errno</i> to indicate the
error.
</blockquote><h4><a name = "tag_000_006_012">&nbsp;</a>ERRORS</h4><blockquote>
Under the following general conditions,
<i>ioctl()</i>
will fail if:
<dl compact>

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

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

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

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

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

<dt>[EIO]<dd>
Some physical I/O error has occurred.

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

<dt>[ENXIO]<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.

<dt>[ENODEV]<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.

</dl>
<p>
If a STREAM is connected downstream from a multiplexer, any
<i>ioctl()</i>
command except I_UNLINK and I_PUNLINK will set
<i>errno</i>
to [EINVAL].
</blockquote><h4><a name = "tag_000_006_013">&nbsp;</a>EXAMPLES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_006_014">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
The implementation-dependent timeout interval for STREAMS has historically
been 15 seconds.
</blockquote><h4><a name = "tag_000_006_015">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_006_016">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="close.html">close()</a></i>,
<i><a href="fcntl.html">fcntl()</a></i>,
<i><a href="getmsg.html">getmsg()</a></i>,
<i><a href="open.html">open()</a></i>,
<i><a href="pipe.html">pipe()</a></i>,
<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="sigaction.html">sigaction()</a></i>,
<i><a href="write.html">write()</a></i>,
<i><a href="stropts.h.html">&lt;stropts.h&gt;</a></i>,
<a href="STREAMS.html">STREAMS overview</a>.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 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>