ioctl(), ioctl_socket(), vioctl()

Control a device

Synopsis:

#include <sys/ioctl.h> 

int ioctl( int fd, 
           int request, 
           ... );

int ioctl_socket( int fd, 
                  int request, 
                  ... );

int vioctl( int fd, 
            int request, 
            va_list arg );

Arguments:

fd
An open file descriptor for the file or device that you want to manipulate.
request
What you want to do to the file or device; see below for a summary. The macros and definitions that you use in specifying a request are located in the file <sys/ioctl.h>.
arg
A variable-argument list of the additional arguments, which you must have initialized with the va_start() macro. Used with vioctl() only.
Additional arguments
As required by the request.

Library:

Function Library Linking option to qcc
ioctl() libc -l c (This library is usually included automatically.)
ioctl_socket() libsocket -l socket
vioctl() libc -l c (This library is usually included automatically.)

Description:

The ioctl() function manipulates the underlying parameters of files. In particular, it can be used to control many of the operating attributes of files (such as the attributes of terminals).

The ioctl_socket() function is an optimized version of ioctl() that provides special handling for commands that use embedded pointers (see Commands with special handling in ioctl_socket(),” below). It uses ioctl() for commands that don't require special handling. The fd argument must be a socket for ioctl_socket().

Note: If you're using QNX Neutrino 6.4.1 or earlier, use ioctl_socket() instead of ioctl() in network applications such as packet filters.

In QNX Neutrino 6.5.0 and later, ioctl() handles embedded pointers, so you don't have to use ioctl_socket() instead.

The vioctl() function is a "varargs" version of ioctl().

The request argument determines whether the subsequent arguments are an “in” or “out” parameter; it also specifies the size of the arguments in bytes.

I/O control commands

Use these macros to set up the I/O control commands:

_IO(class, cmd)
A command with no associated data.
_IOR(class, cmd, data)
Get information from the device.
_IOW(class, cmd, data)
Pass information to the device.
_IOWR(class, cmd, data)
Pass some information to the device, and get some from it.

The arguments to these macros are:

class
A single character that denotes the major category for the command.
cmd
An integer that identifies the command in the class.
data
The type of data to pass to and/or from the device. The additional argument to ioctl() must be a pointer to this type of data.
Note: The size of the structure that's passed as the last field to the __IO* macros must be less than 2^14 == 16 KB. Anything larger than this interferes with the upper two directional bits.

How ioctl() commands map to other commands

Some ioctl() commands map to calls to fcntl(), tcgetattr(), tcsetattr(), and tcsetsid(). Other commands are transformed into devctl() commands, and the rest are simply passed to devctl(). Here's a summary (for details, see the Devctl and Ioctl Commands reference):

ioctl() command Description Maps to:
CIO*, CRIOGET Handle cryptography operations These commands are sent to devcrypto using regular message passing functionality. See the entry for devcrypto in the Utilities Reference.
FIOASYNC Set or clear asynchronous I/O fcntl(): F_GETFL (which becomes a devctl() DCMD_ALL_GETFLAGS), followed by fcntl(): F_SETFL (which becomes a devctl() DCMD_ALL_SETFLAGS), setting or clearing O_ASYNC
FIOCLEX Set “close on exec” on a file descriptor fcntl(): F_SETFD with FD_CLOEXEC
FIOGETOWN Get the owner fcntl(): F_GETOWN
FIONBIO Set or clear non-blocking I/O fcntl(): F_GETFL (which becomes a devctl() DCMD_ALL_GETFLAGS), followed by fcntl(): F_SETFL (which becomes a devctl() DCMD_ALL_SETFLAGS), setting or clearing O_NONBLOCK
FIONCLEX Remove “close on exec” fcntl(): F_SETFD with ~FD_CLOEXEC
FIONREAD Get the number of bytes to read devctl(): DCMD_CHR_ISCHARS
FIOSETOWN Set the owner fcntl(): F_SETOWN
NOSIOCGIFCONF Get ifnet list Passed to devctl()
SIOCADDMULTI Add multicast address Passed to devctl()
SIOCADDRT Add route Passed to devctl()
SIOCAIFADDR Add or change an interface alias Passed to devctl()
SIOCALIFADDR Add interface address Passed to devctl()
SIOCATMARK At out-of-band mark? Passed to devctl()
SIOCDELMULTI Delete multicast address Passed to devctl()
SIOCDELRT Delete route Passed to devctl()
SIOCDIFADDR Delete interface address Passed to devctl()
SIOCDIFPHYADDR Delete gif addresses Passed to devctl()
SIOCDLIFADDR Delete interface address Passed to devctl()
SIOCGDRVSPEC Get driver-specific parameters Passed to devctl()
SIOCGETSGCNT Get the source group packet count Passed to devctl()
SIOCGETVIFCNT Get the packet count for a virtual interface Passed to devctl()
SIOCGHIWAT Get high watermark Passed to devctl()
SIOCGIFADDR Get the interface address Passed to devctl()
SIOCGIFALIAS Get interface alias Passed to devctl()
SIOCGIFASYNCMAP Get ppp asyncmap Passed to devctl()
SIOCGIFBRDADDR Get broadcast address Passed to devctl()
SIOCGIFCAP Get capabilities Passed to devctl()
SIOCGIFCONF Return a list of interface (transport layer) addresses Passed to devctl()
SIOCGIFDLT Get data link type Passed to devctl()
SIOCGIFDSTADDR Get point-to-point address Passed to devctl()
SIOCGIFFLAGS Get ifnet flags Passed to devctl()
SIOCGIFGENERIC Generic interface get op Passed to devctl()
SIOCGIFMEDIA Get net media; ioctl_socket() provides special handling for this command. Passed to devctl()
SIOCGIFMETRIC Get interface metric Passed to devctl()
SIOCGIFMTU Get ifnet MTU Passed to devctl()
SIOCGIFNETMASK Get net address mask Passed to devctl()
SIOCGIFPDSTADDR Get gif pdst address Passed to devctl()
SIOCGIFPSRCADDR Get gif psrc address Passed to devctl()
SIOCGLIFADDR Get interface address Passed to devctl()
SIOCGLIFPHYADDR Get gif addresses Passed to devctl()
SIOCGLOWAT Get low watermark Passed to devctl()
SIOCGPGRP Get process group fcntl(): F_GETOWN
SIOCIFCREATE Create clone interface Passed to devctl()
SIOCIFDESTROY Destroy clone interface Passed to devctl()
SIOCIFGCLONERS Get cloners; ioctl_socket() provides special handling for this command. Passed to devctl()
SIOCSDRVSPEC Set driver-specific parameters Passed to devctl()
SIOCSHIWAT Set high watermark Passed to devctl()
SIOCSIFADDR Set ifnet address Passed to devctl()
SIOCSIFASYNCMAP Set ppp asyncmap Passed to devctl()
SIOCSIFBRDADDR Set broadcast address Passed to devctl()
SIOCSIFCAP Set capabilities Passed to devctl()
SIOCSIFDSTADDR Set point-to-point address Passed to devctl()
SIOCSIFFLAGS Set ifnet flags Passed to devctl()
SIOCSIFGENERIC Generic interface set op Passed to devctl()
SIOCSIFMEDIA Set net media Passed to devctl()
SIOCSIFMETRIC Set interface metric Passed to devctl()
SIOCSIFMTU Set ifnet MTU Passed to devctl()
SIOCSIFNETMASK Set net address mask Passed to devctl()
SIOCSIFPHYADDR Set gif address Passed to devctl()
SIOCSLIFPHYADDR Set gif addresses Passed to devctl()
SIOCSLOWAT Set low watermark Passed to devctl()
SIOCSPGRP Set process group fcntl(): F_SETOWN
TCFLSH Flush buffers Passed to devctl()
TCGETA Get the terminal's properties in a termio structure tcgetattr()
TCGETS Get the terminal's properties in a termios structure tcgetattr()
TCSBRK Send a break for a period of time devctl() : DCMD_CHR_SERCTL
TCSETA Set the terminal's properties tcsetattr()
TCSETAF Set the terminal's properties, waiting until all currently written data has been transmitted, and discarding any received but unread data tcsetattr()
TCSETAW Set the terminal's properties, waiting until all currently written data has been transmitted tcsetattr()
TCSETS Set the terminal's properties from a termios structure devctl() : DCMD_CHR_TCSETATTR
TCSETSF Drain the output, flush the input, and set Passed to devctl()
TCSETSW Drain output, set Passed to devctl()
TCXONC Perform a flow-control operation on a data stream devctl(): DCMD_CHR_TCFLOW
TIOCCBRK Clear the break bit tcsetattr()
TIOCCDTR Clear the Data Terminal Ready line devctl() : DCMD_CHR_LINESTATUS, followed by DCMD_CHR_SERCTL
TIOCDRAIN Wait until output has drained devctl(): DCMD_CHR_TCDRAIN
TIOCEXCL Set exclusive use of tty fcntl(): F_SETLK
TIOCFLUSH Flush buffers devctl(): DCMD_CHR_TCFLUSH
TIOCGETA Get the terminal's properties in a termios structure devctl() : DCMD_CHR_TCGETATTR
TIOCGETC Get special characters tcgetattr()
TIOCGETP Get the terminal's parameters in a sgttyb structure tcgetattr()
TIOCGETPGRP Get the process group of the tty (POSIX) Passed to devctl()
TIOCGLTC Get local special characters tcgetattr()
TIOCGPGRP Get the process group of the tty devctl(): DCMD_CHR_TCGETPGRP
TIOCGSIZE Get window size devctl(): DCMD_CHR_GETSIZE
TIOCGWINSZ Get window size devctl(): DCMD_CHR_GETSIZE
TIOCHPCL Hang up on last close tcsetattr()
TIOCLGET Get local modes tcgetattr()
TIOCLSET Set entire local mode word tcsetattr()
TIOCMBIC Clear modem port B interrupt devctl() : DCMD_CHR_LINESTATUS, followed by DCMD_CHR_SERCTL
TIOCMBIS Set modem port B interrupt devctl() : DCMD_CHR_LINESTATUS, followed by DCMD_CHR_SERCTL
TIOCMGET Get the state of the modem lines devctl() : DCMD_CHR_SERCTL
TIOCMSET Set all modem bits Passed to devctl()
TIOCNOTTY Make this terminal not be the controlling terminal for the process tcsetsid()
TIOCNXCL Reset exclusive use of tty fcntl(): F_SETLK
TIOCOUTQ Output queue size devctl(): DCMD_CHR_OSCHARS
TIOCPKT Pty: set/clear packet mode Passed to devctl()
TIOCSBRK Set break bit Passed to devctl()
TIOCSCTTY Make the terminal become the controlling tty tcsetsid()
TIOCSDTR Set the Data Terminal Ready line devctl() : DCMD_CHR_LINESTATUS, followed by DCMD_CHR_SERCTL
TIOCSETA Set the terminal's properties from a termios structure devctl() : DCMD_CHR_TCSETATTR
TIOCSETAF Drain the output, flush the input, and set devctl(): DCMD_CHR_TCSETATTRF
TIOCSETAW Drain output, set devctl(): DCMD_CHR_TCSETATTRD
TIOCSETC Set special characters tcsetattr()
TIOCSETN Similar to TIOCSETP, but the changes are made immediately without discarding any data. tcsetattr()
TIOCSETP Set the terminal's parameters in a sgttyb structure. No change is made until all currently written data has been transmitted, at which point any received but unread data is discarded. tcsetattr()
TIOCSETPGRP Set the process group of the tty (POSIX) Passed to devctl()
TIOCSINUSE Set exclusive use of tty fcntl(): F_SETLK
TIOCSLTC Set local special characters tcsetattr()
TIOCSPGRP Set the process group of the tty devctl(): DCMD_CHR_TCSETPGRP
TIOCSSIZE Set the window size devctl(): DCMD_CHR_SETSIZE
TIOCSTART Start output, like CtrlQ Passed to devctl()
TIOCSTI Simulate terminal input devctl(): DCMD_CHR_TCINJECTC
TIOCSTOP Stop output, like CtrlS Passed to devctl()
TIOCSWINSZ Set window size devctl(): DCMD_CHR_SETSIZE
UIOCCMD() User control operator n Passed to devctl()
Note: If you're writing a resource manager, note that the iofunc_devctl_default() function handles the DCMD_ALL_GETFLAGS and DCMD_ALL_SETFLAGS commands; your resource manager will need to handle all other devctl commands that apply to it.

Commands with special handling in ioctl_socket()

The ioctl_socket() function provides special handling for the commands listed below. Unless otherwise noted, it eventually passes the command to devctl().

These commands are for the Berkeley Packet Filter:

BIOCGDLTLIST
Get an array of the available types of the data link layer underlying the attached interface.
BIOCSETF
Set the BPF filter program.

The following commands are for use with the Packet Filtering interface; for more information, see the entry for pf in the Utilities Reference:

These commands are for use with sockets:

SIOCG80211
Get configuration or status information.
SIOCG80211NWID
Get the network ID.
SIOCG80211NWKEY
Get the values of the WEP keys.
SIOCG80211STATS, SIOCG80211ZSTATS
Get IEEE 80211 statistics.
SIOCGETVLAN
Get the vlan tag and parent for a given vlan interface.
SIOCGIFMEDIA
Get net media.
SIOCIFGCLONERS
Get cloners.
SIOCS80211
Set configuration or status information.
SIOCS80211NWID
Set the network ID.
SIOCS80211NWKEY
Set the WEP key.
SIOCSETVLAN
Set the vlan tag and parent for a given vlan interface.

Registering an I/O control handler

An ioctl() command with data to pass is often passed to devctl(). However, this mechanism is not supported for commands that pass data using pointers to data buffers. For these types of ioctl() commands, you can register an I/O control handler that serializes the data. For more information, see _register_ioctl_handler() and _unregister_ioctl_handler().

Returns:

A value based on the request, or -1 if an error occurs (errno is set).

Errors:

EBADF
Invalid descriptor fd.
EINVAL
The request or optional variables aren't valid.
ENOBUFS
There wasn't enough memory available to allocate for data referred to by embedded pointers.
ENOTTY
The fd argument isn't associated with a character-special device; the specified request doesn't apply to the kind of object that the descriptor fd references.

Classification:

ioctl() is POSIX 1003.1 OB XSR, ioctl_socket() is QNX Neutrino, and vioctl() is QNX Neutrino. The ioctl() function is marked as obsolescent, and may be removed from a future version of the standard.

Safety:  
Cancellation point Yes
Interrupt handler No
Signal handler No
Thread No

Caveats:

The ioctl() function is a Unix function that varies greatly from platform to platform.