`fcntl.md`

153 строк · 19.4 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.15/library/fcntl.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `fcntl` – системные вызовы `fcntl` и `ioctl`89---1011Этот модуль выполняет управление файлами и вводом-выводом на файловых дескрипторах. Он является интерфейсом к `fcntl()` и `ioctl()` процедурам Unix. За подробностями обращайтесь к *[fcntl(2)](https://python-all.ru/3.15/library/fcntl.html)* и *[ioctl(2)](https://python-all.ru/3.15/library/fcntl.html)* справочным страницам Unix.1213[Доступность](https://python-all.ru/3.15/library/intro.html#availability): Unix, не WASI.1415Все функции в этом модуле первым аргументом принимают файловый дескриптор *fd*. Это может быть целочисленный файловый дескриптор, например, возвращаемый `sys.stdin.fileno()`, или объект [`io.IOBase`](https://python-all.ru/3.15/library/io.html#io.IOBase), такой как сам `sys.stdin`, который предоставляет [`fileno()`](https://python-all.ru/3.15/library/io.html#io.IOBase.fileno), возвращающий настоящий файловый дескриптор.1617Изменено в версии 3.3: Ранее операции в этом модуле вызывали [`IOError`](https://python-all.ru/3.15/library/exceptions.html#IOError), теперь они вызывают [`OSError`](https://python-all.ru/3.15/library/exceptions.html#OSError).1819Изменено в версии 3.8: Модуль `fcntl` теперь содержит константы `F_ADD_SEALS`, `F_GET_SEALS` и `F_SEAL_*` для запечатывания [`os.memfd_create()`](https://python-all.ru/3.15/library/os.html#os.memfd_create) файловых дескрипторов.2021Изменено в версии 3.9: На macOS модуль `fcntl` предоставляет константу `F_GETPATH`, которая получает путь к файлу из файлового дескриптора. На Linux (\>=3.15) модуль `fcntl` предоставляет константы `F_OFD_GETLK`, `F_OFD_SETLK` и `F_OFD_SETLKW`, используемые при работе с блокировками открытых файловых дескрипторов.2223Изменено в версии 3.10: На Linux \>= 2.6.11 модуль `fcntl` предоставляет константы `F_GETPIPE_SZ` и `F_SETPIPE_SZ`, которые позволяют проверять и изменять размер канала соответственно.2425Изменено в версии 3.11: На FreeBSD модуль `fcntl` предоставляет константы `F_DUP2FD` и `F_DUP2FD_CLOEXEC`, которые позволяют дублировать файловый дескриптор, при этом последняя дополнительно устанавливает флаг `FD_CLOEXEC`.2627Изменено в версии 3.12: На Linux \>= 4.5 модуль `fcntl` предоставляет константы `FICLONE` и `FICLONERANGE`, которые позволяют совместно использовать часть данных одного файла с другим файлом через рефлинк в некоторых файловых системах (например, btrfs, OCFS2 и XFS). Такое поведение обычно называется «копирование при записи».2829Изменено в версии 3.13: На Linux \>= 2.6.32 модуль `fcntl` предоставляет константы `F_GETOWN_EX`, `F_SETOWN_EX`, `F_OWNER_TID`, `F_OWNER_PID`, `F_OWNER_PGRP`, которые позволяют направлять сигналы готовности ввода-вывода определённому потоку, процессу или группе процессов. На Linux \>= 4.13 модуль `fcntl` предоставляет константы `F_GET_RW_HINT`, `F_SET_RW_HINT`, `F_GET_FILE_RW_HINT`, `F_SET_FILE_RW_HINT` и `RWH_WRITE_LIFE_*`, которые позволяют информировать ядро об относительном ожидаемом времени жизни записей для заданного индексного дескриптора или через конкретное описание открытого файла. На Linux \>= 5.1 и NetBSD модуль `fcntl` предоставляет константу `F_SEAL_FUTURE_WRITE` для использования с операциями `F_ADD_SEALS` и `F_GET_SEALS`. На FreeBSD модуль `fcntl` предоставляет константы `F_READAHEAD`, `F_ISUNIONSTACK` и `F_KINFO`. На macOS и FreeBSD модуль `fcntl` предоставляет константу `F_RDAHEAD`. На NetBSD и AIX модуль `fcntl` предоставляет константу `F_CLOSEM`. На NetBSD модуль `fcntl` предоставляет константу `F_MAXFD`. На macOS и NetBSD модуль `fcntl` предоставляет константы `F_GETNOSIGPIPE` и `F_SETNOSIGPIPE`.3031Изменено в версии 3.14: На Linux \>= 6.1 модуль `fcntl` предоставляет `F_DUPFD_QUERY` для запроса файлового дескриптора, указывающего на тот же файл.3233Модуль определяет следующие функции:3435#### `fcntl.fcntl(fd, cmd, arg=0, /)`3637Выполняет операцию *cmd* над файловым дескриптором *fd* (также принимаются файловые объекты, предоставляющие метод [`fileno()`](https://python-all.ru/3.15/library/io.html#io.IOBase.fileno)). Значения, используемые для *cmd*, зависят от операционной системы и доступны в виде констант в модуле `fcntl` с теми же именами, что и в соответствующих заголовочных файлах C. Аргумент *arg* может быть целым числом, [байтоподобным объектом](https://python-all.ru/3.15/glossary.html#term-bytes-like-object) или строкой. Тип и размер *arg* должны соответствовать типу и размеру аргумента операции, как указано в соответствующей документации C.3839Когда *arg* является целым числом, функция возвращает целочисленное возвращаемое значение вызова C `fcntl()`.4041Когда аргумент является байтоподобным объектом, он представляет собой двоичную структуру, например, созданную с помощью [`struct.pack()`](https://python-all.ru/3.15/library/struct.html#struct.pack). Строковое значение кодируется в двоичный вид с использованием кодировки UTF-8. Двоичные данные копируются в буфер, адрес которого передаётся в вызов C `fcntl()`. Возвращаемое значение после успешного вызова – содержимое буфера, преобразованное в объект [`bytes`](https://python-all.ru/3.15/library/stdtypes.html#bytes). Длина возвращаемого объекта будет такой же, как длина аргумента *arg*.4243Если вызов `fcntl()` завершается неудачей, возбуждается [`OSError`](https://python-all.ru/3.15/library/exceptions.html#OSError).4445> **Примечание**46>47> Если тип или размер *arg* не совпадает с типом или размером аргумента операции (например, если передаётся целое число, когда ожидается указатель, или информация, возвращаемая операционной системой в буфер, превышает размер *arg*), это, скорее всего, приведёт к ошибке сегментации или более тонкому повреждению данных.4849Вызывает [событие аудита](https://python-all.ru/3.15/library/sys.html#auditing) `fcntl.fcntl` с аргументами `fd`, `cmd`, `arg`.5051Изменено в версии 3.14: Добавлена поддержка произвольных [байтоподобных объектов](https://python-all.ru/3.15/glossary.html#term-bytes-like-object), а не только [`bytes`](https://python-all.ru/3.15/library/stdtypes.html#bytes).5253Изменено в версии 3.15: Размер байтоподобных объектов больше не ограничен 1024 байтами.5455#### `fcntl.ioctl(fd, request, arg=0, mutate_flag=True, /)`5657Эта функция идентична [`fcntl()`](https://python-all.ru/3.15/library/fcntl.html#fcntl.fcntl), за исключением того, что обработка аргументов ещё более сложная.5859Параметр *request* ограничен значениями, которые могут поместиться в 32 или 64 бита, в зависимости от платформы. Дополнительные константы, которые могут быть полезны в качестве аргумента *request*, можно найти в модуле [`termios`](https://python-all.ru/3.15/library/termios.html#module-termios) под теми же именами, что и в соответствующих заголовочных файлах C.6061Параметр *arg* может быть целым числом, [байтоподобным объектом](https://python-all.ru/3.15/glossary.html#term-bytes-like-object) или строкой. Тип и размер *arg* должны соответствовать типу и размеру аргумента операции, как указано в соответствующей документации C.6263Если *arg* не поддерживает интерфейс буфера для чтения-записи или *mutate\_flag* равен false, поведение аналогично функции [`fcntl()`](https://python-all.ru/3.15/library/fcntl.html#fcntl.fcntl).6465Если *arg* поддерживает интерфейс буфера для чтения-записи (например, [`bytearray`](https://python-all.ru/3.15/library/stdtypes.html#bytearray)) и *mutate\_flag* равен true (по умолчанию), то буфер (фактически) передаётся нижележащему системному вызову `ioctl()`, код возврата последнего передаётся обратно в вызывающий код Python, а новое содержимое буфера отражает результат действия `ioctl()`. Это небольшое упрощение, потому что если предоставленный буфер короче 1024 байт, он сначала копируется в статический буфер длиной 1024 байта, который затем передаётся `ioctl()`, и результат копируется обратно в предоставленный буфер.6667Если вызов `ioctl()` завершается неудачей, возбуждается исключение [`OSError`](https://python-all.ru/3.15/library/exceptions.html#OSError).6869> **Примечание**70>71> Если тип или размер *arg* не совпадает с типом или размером аргумента операции (например, если передаётся целое число, когда ожидается указатель, или информация, возвращаемая операционной системой в буфер, превышает размер *arg*), это, скорее всего, приведёт к ошибке сегментации или более тонкому повреждению данных.7273Пример:7475```python76>>> import array, fcntl, struct, termios, os77>>> os.getpgrp()781334179>>> struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, "  "))[0]801334181>>> buf = array.array('h', [0])82>>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1)83084>>> buf85array('h', [13341])86```8788Вызывает [событие аудита](https://python-all.ru/3.15/library/sys.html#auditing) `fcntl.ioctl` с аргументами `fd`, `request`, `arg`.8990Изменено в версии 3.14: GIL всегда освобождается во время системного вызова. Системные вызовы, завершающиеся с ошибкой EINTR, автоматически повторяются.9192Изменено в версии 3.15: Размер неизменённых байтоподобных объектов больше не ограничен 1024 байтами.9394#### `fcntl.flock(fd, operation, /)`9596Выполняет операцию блокировки *operation* для файлового дескриптора *fd* (также принимаются файловые объекты, предоставляющие метод [`fileno()`](https://python-all.ru/3.15/library/io.html#io.IOBase.fileno)). Подробнее см. в руководстве Unix *[flock(2)](https://python-all.ru/3.15/library/fcntl.html)*. (В некоторых системах эта функция эмулируется с помощью `fcntl()`.)9798Если вызов `flock()` завершается неудачей, возбуждается исключение [`OSError`](https://python-all.ru/3.15/library/exceptions.html#OSError).99100Возбуждает [событие аудита](https://python-all.ru/3.15/library/sys.html#auditing) `fcntl.flock` с аргументами `fd`, `operation`.101102#### `fcntl.lockf(fd, cmd, len=0, start=0, whence=0, /)`103104По сути, это обёртка вокруг вызовов блокировки [`fcntl()`](https://python-all.ru/3.15/library/fcntl.html#fcntl.fcntl). *fd* – это файловый дескриптор (также принимаются файловые объекты, предоставляющие метод [`fileno()`](https://python-all.ru/3.15/library/io.html#io.IOBase.fileno)) файла, который нужно заблокировать или разблокировать, а *cmd* – одно из следующих значений:105106#### `fcntl.LOCK_UN`107108Освобождает существующую блокировку.109110#### `fcntl.LOCK_SH`111112Захватывает разделяемую блокировку.113114#### `fcntl.LOCK_EX`115116Захватывает исключительную блокировку.117118#### `fcntl.LOCK_NB`119120Побитовое ИЛИ с любой из трёх других констант `LOCK_*`, чтобы сделать запрос неблокирующим.121122Если используется `LOCK_NB` и блокировку не удаётся захватить, будет возбуждено исключение [`OSError`](https://python-all.ru/3.15/library/exceptions.html#OSError), и у исключения будет атрибут *errno*, установленный в [`EACCES`](https://python-all.ru/3.15/library/errno.html#errno.EACCES) или [`EAGAIN`](https://python-all.ru/3.15/library/errno.html#errno.EAGAIN) (в зависимости от операционной системы; для переносимости проверяйте оба значения). По крайней мере в некоторых системах `LOCK_EX` можно использовать только если файловый дескриптор ссылается на файл, открытый для записи.123124*len* – количество байтов для блокировки, *start* – смещение в байтах, с которого начинается блокировка, относительно *whence*, а *whence* работает как в [`io.IOBase.seek()`](https://python-all.ru/3.15/library/io.html#io.IOBase.seek), а именно:125126- `0` – относительно начала файла ([`os.SEEK_SET`](https://python-all.ru/3.15/library/os.html#os.SEEK_SET))127- `1` – относительно текущей позиции буфера ([`os.SEEK_CUR`](https://python-all.ru/3.15/library/os.html#os.SEEK_CUR))128- `2` – относительно конца файла ([`os.SEEK_END`](https://python-all.ru/3.15/library/os.html#os.SEEK_END))129130Значение по умолчанию для *start* – 0, то есть начало от начала файла. Значение по умолчанию для *len* – 0, то есть блокировка до конца файла. Значение по умолчанию для *whence* – также 0.131132Возбуждает [событие аудита](https://python-all.ru/3.15/library/sys.html#auditing) `fcntl.lockf` с аргументами `fd`, `cmd`, `len`, `start`, `whence`.133134Примеры (все на системе, совместимой с SVR4):135136```python137import struct, fcntl, os138139f = open(...)140rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY)141142lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0)143rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata)144```145146Обратите внимание, что в первом примере переменная возвращаемого значения *rv* будет содержать целое число; во втором примере она будет содержать объект [`bytes`](https://python-all.ru/3.15/library/stdtypes.html#bytes). Разметка структуры для переменной *lockdata* зависит от системы, поэтому использование вызова [`flock()`](https://python-all.ru/3.15/library/fcntl.html#fcntl.flock) может быть предпочтительнее.147148> **См. также**149>150> **Модуль [`os`](https://python-all.ru/3.15/library/os.html#module-os)**151>152> Если флаги блокировки [`O_SHLOCK`](https://python-all.ru/3.15/library/os.html#os.O_SHLOCK) и [`O_EXLOCK`](https://python-all.ru/3.15/library/os.html#os.O_EXLOCK) присутствуют в модуле [`os`](https://python-all.ru/3.15/library/os.html#module-os) (только в BSD), функция [`os.open()`](https://python-all.ru/3.15/library/os.html#os.open) предоставляет альтернативу функциям [`lockf()`](https://python-all.ru/3.15/library/fcntl.html#fcntl.lockf) и [`flock()`](https://python-all.ru/3.15/library/fcntl.html#fcntl.flock).153