# `fcntl` — as chamadas de sistema `fcntl` e `ioctl`

Este módulo executa o controle de arquivos e de E/S em descritores de arquivos. É uma interface para as rotinas `fcntl()` e `ioctl()` do Unix. Veja as páginas de manual do Unix fcntl(2) e ioctl(2) para mais detalhes.

Disponibilidade: Unix, não Emscripten, não WASI.

Todas as funções neste módulo recebem um descritor de arquivo fd como seu primeiro argumento. Este pode ser um descritor de arquivo inteiro, como retornado por `sys.stdin.fileno()`, ou um objeto `io.IOBase`, como o próprio `sys.stdin`, que fornece um `fileno()` que retorna um descritor de arquivo genuíno.

Alterado na versão 3.3: As operações neste módulo costumavam levantar um `IOError`, mas agora levantam um `OSError`.

Alterado na versão 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.

Alterado na versão 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.

Alterado na versão 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.

Alterado na versão 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.

O módulo define as seguintes funções:

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

  Executa a operação cmd no descritor de arquivo fd (objetos arquivo que fornecem um método `fileno()` também são aceitos). Os valores usados para cmd dependem do sistema operacional e estão disponíveis como constantes no módulo `fcntl`, usando os mesmos nomes usados nos arquivos de cabeçalho C relevantes. O argumento arg pode ser um valor inteiro ou um objeto `bytes`. Com um valor inteiro, o valor de retorno desta função é o valor de retorno inteiro da chamada C `fcntl()`. Quando o argumento é bytes, ele representa uma estrutura binária, por exemplo, criada por `struct.pack()`. Os dados binários são copiados para um buffer cujo endereço é passado para a chamada C `fcntl()`. O valor de retorno após uma chamada bem-sucedida é o conteúdo do buffer, convertido em um objeto `bytes`. O comprimento do objeto retornado será o mesmo que o comprimento do argumento arg. Isso é limitado a 1024 bytes. Se as informações retornadas no buffer pelo sistema operacional forem maiores que 1024 bytes, isso provavelmente resultará em uma violação de segmentação ou uma corrupção de dados mais sutil.

  Se a chamada a `fcntl()` falhar, um exceção `OSError` é levantada.

  Levanta um evento de auditoria `fcntl.fcntl` com os argumentos `fd`, `cmd`, `arg`.

fcntl.ioctl(fd, request, arg=0, mutate_flag=True)

  Esta função é idêntica à função `fcntl()`, exceto que o tratamento de argumentos é ainda mais complicado.

  The request parameter is limited to values that can fit in 32-bits. Additional constants of interest for use as the request argument can be found in the `termios` module, under the same names as used in the relevant C header files.

  The parameter arg can be one of an integer, an object supporting the read-only buffer interface (like `bytes`) or an object supporting the read-write buffer interface (like `bytearray`).

  In all but the last case, behaviour is as for the `fcntl()` function.

  If a mutable buffer is passed, then the behaviour is determined by the value of the mutate_flag parameter.

  If it is false, the buffer’s mutability is ignored and behaviour is as for a read-only buffer, except that the 1024 byte limit mentioned above is avoided – so long as the buffer you pass is at least as long as what the operating system wants to put there, things should work.

  If mutate_flag is true (the default), then the buffer is (in effect) passed to the underlying `ioctl()` system call, the latter’s return code is passed back to the calling Python, and the buffer’s new contents reflect the action of the `ioctl()`. This is a slight simplification, because if the supplied buffer is less than 1024 bytes long it is first copied into a static buffer 1024 bytes long which is then passed to `ioctl()` and copied back into the supplied buffer.

  Se a chamada a `ioctl()` falhar, uma exceção `OSError` é levantada.

  Um exemplo:

      >>> 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])

  Levanta um evento de auditoria `fcntl.ioctl` com os argumentos `fd`, `request`, `arg`.

fcntl.flock(fd, operation)

  Executa a operação de trava operation no descritor de arquivo fd (objetos arquivo que fornecem um método `fileno()` também são aceitos). Consulte o manual do Unix flock(2) para obter detalhes. (Em alguns sistemas, esta função é emulada usando `fcntl()`.)

  Se a chamada `flock()` falhar, uma exceção `OSError` será levantada.

  Levanta um evento de auditoria `fcntl.flock` com os argumentos `fd` e `operation`.

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

  Este é essencialmente um invólucro em torno das chamadas de trava `fcntl()`. fd é o descritor de arquivo (objetos arquivo que fornecem um método `fileno()` também são aceitos) do arquivo para travar ou destravar, e cmd é um dos seguintes valores:

  fcntl.LOCK_UN

    Libera uma trava existente.

  fcntl.LOCK_SH

    Adquire uma trava compartilhada.

  fcntl.LOCK_EX

    Adquire uma trava exclusiva.

  fcntl.LOCK_NB

    Aplica OU (OR) bit a bit com qualquer uma das outras três constantes `LOCK_*` para tornar a solicitação não bloqueante.

  Se `LOCK_NB` for usado e a trava não puder ser obtido, uma exceção `OSError` será levantada e terá um atributo errno definido como `EACCES` ou `EAGAIN` (dependendo do sistema operacional; para portabilidade, verifique ambos os valores). Em pelo menos alguns sistemas, `LOCK_EX` só pode ser usado se o descritor de arquivo se referir a um arquivo aberto para escrita.

  len é o número de bytes para travar, start é o deslocamento de bytes em que a trava começa, em relação a whence, e whence é como em `io.IOBase.seek()`, especificamente:

  - `0` – relativo ao início do arquivo (`os.SEEK_SET`)

  - `1` – relativo à posição atual do buffer (`os.SEEK_CUR`)

  - `2` – relativo ao fim do arquivo (`os.SEEK_END`)

  O padrão para start é 0, o que significa iniciar no início do arquivo. O padrão para len é 0, o que significa travar no final do arquivo. O padrão para whence também é 0.

  Levanta um evento de auditoria `fcntl.lockf` com os argumentos `fd`, `cmd`, `len`, `start`, `whence`.

Exemplos (todos em um sistema compatível com 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)

Observe que, no primeiro exemplo, a variável de valor de retorno rv conterá um valor inteiro; no segundo exemplo, ela conterá um objeto `bytes`. O layout da estrutura da variável lockdata depende do sistema — portanto, usar a chamada `flock()` pode ser melhor.

Ver também

Módulo `os`

  Se os sinalizadores de trava `O_SHLOCK` e `O_EXLOCK` estiverem presentes no módulo `os` (somente no BSD), a função `os.open()` fornece uma alternativa às funções `lockf()` e `flock()`.