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

Этот модуль выполняет управление файлами и управлением вводом-выводом для дескрипторов файлов. Это интерфейс к 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. При целочисленном значении, возвращаемое значение этой функции — это целочисленное возвращаемое значение C-вызова fcntl(). Когда аргумент является объектом байтов, он представляет бинарную структуру, например, созданную функцией 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 — одно из следующих значений:

• LOCK_UN — разблокировать
• LOCK_SH — получить общую блокировку
• LOCK_EX — получить эксклюзивную блокировку

Когда cmd равно LOCK_SH или LOCK_EX, оно также может быть побитовым ИЛИ с LOCK_NB для предотвращения блокировки при получении блокировки. Если используется 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() может быть предпочтительнее.