fcntl — системные вызовы fcntl и ioctl

Этот модуль выполняет операции управления файлами и вводом-выводом для файловых дескрипторов. Он предоставляет интерфейс к процедурам Unix fcntl() и ioctl(). Полную информацию см. на страницах руководства Unix fcntl(2) и ioctl(2).

Все функции этого модуля принимают файловый дескриптор fd в качестве первого аргумента. Это может быть целочисленный файловый дескриптор, например возвращаемый sys.stdin.fileno(), или объект io.IOBase, например сам sys.stdin, который предоставляет метод fileno(), возвращающий настоящий файловый дескриптор.

Модуль определяет следующие функции:

fcntl.fcntl(fd, cmd, arg=0, /)

Выполняет операцию cmd для файлового дескриптора fd (также принимаются файловые объекты, предоставляющие метод fileno()). Значения cmd зависят от операционной системы и доступны в виде констант модуля fcntl; их имена совпадают с именами в соответствующих заголовочных файлах C. Аргумент arg может быть целочисленным значением, объектом bytes или строкой. Тип и размер arg должны соответствовать типу и размеру аргумента операции, указанным в соответствующей документации C.

Если arg — целое число, функция возвращает целочисленное значение, возвращаемое вызовом C fcntl().

Если аргумент имеет тип bytes, он представляет собой двоичную структуру, например созданную с помощью struct.pack(). Строковое значение преобразуется в двоичные данные с использованием кодировки UTF-8. Двоичные данные копируются в буфер, адрес которого передаётся вызову C fcntl(). После успешного вызова возвращается содержимое буфера, преобразованное в объект bytes. Длина возвращаемого объекта будет такой же, как длина аргумента arg. Максимальная длина — 1024 байта.

Если вызов fcntl() завершается ошибкой, возникает исключение OSError.

Примечание

Если тип или размер arg не совпадает с типом или размером аргумента операции (например, если вместо ожидаемого указателя передано целое число или возвращённая операционной системой информация в буфере превышает 1024 байта), это, скорее всего, приведёт к ошибке сегментации или более трудно обнаруживаемому повреждению данных.

Вызывает событие аудита fcntl.fcntl с аргументами fd, cmd, arg.

fcntl.ioctl(fd, request, arg=0, mutate_flag=True, /)

Эта функция аналогична функции fcntl(), за исключением того, что обработка аргументов устроена ещё сложнее.

Параметр request может принимать только значения, умещающиеся в 32 или 64 бита, в зависимости от платформы. Дополнительные полезные константы для аргумента request можно найти в модуле termios; их имена совпадают с именами в соответствующих заголовочных файлах C.

Параметр arg может быть целым числом, объектом, подобным bytes, или строкой. Тип и размер arg должны соответствовать типу и размеру аргумента операции, указанным в соответствующей документации C.

Если arg не поддерживает интерфейс буфера для чтения и записи или значение mutate_flag равно false, поведение будет таким же, как у функции fcntl().

Если arg поддерживает интерфейс буфера для чтения и записи (как, например, bytearray), а значение mutate_flag равно true (по умолчанию), то буфер (фактически) передаётся лежащему в основе системному вызову ioctl(), его код возврата передаётся обратно в вызывающий код Python, а новое содержимое буфера отражает результат работы ioctl(). Это небольшое упрощение: если длина переданного буфера меньше 1024 байт, сначала он копируется в статический буфер длиной 1024 байта, который затем передаётся в ioctl(), после чего копируется обратно в переданный буфер.

Если вызов ioctl() завершается ошибкой, возникает исключение OSError.

Примечание

Если тип или размер arg не совпадает с типом или размером аргумента операции (например, если вместо ожидаемого указателя передано целое число, возвращённая операционной системой информация в буфере превышает 1024 байта или размер изменяемого объекта, подобного bytes, слишком мал), это, скорее всего, приведёт к ошибке сегментации или более трудно обнаруживаемому повреждению данных.

Пример:

>>> import array, fcntl, struct, termios, os
>>> os.getpgrp()
13341
>>> struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, "  "))[0]
13341
>>> buf = array.array('h', [0])
>>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1)
0
>>> buf
array('h', [13341])

Вызывает событие аудита fcntl.ioctl с аргументами fd, request, arg.

fcntl.flock(fd, operation, /)

Выполняет операцию блокировки operation для файлового дескриптора fd (также принимаются файловые объекты, предоставляющие метод fileno()). Подробности см. в руководстве Unix flock(2). (В некоторых системах эта функция эмулируется с помощью fcntl().)

Если вызов flock() завершается ошибкой, возникает исключение OSError.

Вызывает событие аудита fcntl.flock с аргументами fd, operation.

fcntl.lockf(fd, cmd, len=0, start=0, whence=0, /)

По сути, это обёртка для вызовов блокировки fcntl(). fd — файловый дескриптор (также принимаются файловые объекты, предоставляющие метод fileno()) файла, который нужно заблокировать или разблокировать, а cmd — одно из следующих значений:

fcntl.LOCK_UN

Снять существующую блокировку.

fcntl.LOCK_SH

Установить разделяемую блокировку.

fcntl.LOCK_EX

Установить исключительную блокировку.

fcntl.LOCK_NB

Выполнить побитовое ИЛИ с любой из трёх остальных констант LOCK_*, чтобы запрос не блокировал выполнение.

Если используется LOCK_NB и установить блокировку не удаётся, будет вызвано исключение OSError, атрибут errno которого будет иметь значение EACCES или EAGAIN (в зависимости от операционной системы; для переносимости проверяйте оба значения). По крайней мере в некоторых системах LOCK_EX можно использовать только в том случае, если файловый дескриптор ссылается на файл, открытый для записи.

len — количество блокируемых байтов, start — смещение в байтах, с которого начинается блокировка относительно whence, а whence имеет то же значение, что и в io.IOBase.seek(), а именно:

• 0 — относительно начала файла (os.SEEK_SET)
• 1 — относительно текущего положения в буфере (os.SEEK_CUR)
• 2 — относительно конца файла (os.SEEK_END)

Значение start по умолчанию равно 0, то есть блокировка начинается с начала файла. Значение len по умолчанию равно 0, то есть блокировка распространяется до конца файла. Значение whence по умолчанию также равно 0.

Вызывает событие аудита fcntl.lockf с аргументами fd, cmd, len, start, whence.

Примеры (для системы, совместимой с SVR4):

import struct, fcntl, os

f = open(...)
rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY)

lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0)
rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata)

Обратите внимание, что в первом примере переменная возвращаемого значения rv будет содержать целочисленное значение, а во втором — объект bytes. Расположение полей структуры переменной lockdata зависит от системы — поэтому вызов flock() может оказаться предпочтительнее.