HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
PROLOG |NAME |SYNOPSIS |DESCRIPTION |RETURN VALUE |ERRORS |EXAMPLES |APPLICATION USAGE |RATIONALE |FUTURE DIRECTIONS |SEE ALSO |COPYRIGHT | |
IOCTL(3P) POSIX Programmer's ManualIOCTL(3P)This manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ (consult the corresponding Linux manual page for details of Linux behavior), or the interface may not be implemented on Linux.
ioctl — control a STREAMS device (STREAMS)
#include <stropts.h> int ioctl(intfildes, intrequest, ... /* arg */);
Theioctl() function shall perform a variety of control functions on STREAMS devices. For non-STREAMS devices, the functions performed by this call are unspecified. Therequest argument and an optional third argument (with varying type) shall be passed to and interpreted by the appropriate part of the STREAM associated withfildes. Thefildes argument is an open file descriptor that refers to a device. Therequest argument selects the control function to be performed and shall depend on the STREAMS device being addressed. Thearg argument represents additional information that is needed by this specific STREAMS device to perform the requested function. The type ofarg depends upon the particular control request, but it shall be either an integer or a pointer to a device-specific data structure. Theioctl() commands applicable to STREAMS, their arguments, and error conditions that apply to each individual command are described below. The followingioctl() commands, with error values indicated, are applicable to all STREAMS files: I_PUSH Pushes the module whose name is pointed to byarg onto the top of the current STREAM, just below the STREAM head. It then calls theopen() function of the newly- pushed module. Theioctl() function with the I_PUSH command shall fail if:EINVALInvalid module name.ENXIOOpen function of new module failed.ENXIOHangup received onfildes. I_POP Removes the module just below the STREAM head of the STREAM pointed to byfildes. Thearg argument should be 0 in an I_POP request. Theioctl() function with the I_POP command shall fail if:EINVALNo module present in the STREAM.ENXIOHangup received onfildes. I_LOOK Retrieves the name of the module just below the STREAM head of the STREAM pointed to byfildes, and places it in a character string pointed to byarg. The buffer pointed to byarg should be at least FMNAMESZ+1 bytes long, where FMNAMESZ is defined in<stropts.h>. Theioctl() function with the I_LOOK command shall fail if:EINVALNo module present in the STREAM. I_FLUSH Flushes read and/or write queues, depending on the value ofarg. Validarg values are: FLUSHR Flush all read queues. FLUSHW Flush all write queues. FLUSHRW Flush all read and all write queues. Theioctl() function with the I_FLUSH command shall fail if:EINVALInvalidarg value.EAGAINorENOSR Unable to allocate buffers for flush message.ENXIOHangup received onfildes. I_FLUSHBAND Flushes a particular band of messages. Thearg argument points to abandinfostructure. Thebi_flag member may be one of FLUSHR, FLUSHW, or FLUSHRW as described above. Thebi_pri member determines the priority band to be flushed. 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 withfildes. I_SETSIG supports an asynchronous processing capability in STREAMS. The value ofarg 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: S_RDNORM 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. S_RDBAND 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. S_INPUT 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. S_HIPRI 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. S_OUTPUT 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. S_WRNORM Equivalent to S_OUTPUT. S_WRBAND 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. S_MSG A STREAMS signal message that contains the SIGPOLL signal has reached the front of the STREAM head read queue. S_ERROR Notification of an error condition has reached the STREAM head. S_HANGUP Notification of a hangup has reached the STREAM head. S_BANDURG 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. Ifarg is 0, the calling process shall be unregistered and shall not receive further SIGPOLL signals for the stream associated withfildes. 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. Theioctl() function with the I_SETSIG command shall fail if:EINVALThe value ofarg is invalid.EINVALThe value ofarg is 0 and the calling process is not registered to receive the SIGPOLL signal.EAGAINThere were insufficient resources to store the signal request. 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 anintpointed to byarg, where the events are those specified in the description of I_SETSIG above. Theioctl() function with the I_GETSIG command shall fail if:EINVALProcess is not registered to receive the SIGPOLL signal. I_FIND Compares the names of all modules currently present in the STREAM to the name pointed to byarg, and returns 1 if the named module is present in the STREAM, or returns 0 if the named module is not present. Theioctl() function with the I_FIND command shall fail if:EINVALarg does not contain a valid module name. 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 togetmsg() except that this command does not remove the message from the queue. Thearg argument points to astrpeek structure. The application shall ensure that themaxlen member in thectlbufanddatabuf strbufstructures is set to the number of bytes of control information and/or data information, respectively, to retrieve. Theflags member may be marked RS_HIPRI or 0, as described bygetmsg(). If the process setsflags to RS_HIPRI, for example, I_PEEK shall only look for a high-priority message on the STREAM head read queue. 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 inflags 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,ctlbufspecifies information in the control buffer,databufspecifies information in the data buffer, andflags contains the value RS_HIPRI or 0. I_SRDOPT Sets the read mode using the value of the argumentarg. Read modes are described inread(). Validarg flags are: RNORM Byte-stream mode, the default. RMSGD Message-discard mode. RMSGN Message-nondiscard mode. 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. In addition, treatment of control messages by the STREAM head may be changed by setting any of the following flags inarg: RPROTNORM Failread() with[EBADMSG]if a message containing a control part is at the front of the STREAM head read queue. RPROTDAT Deliver the control part of a message as data when a process issues aread(). RPROTDIS Discard the control part of a message, delivering any data portion, when a process issues aread(). Theioctl() function with the I_SRDOPT command shall fail if:EINVALThearg argument is not valid. I_GRDOPT Returns the current read mode setting, as described above, in anintpointed to by the argumentarg. Read modes are described inread(). 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 theintpointed to byarg. The return value for the command shall be the number of messages on the STREAM head read queue. For example, if 0 is returned inarg, but theioctl() return value is greater than 0, this indicates that a zero-length message is next on the queue. 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. Thearg argument points to astrfdinsertstructure. The application shall ensure that thelen member in thectlbuf strbufstructure is set to the size of at_uscalar_tplus the number of bytes of control information to be sent with the message. Thefildes member specifies the file descriptor of the other STREAM, and theoffset member, which must be suitably aligned for use as at_uscalar_t, specifies the offset from the start of the control buffer where I_FDINSERT shall store at_uscalar_twhose interpretation is specific to the STREAM end. The application shall ensure that thelen member in thedatabuf strbuf 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. Theflags member specifies the type of message to be created. A normal message is created ifflags is set to 0, and a high-priority message is created ifflags 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 setserrno to[EAGAIN]. 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. Theioctl() function with the I_FDINSERT command shall fail if:EAGAINA non-priority message is specified, the O_NONBLOCK flag is set, and the STREAM write queue is full due to internal flow control conditions.EAGAINorENOSR Buffers cannot be allocated for the message that is to be created.EINVALOne of the following: -- Thefildes member of thestrfdinsert structure is not a valid, open STREAM file descriptor. -- The size of at_uscalar_tplusoffset is greater than thelen member for the buffer specified throughctlbuf. -- Theoffset member does not specify a properly-aligned location in the data buffer. -- An undefined value is stored inflags.ENXIOHangup received on the STREAM identified by either thefildes argument or thefildes member of thestrfdinsertstructure.ERANGEThelen member for the buffer specified throughdatabufdoes not fall within the range specified by the maximum and minimum packet sizes of the topmost STREAM module; or thelen member for the buffer specified throughdatabuf is larger than the maximum configured size of the data part of a message; or thelen member for the buffer specified throughctlbufis larger than the maximum configured size of the control part of a message. I_STR Constructs an internal STREAMSioctl() message from the data pointed to byarg, and sends that message downstream. This mechanism is provided to sendioctl() requests to downstream modules and drivers. It allows information to be sent withioctl(), 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 witherrno set to[ETIME]. 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. To send requests downstream, the application shall ensure thatarg points to astrioctlstructure. Theic_cmd member is the internalioctl() command intended for a downstream module or driver andic_timout 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.ic_len is the number of bytes in the data argument, andic_dp is a pointer to the data argument. Theic_len 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 byic_dp should be large enough to contain the maximum amount of data that any module or the driver in the STREAM can return). The STREAM head shall convert the information pointed to by thestrioctlstructure to an internalioctl() command message and send it downstream. Theioctl() function with the I_STR command shall fail if:EAGAINorENOSR Unable to allocate buffers for theioctl() message.EINVALTheic_len member is less than 0 or larger than the maximum configured size of the data part of a message, oric_timout is less than -1.ENXIOHangup received onfildes.ETIMEA downstreamioctl() timed out before acknowledgement was received. 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 theioctl() command sent downstream fails. For these cases, I_STR shall fail witherrno set to the value in the message. I_SWROPT Sets the write mode using the value of the argumentarg. Valid bit settings forarg are: SNDZERO Send a zero-length message downstream when awrite() of 0 bytes occurs. To not send a zero-length message when awrite() of 0 bytes occurs, the application shall ensure that this bit is not set inarg (for example,arg would be set to 0). Theioctl() function with the I_SWROPT command shall fail if:EINVALarg is not the above value. I_GWROPT Returns the current write mode setting, as described above, in theintthat is pointed to by the argumentarg. I_SENDFD Creates a new reference to the open file description associated with the file descriptorarg, and writes a message on the STREAMS-based pipefildes containing this reference, together with the user ID and group ID of the calling process. Theioctl() function with the I_SENDFD command shall fail if:EAGAINThe 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.EBADFThearg argument is not a valid, open file descriptor.EINVALThefildes argument is not connected to a STREAM pipe.ENXIOHangup received onfildes. Theioctl() function with the I_SENDFD command may fail if:EINVALThearg argument is equal to thefildes argument. 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. Thearg argument is a pointer to astrrecvfddata structure as defined in<stropts.h>. Thefd member is a file descriptor. Theuid andgid members are the effective user ID and effective group ID, respectively, of the sending process. 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 witherrno set to[EAGAIN] if no message is present at the STREAM head. 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 thefd member of thestrrecvfdstructure pointed to byarg. Theioctl() function with the I_RECVFD command shall fail if:EAGAINA message is not present at the STREAM head read queue and the O_NONBLOCK flag is set.EBADMSG The message at the STREAM head read queue is not a message containing a passed file descriptor.EMFILEAll file descriptors available to the process are currently open.ENXIOHangup received onfildes. I_LIST Allows the process to list all the module names on the STREAM, up to and including the topmost driver name. Ifarg is a null pointer, the return value shall be the number of modules, including the driver, that are on the STREAM pointed to byfildes. This lets the process allocate enough space for the module names. Otherwise, it should point to astr_liststructure. Thesl_nmods member indicates the number of entries the process has allocated in the array. Upon return, thesl_modlist member of thestr_liststructure shall contain the list of module names, and the number of entries that have been filled into thesl_modlist array is found in thesl_nmods member (the number includes the number of modules including the driver). The return value fromioctl() 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 (sl_nmods) is satisfied. Theioctl() function with the I_LIST command shall fail if:EINVALThesl_nmods member is less than 1.EAGAINorENOSR Unable to allocate buffers. 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. Thearg 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: ANYMARK Check if the message is marked. LASTMARK Check if the message is the last one marked on the queue. The bitwise-inclusive OR of the flags ANYMARK and LASTMARK is permitted. The return value shall be 1 if the mark condition is satisfied; otherwise, the value shall be 0. Theioctl() function with the I_ATMARK command shall fail if:EINVALInvalidarg value. 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.arg should be of typeint. Theioctl() function with the I_CKBAND command shall fail if:EINVALInvalidarg value. I_GETBAND Returns the priority band of the first message on the STREAM head read queue in the integer referenced byarg. Theioctl() function with the I_GETBAND command shall fail if:ENODATA No message on the STREAM head read queue. I_CANPUT Checks if a certain band is writable.arg 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. Theioctl() function with the I_CANPUT command shall fail if:EINVALInvalidarg value. 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. Thearg 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. Theioctl() function with the I_SETCLTIME command shall fail if:EINVALInvalidarg value. I_GETCLTIME Returns the close time delay in the integer pointed to byarg.Multiplexed STREAMS Configurations The following commands are used for connecting and disconnecting multiplexed STREAMS configurations. These commands use an implementation-defined default timeout interval. I_LINK Connects two STREAMs, wherefildes is the file descriptor of the STREAM connected to the multiplexing driver, andarg is the file descriptor of the STREAM connected to another driver. The STREAM designated byarg 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. Theioctl() function with the I_LINK command shall fail if:ENXIOHangup received onfildes.ETIMETimeout before acknowledgement message was received at STREAM head.EAGAINorENOSR Unable to allocate STREAMS storage to perform the I_LINK.EBADFThearg argument is not a valid, open file descriptor.EINVALThefildes argument does not support multiplexing; orarg 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. 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 offildes. In addition, an error code can be returned in the positive or negative acknowledgement message. For these cases, I_LINK fails witherrno set to the value in the message. I_UNLINK Disconnects the two STREAMs specified byfildes andarg.fildes is the file descriptor of the STREAM connected to the multiplexing driver. Thearg argument is the multiplexer ID number that was returned by the I_LINKioctl() command when a STREAM was connected downstream from the multiplexing driver. Ifarg is MUXID_ALL, then all STREAMs that were connected tofildes shall be disconnected. As in I_LINK, this command requires acknowledgement. Theioctl() function with the I_UNLINK command shall fail if:ENXIOHangup received onfildes.ETIMETimeout before acknowledgement message was received at STREAM head.EAGAINorENOSR Unable to allocate buffers for the acknowledgement message.EINVALInvalid multiplexer ID number. 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 offildes. In addition, an error code can be returned in the positive or negative acknowledgement message. For these cases, I_UNLINK shall fail witherrno set to the value in the message. I_PLINK Creates apersistent connection between two STREAMs, wherefildes is the file descriptor of the STREAM connected to the multiplexing driver, andarg 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 descriptorfildes associated with the upper STREAM to the multiplexing driver is closed. The STREAM designated byarg 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. Theioctl() function with the I_PLINK command shall fail if:ENXIOHangup received onfildes.ETIMETimeout before acknowledgement message was received at STREAM head.EAGAINorENOSR Unable to allocate STREAMS storage to perform the I_PLINK.EBADFThearg argument is not a valid, open file descriptor.EINVALThefildes argument does not support multiplexing; orarg 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. 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 offildes. In addition, an error code can be returned in the positive or negative acknowledgement message. For these cases, I_PLINK shall fail witherrno set to the value in the message. I_PUNLINK Disconnects the two STREAMs specified byfildes andarg from a persistent connection. Thefildes argument is the file descriptor of the STREAM connected to the multiplexing driver. Thearg argument is the multiplexer ID number that was returned by the I_PLINKioctl() command when a STREAM was connected downstream from the multiplexing driver. Ifarg is MUXID_ALL, then all STREAMs which are persistent connections tofildes shall be disconnected. As in I_PLINK, this command requires the multiplexing driver to acknowledge the request. Theioctl() function with the I_PUNLINK command shall fail if:ENXIOHangup received onfildes.ETIMETimeout before acknowledgement message was received at STREAM head.EAGAINorENOSR Unable to allocate buffers for the acknowledgement message.EINVALInvalid multiplexer ID number. 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 offildes. In addition, an error code can be returned in the positive or negative acknowledgement message. For these cases, I_PUNLINK shall fail witherrno set to the value in the message.
Upon successful completion,ioctl() shall return a value other than -1 that depends upon the STREAMS device control function. Otherwise, it shall return -1 and seterrno to indicate the error.
Under the following general conditions,ioctl() shall fail if:EBADFThefildes argument is not a valid open file descriptor.EINTRA signal was caught during theioctl() operation.EINVALThe STREAM or multiplexer referenced byfildes is linked (directly or indirectly) downstream from a multiplexer. If an underlying device driver detects an error, thenioctl() shall fail if:EINVALTherequest orarg argument is not valid for this device.EIOSome physical I/O error has occurred.ENOTTYThe file associated with thefildes argument is not a STREAMS device that accepts control functions.ENXIOTherequest andarg arguments are valid for this device driver, but the service requested cannot be performed on this particular sub-device.ENODEVThefildes argument refers to a valid STREAMS device, but the corresponding device driver does not support theioctl() function. If a STREAM is connected downstream from a multiplexer, anyioctl() command except I_UNLINK and I_PUNLINK shall seterrno to[EINVAL].The following sections are informative.
None.
The implementation-defined timeout interval for STREAMS has historically been 15 seconds.
None.
Theioctl() function may be removed in a future version.
Section 2.6,STREAMS,close(3p),fcntl(3p),getmsg(3p),open(3p),pipe(3p),poll(3p),putmsg(3p),read(3p),sigaction(3p),write(3p) The Base Definitions volume of POSIX.1‐2017,stropts.h(0p)
Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 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 athttp://www.opengroup.org/unix/online.html . Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, seehttps://www.kernel.org/doc/man-pages/reporting_bugs.html .IEEE/The Open Group 2017IOCTL(3P)Pages that refer to this page:signal.h(0p), stropts.h(0p), close(3p), read(3p)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |