"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 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: O módulo "fcntl" agora contém constantes
"F_ADD_SEALS", "F_GET_SEALS" e "F_SEAL_*" para selar descritores de
arquivo "os.memfd_create()".

Alterado na versão 3.9: No macOS, o módulo "fcntl" expõe a constante
"F_GETPATH", que obtém o caminho de um arquivo de um descritor de
arquivo. No Linux(>=3.15), o módulo "fcntl" expõe as constantes
"F_OFD_GETLK", "F_OFD_SETLK" e "F_OFD_SETLKW", que são usadas ao
trabalhar com travas de descrição de arquivo aberto.

Alterado na versão 3.10: No Linux >= 2.6.11, o módulo "fcntl" expõe as
constantes "F_GETPIPE_SZ" e "F_SETPIPE_SZ", que permitem verificar e
modificar o tamanho de um encadeamento, respectivamente.

Alterado na versão 3.11: No FreeBSD, o módulo "fcntl" expõe as
constantes "F_DUP2FD" e "F_DUP2FD_CLOEXEC", que permitem duplicar um
descritor de arquivo, sendo que esta última define também o
sinalizador "FD_CLOEXEC".

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

Alterado na versão 3.13: No Linux >= 2.6.32, o módulo "fcntl" expõe as
constantes "F_GETOWN_EX", "F_SETOWN_EX", "F_OWNER_TID", "F_OWNER_PID",
"F_OWNER_PGRP", que permitem direcionar sinais de disponibilidade de
E/S para uma thread, processo ou grupo de processos específico. No
Linux >= 4.13, o módulo "fcntl" expõe as constantes "F_GET_RW_HINT",
"F_SET_RW_HINT", "F_GET_FILE_RW_HINT", "F_SET_FILE_RW_HINT" e
"RWH_WRITE_LIFE_*", que permitem informar o kernel sobre o tempo de
vida relativo esperado de gravações em um determinado nó-i ou por meio
de uma descrição de arquivo aberto específica. No Linux >= 5.1 e
NetBSD, o módulo "fcntl" expõe a constante "F_SEAL_FUTURE_WRITE" para
uso com as operações "F_ADD_SEALS" e "F_GET_SEALS". No FreeBSD, o
módulo "fcntl" expõe as constantes "F_READAHEAD", "F_ISUNIONSTACK" e
"F_KINFO". No macOS e FreeBSD, o módulo "fcntl" expõe a constante
"F_RDAHEAD". No NetBSD e AIX, o módulo "fcntl" expõe a constante
"F_CLOSEM". No NetBSD, o módulo "fcntl" expõe a constante "F_MAXFD".
No macOS e no NetBSD, o módulo "fcntl" expõe as constantes
"F_GETNOSIGPIPE" e "F_SETNOSIGPIPE".

Alterado na versão 3.14: No Linux >= 6.1, o módulo "fcntl" expõe o
"F_DUPFD_QUERY" para consultar um descritor de arquivo apontando para
o mesmo arquivo.

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, um *objeto bytes ou similar* ou
   uma string. O tipo e o tamanho de *arg* devem corresponder ao tipo
   e ao tamanho do argumento da operação, conforme especificado na
   documentação C relevante.

   Quando *arg* é um inteiro, a função retorna o valor de retorno
   inteiro da chamada C "fcntl()".

   Quando o argumento é um objeto bytes ou similar, ele representa uma
   estrutura binária, por exemplo, criada por "struct.pack()". Um
   valor de string é codificado em binário usando a codificação UTF-8.
   Os dados binários são copiados para um buffer cujo endereço é
   passado para a chamada "fcntl()" em C. 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á igual ao
   comprimento do argumento *arg*. Este é limitado a 1024 bytes.

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

   Nota:

     Se o tipo ou o tamanho de *arg* não corresponder ao tipo ou
     tamanho do argumento da operação (por exemplo, se um inteiro for
     passado quando um ponteiro for esperado, ou se as informações
     retornadas no buffer pelo sistema operacional forem maiores que
     1024 bytes), é mais provável que isso resulte em uma violação de
     segmentação ou em uma corrupção de dados mais sutil.

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

   Alterado na versão 3.14: Adicione suporte a *objetos bytes ou
   similares* arbitrários, não apenas "bytes".

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.

   O parâmetro *request* é limitado a valores que cabem em 32 ou 64
   bits, dependendo da plataforma. Constantes adicionais de interesse
   para uso como argumento *request* podem ser encontradas no módulo
   "termios", com os mesmos nomes usados nos arquivos de cabeçalho C
   relevantes.

   O parâmetro *arg* pode ser um inteiro, um *objeto bytes ou similar*
   ou uma string. O tipo e o tamanho de *arg* devem corresponder ao
   tipo e ao tamanho do argumento da operação, conforme especificado
   na documentação C relevante.

   Se *arg* não oferecer suporte à interface de buffer de leitura e
   escrita ou o *mutate_flag* for falso, o comportamento será o mesmo
   da função "fcntl()".

   Se *arg* oferece suporte à interface de buffer de leitura e escrita
   (como "bytearray") e *mutate_flag* for true (o padrão), o buffer
   será (na prática) passado para a chamada de sistema subjacente
   "ioctl()", o código de retorno desta última será passado de volta
   para o Python que fez a chamada, e o novo conteúdo do buffer
   refletirá a ação de "ioctl()". Esta é uma pequena simplificação,
   pois se o buffer fornecido tiver menos de 1024 bytes, ele será
   primeiro copiado para um buffer estático de 1024 bytes, que será
   então passado para "ioctl()" e copiado de volta para o buffer
   fornecido.

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

   Nota:

     Se o tipo ou o tamanho de *arg* não corresponder ao tipo ou
     tamanho do argumento da operação (por exemplo, se um inteiro for
     passado quando um ponteiro for esperado, ou se as informações
     retornadas no buffer pelo sistema operacional forem maiores que
     1024 bytes ou o tamanho do objeto byte ou similar mutável é
     pequeno demais), é mais provável que isso resulte em uma violação
     de segmentação ou em uma corrupção de dados mais sutil.

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

   Alterado na versão 3.14: A GIL é sempre liberada durante uma
   chamada de sistema. Chamadas de sistema que falham com EINTR são
   repetidas automaticamente.

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