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.ioctl(fd, request, arg=0, mutate_flag=True)

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

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

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

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

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

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

Если mutate_flag имеет значение true (по умолчанию), то буфер (по существу) передается в системный вызов 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.flock(fd, operation)

Выполняет операцию блокировки operation над дескриптором файла fd (также принимаются объекты файлов, предоставляющие метод fileno()). Для получения подробностей см. страницу руководства Unix flock(2). (На некоторых системах эта функция эмулируется с помощью fcntl().)

Если вызов flock() терпит неудачу, возникает исключение OSError.

fcntl.lockf(fd, cmd, len=0, start=0, whence=0)

Это по существу обёртка вокруг вызовов блокировки fcntl(). fd — дескриптор файла, который нужно заблокировать или разблокировать, а 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.

Примеры (все на 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().