Ubuntu Manpage: fcntl - manipula el descriptor de fichero

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.