.\" Hey Emacs! This file is -*- nroff -*- source.
.\"
.\" This manpage is Copyright (C) 1992 Drew Eckhardt;
.\"                               1993 Michael Haardt, Ian Jackson;
.\"                               1998 Jamie Lokier.
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one
.\" 
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\" 
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\"
.\" Modified Sat Jul 24 13:39:26 1993 by Rik Faith (faith@cs.unc.edu)
.\" Modified Tue Sep 26 21:47:21 1995 by Andries Brouwer <aeb@cwi.nl>
.\" and again on 960413 and 989804 and 981223.
.\"
.\" Translated 22 Dec 1995 Miguel A. Sepulveda (miguel@typhoon.harvard.edu)
.\" Modified 1 Jul 1996 Miguel A. Sepulveda (angel@vivaldi.princeton.edu)
.\" Translation fixed and revised on Mon Apr 27 18:22:37 CEST 1998 by
.\" Gerardo Aburruzaga Garca <gerardo.aburruzaga@uca.es>
.\" Translation revised Tue Aug 18 1998 by Juan Piernas <piernas@ditec.um.es>
.\" Translation revised Fri Oct 2 1998 by Juan Piernas <piernas@ditec.um.es>
.\" Modified Fri Dec 11 17:57:27 1998 by Jamie Lokier <jamie@imbolc.ucc.ie>
.\" Translation revised Tue Apr 6 1999 by Juan Piernas <piernas@ditec.um.es>
.\" Translation revised Fri Jun 25 1999 by Juan Piernas <piernas@ditec.um.es>
.\"
.TH FCNTL 2 "23 Diciembre 1998" Linux "Manual del Programador de Linux"
.SH NOMBRE
fcntl \- manipula el descriptor de fichero
.SH SINOPSIS
.nf
.B #include <unistd.h>
.B #include <fcntl.h>
.sp
.BI "int fcntl(int " fd ", int " cmd );
.BI "int fcntl(int " fd ", int " cmd ", long " arg );
.BI "int fcntl(int " fd ", int " cmd ", struct flock * " lock );
.fi
.SH DESCRIPCIN
.B fcntl
realiza una de las diversas y variadas operaciones sobre
.IR fd .
La operacin en cuestin se determina mediante
.IR cmd :
.TP 0.9i
.B F_DUPFD
Hace que 
.I arg
sea una copia de
.IR fd ,
cerrando 
.I fd
si es necesario.
.sp
El mismo resultado se puede obtener fcilmente usando        
.BR dup2 .
.sp
Los descriptores antiguo y nuevo pueden usarse indistintamente. Ambos
comparten candados (locks), indicadores de posicin de ficheros y
banderas (flags); por ejemplo, 
si la posicin del fichero se modifica usando
.B lseek
en uno de los descriptores, la posicin del otro resulta modificada   
simultneamente.
.sp
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, singificando que se cerrar en ejecucin.
.sp
En caso de xito, se devuelve el nuevo descriptor.
.TP
.B F_GETFD
Lee la bandera close-on-exec. Si el bit
.B FD_CLOEXEC
es 0, el fichero permanecer abierto durante
.BR exec ,
en caso contrario se cerrar el fichero.
.TP
.B F_SETFD
Asigna el valor de la bandera close-on-exec al valor especificado por el bit
.B FD_CLOEXEC
de
.IR arg .
.TP
.B F_GETFL
Lee las banderas del descriptor (todas las banderas, segn 
hayan sido asignadas por
.BR open (2),
sern devueltas).
.TP
.B F_SETFL
Asigna las banderas del descriptor al valor asignado por
.IR arg .
Slo
.BR O_APPEND ", " O_NONBLOCK " y " O_ASYNC
pueden asignarse; las otras banderas no se ven afectadas.
.sp
Las banderas se comparten entre copias (hechas con
.BR dup "(2), " fork (2),
etc.) del mismo descriptor de fichero.
.sp
Las banderas y su semntica estn descritas en 
.BR open (2).
.P
.BR F_GETLK ", " F_SETLK " y " F_SETLKW
se utilizan para gestionar candados de ficheros
discrecionales (discretionary file locks).
El tercer argumento
.I lock
es un puntero a una struct flock
(que puede ser sobrescrita por esta llamada).
.TP
.B F_GETLK
Devuelve la estructura flock que nos impide obtener el candado, o
establece el campo
.B l_type
del candado a
.B F_UNLCK
si no hay obstruccin.
.TP
.B F_SETLK
El candado est cerrado (cuando
.B l_type
es
.B F_RDLCK
o 
.BR F_WRLCK )
o abierto (cuando es
.BR F_UNLCK ).
Si el candado est cogido por alguien ms, esta llamada devuelve \-1 y
pone en
.I errno 
el cdigo de error
.B EACCES
o
.BR EAGAIN .
.TP
.B F_SETLKW
Como
.BR F_SETLK ,
pero en vez de devolver un error esperamos que el candado se abra.
Si se recibe una seal a capturar mientras
.B fcntl
est esperando, se interrumpe y (despus de que el manejador de la seal
haya terminado) regresa inmediatamente (devolviendo \-1 y
asignado a
.I errno
el valor
.BR EINTR ).
.P
.BR F_GETOWN ", " F_SETOWN ", " F_GETSIG " y " F_SETSIG
se utilizan para gestionar las seales de disponibilidad de E/S:
.TP
.B F_GETOWN
Obtiene el ID de proceso o el grupo de procesos que actualmente recibe las
seales SIGIO y SIGURG para los eventos sobre el descriptor de fichero
.IR fd .
.sp
Los grupos de procesos se devuelven como valores negativos.
.TP
.B F_SETOWN
Establece el ID de proceso o el grupo de procesos que recibir las seales
SIGIO y SIGURG para los eventos sobre el descriptor de fichero
.IR fd .
.sp
Los grupos de procesos se especifican mediante valores negativos.
(Se puede usar
.B F_SETSIG
para especificar una seal diferente a SIGIO).

.\" De glibc.info:
Si activa la bandera de estado
.B O_ASYNC
sobre un descriptor de fichero (tanto si proporciona esta bandera con la
llamada
.IR open (2)
como si usa la orden
.B F_SETFL
de
.BR fcntl ),
se enviar una seal SIGIO cuando sea posible la entrada o la salida sobre
ese descriptor de fichero.
.sp
El proceso o el grupo de procesos que recibir la
seal se puede seleccionar usando la orden
.B F_SETOWN
de la funcin
.BR fcntl .
Si el descriptor de fichero es un enchufe (socket), esto tambin
seleccionar al recipiente de las seales SIGURG que se entregan cuando
llegan datos fuera de orden (out-of-band, OOB) sobre el enchufe. (SIGURG se
enva en cualquier situacin en la que
.BR select (2)
informara que el enchufe tiene una "condicin excepcional"). Si el
descriptor de fichero corresponde a un dispositivo de terminal, entonces las
seales SIGIO se envan al grupo de procesos en primer plano de la terminal.
.TP
.B F_GETSIG
Obtiene la seal enviada cuando la entrada o la salida son posibles. Un
valor cero significa que se enva SIGIO. Cualquier otro valor (incluyendo
SIGIO) es la seal enviada en su lugar y en este caso se dispone de
informacin adicional para el manejador de seal si se instala con
SA_SIGINFO.
.TP
.B F_SETSIG
Establece la seal enviada cuando la entrada o la salida son posibles. Un
valor cero significa enviar la seal por defecto SIGIO. Cualquier otro valor
(incluyendo SIGIO) es la seal a enviar en su lugar y en este caso se
dispone de informacin adiciona para el manejador de seal si se instala con
SA_SIGINFO.
.sp
Usando F_SETSIF con un valor distinto de cero y asignando SA_SIGINFO para el
manejador de seal (vea
.BR sigaction (2)),
se pasa informacin extra sobre los eventos de E/S al manejador en la
estructura
.IR siginfo_t .
Si el campo
.I si_code
indica que la fuente is SI_SIGIO, el campo
.I 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 estn disponibles para E/S, debera
usar los mecanismos usuales
.RB ( select (2),
.BR poll (2),
.BR read (2)
con
.B O_NONBLOCK
activo, etc.).
.sp
Seleccionando una seal de tiempo real POSIX.1b (valor >= SIGRTMIN), se
pueden encolar varios eventos de E/S usando los mismos nmeros de seal. (El
encolamiento depende de la memoria disponible). Se dispone de informacin
extra si se asigna SA_SIGINFO al manejador de seal, como antes.
.PP
Usando estos mecanismos, un programa puede implementar E/S totalmente
asncrona, sin usar
.BR select (2)
ni
.BR poll (2)
la mayor parte del tiempo.
.PP
El uso de 
.BR O_ASYNC ,
.BR F_GETOWN
y
.B F_SETOWN
es especfico de Linux y BSD.
.B F_GETSIG
y
.B F_SETSIG
son especficos de Linux. POSIX posee E/S asncrona y la estructura
.I aio_sigevent
para conseguir cosas similares; estas tambin estn disponibles en Linux
como parte de la biblioteca de C de GNU (GNU C Library, Glibc).
.SH "VALOR DEVUELTO"
Para una llamada con xito, el valor devuelto depende de la operacin:
.TP 0.9i
.B F_DUPFD
El nuevo descriptor.
.TP
.B F_GETFD
Valor de la bandera.
.TP
.B F_GETFL
Valor de las banderas.
.TP
.B F_GETOWN
Valor del propietario del descriptor.
.TP
.B F_GETSIG
Valor de la seal enviada cuando la lectura o la escritura son posibles o
cero para el comportamiento tradicional con SIGIO.
.TP
.B Para cualquier otra orden
Cero.
.PP
En caso de error el valor devuelto es \-1, y 
se pone un valor apropiado en
.IR errno .
.SH ERRORES
.TP 0.9i
.B EACCES
La operacin est prohibida por candados mantenidos por otros
procesos.
.TP
.B EAGAIN
La operacin est prohibida porque el fichero ha sido asociado a
memoria por otro proceso.
.TP
.B EDEADLK
Se ha detectado que el comando
.B F_SETLKW
especificado provocara un
interbloqueo. 
.TP
.B EFAULT
.I lock
est fuera de su espacio de direcciones accesible.
.TP
.B EBADF
.I fd
no es un descriptor de fichero abierto.
.TP
.B EINTR
El comando
.B F_SETLKW
ha sido interrumpido por una seal.
Para
.BR F_GETLK " y " F_SETLK ,
la orden fue interrumpida por una seal antes de que el candado fuera
comprobado o adquirido. Es ms probable al poner un candado a un fichero
remoto (por ejemplo, un candado sobre NFS) pero algunas veces puede ocurrir
localmente.
.TP
.B EINVAL
Para
.BR F_DUPFD ,
.I arg
es negativo o mayor que el valor mximo permitido. Para
.BR F_SETSIG ,
.I arg
no es un nmero de seal permitido.
.TP
.B EMFILE
Para
.BR F_DUPFD ,
el proceso ya ha llegado al nmero mximo de descriptores de ficheros abiertos. 
.TP
.B ENOLCK
Demasiados candados de segmento abiertos, la tabla de candados est llena o
ha fallado un protocolo de candados remoto (por ejemplo, un candado sobre
NFS).
.TP
.B EPERM
Se ha intentado limpiar la bandera
.B O_APPEND
sobre un fichero que tiene activo el atributo de `slo aadir'
(append-only).
.SH NOTAS
Los errores devueltos por
.B dup2
son distintos de aqullos dados por 
.BR F_DUPFD .
.SH "CONFORME A"
SVID, AT&T, POSIX, X/OPEN, BSD 4.3. Slo 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 especficos de Linux.
Las banderas legales para F_GETFL/F_SETFL son aqullas que acepta
.BR open (2)
y varan 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.
.PP
SVr4 documenta las condiciones de error adicionales EIO, ENOLINK y EOVERFLOW.
.SH "VASE TAMBIN"
.BR open (2),
.BR socket (2),
.BR dup2 (2),
.BR flock (2).