"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, not Emscripten, not 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.

Alterado na versão 3.12: No Linux >= 4.5, o módulo "fcntl" expõe as
constantes "FICLONE" e "FICLONERANGE", que permitem compartilhar
alguns dados de um arquivo com outro arquivo por meio de reflinking em
alguns sistemas de arquivos (por exemplo, btrfs, OCFS2 e XFS). Esse
comportamento é comumente chamado de "copy-on-write".

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