ОБЗОР

#include <termios.h>

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

ОПИСАНИЕ

Вызов ioctl(2) для терминалов и последовательных портов принимает много разных параметров команд. Большинство из них требуют при этом третий аргумент разных типов, далее по тексту называемый argp или arg.

Вызовы ioctl используются только в непереносимых программах. По возможности старайтесь везде использовать интерфейс POSIX, описанный в termios(3).

Определение и установка атрибутов терминала

TCGETSstruct termios *argp

Эквивалентно tcgetattr(fd, argp).

Получить текущие настройки последовательного порта.

TCSETSconst struct termios *argp

Эквивалентно tcsetattr(fd, TCSANOW, argp).

Установить новые текущие настройки последовательного порта.

TCSETSWconst struct termios *argp

Эквивалентно tcsetattr(fd, TCSADRAIN, argp).

Позволить очистить буфер вывода и установить новые текущие настройки последовательного порта.

TCSETSFconst struct termios *argp

Эквивалентно tcsetattr(fd, TCSAFLUSH, argp).

Позволить очистить буфер вывода, отменить ожидаемые данные на входе и установить новые текущие настройки последовательного порта.

Следующие четыре вызова ioctl аналогичны TCGETS, TCSETS, TCSETSW, TCSETSF, за исключением того, что они работают с struct termio *, а не с struct termios *.

TCGETAstruct termio *argp

TCSETAconst struct termio *argp

TCSETAWconst struct termio *argp

TCSETAFconst struct termio *argp

Блокировка структуры termios

Структура termios для терминала может быть заблокирована. Блокировка сама по себе является структурой termios, но с ненулевыми битами или полями, обозначающими заблокированные значения.

TIOCGLCKTRMIOSstruct termios *argp

Получить состояние блокировки структуры termios терминала.

TIOCSLCKTRMIOSconst struct termios *argp

Установить состояние блокировки структуры termios терминала. Это может
делать только процесс с мандатом CAP_SYS_ADMIN.

Определение и установка размера окна

Размеры окон хранятся в ядре, но не используются им (за исключением случаев виртуальных консолей, где ядро обновляет размер окна при его изменении, например из-за загрузки новых шрифтов).

Следующие константы и структура определены в <sys/ioctl.h>.

TIOCGWINSZstruct winsize *argp

Получить размер окна.

TIOCSWINSZconst struct winsize *argp

Установить размер окна.

Структура, используемая этими системными вызовами ioctl, определяется так:

struct winsize {
 unsigned short ws_row;
 unsigned short ws_col;
 unsigned short ws_xpixel; /* не используется */
 unsigned short ws_ypixel; /* не используется */
};

При изменении размера окна отправляется сигнал SIGWINCH группе активных (foreground) процессов.

Отправка сигнала Break

TCSBRKint arg

Эквивалентно tcsendbreak(fd, arg).

Если терминал использует асинхронную передачу данных и arg равно нулю, то отправляется сигнал break (поток нулевых битов) в течении 0.25 - 0.5 секунд. Если терминал не использует асинхронную передачу данных, то либо сигнал break не отправляется, либо функция просто завершает работу, ничего не исполняя. Если arg не равно нулю, то неизвестно, что произойдет.

(В SVr4, UnixWare, Solaris, Linux tcsendbreak(fd,arg) ненулевые значение arg воспринимается аналогично вызову tcdrain(fd). В SunOS arg воспринимается как множитель и отправляет поток битов в arg раз дольше, чем для нулевого значения arg. В DG/UX и AIX arg (если оно не равно нулю) воспринимается как временной интервал в миллисекундах. В HP-UX arg игнорируется.)

TCSBRKPint arg

Так называемая "POSIX-версия" TCSBRK. Она воспринимает ненулевые значения
arg как временной интервал в децисекундах (1/10 секунды), и ничего не делает, если драйвер не поддерживает сигналы break.

TIOCSBRKvoid

Включить сигнал break, то есть начать отправку нулевых битов.

TIOCCBRKvoid

Выключить сигнал break, то есть прекратить отправку нулевых битов.

Программное управление потоком

TCXONCint arg

Эквивалентно tcflow(fd, arg).

Смотрите tcflow(3) со значениями аргументов TCOOFF, TCOON, TCIOFF, TCION.

Счетчик буфера и очистка

FIONREADint *argp

Получить количество байтов в буфере ввода.

TIOCINQint *argp

То же что и FIONREAD.

TIOCOUTQint *argp

Получить количество байтов в буфере вывода.

TCFLSHint arg

Эквивалентно tcflush(fd, arg).

Смотрите tcflush(3) со значениями аргументов TCIFLUSH, TCOFLUSH, TCIOFLUSH.

Мнимый ввод

TIOCSTIconst char *argp

Вставить заданный байт в очередь ввода.

Перенаправление вывода консоли

TIOCCONSvoid

Перенаправляет вывод, который должен идти на /dev/console или
/dev/tty0, на указанный терминал. Если это был основной псевдо-терминал, то вывод отправляется на подчинённый. В Linux до версии 2.6.10 кто угодно мог делать это, пока вывод не был ещё ни разу перенаправлен; начиная с версии 2.6.10 только процесс с мандатом CAP_SYS_ADMIN может делать это. Если вывод уже был перенаправлен, то будет выдана ошибка EBUSY, но перенаправление можно остановить с помощью этого вызова ioctl с fd, указывающим на /dev/console или /dev/tty0.

Управляющий терминал

TIOCSCTTYint arg

Сделать заданный терминал управляющим для вызывающего процесса. Вызывающий
процесс должен быть лидером сеанса и не иметь управляющего терминала. Для этого случая значение arg должно быть равно 0.

Если этот терминал уже является управляющим для другой группы сеансов, то ioctl завершается с ошибкой EPERM, если только вызывающий не имеет мандата CAP_SYS_ADMIN и arg не равно 1 — в этом случае терминал отбирается и все процессы, где он был управляющим, теряют его.

TIOCNOTTYvoid

Если заданный терминал является управляющим для вызывающего процесса, то
выполняется отключение этого управляющего терминала. Если процесс был лидером сеанса, то активной группе процессов посылаются сигналы SIGHUP и SIGCONT, и все процессы в этом сеансе теряют управляющий терминал.

Группа процессов и идентификатор сеанса

TIOCGPGRPpid_t *argp

При успешном выполнении эквивалентно *argp = tcgetpgrp(fd).

Получить идентификатор активной группы процессов данного терминала.

TIOCSPGRPconst pid_t *argp

Эквивалентно tcsetpgrp(fd, *argp).

Установить идентификатор активной группы процессов данного терминала.

TIOCGSIDpid_t *argp

Получить идентификатор сеанса данного терминала. Завершается с ошибкой
ENOTTY в случае, если терминал не является основным псевдо-терминалом и не является управляющим для вызывающего процесса. Странно.

Закрытый (Exclusive) режим

TIOCEXCLvoid

Перевести терминал в закрытый режим. Дальнейшие операции open(2) с
терминалом запрещены (они будут выдавать ошибку EBUSY, если процесс не имеет мандата CAP_SYS_ADMIN).

TIOCGEXCLint *argp

Если терминал находится в закрытом режиме, поместить ненулевое значение в
расположение, указанное argp; в противном случае, поместить ноль в *argp (начиная с Linux 3.8).

TIOCNXCLvoid

Отменить закрытый режим.

Параметры линии

TIOCGETDint *argp

Получить параметры линии для терминала.

TIOCSETDconst int *argp

Установить параметры линии для терминала.

Вызовы ioctl для псевдо-терминала

TIOCPKTconst int *argp

Включить (если *argp не равно нулю) или отключить пакетный режим. Может
применяться только к основному псевдо-терминалу (иначе будет возвращено ENOTTY). В пакетном режиме каждый последующий read(2) возвращает пакет, содержащий либо один ненулевой управляющий байт, либо один нулевой байт (' ') с последующими данными, записанными на подчинённом псевдо-терминале. Если первый байт не равен TIOCPKT_DATA (0), то он логически складывается с одним или несколькими следующими битами:

TIOCPKT_FLUSHREAD Очередь чтения терминала очищается.
TIOCPKT_FLUSHWRITE Очередь записи терминала очищается.
TIOCPKT_STOP Вывод на терминал останавливается.
TIOCPKT_START Вывод на терминал перезапускается.
TIOCPKT_DOSTOP Символами запуска/останова являются ^S/^Q.
TIOCPKT_NOSTOP Символами запуска/останова не являются ^S/^Q.

При использовании этого режима наличие состояния управляющей информации, считываемой с основного псевдо-терминала, может быть определено с помощью select(2) для исключительных условий.

Этот режим используется rlogin(1) и rlogind(8) для реализации удалённого эха с локально управляемым потоком с помощью ^S/^Q для удалённого входа.

TIOGCPKTconst int *argp

Вернуть текущую настройку пакетного режима в виде целого в память, на
которую указывает argp (начиная с Linux 3.8).

TIOCSPTLCKint *argp

Назначить (если *argp не равно нулю nonzero) или удалить (если *argp
равно нулю) устройство подчинённого псевдо-терминала (также смотрите unlockpt(3)).

TIOCGPTLCKint *argp

Поместить текущее состояние блокировки устройства подчинённого
псевдо-терминала в расположение, на которое указывает argp (начиная с Linux 3.8).

Вызовы ioctl для BSD --- TIOCSTOP, TIOCSTART, TIOCUCNTL, TIOCREMOTE --- не реализованы в Linux.

Управление модемом

TIOCMGETint *argp

Получить состояние битов модема.

TIOCMSETconst int *argp

Установить состояние битов модема.

TIOCMBICconst int *argp

Очистить указанные биты модема.

TIOCMBISconst int *argp

Установить указанные биты модема.

Приведёнными выше ioctl используются следующие биты:

TIOCM_LE DSR (источник данных готов/линия включена)
TIOCM_DTR DTR (сигнал готовности терминала)
TIOCM_RTS RTS (запрос на передачу)
TIOCM_ST Вторичный TXD (передача)
TIOCM_SR Вторичный RXD (приём)
TIOCM_CTS CTS (разрешение на передачу)
TIOCM_CAR DCD (обнаружен информационный сигнал)
TIOCM_CD см. TIOCM_CAR
TIOCM_RNG RNG (звонок)
TIOCM_RI см. TIOCM_RNG
TIOCM_DSR DSR (источник данных готов)

TIOCMIWAITint arg

Ждать изменения любого из 4 битов модема (DCD, RI, DSR, CTS). Интересующие
биты указываются в arg в виде битовой маски с помощью операции OR значений TIOCM_RNG, TIOCM_DSR, TIOCM_CD и TIOCM_CTS. Чтобы понять какие биты изменились вызывающий должен использовать TIOCGICOUNT.

TIOCGICOUNTstruct serial_icounter_struct *argp

Получить счётчики входных прерываний последовательной линии (DCD, RI, DSR,
CTS). Счётчики записываются в структуру serial_icounter_struct, на которую указывает argp.

Замечание: считаются переходы 1->0 и 0->1, за исключением RI, где учитывается только переход 0->1.

Локальная линия

TIOCGSOFTCARint *argp

Получить состояние флага CLOCAL в поле c_cflag структуры termios.

TIOCSSOFTCARconst int *argp

Установить флаг CLOCAL в поле c_cflag структуры termios при *argp не
равном нулю или очистить его в противном случае.

Если флаг CLOCAL для линии не установлен, то учитывается сигнал DCD, а вызов open(2) для соответствующего терминала будет блокирован, пока не появится сигнал DCD ( если не установлен флаг O_NONBLOCK). Если флаг CLOCAL установлен, то линия ведёт себя так, как если DCD установлен всегда. Программное задание несущего сигнала обычно включено для локальных устройств и выключено для модемных линий.

Вызовы, определённые только в Linux

Описание вызова ioctl TIOCLINUX смотрите в console_ioctl(4).

Отладка ядра

#include <linux/tty.h>

TIOCTTYGSTRUCTstruct tty_struct *argp

Получить структуру tty_struct, соответствующую fd. Эта команда удалена
в Linux 2.5.67.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

При нормальном завершении работы системный вызов ioctl(2) возвращает 0. При ошибке возвращается -1 и соответствующим образом устанавливается переменная errno.

ОШИБКИ

EINVAL

Неизвестный параметр команды.

ENOIOCTLCMD

Неизвестная команда.

ENOTTY

Неподходящий fd.

EPERM

Недостаточно прав.

ПРИМЕР

Проверка состояния DTR на последовательном порту.

#include <termios.h>
#include <fcntl.h>
#include <sys/ioctl.h>
int
main(void)
{
 int fd, serial;
 fd = open("/dev/ttyS0", O_RDONLY);
 ioctl(fd, TIOCMGET, &serial);
 if (serial & TIOCM_DTR)
 puts("TIOCM_DTR установлен");
 else
 puts("TIOCM_DTR не установлен");
 close(fd);
}