Provided by: manpages-es_1.55-8_all bug

NOMBRE

       fcntl - manipula el descriptor de fichero

SINOPSIS

       #include <unistd.h>
       #include <fcntl.h>

       int fcntl(int fd, int cmd);
       int fcntl(int fd, int cmd, long arg);
       int fcntl(int fd, int cmd, struct flock *lock);

DESCRIPCIÓN

       fcntl  realiza una de las diversas y variadas operaciones que se pueden
       hacer sobre fd.  La operación en cuestión se determina mediante cmd.

   Tratamiento de la bandera «cerrar al ejecutar»
       F_DUPFD
              Busca el descriptor de fichero disponible de menor número, mayor
              o  igual  que  arg,  y lo convierte en una copia de fd.  Esto es
              diferente  en  dup2(2)  que  usa   exactamente   el   descriptor
              especificado.

              Los  descriptores antiguo y nuevo pueden usarse indistintamente.
              Ambos comparten bloqueos (‘‘locks’’), indicadores de posición de
              ficheros  y  opciones o banderas (‘‘flags’’); por ejemplo, si la
              posición del fichero se modifica usando  lseek  en  uno  de  los
              descriptores,   la   posición   del   otro   resulta  modificada
              simultáneamente.

              Sin embargo, los dos descriptores no comparten la bandera close-
              on-exec  («cerrar  al ejecutar»). La bandera close-on-exec de la
              copia está desactivada, lo que significa que no  se  cerrará  al
              ejecutar.

              En caso de éxito, se devuelve el nuevo descriptor.

       F_GETFD
              Lee  la  bandera  close-on-exec.   Si el bit FD_CLOEXEC es 0, el
              fichero permanecerá abierto tras  exec,  en  caso  contrario  se
              cerrará el fichero.

       F_SETFD
              Establece  la bandera close-on-exec al valor especificado por el
              bit FD_CLOEXEC de arg.

   Banderas de situación de un fichero
       Un  descriptor   de   fichero   posee   ciertas   banderas   asociadas,
       inicializadas por open(2) y posiblemente modificadas por fcntl(2).  Las
       banderas se comparten entre copias (hechas con dup(2),  fork(2),  etc.)
       del mismo descriptor de fichero.

       Las banderas y su semántica están descritas en open(2).

       F_GETFL
              Lee las banderas de un descriptor de fichero.

       F_SETFL
              De  las  banderas  de  un  descriptor, establece la parte que se
              corresponde con las banderas de situación de un fichero al valor
              especificado  por  arg.   Los  restantes  bits  (modo de acceso,
              banderas de creación de un  fichero)  de  arg  se  ignoran.   En
              Linux,  esta  orden  sólo  puede  cambiar las banderas O_APPEND,
              O_NONBLOCK, O_ASYNC y O_DIRECT.

   Bloqueos (candados) consultivos
       F_GETLK, F_SETLK y F_SETLKW se usan para adquirir, liberar y  comprobar
       la existencia de bloqueos de registros (también conocidos como bloqueos
       de segmentos de ficheros o regiones de ficheros).  El tercer  argumento
       lock es un puntero a una estructura que tiene, al menos, los siguientes
       campos (en un orden indeterminado).

         struct flock {
             ...
             short l_type;    /* Tipo de bloqueo: F_RDLCK,
                                 F_WRLCK, F_UNLCK */
             short l_whence;  /* Cómo interpretar l_start:
                                 SEEK_SET, SEEK_CUR, SEEK_END */
             off_t l_start;   /* Dirección de inicio del bloqueo */
             off_t l_len;     /* Número de bytes a bloquear */
             pid_t l_pid;     /* PID del proceso que bloquea nuestro candado
                                 (sólo F_GETLK) */
             ...
         };

       Los campos l_whence, l_start y l_len de esta estructura especifican  el
       rango  de bytes que deseamos bloquear.  l_start es la dirección inicial
       para el bloqueo y se interpreta relativa a: el inicio del  fichero  (si
       l_whence  es  SEEK_SET);  la  posición  actual  dentro  del fichero (si
       l_whence es SEEK_CUR) o el fin del fichero (si l_whence  es  SEEK_END).
       En  los dos últimos casos, l_start puede ser un número negativo siempre
       que la dirección  inicial  final  no  quede  antes  del  principio  del
       fichero.   l_len  es un entero no negativo (aunque vea NOTAS más abajo)
       que indica el número de bytes a bloquear. Los bytes que  se  encuentren
       más  allá  del  final del fichero se pueden bloquear, pero no los bytes
       que se encuentren antes del inicio del fichero. El especificar  0  para
       l_len  tiene un significado especial: bloquear todos los bytes desde la
       posición indicada por l_whence y l_start hasta el  final  del  fichero,
       sin importar cuánto crezca el fichero.

       El  campo  l_type  se  puede  usar  para  colocar un bloqueo de lectura
       (F_RDLCK) o de escritura (F_WDLCK) sobre un fichero.   Varios  procesos
       pueden  tener  un  bloqueo  de  lectura  (bloqueo compartido) sobre una
       región de fichero, pero sólo un  proceso  puede  tener  un  bloqueo  de
       escritura (bloqueo exclusivo). Un bloqueo exclusivo excluye a todos los
       demás bloqueos, tanto compartidos como  exclusivos.  Un  único  proceso
       sólo  puede tener un tipo de bloqueo sobre una región de fichero; si se
       aplica un nuevo bloqueo a una región ya bloqueada, el bloqueo existente
       se  convierte  al  nuevo  tipo  de bloqueo.  (Tales conversiones pueden
       suponer dividir, reducir o fusionar un bloqueo existente si el rango de
       bytes  especificado por el nuevo bloqueo no coincide exactamente con el
       rango del bloqueo existente).

       F_SETLK
              Adquiere un bloqueo (cuando  l_type  es  F_RDLCK  o  F_WRLCK)  o
              libera  un  bloqueo  (cunado  l_type es F_UNLCK) sobre los bytes
              especificados por los campos l_whence, l_start y l_len de  lock.
              Si  otro  proceso  mantiene ya un bloqueo que entra en conflicto
              con el nuevo, la llamada devuelve -1 y asigna a errno el  código
              de error EACCES o EAGAIN.

       F_SETLKW
              Como  F_SETLK,  pero  si  ya hay un bloqueo sobre el fichero que
              entra en conflicto con  el  nuevo,  entonces  espera  a  que  el
              bloqueo  se  libere. Si llega y se captura una señal mientras se
              está esperando, se interrumpe la llamada  y  (tras  terminar  el
              manejador  de  señal)  regresa  inmediatamente (devolviendo -1 y
              asignado a errno el valor EINTR).

       F_GETLK
              Al entrar a esta llamada,  lock  describe  un  bloqueo  que  nos
              gustaría  colocar  en  un  fichero.  Si  el  bloqueo  se pudiera
              colocar,  fcntl()  realmente  no  lo  colocará,  pero  devolverá
              F_UNLCK  en el campo l_type de lock y dejará los otros campos de
              la estructura sin cambiar. Si uno o más  bloqueos  incompatibles
              impidieran  que  este  bloqueo  se  colocara,  entonces  fcntl()
              devolverá detalles sobre uno de estos  bloqueos  en  los  campos
              l_type,  l_whence, l_start y l_len de lock y asignará a l_pid el
              PID del proceso que posee el bloqueo.

       Para colocar un bloqueo de lectura, se debe abrir fd para lectura. Para
       colocar  un bloqueo de escritura, se debe abrir fd para escritura. Para
       colocar ambos  tipos  de  bloqueo,  abra  un  fichero  para  lectura  y
       escritura.

       Además  de  ser  eliminados  por  un F_UNLCK explícito, los bloqueos de
       registros se liberan automáticamente cuando un proceso termina o cierra
       cualquier  descriptor de fichero que haga referencia a un fichero sobre
       el que se mantienen los bloqueos.  Esto  está  mal:  significa  que  un
       proceso  puede  perder los bloqueos sobre un fichero como /etc/passwd o
       /etc/mtab cuando, por alguna razón, una función  de  biblioteca  decida
       abrir, leer y cerrar el fichero.

       Los  bloqueos  de  registros  no  los  hereda  un  hijo creado mediante
       fork(2), pero se conservan a través de execve(2).

       Debido al almacenamiento temporal  que  realiza  stdio(3),  se  debería
       evitar  el  bloqueo  de  registros con rutinas de esa biblioteca; en su
       lugar, use read(2) y write(2).

   Bloqueos obligatorios
       (No POSIX.)  Los bloqueos de registro  anteriores  pueden  ser  o  bien
       consultivos  o  bien  obligatorios, y son consultivos por omisión. Para
       usar bloqueos obligatorios, se debe habilitar dicho tipo de bloqueo  en
       el  sistema  de  ficheros que contiene el fichero a bloquear (usando la
       opción "-o mand" en mount(8)) y en el propio fichero (deshabilitando el
       permiso  de  ejecución  para el grupo y activado el bit de permiso set-
       GID).

       Los bloqueos consultivos no son de obligado  cumplimiento  y  sólo  son
       útiles  entre  procesos  que  cooperan.  Los  bloqueos obligatorios son
       respetados por todos los procesos.

   Manejo de señales
       F_GETOWN, F_SETOWN, F_GETSIG y F_SETSIG se utilizan para gestionar  las
       señales de disponibilidad de E/S:

       F_GETOWN
              Obtiene  el ID de proceso o el grupo de procesos que actualmente
              recibe las señales SIGIO y SIGURG  para  los  eventos  sobre  el
              descriptor de fichero fd.

              Los grupos de procesos se devuelven como valores negativos.

       F_SETOWN
              Establece  el  ID de proceso o el grupo de procesos que recibirá
              las señales SIGIO y SIGURG para los eventos sobre el  descriptor
              de fichero fd.

              Los   grupos   de   procesos  se  especifican  mediante  valores
              negativos.  (Se puede usar F_SETSIG para especificar  una  señal
              diferente a SIGIO).

              Si  activa  la  bandera de estado O_ASYNC sobre un descriptor de
              fichero (tanto  si  proporciona  esta  bandera  con  la  llamada
              open(2)  como  si usa la orden F_SETFL de fcntl), se enviará una
              señal SIGIO cuando sea posible la entrada o la salida sobre  ese
              descriptor de fichero.

              El proceso o el grupo de procesos que recibirá la señal se puede
              seleccionar usando la orden F_SETOWN de la función fcntl.  Si el
              descriptor  de fichero es un conector (‘‘socket’’), esto también
              seleccionará al recipiente de las señales SIGURG que se entregan
              cuando  llegan datos fuera de orden (‘‘out-of-band’’, OOB) sobre
              el enchufe. (SIGURG se envía en cualquier situación  en  la  que
              select(2)  informaría  que  el  conector  tiene  una  "condición
              excepcional"). Si el descriptor  de  fichero  corresponde  a  un
              dispositivo de terminal, entonces las señales SIGIO se envían al
              grupo de procesos en primer plano de la terminal.

       F_GETSIG
              Obtiene la señal enviada cuando  la  entrada  o  la  salida  son
              posibles.  Un valor cero significa que se envía SIGIO. Cualquier
              otro valor (incluyendo SIGIO) es la señal enviada en su lugar  y
              en  este  caso  se  dispone  de  información  adicional  para el
              manejador de señal si éste se instala con SA_SIGINFO.

       F_SETSIG
              Establece la señal enviada cuando la entrada  o  la  salida  son
              posibles.  Un  valor  cero significa enviar la señal por defecto
              SIGIO. Cualquier otro valor (incluyendo SIGIO)  es  la  señal  a
              enviar  en  su  lugar  y  en este caso se dispone de información
              adiciona para el manejador de  señal  si  éste  se  instala  con
              SA_SIGINFO.

              Usando  F_SETSIF  con  un  valor  distinto  de  cero y asignando
              SA_SIGINFO para el manejador de  señal  (vea  sigaction(2)),  se
              pasa  información extra sobre los eventos de E/S al manejador en
              la estructura siginfo_t.  Si el  campo  si_code  indica  que  la
              fuente  es SI_SIGIO, el campo si_fd proporciona el descriptor de
              fichero asociado con el evento. En caso contrario, no se indican
              qué  descriptores  de ficheros hay pendientes y, para determinar
              qué descriptores de fichero están disponibles para E/S,  debería
              usar  los  mecanismos  usuales  (select(2), poll(2), read(2) con
              O_NONBLOCK activo, etc.).

              Seleccionando una  señal  de  tiempo  real  POSIX.1b  (valor  >=
              SIGRTMIN),  se  pueden  encolar varios eventos de E/S usando los
              mismos números de señal. (El encolamiento depende de la  memoria
              disponible).  Se  dispone  de  información  extra  si  se asigna
              SA_SIGINFO al manejador de señal, como antes.

       Usando estos mecanismos, un programa puede implementar  E/S  totalmente
       asíncrona, sin usar select(2) ni poll(2) la mayor parte del tiempo.

       El  uso  de  O_ASYNC, F_GETOWN y F_SETOWN es específico de Linux y BSD.
       F_GETSIG y F_SETSIG son específicos de Linux. POSIX posee E/S asíncrona
       y  la  estructura  aio_sigevent  para  conseguir cosas similares; éstas
       también están disponibles en Linux como parte de la biblioteca de C  de
       GNU (GNU C Library, Glibc).

   Arrendamientos
       F_SETLEASE   y   F_GETLEASE   (Linux   2.4   y   posteriores)  se  usan
       (respectivamente) para establecer y obtener la configuración actual del
       arrendamiento  del  proceso invocador sobre el fichero referenciado por
       fd.  Un arrendamiento de fichero proporciona un mecanismo por medio del
       cual  al  proceso  que posee el arrendamiento (el "arrendatario") se le
       notifica (mediante el envío de  una  señal)  cuándo  otro  proceso  (el
       "competidor")  intenta  abrir  (open(2))  o  truncar  (truncate(2)) ese
       fichero.

       F_SETLEASE
              Establece o elimina un arrendamiento de fichero según qué  valor
              de los siguientes se especifique en el entero arg:

              F_RDLCK
                     Obtiene un arrendamiento de lectura. Esto hará que se nos
                     informe cuando otro proceso abra el fichero para escribir
                     en él o cuando lo trunque.

              F_WRLCK
                     Obtiene  un  arrendamiento de escritura. Esto hará que se
                     nos informe cuando otro proceso  abra  el  fichero  (para
                     leer  o  escribir) o lo trunque. Sólo se puede colocar un
                     arrendamiento de escritura en un  fichero  cuando  ningún
                     otro proceso lo tenga abierto en ese momento.

              F_UNLCK
                     Elimina nuestro arrendamiento del fichero.

       Un  proceso sólo puede tener un tipo de arrendamiento sobre un fichero.

       Los arrendamientos sólo se pueden obtener para ficheros  regulares.  Un
       proceso  normal  sólo  puede  obtener un arrendamiento sobre un fichero
       cuyo UID coincida con el UID de sistema de ficheros del proceso.

       F_GETLEASE
              Indica qué  tipo  de  arrendamiento  tenemos  sobre  el  fichero
              referenciado  por  fd devolviendo F_RDLCK, F_WRLCK o F_UNLCK, lo
              que indica, respectivamente, que el proceso invocador  posee  un
              arrendamiento   de   lectura,   de  escritura  o  que  no  posee
              arrendamiento alguno sobre el fichero.  (El tercer argumento  de
              fcntl() se omite.)

       Cuando  el  competidor  realiza  un  open()  o  truncate() que entra en
       conflicto con un  arrendamiento  establecido  mediante  F_SETLEASE,  el
       núcleo  bloquea  la  llamada  al sistema (a menos que se especifique la
       opción  O_NONBLOCK  en  open(),  en  cuyo  caso  la   llamada   regresa
       inmediatamente  con el error EWOULDBLOCK).  El núcleo entonces notifica
       al  arrendatario  enviándole  una  señal  (SIGIO  por   omisión).    El
       arrendatario  debe  responder  a  la  recepción  de esta señal haciendo
       cualquier limpieza que sea necesaria para preparar el fichero para  que
       sea  accedido  por  otro  proceso (por ejemplo, vaciando los buffers en
       caché) y  entonces  eliminar  su  arrendamiento  ejecuntado  una  orden
       F_SETLEASE que especifique en arg el valor F_UNLCK.

       Si  el  arrendatario  no  libera  el  arrendamiento antes del número de
       segundos especificado en /proc/sys/fs/lease-break-time y la llamada  al
       sistema  del  competidor  sigue  bloqueada  (es decir, el competidor no
       especificó O_NONBLOCK en su llamada open() y la llamada al  sistema  no
       ha  sido  interrumpida  por  un manejador de señal), entonces el núcleo
       pone fin al arrendamiento del arrendatario por la fuerza.

       Una vez que  se  ha  eliminado  voluntariamente  o  por  la  fuerza  el
       arrendamiento,  y  suponiendo  que  el competidor no ha desbloqueado su
       llamada al sistema, el núcleo permite continuar a la llamada al sistema
       del competidor.

       La señal por omisión que se usa para informar al arrendatario es SIGIO,
       pero se puede cambiar usando la orden F_SETSIG  de  fcntl  ().   Si  se
       ejecuta  una  orden  F_SETSIG  (incluso una que especifique SIGIO) y el
       manejador  de  señal  se  establece  usando  SA_SIGINFO,  el  manejador
       recibirá  una estructura siginfo_t como su segundo argumento y el campo
       si_fd de este argumento contendrá el descriptor del  fichero  arrendado
       que  ha  sido  accedido por otro proceso. (Esto es útil si el invocador
       tiene arrendamientos para varios ficheros).

   Notificación de cambios en ficheros y directorios
       F_NOTIFY
              (Linux 2.4 y posteriores) Produce una notificación cuando cambia
              el  directorio  referenciado por fd o cualquiera de los ficheros
              que contiene. Los eventos a notificar se indican en arg, que  es
              una  máscara  de  bits que se especifica mediante un O-lógico de
              cero o más de los siguientes bits:

              Bit         Descripción (evento en el directorio)
              ---------------------------------------------------------------------
              DN_ACCESS   Se ha accedido a un fichero (read, pread, readv)
              DN_MODIFY   Se ha modificado un fichero (write, pwrite,
                          writev, truncate, ftruncate)
              DN_CREATE   Se ha creado un fichero (open, creat, mknod,
                          mkdir, link, symlink, rename)
              DN_DELETE   Se ha borrando un fichero (unlink, rename a
                          otro directorio, rmdir)
              DN_RENAME   Se ha cambiado el nombre de un fichero de este
                          directorio (rename)
              DN_ATTRIB   Se han cambiado los atributos de un fichero
                          (chown, chmod, utime[s])

              (Para obtener  estas  definiciones,  se  debe  define  la  macro
              _GNU_SOURCE antes de incluir <fcntl.h>.)

              Las  notificaciones  de  directorio  normalmente  se reciben una
              única vez (son de tipo ‘‘one-shot’’) y la aplicación debe volver
              a  hacer  el  registro  para recibir notificaciones adicionales.
              Otra posibilidad es incluir DN_MULTISHOT en arg, en cuyo caso la
              notificación  se  producirá hasta que se elimine explícitamente.
              Una  serie  de  llamadas   que   especifican   DN_MULTISHOT   es
              acumulativa,  con  los eventos en arg añadiéndose al conjunto ya
              monitorizado.  Para desactivar  la  notificación  de  todos  los
              eventos, haga una llamada F_NOTIFY especificando 0 en arg.

              La  notificación  se  produce mediante el envío de una señal. La
              señal por omisión es SIGIO, pero  se  puede  cambiar  usando  la
              orden  F_SETSIG de fcntl().  En el segundo caso, el manejador de
              señal recibe una estructura siginfo_t como su segundo  argumento
              (si  el  manejador  se  estableció usando SA_SIGINFO) y el campo
              si_fd de esta estructura contiene el descriptor de  fichero  que
              produjo    la    notificación   (útil   cuando   se   establecen
              notificaciones en varios directorios).

              Especialmente cuando se usa DN_MULTISHOT, se  debería  usar  una
              señal  POSIX.1b  de tiempo real para notificación, de tal manera
              que se pueden encolar multiples notificaciones.

VALOR DEVUELTO

       Para una llamada con éxito, el valor devuelto depende de la operación:

       F_DUPFD  El nuevo descriptor.

       F_GETFD  Valor de la bandera.

       F_GETFL  Valor de las banderas.

       F_GETOWN Valor del propietario del descriptor.

       F_GETSIG Valor de la señal enviada cuando la lectura o la escritura son
                posibles  o cero para el comportamiento tradicional con SIGIO.

       Para cualquier otra orden
                Cero.

       En caso de error el valor devuelto es -1 y se asigna a errno  un  valor
       apropiado.

ERRORES

       EACCESS o EAGAIN
              Se  ha  prohibido  la operación debido a bloqueos mantenidos por
              otros procesos.  O  se  ha  prohibido  la  operación  porque  el
              fichero  ha  sido  proyectado  (‘‘mapped’’)  en memoria por otro
              proceso.

       EDEADLK
              Se ha detectado que la orden F_SETLKW especificada provocaría un
              interbloqueo.

       EFAULT lock está fuera de su espacio de direcciones accesible.

       EBADF  fd no es un descriptor de fichero abierto o la orden era F_SETLK
              o F_SETLKW y el modo de apertura del descriptor  de  fichero  no
              coincide con el tipo de bloqueo solicitado.

       EINTR  Para  F_SETLKW,  la  orden  ha  sido interrumpida por una señal.
              Para F_GETLK y F_SETLK, la orden ha sido  interrumpida  por  una
              señal  antes  de  que el bloqueo se haya comprobado o adquirido.
              Esto ocurre con más probabilidad  al  poner  un  bloqueo  en  un
              fichero  remoto (por ejemplo, un bloqueo sobre NFS) pero algunas
              veces puede ocurrir localmente.

       EINVAL Para F_DUPFD, arg es  negativo  o  mayor  que  el  valor  máximo
              permitido.   Para  F_SETSIG,  arg  no  es  un  número  de  señal
              permitido.

       EMFILE Para F_DUPFD, el proceso ya  ha  llegado  al  número  máximo  de
              descriptores de ficheros abiertos.

       ENOLCK Demasiados  bloqueos de segmentos abiertos, la tabla de bloqueos
              está llena o ha fallado un protocolo  de  bloqueos  remoto  (por
              ejemplo, un bloqueo sobre NFS).

       EPERM  Se  ha intentado quitar la bandera O_APPEND sobre un fichero que
              tiene activo el atributo de ‘‘sólo añadir’’ (append-only).

OBSERVACIONES

       Los errores devueltos por dup2 son  distintos  de  aquéllos  dados  por
       F_DUPFD.

       Desde  el  núcleo  2.0,  no  hay interacción entre los tipos de bloqueo
       colocados por flock(2) y fcntl(2).

       POSIX 1003.1-2001 permite que l_len sea  negativo.  (Y  si  lo  es,  el
       intervalo  descrito  por el bloqueo cubre los bytes desde l_start+l_len
       hasta l_start-1 inclusive.)  Sin embargo, para los núcleos actuales, la
       llamada al sistema de Linux devuelve EINVAL en esta situación.

       Otros  sistemas  tienen  más  campos en struct flock como, por ejemplo,
       l_sysid.  Evidentemente, l_pid sólo no va a ser muy útil si el  proceso
       que posee el bloqueo puede residir en una máquina diferente.

CONFORME A

       SVID,  AT&T,  POSIX,  X/OPEN,  BSD  4.3.  Sólo las operaciones F_DUPFD,
       F_GETFD, F_SETFD, F_GETFL, F_SETFL,  F_GETLK,  F_SETLK  y  F_SETLKW  se
       especifican  en POSIX.1. F_GETOWN y F_SETOWN son BSD-ismos no aceptados
       en SVr4; F_GETSIG y  F_SETSIG  son  específicos  de  Linux.   F_NOTIFY,
       F_GETLEASE  y  F_SETLEASE  son  específicos de Linux.  (Defina la macro
       _GNU_SOURCE   antes   de   incluir   <fcntl.h>   para   obtener   estas
       definiciones.)   Las banderas legales para F_GETFL/F_SETFL son aquéllas
       que acepta open(2) y varían entre estos sistemas; O_APPEND, O_NONBLOCK,
       O_RDONLY  y  O_RDWR  son  las  que se mencionan en POSIX.1. SVr4 admite
       algunas otras opciones y banderas no documentadas aquí.

       SVr4 documenta las condiciones de  error  adicionales  EIO,  ENOLINK  y
       EOVERFLOW.

VÉASE TAMBIÉN

       dup2(2), flock(2), lockf(3), open(2), socket(2)

       Vea    también    locks.txt,    mandatory.txt    y    dnotify.txt    en
       /usr/src/linux/Documentation.