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 — одно из следующих значений:

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