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

Этот модуль выполняет управление файлами и вводом-выводом для дескрипторов файлов. Это интерфейс к fcntl() и ioctl() Unix-функциям. Для получения полной информации см. страницы руководства 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. При целочисленном значении возвращаемое значение этой функции — целочисленное возвращаемое значение вызова C fcntl(). Когда аргумент является объектом bytes, он представляет двоичную структуру, например, созданную с помощью struct.pack(). Двоичные данные копируются в буфер, адрес которого передаётся в вызов C fcntl(). Возвращаемое значение после успешного вызова — содержимое буфера, преобразованное в объект bytes. Длина возвращаемого объекта будет такой же, как и длина аргумента arg. Это ограничено 1024 байтами. Если информация, возвращённая в буфер операционной системой, больше 1024 байтов, это, скорее всего, приведёт к нарушению сегментации или более тонкому повреждению данных.

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

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

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

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

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

Параметр arg может быть целым числом, объектом, поддерживающим интерфейс чтения-только буфера (например, bytes) или объектом, поддерживающим интерфейс чтения-записи буфера (например, bytearray).

Во всех случаях, кроме последнего, поведение такое же, как у функции fcntl().

Если передаётся изменяемый буфер, то поведение определяется значением параметра mutate_flag.

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

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

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

Пример:

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