# `fcntl` — The `fcntl` and `ioctl` system calls

This module performs file and I/O control on file descriptors. It is an interface to the `fcntl()` and `ioctl()` Unix routines. See the fcntl(2) and ioctl(2) Unix manual pages for full details.

Availability: Unix, not WASI.

Усі функції в цьому модулі приймають файловий дескриптор fd як перший аргумент. Це може бути цілочисельний файловий дескриптор, наприклад, повернутий `sys.stdin.fileno()`, або об’єкт `io.IOBase`, як-от сам `sys.stdin`, який надає `fileno()`, який повертає справжній дескриптор файлу.

Змінено в версії 3.3: Раніше операції в цьому модулі викликали `IOError`, а тепер вони викликають `OSError`.

Змінено в версії 3.8: The `fcntl` module now contains `F_ADD_SEALS`, `F_GET_SEALS`, and `F_SEAL_*` constants for sealing of `os.memfd_create()` file descriptors.

Змінено в версії 3.9: On macOS, the `fcntl` module exposes the `F_GETPATH` constant, which obtains the path of a file from a file descriptor. On Linux(>=3.15), the `fcntl` module exposes the `F_OFD_GETLK`, `F_OFD_SETLK` and `F_OFD_SETLKW` constants, which are used when working with open file description locks.

Змінено в версії 3.10: On Linux >= 2.6.11, the `fcntl` module exposes the `F_GETPIPE_SZ` and `F_SETPIPE_SZ` constants, which allow to check and modify a pipe’s size respectively.

Змінено в версії 3.11: On FreeBSD, the `fcntl` module exposes the `F_DUP2FD` and `F_DUP2FD_CLOEXEC` constants, which allow to duplicate a file descriptor, the latter setting `FD_CLOEXEC` flag in addition.

Змінено в версії 3.12: On Linux >= 4.5, the `fcntl` module exposes the `FICLONE` and `FICLONERANGE` constants, which allow to share some data of one file with another file by reflinking on some filesystems (e.g., btrfs, OCFS2, and XFS). This behavior is commonly referred to as «copy-on-write».

Змінено в версії 3.13: On Linux >= 2.6.32, the `fcntl` module exposes the `F_GETOWN_EX`, `F_SETOWN_EX`, `F_OWNER_TID`, `F_OWNER_PID`, `F_OWNER_PGRP` constants, which allow to direct I/O availability signals to a specific thread, process, or process group. On Linux >= 4.13, the `fcntl` module exposes the `F_GET_RW_HINT`, `F_SET_RW_HINT`, `F_GET_FILE_RW_HINT`, `F_SET_FILE_RW_HINT`, and `RWH_WRITE_LIFE_*` constants, which allow to inform the kernel about the relative expected lifetime of writes on a given inode or via a particular open file description. On Linux >= 5.1 and NetBSD, the `fcntl` module exposes the `F_SEAL_FUTURE_WRITE` constant for use with `F_ADD_SEALS` and `F_GET_SEALS` operations. On FreeBSD, the `fcntl` module exposes the `F_READAHEAD`, `F_ISUNIONSTACK`, and `F_KINFO` constants. On macOS and FreeBSD, the `fcntl` module exposes the `F_RDAHEAD` constant. On NetBSD and AIX, the `fcntl` module exposes the `F_CLOSEM` constant. On NetBSD, the `fcntl` module exposes the `F_MAXFD` constant. On macOS and NetBSD, the `fcntl` module exposes the `F_GETNOSIGPIPE` and `F_SETNOSIGPIPE` constant.

Модуль визначає такі функції:

fcntl.fcntl(fd, cmd, arg=0)

  Виконайте операцію cmd над файловим дескриптором fd (також приймаються файлові об’єкти, що містять метод `fileno()`). Значення, які використовуються для cmd, залежать від операційної системи та доступні як константи в модулі `fcntl`, використовуючи ті самі імена, що використовуються у відповідних файлах заголовків C. Аргумент arg може бути або цілим значенням, або об’єктом `bytes`. З цілим значенням значення, що повертається цією функцією, є цілим значенням, що повертається викликом C `fcntl()`. Коли аргумент є байтами, він представляє двійкову структуру, наприклад. створено `struct.pack()`. Двійкові дані копіюються в буфер, адреса якого передається виклику C `fcntl()`. Значення, що повертається після успішного виклику, є вмістом буфера, перетвореним на об’єкт `bytes`. Довжина повернутого об’єкта буде такою ж, як і довжина аргументу arg. Це обмежено 1024 байтами. Якщо інформація, яку операційна система повертає в буфер, перевищує 1024 байти, це, швидше за все, призведе до порушення сегментації або більш тонкого пошкодження даних.

  If the `fcntl()` call fails, an `OSError` is raised.

  Викликає подію аудиту `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.

  Якщо значення false, мінливість буфера ігнорується, а поведінка така ж, як і для буфера лише для читання, за винятком того, що обмеження у 1024 байти, згадане вище, уникає — доки переданий буфер має принаймні таку довжину, як і операційна система. хоче поставити туди, речі повинні працювати.

  Якщо mutate_flag має значення true (за замовчуванням), тоді буфер (фактично) передається базовому системному виклику `ioctl()`, код повернення останнього передається назад викликаючому Python, а новий вміст буфера відображає дія `ioctl()`. Це невелике спрощення, тому що якщо довжина наданого буфера менша за 1024 байти, він спочатку копіюється в статичний буфер довжиною 1024 байти, який потім передається до `ioctl()` і копіюється назад у наданий буфер.

  If the `ioctl()` call fails, an `OSError` exception is raised.

  Приклад:

      >>> 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()`.)

  If the `flock()` call fails, an `OSError` exception is raised.

  Викликає подію аудиту `fcntl.flock` з аргументами `fd`, `operation`.

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

  По суті, це обгортка викликів блокування `fcntl()`. fd — це дескриптор файлу (також приймаються об’єкти файлу, що містять метод `fileno()`) файлу, який потрібно заблокувати або розблокувати, а cmd — одне з таких значень:

  fcntl.LOCK_UN

    Release an existing lock.

  fcntl.LOCK_SH

    Acquire a shared lock.

  fcntl.LOCK_EX

    Acquire an exclusive lock.

  fcntl.LOCK_NB

    Bitwise OR with any of the other three `LOCK_*` constants to make the request non-blocking.

  If `LOCK_NB` is used and the lock cannot be acquired, an `OSError` will be raised and the exception will have an errno attribute set to `EACCES` or `EAGAIN` (depending on the operating system; for portability, check for both values). On at least some systems, `LOCK_EX` can only be used if the file descriptor refers to a file opened for writing.

  len — це кількість байтів для блокування, start — зсув у байтах, з якого починається блокування, відносно whence, а whence — як у `io.IOBase.seek()`, зокрема:

  - `0` – relative to the start of the file (`os.SEEK_SET`)

  - `1` – relative to the current buffer position (`os.SEEK_CUR`)

  - `2` – relative to the end of the file (`os.SEEK_END`)

  Типовим значенням для початку є 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()` може бути кращим.

Дивись також

Модуль `os`

  If the locking flags `O_SHLOCK` and `O_EXLOCK` are present in the `os` module (on BSD only), the `os.open()` function provides an alternative to the `lockf()` and `flock()` functions.