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

   * "0" -- relativo al inicio del archivo ("os.SEEK_SET")

   * "1" -- relativo a la posición actual del buffer ("os.SEEK_CUR")

   * "2" -- relativo al final del archivo ("os.SEEK_END")

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