mirror of https://github.com/mkerrisk/man-pages
1059 lines
31 KiB
Plaintext
1059 lines
31 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "IOCTL" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" ioctl
|
|
.SH NAME
|
|
ioctl \- control a STREAMS device (\fBSTREAMS\fP)
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <stropts.h>
|
|
.br
|
|
.sp
|
|
int ioctl(int\fP \fIfildes\fP\fB, int\fP \fIrequest\fP\fB, ... /*
|
|
arg */); \fP
|
|
\fB
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fIioctl\fP() function shall perform a variety of control functions
|
|
on STREAMS devices. For non-STREAMS devices, the
|
|
functions performed by this call are unspecified. The \fIrequest\fP
|
|
argument and an optional third argument (with varying type)
|
|
shall be passed to and interpreted by the appropriate part of the
|
|
STREAM associated with \fIfildes\fP.
|
|
.LP
|
|
The \fIfildes\fP argument is an open file descriptor that refers to
|
|
a device.
|
|
.LP
|
|
The \fIrequest\fP argument selects the control function to be performed
|
|
and shall depend on the STREAMS device being
|
|
addressed.
|
|
.LP
|
|
The \fIarg\fP argument represents additional information that is needed
|
|
by this specific STREAMS device to perform the
|
|
requested function. The type of \fIarg\fP depends upon the particular
|
|
control request, but it shall be either an integer or a
|
|
pointer to a device-specific data structure.
|
|
.LP
|
|
The \fIioctl\fP() commands applicable to STREAMS, their arguments,
|
|
and error conditions that apply to each individual command
|
|
are described below.
|
|
.LP
|
|
The following \fIioctl\fP() commands, with error values indicated,
|
|
are applicable to all STREAMS files:
|
|
.TP 7
|
|
I_PUSH
|
|
Pushes the module whose name is pointed to by \fIarg\fP onto the top
|
|
of the current STREAM, just below the STREAM head. It
|
|
then calls the \fIopen\fP() function of the newly-pushed module.
|
|
.LP
|
|
The \fIioctl\fP() function with the I_PUSH command shall fail if:
|
|
.TP 7
|
|
.B EINVAL
|
|
.RS
|
|
Invalid module name.
|
|
.RE
|
|
.TP 7
|
|
.B ENXIO
|
|
.RS
|
|
Open function of new module failed.
|
|
.RE
|
|
.TP 7
|
|
.B ENXIO
|
|
.RS
|
|
Hangup received on \fIfildes\fP.
|
|
.RE
|
|
.sp
|
|
.TP 7
|
|
I_POP
|
|
Removes the module just below the STREAM head of the STREAM pointed
|
|
to by \fIfildes\fP. The \fIarg\fP argument should be 0 in
|
|
an I_POP request.
|
|
.LP
|
|
The \fIioctl\fP() function with the I_POP command shall fail if:
|
|
.TP 7
|
|
.B EINVAL
|
|
.RS
|
|
No module present in the STREAM.
|
|
.RE
|
|
.TP 7
|
|
.B ENXIO
|
|
.RS
|
|
Hangup received on \fIfildes\fP.
|
|
.RE
|
|
.sp
|
|
.TP 7
|
|
I_LOOK
|
|
Retrieves the name of the module just below the STREAM head of the
|
|
STREAM pointed to by \fIfildes\fP, and places it in a
|
|
character string pointed to by \fIarg\fP. The buffer pointed to by
|
|
\fIarg\fP should be at least FMNAMESZ+1 bytes long, where
|
|
FMNAMESZ is defined in \fI<stropts.h>\fP.
|
|
.LP
|
|
The \fIioctl\fP() function with the I_LOOK command shall fail if:
|
|
.TP 7
|
|
.B EINVAL
|
|
.RS
|
|
No module present in the STREAM.
|
|
.RE
|
|
.sp
|
|
.TP 7
|
|
I_FLUSH
|
|
Flushes read and/or write queues, depending on the value of \fIarg\fP.
|
|
Valid \fIarg\fP values are:
|
|
.TP 7
|
|
FLUSHR
|
|
.RS
|
|
Flush all read queues.
|
|
.RE
|
|
.TP 7
|
|
FLUSHW
|
|
.RS
|
|
Flush all write queues.
|
|
.RE
|
|
.TP 7
|
|
FLUSHRW
|
|
.RS
|
|
Flush all read and all write queues.
|
|
.RE
|
|
.sp
|
|
.LP
|
|
The \fIioctl\fP() function with the I_FLUSH command shall fail if:
|
|
.TP 7
|
|
.B EINVAL
|
|
.RS
|
|
Invalid \fIarg\fP value.
|
|
.RE
|
|
.TP 7
|
|
.B EAGAIN \fRor\fP ENOSR
|
|
.RS
|
|
.sp
|
|
Unable to allocate buffers for flush message.
|
|
.RE
|
|
.TP 7
|
|
.B ENXIO
|
|
.RS
|
|
Hangup received on \fIfildes\fP.
|
|
.RE
|
|
.sp
|
|
.TP 7
|
|
I_FLUSHBAND
|
|
Flushes a particular band of messages. The \fIarg\fP argument points
|
|
to a \fBbandinfo\fP structure. The \fIbi_flag\fP member
|
|
may be one of FLUSHR, FLUSHW, or FLUSHRW as described above. The \fIbi_pri\fP
|
|
member determines the priority band to be
|
|
flushed.
|
|
.TP 7
|
|
I_SETSIG
|
|
Requests that the STREAMS implementation send the SIGPOLL signal to
|
|
the calling process when a particular event has occurred on
|
|
the STREAM associated with \fIfildes\fP. I_SETSIG supports an asynchronous
|
|
processing capability in STREAMS. The value of
|
|
\fIarg\fP 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:
|
|
.TP 7
|
|
S_RDNORM
|
|
.RS
|
|
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.
|
|
.RE
|
|
.TP 7
|
|
S_RDBAND
|
|
.RS
|
|
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.
|
|
.RE
|
|
.TP 7
|
|
S_INPUT
|
|
.RS
|
|
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.
|
|
.RE
|
|
.TP 7
|
|
S_HIPRI
|
|
.RS
|
|
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.
|
|
.RE
|
|
.TP 7
|
|
S_OUTPUT
|
|
.RS
|
|
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.
|
|
.RE
|
|
.TP 7
|
|
S_WRNORM
|
|
.RS
|
|
Equivalent to S_OUTPUT.
|
|
.RE
|
|
.TP 7
|
|
S_WRBAND
|
|
.RS
|
|
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.
|
|
.RE
|
|
.TP 7
|
|
S_MSG
|
|
.RS
|
|
A STREAMS signal message that contains the SIGPOLL signal has reached
|
|
the front of the STREAM head read queue.
|
|
.RE
|
|
.TP 7
|
|
S_ERROR
|
|
.RS
|
|
Notification of an error condition has reached the STREAM head.
|
|
.RE
|
|
.TP 7
|
|
S_HANGUP
|
|
.RS
|
|
Notification of a hangup has reached the STREAM head.
|
|
.RE
|
|
.TP 7
|
|
S_BANDURG
|
|
.RS
|
|
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.
|
|
.RE
|
|
.sp
|
|
.LP
|
|
If \fIarg\fP is 0, the calling process shall be unregistered and shall
|
|
not receive further SIGPOLL signals for the stream
|
|
associated with \fIfildes\fP.
|
|
.LP
|
|
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.
|
|
.LP
|
|
The \fIioctl\fP() function with the I_SETSIG command shall fail if:
|
|
.TP 7
|
|
.B EINVAL
|
|
.RS
|
|
The value of \fIarg\fP is invalid.
|
|
.RE
|
|
.TP 7
|
|
.B EINVAL
|
|
.RS
|
|
The value of \fIarg\fP is 0 and the calling process is not registered
|
|
to receive the SIGPOLL signal.
|
|
.RE
|
|
.TP 7
|
|
.B EAGAIN
|
|
.RS
|
|
There were insufficient resources to store the signal request.
|
|
.RE
|
|
.sp
|
|
.TP 7
|
|
I_GETSIG
|
|
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 \fBint\fP pointed to by \fIarg\fP, where the events
|
|
are those specified in the description of I_SETSIG above.
|
|
.LP
|
|
The \fIioctl\fP() function with the I_GETSIG command shall fail if:
|
|
.TP 7
|
|
.B EINVAL
|
|
.RS
|
|
Process is not registered to receive the SIGPOLL signal.
|
|
.RE
|
|
.sp
|
|
.TP 7
|
|
I_FIND
|
|
Compares the names of all modules currently present in the STREAM
|
|
to the name pointed to by \fIarg\fP, and returns 1 if the
|
|
named module is present in the STREAM, or returns 0 if the named module
|
|
is not present.
|
|
.LP
|
|
The \fIioctl\fP() function with the I_FIND command shall fail if:
|
|
.TP 7
|
|
.B EINVAL
|
|
.RS
|
|
\fIarg\fP does not contain a valid module name.
|
|
.RE
|
|
.sp
|
|
.TP 7
|
|
I_PEEK
|
|
Retrieves the information in the first message on the STREAM head
|
|
read queue without taking the message off the queue. It is
|
|
analogous to \fIgetmsg\fP() except that this command does not remove
|
|
the message from the
|
|
queue. The \fIarg\fP argument points to a \fBstrpeek\fP structure.
|
|
.LP
|
|
The application shall ensure that the \fImaxlen\fP member in the \fBctlbuf\fP
|
|
and \fBdatabuf strbuf\fP structures is set to
|
|
the number of bytes of control information and/or data information,
|
|
respectively, to retrieve. The \fIflags\fP member may be
|
|
marked RS_HIPRI or 0, as described by \fIgetmsg\fP(). If the process
|
|
sets \fIflags\fP to
|
|
RS_HIPRI, for example, I_PEEK shall only look for a high-priority
|
|
message on the STREAM head read queue.
|
|
.LP
|
|
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 \fIflags\fP 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, \fBctlbuf\fP specifies information
|
|
in the control buffer, \fBdatabuf\fP specifies information
|
|
in the data buffer, and \fIflags\fP contains the value RS_HIPRI or
|
|
0.
|
|
.TP 7
|
|
I_SRDOPT
|
|
Sets the read mode using the value of the argument \fIarg\fP. Read
|
|
modes are described in \fIread\fP() . Valid \fIarg\fP flags are:
|
|
.TP 7
|
|
RNORM
|
|
.RS
|
|
Byte-stream mode, the default.
|
|
.RE
|
|
.TP 7
|
|
RMSGD
|
|
.RS
|
|
Message-discard mode.
|
|
.RE
|
|
.TP 7
|
|
RMSGN
|
|
.RS
|
|
Message-nondiscard mode.
|
|
.RE
|
|
.sp
|
|
.LP
|
|
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.
|
|
.LP
|
|
In addition, treatment of control messages by the STREAM head may
|
|
be changed by setting any of the following flags in
|
|
\fIarg\fP:
|
|
.TP 7
|
|
RPROTNORM
|
|
.RS
|
|
Fail \fIread\fP() with [EBADMSG] if a message containing a control
|
|
part is at the front
|
|
of the STREAM head read queue.
|
|
.RE
|
|
.TP 7
|
|
RPROTDAT
|
|
.RS
|
|
Deliver the control part of a message as data when a process issues
|
|
a \fIread\fP().
|
|
.RE
|
|
.TP 7
|
|
RPROTDIS
|
|
.RS
|
|
Discard the control part of a message, delivering any data portion,
|
|
when a process issues a \fIread\fP().
|
|
.RE
|
|
.sp
|
|
.LP
|
|
The \fIioctl\fP() function with the I_SRDOPT command shall fail if:
|
|
.TP 7
|
|
.B EINVAL
|
|
.RS
|
|
The \fIarg\fP argument is not valid.
|
|
.RE
|
|
.sp
|
|
.TP 7
|
|
I_GRDOPT
|
|
Returns the current read mode setting, as described above, in an \fBint\fP
|
|
pointed to by the argument \fIarg\fP. Read modes
|
|
are described in \fIread\fP() .
|
|
.TP 7
|
|
I_NREAD
|
|
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 \fBint\fP pointed to by \fIarg\fP. 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 \fIarg\fP, but the \fIioctl\fP()
|
|
return value is greater than 0, this indicates that a
|
|
zero-length message is next on the queue.
|
|
.TP 7
|
|
I_FDINSERT
|
|
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 \fIarg\fP argument points
|
|
to a \fBstrfdinsert\fP structure.
|
|
.LP
|
|
The application shall ensure that the \fIlen\fP member in the \fBctlbuf
|
|
strbuf\fP structure is set to the size of a
|
|
\fBt_uscalar_t\fP plus the number of bytes of control information
|
|
to be sent with the message. The \fIfildes\fP member specifies
|
|
the file descriptor of the other STREAM, and the \fIoffset\fP member,
|
|
which must be suitably aligned for use as a
|
|
\fBt_uscalar_t\fP, specifies the offset from the start of the control
|
|
buffer where I_FDINSERT shall store a \fBt_uscalar_t\fP
|
|
whose interpretation is specific to the STREAM end. The application
|
|
shall ensure that the \fIlen\fP member in the \fBdatabuf
|
|
strbuf\fP 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.
|
|
.LP
|
|
The \fIflags\fP member specifies the type of message to be created.
|
|
A normal message is created if \fIflags\fP is set to 0,
|
|
and a high-priority message is created if \fIflags\fP 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 \fIerrno\fP to [EAGAIN].
|
|
.LP
|
|
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.
|
|
.LP
|
|
The \fIioctl\fP() function with the I_FDINSERT command shall fail
|
|
if:
|
|
.TP 7
|
|
.B EAGAIN
|
|
.RS
|
|
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.
|
|
.RE
|
|
.TP 7
|
|
.B EAGAIN \fRor\fP ENOSR
|
|
.RS
|
|
.sp
|
|
Buffers cannot be allocated for the message that is to be created.
|
|
.RE
|
|
.TP 7
|
|
.B EINVAL
|
|
.RS
|
|
One of the following:
|
|
.RS
|
|
.IP " *" 3
|
|
The \fIfildes\fP member of the \fBstrfdinsert\fP structure is not
|
|
a valid, open STREAM file descriptor.
|
|
.LP
|
|
.IP " *" 3
|
|
The size of a \fBt_uscalar_t\fP plus \fIoffset\fP is greater than
|
|
the \fIlen\fP member for the buffer specified through
|
|
\fBctlbuf\fP.
|
|
.LP
|
|
.IP " *" 3
|
|
The \fIoffset\fP member does not specify a properly-aligned location
|
|
in the data buffer.
|
|
.LP
|
|
.IP " *" 3
|
|
An undefined value is stored in \fIflags\fP.
|
|
.LP
|
|
.RE
|
|
.RE
|
|
.TP 7
|
|
.B ENXIO
|
|
.RS
|
|
Hangup received on the STREAM identified by either the \fIfildes\fP
|
|
argument or the \fIfildes\fP member of the
|
|
\fBstrfdinsert\fP structure.
|
|
.RE
|
|
.TP 7
|
|
.B ERANGE
|
|
.RS
|
|
The \fIlen\fP member for the buffer specified through \fBdatabuf\fP
|
|
does not fall within the range specified by the maximum
|
|
and minimum packet sizes of the topmost STREAM module; or the \fIlen\fP
|
|
member for the buffer specified through \fBdatabuf\fP is
|
|
larger than the maximum configured size of the data part of a message;
|
|
or the \fIlen\fP member for the buffer specified through
|
|
\fBctlbuf\fP is larger than the maximum configured size of the control
|
|
part of a message.
|
|
.RE
|
|
.sp
|
|
.TP 7
|
|
I_STR
|
|
Constructs an internal STREAMS \fIioctl\fP() message from the data
|
|
pointed to by \fIarg\fP, and sends that message
|
|
downstream.
|
|
.LP
|
|
This mechanism is provided to send \fIioctl\fP() requests to downstream
|
|
modules and drivers. It allows information to be sent
|
|
with \fIioctl\fP(), 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 \fIerrno\fP set
|
|
to [ETIME].
|
|
.LP
|
|
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.
|
|
.LP
|
|
To send requests downstream, the application shall ensure that \fIarg\fP
|
|
points to a \fBstrioctl\fP structure.
|
|
.LP
|
|
The \fIic_cmd\fP member is the internal \fIioctl\fP() command intended
|
|
for a downstream module or driver and \fIic_timout\fP
|
|
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. \fIic_len\fP is the number
|
|
of bytes in the data argument, and \fIic_dp\fP is a
|
|
pointer to the data argument. The \fIic_len\fP 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
|
|
\fIic_dp\fP should be large enough to contain the maximum amount of
|
|
data that any module or the driver in the STREAM can
|
|
return).
|
|
.LP
|
|
The STREAM head shall convert the information pointed to by the \fBstrioctl\fP
|
|
structure to an internal \fIioctl\fP() command
|
|
message and send it downstream.
|
|
.LP
|
|
The \fIioctl\fP() function with the I_STR command shall fail if:
|
|
.TP 7
|
|
.B EAGAIN \fRor\fP ENOSR
|
|
.RS
|
|
.sp
|
|
Unable to allocate buffers for the \fIioctl\fP() message.
|
|
.RE
|
|
.TP 7
|
|
.B EINVAL
|
|
.RS
|
|
The \fIic_len\fP member is less than 0 or larger than the maximum
|
|
configured size of the data part of a message, or
|
|
\fIic_timout\fP is less than -1.
|
|
.RE
|
|
.TP 7
|
|
.B ENXIO
|
|
.RS
|
|
Hangup received on \fIfildes\fP.
|
|
.RE
|
|
.TP 7
|
|
.B ETIME
|
|
.RS
|
|
A downstream \fIioctl\fP() timed out before acknowledgement was received.
|
|
.RE
|
|
.sp
|
|
.LP
|
|
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
|
|
\fIioctl\fP() command sent downstream fails. For these cases, I_STR
|
|
shall fail with \fIerrno\fP set to the value in the
|
|
message.
|
|
.TP 7
|
|
I_SWROPT
|
|
Sets the write mode using the value of the argument \fIarg\fP. Valid
|
|
bit settings for \fIarg\fP are:
|
|
.TP 7
|
|
SNDZERO
|
|
.RS
|
|
Send a zero-length message downstream when a \fIwrite\fP() of 0 bytes
|
|
occurs. To not
|
|
send a zero-length message when a \fIwrite\fP() of 0 bytes occurs,
|
|
the application shall
|
|
ensure that this bit is not set in \fIarg\fP (for example, \fIarg\fP
|
|
would be set to 0).
|
|
.RE
|
|
.sp
|
|
.LP
|
|
The \fIioctl\fP() function with the I_SWROPT command shall fail if:
|
|
.TP 7
|
|
.B EINVAL
|
|
.RS
|
|
\fIarg\fP is not the above value.
|
|
.RE
|
|
.sp
|
|
.TP 7
|
|
I_GWROPT
|
|
Returns the current write mode setting, as described above, in the
|
|
\fBint\fP that is pointed to by the argument
|
|
\fIarg\fP.
|
|
.TP 7
|
|
I_SENDFD
|
|
Creates a new reference to the open file description associated with
|
|
the file descriptor \fIarg\fP, and writes a message on
|
|
the STREAMS-based pipe \fIfildes\fP containing this reference, together
|
|
with the user ID and group ID of the calling process.
|
|
.LP
|
|
The \fIioctl\fP() function with the I_SENDFD command shall fail if:
|
|
.TP 7
|
|
.B EAGAIN
|
|
.RS
|
|
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.
|
|
.RE
|
|
.TP 7
|
|
.B EBADF
|
|
.RS
|
|
The \fIarg\fP argument is not a valid, open file descriptor.
|
|
.RE
|
|
.TP 7
|
|
.B EINVAL
|
|
.RS
|
|
The \fIfildes\fP argument is not connected to a STREAM pipe.
|
|
.RE
|
|
.TP 7
|
|
.B ENXIO
|
|
.RS
|
|
Hangup received on \fIfildes\fP.
|
|
.RE
|
|
.sp
|
|
.TP 7
|
|
I_RECVFD
|
|
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 \fIarg\fP argument is a
|
|
pointer to a \fBstrrecvfd\fP data structure as defined in \fI<stropts.h>\fP.
|
|
.LP
|
|
The \fIfd\fP member is a file descriptor. The \fIuid\fP and \fIgid\fP
|
|
members are the effective user ID and effective group
|
|
ID, respectively, of the sending process.
|
|
.LP
|
|
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 \fIerrno\fP set to [EAGAIN] if no message is present
|
|
at the STREAM head.
|
|
.LP
|
|
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 \fIfd\fP member of the \fBstrrecvfd\fP structure
|
|
pointed to by \fIarg\fP.
|
|
.LP
|
|
The \fIioctl\fP() function with the I_RECVFD command shall fail if:
|
|
.TP 7
|
|
.B EAGAIN
|
|
.RS
|
|
A message is not present at the STREAM head read queue and the O_NONBLOCK
|
|
flag is set.
|
|
.RE
|
|
.TP 7
|
|
.B EBADMSG
|
|
.RS
|
|
The message at the STREAM head read queue is not a message containing
|
|
a passed file descriptor.
|
|
.RE
|
|
.TP 7
|
|
.B EMFILE
|
|
.RS
|
|
The process has the maximum number of file descriptors currently open
|
|
that it is allowed.
|
|
.RE
|
|
.TP 7
|
|
.B ENXIO
|
|
.RS
|
|
Hangup received on \fIfildes\fP.
|
|
.RE
|
|
.sp
|
|
.TP 7
|
|
I_LIST
|
|
Allows the process to list all the module names on the STREAM, up
|
|
to and including the topmost driver name. If \fIarg\fP is a
|
|
null pointer, the return value shall be the number of modules, including
|
|
the driver, that are on the STREAM pointed to by
|
|
\fIfildes\fP. This lets the process allocate enough space for the
|
|
module names. Otherwise, it should point to a \fBstr_list\fP
|
|
structure.
|
|
.LP
|
|
The \fIsl_nmods\fP member indicates the number of entries the process
|
|
has allocated in the array. Upon return, the
|
|
\fIsl_modlist\fP member of the \fBstr_list\fP structure shall contain
|
|
the list of module names, and the number of entries that
|
|
have been filled into the \fIsl_modlist\fP array is found in the \fIsl_nmods\fP
|
|
member (the number includes the number of modules
|
|
including the driver). The return value from \fIioctl\fP() 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 ( \fIsl_nmods\fP) is
|
|
satisfied.
|
|
.LP
|
|
The \fIioctl\fP() function with the I_LIST command shall fail if:
|
|
.TP 7
|
|
.B EINVAL
|
|
.RS
|
|
The \fIsl_nmods\fP member is less than 1.
|
|
.RE
|
|
.TP 7
|
|
.B EAGAIN \fRor\fP ENOSR
|
|
.RS
|
|
.sp
|
|
Unable to allocate buffers.
|
|
.RE
|
|
.sp
|
|
.TP 7
|
|
I_ATMARK
|
|
Allows the process to see if the message at the head of the STREAM
|
|
head read queue is marked by some module downstream. The
|
|
\fIarg\fP 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:
|
|
.TP 7
|
|
ANYMARK
|
|
.RS
|
|
Check if the message is marked.
|
|
.RE
|
|
.TP 7
|
|
LASTMARK
|
|
.RS
|
|
Check if the message is the last one marked on the queue.
|
|
.RE
|
|
.sp
|
|
.LP
|
|
The bitwise-inclusive OR of the flags ANYMARK and LASTMARK is permitted.
|
|
.LP
|
|
The return value shall be 1 if the mark condition is satisfied; otherwise,
|
|
the value shall be 0.
|
|
.LP
|
|
The \fIioctl\fP() function with the I_ATMARK command shall fail if:
|
|
.TP 7
|
|
.B EINVAL
|
|
.RS
|
|
Invalid \fIarg\fP value.
|
|
.RE
|
|
.sp
|
|
.TP 7
|
|
I_CKBAND
|
|
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.
|
|
\fIarg\fP should be of type \fBint\fP.
|
|
.LP
|
|
The \fIioctl\fP() function with the I_CKBAND command shall fail if:
|
|
.TP 7
|
|
.B EINVAL
|
|
.RS
|
|
Invalid \fIarg\fP value.
|
|
.RE
|
|
.sp
|
|
.TP 7
|
|
I_GETBAND
|
|
Returns the priority band of the first message on the STREAM head
|
|
read queue in the integer referenced by \fIarg\fP.
|
|
.LP
|
|
The \fIioctl\fP() function with the I_GETBAND command shall fail if:
|
|
.TP 7
|
|
.B ENODATA
|
|
.RS
|
|
No message on the STREAM head read queue.
|
|
.RE
|
|
.sp
|
|
.TP 7
|
|
I_CANPUT
|
|
Checks if a certain band is writable. \fIarg\fP 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.
|
|
.LP
|
|
The \fIioctl\fP() function with the I_CANPUT command shall fail if:
|
|
.TP 7
|
|
.B EINVAL
|
|
.RS
|
|
Invalid \fIarg\fP value.
|
|
.RE
|
|
.sp
|
|
.TP 7
|
|
I_SETCLTIME
|
|
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
|
|
\fIarg\fP 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.
|
|
.LP
|
|
The \fIioctl\fP() function with the I_SETCLTIME command shall fail
|
|
if:
|
|
.TP 7
|
|
.B EINVAL
|
|
.RS
|
|
Invalid \fIarg\fP value.
|
|
.RE
|
|
.sp
|
|
.TP 7
|
|
I_GETCLTIME
|
|
Returns the close time delay in the integer pointed to by \fIarg\fP.
|
|
.sp
|
|
.SS Multiplexed STREAMS Configurations
|
|
.LP
|
|
The following commands are used for connecting and disconnecting multiplexed
|
|
STREAMS configurations. These commands use an
|
|
implementation-defined default timeout interval.
|
|
.TP 7
|
|
I_LINK
|
|
Connects two STREAMs, where \fIfildes\fP is the file descriptor of
|
|
the STREAM connected to the multiplexing driver, and
|
|
\fIarg\fP is the file descriptor of the STREAM connected to another
|
|
driver. The STREAM designated by \fIarg\fP 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.
|
|
.LP
|
|
The \fIioctl\fP() function with the I_LINK command shall fail if:
|
|
.TP 7
|
|
.B ENXIO
|
|
.RS
|
|
Hangup received on \fIfildes\fP.
|
|
.RE
|
|
.TP 7
|
|
.B ETIME
|
|
.RS
|
|
Timeout before acknowledgement message was received at STREAM head.
|
|
.RE
|
|
.TP 7
|
|
.B EAGAIN \fRor\fP ENOSR
|
|
.RS
|
|
.sp
|
|
Unable to allocate STREAMS storage to perform the I_LINK.
|
|
.RE
|
|
.TP 7
|
|
.B EBADF
|
|
.RS
|
|
The \fIarg\fP argument is not a valid, open file descriptor.
|
|
.RE
|
|
.TP 7
|
|
.B EINVAL
|
|
.RS
|
|
The \fIfildes\fP argument does not support multiplexing; or \fIarg\fP
|
|
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.
|
|
.RE
|
|
.sp
|
|
.LP
|
|
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 \fIfildes\fP. In addition,
|
|
an error code can be returned in the positive or negative
|
|
acknowledgement message. For these cases, I_LINK fails with \fIerrno\fP
|
|
set to the value in the message.
|
|
.TP 7
|
|
I_UNLINK
|
|
Disconnects the two STREAMs specified by \fIfildes\fP and \fIarg\fP.
|
|
\fIfildes\fP is the file descriptor of the STREAM
|
|
connected to the multiplexing driver. The \fIarg\fP argument is the
|
|
multiplexer ID number that was returned by the I_LINK
|
|
\fIioctl\fP() command when a STREAM was connected downstream from
|
|
the multiplexing driver. If \fIarg\fP is MUXID_ALL, then all
|
|
STREAMs that were connected to \fIfildes\fP shall be disconnected.
|
|
As in I_LINK, this command requires acknowledgement.
|
|
.LP
|
|
The \fIioctl\fP() function with the I_UNLINK command shall fail if:
|
|
.TP 7
|
|
.B ENXIO
|
|
.RS
|
|
Hangup received on \fIfildes\fP.
|
|
.RE
|
|
.TP 7
|
|
.B ETIME
|
|
.RS
|
|
Timeout before acknowledgement message was received at STREAM head.
|
|
.RE
|
|
.TP 7
|
|
.B EAGAIN \fRor\fP ENOSR
|
|
.RS
|
|
.sp
|
|
Unable to allocate buffers for the acknowledgement message.
|
|
.RE
|
|
.TP 7
|
|
.B EINVAL
|
|
.RS
|
|
Invalid multiplexer ID number.
|
|
.RE
|
|
.sp
|
|
.LP
|
|
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 \fIfildes\fP. In addition,
|
|
an error code can be returned in the positive or negative
|
|
acknowledgement message. For these cases, I_UNLINK shall fail with
|
|
\fIerrno\fP set to the value in the message.
|
|
.TP 7
|
|
I_PLINK
|
|
Creates a \fIpersistent connection\fP between two STREAMs, where \fIfildes\fP
|
|
is the file descriptor of the STREAM connected
|
|
to the multiplexing driver, and \fIarg\fP 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
|
|
\fIfildes\fP associated with the upper STREAM to the
|
|
multiplexing driver is closed. The STREAM designated by \fIarg\fP
|
|
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.
|
|
.LP
|
|
The \fIioctl\fP() function with the I_PLINK command shall fail if:
|
|
.TP 7
|
|
.B ENXIO
|
|
.RS
|
|
Hangup received on \fIfildes\fP.
|
|
.RE
|
|
.TP 7
|
|
.B ETIME
|
|
.RS
|
|
Timeout before acknowledgement message was received at STREAM head.
|
|
.RE
|
|
.TP 7
|
|
.B EAGAIN \fRor\fP ENOSR
|
|
.RS
|
|
.sp
|
|
Unable to allocate STREAMS storage to perform the I_PLINK.
|
|
.RE
|
|
.TP 7
|
|
.B EBADF
|
|
.RS
|
|
The \fIarg\fP argument is not a valid, open file descriptor.
|
|
.RE
|
|
.TP 7
|
|
.B EINVAL
|
|
.RS
|
|
The \fIfildes\fP argument does not support multiplexing; or \fIarg\fP
|
|
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.
|
|
.RE
|
|
.sp
|
|
.LP
|
|
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 \fIfildes\fP. In addition,
|
|
an error code can be returned in the positive or negative
|
|
acknowledgement message. For these cases, I_PLINK shall fail with
|
|
\fIerrno\fP set to the value in the message.
|
|
.TP 7
|
|
I_PUNLINK
|
|
Disconnects the two STREAMs specified by \fIfildes\fP and \fIarg\fP
|
|
from a persistent connection. The \fIfildes\fP argument
|
|
is the file descriptor of the STREAM connected to the multiplexing
|
|
driver. The \fIarg\fP argument is the multiplexer ID number
|
|
that was returned by the I_PLINK \fIioctl\fP() command when a STREAM
|
|
was connected downstream from the multiplexing driver. If
|
|
\fIarg\fP is MUXID_ALL, then all STREAMs which are persistent connections
|
|
to \fIfildes\fP shall be disconnected. As in I_PLINK,
|
|
this command requires the multiplexing driver to acknowledge the request.
|
|
.LP
|
|
The \fIioctl\fP() function with the I_PUNLINK command shall fail if:
|
|
.TP 7
|
|
.B ENXIO
|
|
.RS
|
|
Hangup received on \fIfildes\fP.
|
|
.RE
|
|
.TP 7
|
|
.B ETIME
|
|
.RS
|
|
Timeout before acknowledgement message was received at STREAM head.
|
|
.RE
|
|
.TP 7
|
|
.B EAGAIN \fRor\fP ENOSR
|
|
.RS
|
|
.sp
|
|
Unable to allocate buffers for the acknowledgement message.
|
|
.RE
|
|
.TP 7
|
|
.B EINVAL
|
|
.RS
|
|
Invalid multiplexer ID number.
|
|
.RE
|
|
.sp
|
|
.LP
|
|
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 \fIfildes\fP. In addition,
|
|
an error code can be returned in the positive or negative
|
|
acknowledgement message. For these cases, I_PUNLINK shall fail with
|
|
\fIerrno\fP set to the value in the message.
|
|
.sp
|
|
.SH RETURN VALUE
|
|
.LP
|
|
Upon successful completion, \fIioctl\fP() shall return a value other
|
|
than -1 that depends upon the STREAMS device control
|
|
function. Otherwise, it shall return -1 and set \fIerrno\fP to indicate
|
|
the error.
|
|
.SH ERRORS
|
|
.LP
|
|
Under the following general conditions, \fIioctl\fP() shall fail if:
|
|
.TP 7
|
|
.B EBADF
|
|
The \fIfildes\fP argument is not a valid open file descriptor.
|
|
.TP 7
|
|
.B EINTR
|
|
A signal was caught during the \fIioctl\fP() operation.
|
|
.TP 7
|
|
.B EINVAL
|
|
The STREAM or multiplexer referenced by \fIfildes\fP is linked (directly
|
|
or indirectly) downstream from a multiplexer.
|
|
.sp
|
|
.LP
|
|
If an underlying device driver detects an error, then \fIioctl\fP()
|
|
shall fail if:
|
|
.TP 7
|
|
.B EINVAL
|
|
The \fIrequest\fP or \fIarg\fP argument is not valid for this device.
|
|
.TP 7
|
|
.B EIO
|
|
Some physical I/O error has occurred.
|
|
.TP 7
|
|
.B ENOTTY
|
|
The \fIfildes\fP argument is not associated with a STREAMS device
|
|
that accepts control functions.
|
|
.TP 7
|
|
.B ENXIO
|
|
The \fIrequest\fP and \fIarg\fP arguments are valid for this device
|
|
driver, but the service requested cannot be performed on
|
|
this particular sub-device.
|
|
.TP 7
|
|
.B ENODEV
|
|
The \fIfildes\fP argument refers to a valid STREAMS device, but the
|
|
corresponding device driver does not support the
|
|
\fIioctl\fP() function.
|
|
.sp
|
|
.LP
|
|
If a STREAM is connected downstream from a multiplexer, any \fIioctl\fP()
|
|
command except I_UNLINK and I_PUNLINK shall set
|
|
\fIerrno\fP to [EINVAL].
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.LP
|
|
None.
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
The implementation-defined timeout interval for STREAMS has historically
|
|
been 15 seconds.
|
|
.SH RATIONALE
|
|
.LP
|
|
None.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fISTREAMS\fP , \fIclose\fP() , \fIfcntl\fP() , \fIgetmsg\fP() , \fIopen\fP()
|
|
, \fIpipe\fP() , \fIpoll\fP() , \fIputmsg\fP() , \fIread\fP() , \fIsigaction\fP()
|
|
, \fIwrite\fP() , the
|
|
Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI<stropts.h>\fP
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
event of any discrepancy between this version and the original IEEE and
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
is the referee document. The original Standard can be obtained online at
|
|
http://www.opengroup.org/unix/online.html .
|