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.

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)

This function is identical to the fcntl() function, except that the argument handling is even more complicated.

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.

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

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)

Perform the lock operation operation on file descriptor fd (file objects providing a fileno() method are accepted as well). See the Unix manual flock(2) for details. (On some systems, this function is emulated using fcntl().)

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

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

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

This is essentially a wrapper around the fcntl() locking calls. fd is the file descriptor (file objects providing a fileno() method are accepted as well) of the file to lock or unlock, and cmd is one of the following values:

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 is the number of bytes to lock, start is the byte offset at which the lock starts, relative to whence, and whence is as with io.IOBase.seek(), specifically:

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

The default for start is 0, which means to start at the beginning of the file. The default for len is 0 which means to lock to the end of the file. The default for whence is also 0.

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

Examples (all on a SVR4 compliant system):

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)

Note that in the first example the return value variable rv will hold an integer value; in the second example it will hold a bytes object. The structure lay-out for the lockdata variable is system dependent — therefore using the flock() call may be better.

Ver também

Módulo 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.