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

Todas las funciones de este módulo toman un descriptor de fichero fd como su primer argumento. Puede ser un descriptor de fichero entero, como el retornado por sys.stdin.fileno(), o un objeto io.IOBase, como sys.stdin, que proporciona un fileno() que retorna un descriptor de fichero original.

Distinto en la versión 3.3: Las operaciones en este módulo solían lanzar un IOError donde ahora lanzan un OSError.

Distinto en la versión 3.8: El módulo fcntl ahora contiene las constantes F_ADD_SEALS, F_GET_SEALS, y F_SEAL_* para sellar los descriptores de fichero os.memfd_create().

Distinto en la versión 3.9: En macOS, el módulo fcntl expone la constante F_GETPATH, que obtiene la ruta de un archivo a partir de un descriptor de archivo. En Linux (>=3.15), el módulo fcntl expone las constantes F_OFD_GETLK, F_OFD_SETLK y F_OFD_SETLKW, que funcionan con bloqueos de descripción de archivos abiertos.

Distinto en la versión 3.10: En Linux >= 2.6.11, el módulo fcntl expone las constantes F_GETPIPE_SZ y F_SETPIPE_SZ, las cuales permiten chequear y modificar el tamaño de un pipe, respectivamente.

Distinto en la versión 3.11: En FreeBSD, el módulo fcntl expone las constantes F_DUP2FD y F_DUP2FD_CLOEXEC, que permiten duplicar un descriptor de fichero, esta última fijando además el indicador FD_CLOEXEC.

Distinto en la versión 3.12: En Linux >= 4.5, el módulo fcntl expone las constantes FICLONE y FICLONERANGE, que permiten compartir algunos datos de un fichero con otro fichero mediante el reflinking en algunos sistemas de ficheros (por ejemplo, btrfs, OCFS2 y XFS). Este comportamiento se conoce comúnmente como «copy-on-write».

El módulo define las siguientes funciones:

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

Realiza la operación cmd en el descriptor de fichero fd (también se aceptan objetos de fichero que proporcionen un método fileno()). Los valores utilizados para cmd dependen del sistema operativo y están disponibles como constantes en el módulo fcntl, utilizando los mismos nombres que se utilizan en los archivos de cabecera C relevantes. El argumento arg puede ser un valor entero o un objeto bytes. Con un valor entero, el valor retornado en esta función es el valor entero retornado por la llamada en C fcntl() . Cuando el argumento son bytes representa una estructura binaria, e.g. creada por struct.pack(). Los datos binarios se copian en un búfer cuya dirección se pasa a la llamada en C :fcntl(). El valor retornado después de una llamada correcta es el contenido del búfer, convertido en un objeto bytes. La longitud del objeto retornado será la misma que la longitud del argumento arg. Esta longitud está limitada a 1024 bytes. Si la información retornada en el búfer por el sistema operativo es mayor que 1024 bytes, lo más probable es que se produzca una violación de segmento o a una corrupción de datos más sutil.

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

Lanza un evento de auditoria fcntl.fcntl con argumentos fd, cmd, arg.

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

Esta función es idéntica a la función fcntl(), excepto por el manejo de los argumentos que es aún más complicado.

El parámetro request se encuentra limitado a valores que encajen en 32-bits. Se pueden encontrar constantes adicionales de interés para usar como argumento request en el módulo termios, con los mismos nombres que se usan en los archivos de cabecera C correspondientes.

El parámetro arg puede ser un entero, un objeto que admita una interfaz de búfer de solo lectura (como bytes) o un objeto que admita una interfaz de búfer de lectura-escritura (como: clase bytearray).

En todos los casos, excepto en el último, el comportamiento es el mismo que para la función fcntl().

Si se pasa un búfer mutable, el comportamiento estará determinado por el valor del parámetro mutate_flag.

Si es falso, la mutabilidad del búfer se ignorará y el comportamiento será como el de un búfer de solo lectura, excepto por el límite de 1024 bytes mencionado arriba, que será evitado – siempre que el búfer que pase sea al menos tan largo como el sistema operativo quiera colocar allí, las cosas deberían funcionar.

Si mutate_flag es verdadero (valor predeterminado), entonces el búfer se pasa (en efecto) a la llamada al sistema subyacente ioctl(), el código de retorno de este último retorna una llamada Python, y el nuevo contenido del búfer refleja la acción de ioctl(). Esto es una ligera simplificación, porque si el búfer proporcionado tiene menos de 1024 bytes de longitud, primero se copia en un búfer estático de 1024 bytes de longitud que luego se pasa a ioctl() y se copia de nuevo en el búfer proporcionado.

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

Un ejemplo:

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

Lanza un evento de auditoria fcntl.ioctl con argumentos fd, request, arg.

fcntl.flock(fd, operation)

Realiza la operación de bloqueo operation sobre el descriptor de fichero fd (también se aceptan objetos de fichero que proporcionen un método fileno()). Ver el manual de Unix flock(2) para más detalles. (En algunos sistemas, esta función es emulada usando fcntl().)

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

Lanza un evento de auditoria fcntl.flock con argumentos fd, operation.

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

Esto es esencialmente un «wrapper» de las llamadas de bloqueo fcntl(). fd es el descriptor de fichero (también se aceptan objetos de fichero que proporcionen un método fileno()) del archivo para bloquear o desbloquear, y cmd es uno de los siguientes valores:

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 es el número de bytes a bloquear, start es el desplazamiento de bytes en el que comienza el bloqueo, relativo a whence, y whence es como con io.IOBase.seek(), específicamente:

El valor por defecto de*start* es 0, lo que significa que comienza al inicio del archivo. El valor por defecto para len es 0 lo que significa bloquear hasta el final del archivo. El valor por defecto para whence también es 0.

Lanza un evento de auditoria fcntl.lockf con argumentos fd, cmd, len, start, whence.

Ejemplos (todos en un sistema compatible con 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)

Tenga en cuenta que en el primer ejemplo, el valor de la variable retornada rv contendrá un valor entero; en el segundo ejemplo contendrá un objeto bytes. La estructura para la variable lockdata depende del sistema — por lo tanto, usar la llamada flock() puede ser mejor.

Ver también

Módulo os

Si los indicadores de bloqueo O_SHLOCK y O_EXLOCK están presentes en el módulo os (sólo en BSD), la función os.open() proporciona una alternativa a las funciones lockf() y flock().