ioctl(), ioctl_socket()

Управлять устройством

Прототип:

#include <sys/ioctl.h> 
                                       
int ioctl( int fd, 
           int request, 
           ... );
                                       
int ioctl_socket( int fd, 
                  int request, 
                  ... );

Аргументы:

fd: Файловый дескриптор файла или устройства, которым требуется управлять.
request: Действие, которое требуется выполнить с файлом или устройством. Макросы и определения используемых запросов описаны в <sys/ioctl.h>.
...: В соответствии с запросом.

Библиотека:

libc — ioctl()
libsocket — ioctl_socket()

Описание:

Функция ioctl() управляет параметрами файла. В частности, функция может быть использована для управления многими атрибутами файла (например, атрибутами терминала).

Функция ioctl_socket() является оптимизированной версией функции ioctl(), обеспечивает специальную обработку команд, использующих внутренние указатели (смотрите “Команды со специальной обработкой ioctl_socket()” ниже). Эта функция использует ioctl() для команд, не требующих специальной обработки. Аргумент fd является сокетом для ioctl_socket().

ioctl() обрабатывает внутренние указатели, поэтому не нужно использовать вместо неё ioctl_socket().

Аргумент request определяет, являются последующие аргументы входными или выходными параметрами; также указывает размер аргументов в байтах.

Сопоставление команд ioctl() с другими командами

Часть команд ioctl() преобразуется в вызовы fcntl(), tcgetattr(), tcsetattr(), и tcsetsid(). Другая часть преобразуются в команды devctl(), остальные без изменений передаются devctl(). Команды приведены ниже:

команда ioctl()	Описание	Сопоставление:
`FIOASYNC`	Установить или очистить асинхронный ввод/вывод	fcntl(): `F_GETFL` (вызывает devctl() с DCMD_ALL_GETFLAGS), затем fcntl(): `F_SETFL` (вызывает devctl() с DCMD_ALL_SETFLAGS), с установкой или очисткой `O_ASYNC`
`FIOCLEX`	Установить флаг закрытия при исполнении exec()/spawn() (close-on-exec) для файлового дескриптора	fcntl(): `F_SETFD` с `FD_CLOEXEC`
`FIOGETOWN`	Получить владельца	fcntl(): `F_GETOWN`
`FIONBIO`	Установить или очистить неблокирующий ввод/вывод	fcntl(): `F_GETFL` (вызывает devctl() с DCMD_ALL_GETFLAGS), за ней следует fcntl(): `F_SETFL` (вызывает devctl() с DCMD_ALL_SETFLAGS), с установкой или очисткой `O_NONBLOCK`
`FIONCLEX`	Удалить флаг закрытия при исполнении exec()/spawn() (close-on-exec) для файлового дескриптора	fcntl(): `F_SETFD` с ~`FD_CLOEXEC`
`FIONREAD`	Получить количество байт, которое необходимо прочитать	devctl(): `DCMD_CHR_ISCHARS`
`FIOSETOWN`	Установить владельца	fcntl(): `F_SETOWN`
`NOSIOCGIFCONF`	Получить список сетевых интерфейсов	Передаётся в devctl()
`OSIOCGIFADDR`	Получить адрес сетевого интерфейса	Передаётся в devctl()
`OSIOCGIFBRDADDR`	Получить широковещательный адрес	Передаётся в devctl()
`OSIOCGIFCONF`	Получить список сетевых интерфейсов	Передаётся в devctl()
`OSIOCGIFDSTADDR`	Получить адрес p2p (point-to-point)	Передаётся в devctl()
`OSIOCGIFNETMASK`	Получить маску сетевого адреса	Передаётся в devctl()
`SIOCADDMULTI`	Добавить мультикаст адрес	Передаётся в devctl()
`SIOCADDRT`	Добавить маршрут	Передаётся в devctl()
`SIOCAIFADDR`	Добавить или изменить псевдоним интерфейса	Передаётся в devctl()
`SIOCALIFADDR`	Добавить адрес интерфейса	Передаётся в devctl()
`SIOCATMARK`	На нештатной (out-of-band ) отметке?	Передаётся в devctl()
`SIOCDARP`	Удалить ARP запись	Передаётся в devctl()
`SIOCDELMULTI`	Удалить мультикаст адрес	Передаётся в devctl()
`SIOCDELRT`	Удалить маршрут	Передаётся в devctl()
`SIOCDIFADDR`	Удалить адрес интерфейса	Передаётся в devctl()
`SIOCDIFPHYADDR`	Удалить адрес gif	Передаётся в devctl()
`SIOCDLIFADDR`	Удалить адрес интерфейса	Передаётся в devctl()
`SIOCGARP`	Получить ARP запись	Передаётся в devctl()
`SIOCGDRVSPEC`	Получить специфичные параметры драйвера	Передаётся в devctl()
`SIOCGETSGCNT`	Получить количество пакетов исходной группы	Передаётся в devctl()
`SIOCGETVIFCNT`	Получить количество пакетов виртуального интерфейса	Передаётся в devctl()
`SIOCGHIWAT`	Получить значение высокого порога срабатывания	Передаётся в devctl()
`SIOCGIFADDR`	Получить адрес интерфейса	Передаётся в devctl()
`SIOCGIFALIAS`	Получить псевдоним интерфейса	Передаётся в devctl()
`SIOCGIFASYNCMAP`	Получить ppp asyncmap	Передаётся в devctl()
`SIOCGIFBRDADDR`	Получить широковещательный адрес	Передаётся в devctl()
`SIOCGIFCAP`	Получить характеристики	Передаётся в devctl()
`SIOCGIFCONF`	Вернуть список адресов интерфейса (транспортный уровень)	Передаётся в devctl()
`SIOCGIFDLT`	Получить тип канала передачи данных	Передаётся в devctl()
`SIOCGIFDSTADDR`	Получить p2p адрес	Передаётся в devctl()
`SIOCGIFFLAGS`	Получить флаги интерфейса	Передаётся в devctl()
`SIOCGIFGENERIC`	Общий интерфейс запроса	Передаётся в devctl()
`SIOCGIFMEDIA`	Получить сетевой режим; ioctl_socket() обеспечивает специальную обработку данной команды.	Передаётся в devctl()
`SIOCGIFMETRIC`	Получить метрики интерфейса	Передаётся в devctl()
`SIOCGIFMTU`	Получить MTU сетевого интерфейса	Передаётся в devctl()
`SIOCGIFNETMASK`	Получить маску сетевого адреса	Передаётся в devctl()
`SIOCGIFPDSTADDR`	Получить адрес gif pdst	Передаётся в devctl()
`SIOCGIFPSRCADDR`	Получить адрес gif psrc	Передаётся в devctl()
`SIOCGLIFADDR`	Получить адрес интерфейса	Передаётся в devctl()
`SIOCGLIFPHYADDR`	Получить адрес gif	Передаётся в devctl()
`SIOCGLOWAT`	Получить значение низкого порога срабатывания	Передаётся в devctl()
`SIOCGPGRP`	Получить группу процесса	fcntl(): `F_GETOWN`
`SIOCIFCREATE`	Клонировать интерфейс	Передаётся в devctl()
`SIOCIFDESTROY`	Уничтожить клонированный интерфейс	Передаётся в devctl()
`SIOCIFGCLONERS`	Получить список клонируемых интерфейсов; ioctl_socket() обеспечивает специальную обработку данной команды.	Передаётся в devctl()
`SIOCSARP`	Установить ARP запись	Передаётся в devctl()
`SIOCSDRVSPEC`	Задать специфичные для драйвера параметры	Передаётся в devctl()
`SIOCSHIWAT`	Установить значение высокого порога срабатывания	Передаётся в devctl()
`SIOCSIFADDR`	Задать адрес сетевого интерфейса	Передаётся в devctl()
`SIOCSIFASYNCMAP`	Задать ppp asyncmap	Передаётся в devctl()
`SIOCSIFBRDADDR`	Задать широковещательный адрес	Передаётся в devctl()
`SIOCSIFCAP`	Задать характеристики	Передаётся в devctl()
`SIOCSIFDSTADDR`	Задать p2p адрес	Передаётся в devctl()
`SIOCSIFFLAGS`	Задать флаги интерфейса	Передаётся в devctl()
`SIOCSIFGENERIC`	Общий интерфейс установки	Передаётся в devctl()
`SIOCSIFMEDIA`	Задать сетевой режим	Передаётся в devctl()
`SIOCSIFMETRIC`	Задать метрики интерфейса	Передаётся в devctl()
`SIOCSIFMTU`	Задать MTU сетевого интерфейса	Передаётся в devctl()
`SIOCSIFNETMASK`	Задать маску сетевого адреса	Передаётся в devctl()
`SIOCSIFPHYADDR`	Задать адрес gif	Передаётся в devctl()
`SIOCSLIFPHYADDR`	Задать gif адреса	Передаётся в devctl()
`SIOCSLOWAT`	Задать значение низкого порога срабатывания	Передаётся в devctl()
`SIOCSPGRP`	Задать группу процесса	fcntl(): `F_SETOWN`
`TCFLSH`	Очистить буферы	Передаётся в devctl()
`TCGETA`	Заполнить структуру `termio` свойствами терминала	tcgetattr()
`TCGETS`	Заполнить структуру struct termios свойствами терминала	tcgetattr()
`TCSBRK`	Установить сигнал break на период времени	devctl() : `DCMD_CHR_SERCTL`
`TCSETA`	Задать свойства терминала	tcsetattr()
`TCSETAF`	Задать свойства терминала после ожидания записи всех переданных данных и отбросить любые полученные, но непрочитанные данные	tcsetattr()
`TCSETAW`	Задать свойства терминала после ожидания записи всех переданных данных	tcsetattr()
`TCSETS`	Установить свойства терминала, указанные в структуре struct termios	devctl() : `DCMD_CHR_TCSETATTR`
`TCSETSF`	Очистить вывод и ввод, и установить	Передаётся в devctl()
`TCSETSW`	Очистить вывод, установить	Передаётся в devctl()
`TCXONC`	Выполнить операцию управления потоком данных	devctl(): `DCMD_CHR_TCFLOW`
`TIOCCBRK`	Очистить бит сигнала разрыва (break)	tcsetattr()
`TIOCCDTR`	Очистить DTR	devctl() : `DCMD_CHR_LINESTATUS`, затем `DCMD_CHR_SERCTL`
`TIOCDRAIN`	Ожидать, пока вывод будет опустошён	devctl(): `DCMD_CHR_TCDRAIN`
`TIOCEXCL`	Установить эксклюзивное использование псевдотерминала (tty)	fcntl(): `F_SETLK`
`TIOCFLUSH`	Очистить буферы	devctl(): `DCMD_CHR_TCFLUSH`
`TIOCGETA`	Заполнить структуру struct termios свойствами терминала	devctl() : `DCMD_CHR_TCGETATTR`
`TIOCGETC`	Получить специальные символы	tcgetattr()
`TIOCGETP`	Заполнить структуру sgttyb с параметрами терминала	tcgetattr()
`TIOCGETPGRP`	Получить группу процесса tty (POSIX)	Передаётся в devctl()
`TIOCGLTC`	Получить локальные специальные символы	tcgetattr()
`TIOCGPGRP`	Получить группу процесса tty	devctl(): `DCMD_CHR_TCGETPGRP`
`TIOCGSIZE`	Получить размер окна	devctl(): `DCMD_CHR_GETSIZE`
`TIOCGWINSZ`	Получить размер окна	devctl(): `DCMD_CHR_GETSIZE`
`TIOCHPCL`	Остановиться при последнем закрытии	tcsetattr()
`TIOCLGET`	Получить локальные режимы	tcgetattr()
`TIOCLSET`	Установить локальный режим	tcsetattr()
`TIOCMBIC`	Очистить биты модема	devctl() : `DCMD_CHR_LINESTATUS`, затем `DCMD_CHR_SERCTL`
`TIOCMBIS`	Установить биты модема	devctl() : `DCMD_CHR_LINESTATUS`, затем `DCMD_CHR_SERCTL`
`TIOCMGET`	Получить состояние линий модема	devctl() : `DCMD_CHR_SERCTL`
`TIOCMSET`	Установить все биты модема	Передаётся в devctl()
`TIOCNOTTY`	Сделать данный терминал неконтролирующим для процесса	tcsetsid()
`TIOCNXCL`	Сбросить эксклюзивное использование tty	fcntl(): `F_SETLK`
`TIOCOUTQ`	Размер очереди на вывод	devctl(): `DCMD_CHR_OSCHARS`
`TIOCPKT`	Псевдотерминал: задать/очистить пакетный режим	Передаётся в devctl()
`TIOCSBRK`	Установить бит разрыва	Передаётся в devctl()
`TIOCSCTTY`	Сделать терминал управляющим tty	tcsetsid()
`TIOCSDTR`	Установить DTR	devctl() : `DCMD_CHR_LINESTATUS`, затем `DCMD_CHR_SERCTL`
`TIOCSETA`	Задать свойства терминал из структуры struct termios	devctl() : `DCMD_CHR_TCSETATTR`
`TIOCSETAF`	Опустошить вывод, очистить ввод	devctl(): `DCMD_CHR_TCSETATTRF`
`TIOCSETAW`	Очистить вывод	devctl(): `DCMD_CHR_TCSETATTRD`
`TIOCSETC`	Задать специальные символы	tcsetattr()
`TIOCSETN`	Аналогично `TIOCSETP`, но изменения вносятся сразу, без сброса данных.	tcsetattr()
`TIOCSETP`	Установить параметры терминала из структуры `sgttyb`. Изменения не вносятся до тех пор, пока не будут переданы все записанные данные, после чего полученные, но непрочитанные данные будут очищены.	tcsetattr()
`TIOCSETPGRP`	Задать группу процесса tty (POSIX)	Передаётся в devctl()
`TIOCSINUSE`	Задать эксклюзивное использование tty	fcntl(): `F_SETLK`
`TIOCSLTC`	Задать локальные специальные символы	tcsetattr()
`TIOCSPGRP`	Задать группу процесса tty	devctl(): `DCMD_CHR_TCSETPGRP`
`TIOCSSIZE`	Задать размер окна	devctl(): `DCMD_CHR_SETSIZE`
`TIOCSTART`	Начать вывод, аналог Ctrl-Q	Передаётся в devctl()
`TIOCSTI`	Имитация ввода	devctl(): `DCMD_CHR_TCINJECTC`
`TIOCSTOP`	Остановить вывод, аналог Ctrl-S	Передаётся в devctl()
`TIOCSWINSZ`	Установить размер окна	devctl(): `DCMD_CHR_SETSIZE`
`UIOCCMD`	Пользовательская команда n	Передаётся в devctl()

При разработке менеджера ресурсов необходимо обратить внимание, что функция iofunc_devctl_default() обрабатывает команды DCMD_ALL_GETFLAGS и DCMD_ALL_SETFLAGS; разрабатываемому менеджеру ресурсов необходимо обрабатывать все остальные применимые к нему команды devctl().

__Команды со специальной обработкой _ioctl_socket()___

Функция ioctl_socket() обеспечивает специальную обработку команд, перечисленных ниже. Если не указано обратное, команда передаётся функции devctl().

Команды для пакетного фильтра Беркли (BPF):

BIOCGDLTLIST: Получить для подключённого интерфейса массив доступных типов канального уровня.
BIOCSETF: Задать программу BPF-фильтра.

Команды для криптографии:

CIOCCRYPT: Запросить операцию с симметричным ключом (или хэш без ключа).
CIOCGSESSION: Настройка сеанса симметричного шифрования.
CIOCKEY: Выполнить операцию асимметричного шифрования.
CRIOGET: Получить клонированный файловый дескриптор /dev/crypto вызовом open(). В ЗОСРВ «Нейтрино» это необязательно, но данная возможность предусмотрена для совместимости и переносимости.

Следующие команды используются для интерфейса пакетной фильтрации; для дополнительной информации см. описание pf:

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

Команды для сокетов:

SIOCG80211: Получить конфигурацию или информацию о статусе.
SIOCG80211NWID: Получить сетевой ID.
SIOCG80211NWKEY: Получить значения WEP ключей.
SIOCG80211STATS, SIOCG80211ZSTATS: Получить статистику IEEE 80211.
SIOCGETVLAN: Получить тэг vlan и родительский интерфейс для данного vlan.
SIOCGIFMEDIA: Получить сетевой режим.
SIOCIFGCLONERS: Получить список клонируемых интерфейсов.
SIOCS80211: Задать конфигурацию или информацию о статусе.
SIOCS80211NWID: Задать сетевой ID.
SIOCS80211NWKEY: Задать WEP ключ.
SIOCSETVLAN: Задать тэг vlan и родительский интерфейс для данного vlan.

Возвращаемое значение:

Значение зависит от запроса.

Если возникла ошибка, функция возвращает -1, код ошибки записывается в errno.

Коды ошибок:

EBADF: Некорректный дескриптор fd.
EINVAL: Запрос или необязательные переменные некорректны.
ENOBUFS: Недостаточно памяти для размещения данных, указанных во внутренних указателях.
ENOTTY: Аргумент fd не связан со специальным символьным устройством; указанный запрос request неприменим к типу объектов, на который ссылается дескриптор fd.

Классификация:

POSIX 1003.1 X/Open Systems Interfaces Streams

Безопасность использования
Точка остановки потока: Нет
Обработчик прерываний: Нет
Обработчик сигналов: Нет
В потоке: Нет

Предостережения:

ioctl() - это Unix-функция, сильно различающаяся для разных платформ.

Тематические ссылки:

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

Предыдущий раздел: Описание API системной библиотеки