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

Этот модуль выполняет управление файлами и управлением вводом-выводом по дескрипторам файлов. Это интерфейс к 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 может быть целым значением или объектом 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() может быть предпочтительнее.