ioctl(), ioctl_socket()

Control a device

Synopsis:

#include <sys/ioctl.h> 

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

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

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>.

Additional arguments

As required by the request.

Library:

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().

---

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 request argument determines whether the subsequent arguments are an “in” or “out” parameter; it also specifies the size of the arguments in bytes.

How ioctl() commands map to other commands

Some ioctl() commands map to calls to fcntl(), tcgetattr(), tcsetattr(), and tcsetsid(). Other commands are transformed into a different devctl() command, and the rest are simply passed to devctl(). Here's a summary:

---

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.

These commands are for use with cryptography:

CIOCCRYPT

Request a symmetric-key (or unkeyed hash) operation.

CIOCGSESSION

Set up a session for symmetric crypto operations.

CIOCKEY

Perform an asymmetric crypto operation.

CRIOGET

Get a cloned file descriptor of /dev/crypto by calling open(). This isn't necessary in QNX Neutrino, but we've provided it for compatibility and portability.

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

• DIOCGETSRCNODES
• DIOCGETSTATES
• DIOCIGETIFACES
• DIOCRADDADDRS
• DIOCRADDTABLES
• DIOCRCLRASTATS
• DIOCRCLRTSTATS
• DIOCRDELADDRS
• DIOCRDELTABLES
• DIOCRGETADDRS
• DIOCRGETASTATS
• DIOCRGETTABLES
• DIOCRGETTSTATS
• DIOCRINADEFINE
• DIOCRSETADDRS
• DIOCRSETTFLAGS
• DIOCRTSTADDRS
• DIOCXBEGIN
• DIOCXCOMMIT
• DIOCXROLLBACK

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.

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:

POSIX 1003.1 XSR

Caveats:

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

See also:

devctl(), fcntl(), tcgetattr(), tcsetattr(), tcsetsid().