974 lines
36 KiB
HTML
974 lines
36 KiB
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 The Open Group, All Rights Reserved -->
|
|
<title>ioctl</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="ioctl"></a> <a name="tag_03_282"></a><!-- ioctl -->
|
|
<!--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_282_01"></a>NAME</h4>
|
|
|
|
<blockquote>ioctl - control a STREAMS device (<b>STREAMS</b>)</blockquote>
|
|
|
|
<h4><a name="tag_03_282_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 ioctl(int</tt> <i>fildes</i><tt>, int</tt> <i>request</i><tt>, ... /* arg */); <img src="../images/opt-end.gif" alt=
|
|
"[Option End]" border="0"></tt></code></div>
|
|
|
|
<tt><br>
|
|
</tt></blockquote>
|
|
|
|
<h4><a name="tag_03_282_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>ioctl</i>() function shall perform a variety of control functions on STREAMS devices. For non-STREAMS devices, the
|
|
functions performed by this call are unspecified. The <i>request</i> argument and an optional third argument (with varying type)
|
|
shall be passed to and interpreted by the appropriate part of the STREAM associated with <i>fildes</i>.</p>
|
|
|
|
<p>The <i>fildes</i> argument is an open file descriptor that refers to a device.</p>
|
|
|
|
<p>The <i>request</i> argument selects the control function to be performed and shall depend on the STREAMS device being
|
|
addressed.</p>
|
|
|
|
<p>The <i>arg</i> argument represents additional information that is needed by this specific STREAMS device to perform the
|
|
requested function. The type of <i>arg</i> depends upon the particular control request, but it shall be either an integer or a
|
|
pointer to a device-specific data structure.</p>
|
|
|
|
<p>The <i>ioctl</i>() commands applicable to STREAMS, their arguments, and error conditions that apply to each individual command
|
|
are described below.</p>
|
|
|
|
<p>The following <i>ioctl</i>() commands, with error values indicated, are applicable to all STREAMS files:</p>
|
|
|
|
<dl compact>
|
|
<dt>I_PUSH</dt>
|
|
|
|
<dd>Pushes the module whose name is pointed to by <i>arg</i> onto the top of the current STREAM, just below the STREAM head. It
|
|
then calls the <a href="../functions/open.html"><i>open</i>()</a> function of the newly-pushed module.
|
|
|
|
<p>The <i>ioctl</i>() function with the I_PUSH command shall fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd>Invalid module name.</dd>
|
|
|
|
<dt>[ENXIO]</dt>
|
|
|
|
<dd>Open function of new module failed.</dd>
|
|
|
|
<dt>[ENXIO]</dt>
|
|
|
|
<dd>Hangup received on <i>fildes</i>.</dd>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt>I_POP</dt>
|
|
|
|
<dd>Removes the module just below the STREAM head of the STREAM pointed to by <i>fildes</i>. The <i>arg</i> argument should be 0 in
|
|
an I_POP request.
|
|
|
|
<p>The <i>ioctl</i>() function with the I_POP command shall fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd>No module present in the STREAM.</dd>
|
|
|
|
<dt>[ENXIO]</dt>
|
|
|
|
<dd>Hangup received on <i>fildes</i>.</dd>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt>I_LOOK</dt>
|
|
|
|
<dd>Retrieves the name of the module just below the STREAM head of the STREAM pointed to by <i>fildes</i>, and places it in a
|
|
character string pointed to by <i>arg</i>. The buffer pointed to by <i>arg</i> should be at least FMNAMESZ+1 bytes long, where
|
|
FMNAMESZ is defined in <a href="../basedefs/stropts.h.html"><i><stropts.h></i></a>.
|
|
|
|
<p>The <i>ioctl</i>() function with the I_LOOK command shall fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd>No module present in the STREAM.</dd>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt>I_FLUSH</dt>
|
|
|
|
<dd>Flushes read and/or write queues, depending on the value of <i>arg</i>. Valid <i>arg</i> values are:
|
|
|
|
<dl compact>
|
|
<dt>FLUSHR</dt>
|
|
|
|
<dd>Flush all read queues.</dd>
|
|
|
|
<dt>FLUSHW</dt>
|
|
|
|
<dd>Flush all write queues.</dd>
|
|
|
|
<dt>FLUSHRW</dt>
|
|
|
|
<dd>Flush all read and all write queues.</dd>
|
|
</dl>
|
|
|
|
<p>The <i>ioctl</i>() function with the I_FLUSH command shall fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd>Invalid <i>arg</i> value.</dd>
|
|
|
|
<dt>[EAGAIN] or [ENOSR]</dt>
|
|
|
|
<dd><br>
|
|
Unable to allocate buffers for flush message.</dd>
|
|
|
|
<dt>[ENXIO]</dt>
|
|
|
|
<dd>Hangup received on <i>fildes</i>.</dd>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt>I_FLUSHBAND</dt>
|
|
|
|
<dd>Flushes a particular band of messages. The <i>arg</i> argument points to a <b>bandinfo</b> structure. The <i>bi_flag</i> member
|
|
may be one of FLUSHR, FLUSHW, or FLUSHRW as described above. The <i>bi_pri</i> member determines the priority band to be
|
|
flushed.</dd>
|
|
|
|
<dt>I_SETSIG</dt>
|
|
|
|
<dd>Requests that the STREAMS implementation send the SIGPOLL signal to the calling process when a particular event has occurred on
|
|
the STREAM associated with <i>fildes</i>. I_SETSIG supports an asynchronous processing capability in STREAMS. The value of
|
|
<i>arg</i> is a bitmask that specifies the events for which the process should be signaled. It is the bitwise-inclusive OR of any
|
|
combination of the following constants:
|
|
|
|
<dl compact>
|
|
<dt>S_RDNORM</dt>
|
|
|
|
<dd>A normal (priority band set to 0) message has arrived at the head of a STREAM head read queue. A signal shall be generated even
|
|
if the message is of zero length.</dd>
|
|
|
|
<dt>S_RDBAND</dt>
|
|
|
|
<dd>A message with a non-zero priority band has arrived at the head of a STREAM head read queue. A signal shall be generated even
|
|
if the message is of zero length.</dd>
|
|
|
|
<dt>S_INPUT</dt>
|
|
|
|
<dd>A message, other than a high-priority message, has arrived at the head of a STREAM head read queue. A signal shall be generated
|
|
even if the message is of zero length.</dd>
|
|
|
|
<dt>S_HIPRI</dt>
|
|
|
|
<dd>A high-priority message is present on a STREAM head read queue. A signal shall be generated even if the message is of zero
|
|
length.</dd>
|
|
|
|
<dt>S_OUTPUT</dt>
|
|
|
|
<dd>The write queue for normal data (priority band 0) just below the STREAM head is no longer full. This notifies the process that
|
|
there is room on the queue for sending (or writing) normal data downstream.</dd>
|
|
|
|
<dt>S_WRNORM</dt>
|
|
|
|
<dd>Equivalent to S_OUTPUT.</dd>
|
|
|
|
<dt>S_WRBAND</dt>
|
|
|
|
<dd>The write queue for a non-zero priority band just below the STREAM head is no longer full. This notifies the process that there
|
|
is room on the queue for sending (or writing) priority data downstream.</dd>
|
|
|
|
<dt>S_MSG</dt>
|
|
|
|
<dd>A STREAMS signal message that contains the SIGPOLL signal has reached the front of the STREAM head read queue.</dd>
|
|
|
|
<dt>S_ERROR</dt>
|
|
|
|
<dd>Notification of an error condition has reached the STREAM head.</dd>
|
|
|
|
<dt>S_HANGUP</dt>
|
|
|
|
<dd>Notification of a hangup has reached the STREAM head.</dd>
|
|
|
|
<dt>S_BANDURG</dt>
|
|
|
|
<dd>When used in conjunction with S_RDBAND, SIGURG is generated instead of SIGPOLL when a priority message reaches the front of the
|
|
STREAM head read queue.</dd>
|
|
</dl>
|
|
|
|
<p>If <i>arg</i> is 0, the calling process shall be unregistered and shall not receive further SIGPOLL signals for the stream
|
|
associated with <i>fildes</i>.</p>
|
|
|
|
<p>Processes that wish to receive SIGPOLL signals shall ensure that they explicitly register to receive them using I_SETSIG. If
|
|
several processes register to receive this signal for the same event on the same STREAM, each process shall be signaled when the
|
|
event occurs.</p>
|
|
|
|
<p>The <i>ioctl</i>() function with the I_SETSIG command shall fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd>The value of <i>arg</i> is invalid.</dd>
|
|
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd>The value of <i>arg</i> is 0 and the calling process is not registered to receive the SIGPOLL signal.</dd>
|
|
|
|
<dt>[EAGAIN]</dt>
|
|
|
|
<dd>There were insufficient resources to store the signal request.</dd>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt>I_GETSIG</dt>
|
|
|
|
<dd>Returns the events for which the calling process is currently registered to be sent a SIGPOLL signal. The events are returned
|
|
as a bitmask in an <b>int</b> pointed to by <i>arg</i>, where the events are those specified in the description of I_SETSIG above.
|
|
|
|
<p>The <i>ioctl</i>() function with the I_GETSIG command shall fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd>Process is not registered to receive the SIGPOLL signal.</dd>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt>I_FIND</dt>
|
|
|
|
<dd>Compares the names of all modules currently present in the STREAM to the name pointed to by <i>arg</i>, and returns 1 if the
|
|
named module is present in the STREAM, or returns 0 if the named module is not present.
|
|
|
|
<p>The <i>ioctl</i>() function with the I_FIND command shall fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd><i>arg</i> does not contain a valid module name.</dd>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt>I_PEEK</dt>
|
|
|
|
<dd>Retrieves the information in the first message on the STREAM head read queue without taking the message off the queue. It is
|
|
analogous to <a href="../functions/getmsg.html"><i>getmsg</i>()</a> except that this command does not remove the message from the
|
|
queue. The <i>arg</i> argument points to a <b>strpeek</b> structure.
|
|
|
|
<p>The application shall ensure that the <i>maxlen</i> member in the <b>ctlbuf</b> and <b>databuf strbuf</b> structures is set to
|
|
the number of bytes of control information and/or data information, respectively, to retrieve. The <i>flags</i> member may be
|
|
marked RS_HIPRI or 0, as described by <a href="../functions/getmsg.html"><i>getmsg</i>()</a>. If the process sets <i>flags</i> to
|
|
RS_HIPRI, for example, I_PEEK shall only look for a high-priority message on the STREAM head read queue.</p>
|
|
|
|
<p>I_PEEK returns 1 if a message was retrieved, and returns 0 if no message was found on the STREAM head read queue, or if the
|
|
RS_HIPRI flag was set in <i>flags</i> and a high-priority message was not present on the STREAM head read queue. It does not wait
|
|
for a message to arrive. On return, <b>ctlbuf</b> specifies information in the control buffer, <b>databuf</b> specifies information
|
|
in the data buffer, and <i>flags</i> contains the value RS_HIPRI or 0.</p>
|
|
</dd>
|
|
|
|
<dt>I_SRDOPT</dt>
|
|
|
|
<dd>Sets the read mode using the value of the argument <i>arg</i>. Read modes are described in <a href=
|
|
"read.html"><i>read</i>()</a> . Valid <i>arg</i> flags are:
|
|
|
|
<dl compact>
|
|
<dt>RNORM</dt>
|
|
|
|
<dd>Byte-stream mode, the default.</dd>
|
|
|
|
<dt>RMSGD</dt>
|
|
|
|
<dd>Message-discard mode.</dd>
|
|
|
|
<dt>RMSGN</dt>
|
|
|
|
<dd>Message-nondiscard mode.</dd>
|
|
</dl>
|
|
|
|
<p>The bitwise-inclusive OR of RMSGD and RMSGN shall return [EINVAL]. The bitwise-inclusive OR of RNORM and either RMSGD or RMSGN
|
|
shall result in the other flag overriding RNORM which is the default.</p>
|
|
|
|
<p>In addition, treatment of control messages by the STREAM head may be changed by setting any of the following flags in
|
|
<i>arg</i>:</p>
|
|
|
|
<dl compact>
|
|
<dt>RPROTNORM</dt>
|
|
|
|
<dd>Fail <a href="../functions/read.html"><i>read</i>()</a> with [EBADMSG] if a message containing a control part is at the front
|
|
of the STREAM head read queue.</dd>
|
|
|
|
<dt>RPROTDAT</dt>
|
|
|
|
<dd>Deliver the control part of a message as data when a process issues a <a href="../functions/read.html"><i>read</i>()</a>.</dd>
|
|
|
|
<dt>RPROTDIS</dt>
|
|
|
|
<dd>Discard the control part of a message, delivering any data portion, when a process issues a <a href=
|
|
"../functions/read.html"><i>read</i>()</a>.</dd>
|
|
</dl>
|
|
|
|
<p>The <i>ioctl</i>() function with the I_SRDOPT command shall fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd>The <i>arg</i> argument is not valid.</dd>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt>I_GRDOPT</dt>
|
|
|
|
<dd>Returns the current read mode setting, as described above, in an <b>int</b> pointed to by the argument <i>arg</i>. Read modes
|
|
are described in <a href="read.html"><i>read</i>()</a> .</dd>
|
|
|
|
<dt>I_NREAD</dt>
|
|
|
|
<dd>Counts the number of data bytes in the data part of the first message on the STREAM head read queue and places this value in
|
|
the <b>int</b> pointed to by <i>arg</i>. The return value for the command shall be the number of messages on the STREAM head read
|
|
queue. For example, if 0 is returned in <i>arg</i>, but the <i>ioctl</i>() return value is greater than 0, this indicates that a
|
|
zero-length message is next on the queue.</dd>
|
|
|
|
<dt>I_FDINSERT</dt>
|
|
|
|
<dd>Creates a message from specified buffer(s), adds information about another STREAM, and sends the message downstream. The
|
|
message contains a control part and an optional data part. The data and control parts to be sent are distinguished by placement in
|
|
separate buffers, as described below. The <i>arg</i> argument points to a <b>strfdinsert</b> structure.
|
|
|
|
<p>The application shall ensure that the <i>len</i> member in the <b>ctlbuf strbuf</b> structure is set to the size of a
|
|
<b>t_uscalar_t</b> plus the number of bytes of control information to be sent with the message. The <i>fildes</i> member specifies
|
|
the file descriptor of the other STREAM, and the <i>offset</i> member, which must be suitably aligned for use as a
|
|
<b>t_uscalar_t</b>, specifies the offset from the start of the control buffer where I_FDINSERT shall store a <b>t_uscalar_t</b>
|
|
whose interpretation is specific to the STREAM end. The application shall ensure that the <i>len</i> member in the <b>databuf
|
|
strbuf</b> structure is set to the number of bytes of data information to be sent with the message, or to 0 if no data part is to
|
|
be sent.</p>
|
|
|
|
<p>The <i>flags</i> member specifies the type of message to be created. A normal message is created if <i>flags</i> is set to 0,
|
|
and a high-priority message is created if <i>flags</i> is set to RS_HIPRI. For non-priority messages, I_FDINSERT shall block if the
|
|
STREAM write queue is full due to internal flow control conditions. For priority messages, I_FDINSERT does not block on this
|
|
condition. For non-priority messages, I_FDINSERT does not block when the write queue is full and O_NONBLOCK is set. Instead, it
|
|
fails and sets <i>errno</i> to [EAGAIN].</p>
|
|
|
|
<p>I_FDINSERT also blocks, unless prevented by lack of internal resources, waiting for the availability of message blocks in the
|
|
STREAM, regardless of priority or whether O_NONBLOCK has been specified. No partial message is sent.</p>
|
|
|
|
<p>The <i>ioctl</i>() function with the I_FDINSERT command shall fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EAGAIN]</dt>
|
|
|
|
<dd>A non-priority message is specified, the O_NONBLOCK flag is set, and the STREAM write queue is full due to internal flow
|
|
control conditions.</dd>
|
|
|
|
<dt>[EAGAIN] or [ENOSR]</dt>
|
|
|
|
<dd><br>
|
|
Buffers cannot be allocated for the message that is to be created.</dd>
|
|
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd>One of the following:
|
|
|
|
<ul>
|
|
<li>
|
|
<p>The <i>fildes</i> member of the <b>strfdinsert</b> structure is not a valid, open STREAM file descriptor.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The size of a <b>t_uscalar_t</b> plus <i>offset</i> is greater than the <i>len</i> member for the buffer specified through
|
|
<b>ctlbuf</b>.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The <i>offset</i> member does not specify a properly-aligned location in the data buffer.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>An undefined value is stored in <i>flags</i>.</p>
|
|
</li>
|
|
</ul>
|
|
</dd>
|
|
|
|
<dt>[ENXIO]</dt>
|
|
|
|
<dd>Hangup received on the STREAM identified by either the <i>fildes</i> argument or the <i>fildes</i> member of the
|
|
<b>strfdinsert</b> structure.</dd>
|
|
|
|
<dt>[ERANGE]</dt>
|
|
|
|
<dd>The <i>len</i> member for the buffer specified through <b>databuf</b> does not fall within the range specified by the maximum
|
|
and minimum packet sizes of the topmost STREAM module; or the <i>len</i> member for the buffer specified through <b>databuf</b> is
|
|
larger than the maximum configured size of the data part of a message; or the <i>len</i> member for the buffer specified through
|
|
<b>ctlbuf</b> is larger than the maximum configured size of the control part of a message.</dd>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt>I_STR</dt>
|
|
|
|
<dd>Constructs an internal STREAMS <i>ioctl</i>() message from the data pointed to by <i>arg</i>, and sends that message
|
|
downstream.
|
|
|
|
<p>This mechanism is provided to send <i>ioctl</i>() requests to downstream modules and drivers. It allows information to be sent
|
|
with <i>ioctl</i>(), and returns to the process any information sent upstream by the downstream recipient. I_STR shall block until
|
|
the system responds with either a positive or negative acknowledgement message, or until the request times out after some period of
|
|
time. If the request times out, it shall fail with <i>errno</i> set to [ETIME].</p>
|
|
|
|
<p>At most, one I_STR can be active on a STREAM. Further I_STR calls shall block until the active I_STR completes at the STREAM
|
|
head. The default timeout interval for these requests is 15 seconds. The O_NONBLOCK flag has no effect on this call.</p>
|
|
|
|
<p>To send requests downstream, the application shall ensure that <i>arg</i> points to a <b>strioctl</b> structure.</p>
|
|
|
|
<p>The <i>ic_cmd</i> member is the internal <i>ioctl</i>() command intended for a downstream module or driver and <i>ic_timout</i>
|
|
is the number of seconds (-1=infinite, 0=use implementation-defined timeout interval, >0=as specified) an I_STR request shall
|
|
wait for acknowledgement before timing out. <i>ic_len</i> is the number of bytes in the data argument, and <i>ic_dp</i> is a
|
|
pointer to the data argument. The <i>ic_len</i> member has two uses: on input, it contains the length of the data argument passed
|
|
in, and on return from the command, it contains the number of bytes being returned to the process (the buffer pointed to by
|
|
<i>ic_dp</i> should be large enough to contain the maximum amount of data that any module or the driver in the STREAM can
|
|
return).</p>
|
|
|
|
<p>The STREAM head shall convert the information pointed to by the <b>strioctl</b> structure to an internal <i>ioctl</i>() command
|
|
message and send it downstream.</p>
|
|
|
|
<p>The <i>ioctl</i>() function with the I_STR command shall fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EAGAIN] or [ENOSR]</dt>
|
|
|
|
<dd><br>
|
|
Unable to allocate buffers for the <i>ioctl</i>() message.</dd>
|
|
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd>The <i>ic_len</i> member is less than 0 or larger than the maximum configured size of the data part of a message, or
|
|
<i>ic_timout</i> is less than -1.</dd>
|
|
|
|
<dt>[ENXIO]</dt>
|
|
|
|
<dd>Hangup received on <i>fildes</i>.</dd>
|
|
|
|
<dt>[ETIME]</dt>
|
|
|
|
<dd>A downstream <i>ioctl</i>() timed out before acknowledgement was received.</dd>
|
|
</dl>
|
|
|
|
<p>An I_STR can also fail while waiting for an acknowledgement if a message indicating an error or a hangup is received at the
|
|
STREAM head. In addition, an error code can be returned in the positive or negative acknowledgement message, in the event the
|
|
<i>ioctl</i>() command sent downstream fails. For these cases, I_STR shall fail with <i>errno</i> set to the value in the
|
|
message.</p>
|
|
</dd>
|
|
|
|
<dt>I_SWROPT</dt>
|
|
|
|
<dd>Sets the write mode using the value of the argument <i>arg</i>. Valid bit settings for <i>arg</i> are:
|
|
|
|
<dl compact>
|
|
<dt>SNDZERO</dt>
|
|
|
|
<dd>Send a zero-length message downstream when a <a href="../functions/write.html"><i>write</i>()</a> of 0 bytes occurs. To not
|
|
send a zero-length message when a <a href="../functions/write.html"><i>write</i>()</a> of 0 bytes occurs, the application shall
|
|
ensure that this bit is not set in <i>arg</i> (for example, <i>arg</i> would be set to 0).</dd>
|
|
</dl>
|
|
|
|
<p>The <i>ioctl</i>() function with the I_SWROPT command shall fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd><i>arg</i> is not the above value.</dd>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt>I_GWROPT</dt>
|
|
|
|
<dd>Returns the current write mode setting, as described above, in the <b>int</b> that is pointed to by the argument
|
|
<i>arg</i>.</dd>
|
|
|
|
<dt>I_SENDFD</dt>
|
|
|
|
<dd>Creates a new reference to the open file description associated with the file descriptor <i>arg</i>, and writes a message on
|
|
the STREAMS-based pipe <i>fildes</i> containing this reference, together with the user ID and group ID of the calling process.
|
|
|
|
<p>The <i>ioctl</i>() function with the I_SENDFD command shall fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EAGAIN]</dt>
|
|
|
|
<dd>The sending STREAM is unable to allocate a message block to contain the file pointer; or the read queue of the receiving STREAM
|
|
head is full and cannot accept the message sent by I_SENDFD.</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 is not connected to a STREAM pipe.</dd>
|
|
|
|
<dt>[ENXIO]</dt>
|
|
|
|
<dd>Hangup received on <i>fildes</i>.</dd>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt>I_RECVFD</dt>
|
|
|
|
<dd>Retrieves the reference to an open file description from a message written to a STREAMS-based pipe using the I_SENDFD command,
|
|
and allocates a new file descriptor in the calling process that refers to this open file description. The <i>arg</i> argument is a
|
|
pointer to a <b>strrecvfd</b> data structure as defined in <a href="../basedefs/stropts.h.html"><i><stropts.h></i></a>.
|
|
|
|
<p>The <i>fd</i> member is a file descriptor. The <i>uid</i> and <i>gid</i> members are the effective user ID and effective group
|
|
ID, respectively, of the sending process.</p>
|
|
|
|
<p>If O_NONBLOCK is not set, I_RECVFD shall block until a message is present at the STREAM head. If O_NONBLOCK is set, I_RECVFD
|
|
shall fail with <i>errno</i> set to [EAGAIN] if no message is present at the STREAM head.</p>
|
|
|
|
<p>If the message at the STREAM head is a message sent by an I_SENDFD, a new file descriptor shall be allocated for the open file
|
|
descriptor referenced in the message. The new file descriptor is placed in the <i>fd</i> member of the <b>strrecvfd</b> structure
|
|
pointed to by <i>arg</i>.</p>
|
|
|
|
<p>The <i>ioctl</i>() function with the I_RECVFD command shall fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EAGAIN]</dt>
|
|
|
|
<dd>A message is not present at the STREAM head read queue and the O_NONBLOCK flag is set.</dd>
|
|
|
|
<dt>[EBADMSG]</dt>
|
|
|
|
<dd>The message at the STREAM head read queue is not a message containing a passed file descriptor.</dd>
|
|
|
|
<dt>[EMFILE]</dt>
|
|
|
|
<dd>The process has the maximum number of file descriptors currently open that it is allowed.</dd>
|
|
|
|
<dt>[ENXIO]</dt>
|
|
|
|
<dd>Hangup received on <i>fildes</i>.</dd>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt>I_LIST</dt>
|
|
|
|
<dd>Allows the process to list all the module names on the STREAM, up to and including the topmost driver name. If <i>arg</i> is a
|
|
null pointer, the return value shall be the number of modules, including the driver, that are on the STREAM pointed to by
|
|
<i>fildes</i>. This lets the process allocate enough space for the module names. Otherwise, it should point to a <b>str_list</b>
|
|
structure.
|
|
|
|
<p>The <i>sl_nmods</i> member indicates the number of entries the process has allocated in the array. Upon return, the
|
|
<i>sl_modlist</i> member of the <b>str_list</b> structure shall contain the list of module names, and the number of entries that
|
|
have been filled into the <i>sl_modlist</i> array is found in the <i>sl_nmods</i> member (the number includes the number of modules
|
|
including the driver). The return value from <i>ioctl</i>() shall be 0. The entries are filled in starting at the top of the STREAM
|
|
and continuing downstream until either the end of the STREAM is reached, or the number of requested modules ( <i>sl_nmods</i>) is
|
|
satisfied.</p>
|
|
|
|
<p>The <i>ioctl</i>() function with the I_LIST command shall fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd>The <i>sl_nmods</i> member is less than 1.</dd>
|
|
|
|
<dt>[EAGAIN] or [ENOSR]</dt>
|
|
|
|
<dd><br>
|
|
Unable to allocate buffers.</dd>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt>I_ATMARK</dt>
|
|
|
|
<dd>Allows the process to see if the message at the head of the STREAM head read queue is marked by some module downstream. The
|
|
<i>arg</i> argument determines how the checking is done when there may be multiple marked messages on the STREAM head read queue.
|
|
It may take on the following values:
|
|
|
|
<dl compact>
|
|
<dt>ANYMARK</dt>
|
|
|
|
<dd>Check if the message is marked.</dd>
|
|
|
|
<dt>LASTMARK</dt>
|
|
|
|
<dd>Check if the message is the last one marked on the queue.</dd>
|
|
</dl>
|
|
|
|
<p>The bitwise-inclusive OR of the flags ANYMARK and LASTMARK is permitted.</p>
|
|
|
|
<p>The return value shall be 1 if the mark condition is satisfied; otherwise, the value shall be 0.</p>
|
|
|
|
<p>The <i>ioctl</i>() function with the I_ATMARK command shall fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd>Invalid <i>arg</i> value.</dd>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt>I_CKBAND</dt>
|
|
|
|
<dd>Checks if the message of a given priority band exists on the STREAM head read queue. This shall return 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 shall fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd>Invalid <i>arg</i> value.</dd>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt>I_GETBAND</dt>
|
|
|
|
<dd>Returns 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 shall fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[ENODATA]</dt>
|
|
|
|
<dd>No message on the STREAM head read queue.</dd>
|
|
</dl>
|
|
</dd>
|
|
|
|
<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 Std 1003.1-2001, <a href="../basedefs/stropts.h.html"><i><stropts.h></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 "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>
|
|
|