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.

Изменено в версии 3.14: Добавлена поддержка произвольных объектов, подобных bytes, а не только bytes.

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.

Изменено в версии 3.14: Во время системного вызова GIL всегда освобождается. Системные вызовы, завершающиеся ошибкой EINTR, автоматически повторяются.

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