ioctl.html

IEEE 1003.1-2003, Single Unix Specification v3

</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, &gt;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>&lt;stropts.h&gt;</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>