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.

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