fcntl – системные вызовы fcntl и ioctl¶fcntl – The fcntl and ioctl system calls

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

Примечание

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

Пример:

>>> 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() может быть предпочтительнее.