'\" t
.\" Hey Emacs! This file is -*- nroff -*- source.
.\"
.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
.\" Parts Copyright (c) 1995 Nicolai Langfeldt (janl@ifi.uio.no), 1/1/95
.\"
.\" 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 by Michael Haardt <michael@moria.de>
.\" Modified Sat Jul 24 10:54:27 1993 by Rik Faith <faith@cs.unc.edu>
.\" Modified Thu May 18 11:00:31 1995 by Rik Faith <faith@cs.unc.edu>
.\"          to add comments suggested by Todd Larason <jtl@molehill.org>
.\" Modified Fri Jan 31 17:43:02 1997 by Eric S. Raymond <esr@thyrsus.com>
.\" Modified Thu Jan 9 10:20:31 1995 by Martin Schulze (joey@infodrom.north.de)
.\"          to add more error codes suggested by Richard Kettlewell (richard@greenend.org.uk)
.\" Modified Wed May 13 18:46:44 1998 by Michael Haardt <michael@cantor.informatik.rwth-aachen.de>
.\" Modified 990706 by aeb; much of the info under `Other Systems' was
.\"          taken from a net post by Albert Cahalan.
.\" Modified 000107 by aeb: added <sys/types.h> include.
.\" Translated 6 Feb 1998 by Vicente Pastor Gómez <VPASTORG@santandersupernet.com , vicpastor@hotmail.com>
.\" Translation revised Wed Aug 19 1998 by Juan Piernas <piernas@ditec.um.es>
.\" Translation revised Wed Dec 30 1998 by Juan Piernas <piernas@ditec.um.es>
.\" Translation revised Tue Apr  6 1999 by Juan Piernas <piernas@ditec.um.es>
.\" Translation revised Sun Apr 16 2000 by Juan Piernas <piernas@ditec.um.es>
.\" Revisado por Miguel Pérez Ibars <mpi79470@alu.um.es> el 1-diciembre-2004
.\"
.TH STAT 2 "13 mayo 1998" "Linux" "Llamadas al Sistema"
.SH NOMBRE
stat, fstat, lstat \- obtiene el estado de un fichero
.SH SINOPSIS
.B #include <sys/types.h>
.br
.B #include <sys/stat.h>
.br
.B #include <unistd.h>
.sp
.BI "int stat(const char *" file_name ", struct stat *" buf );
.br
.BI "int fstat(int " filedes ", struct stat *" buf );
.br
.BI "int lstat(const char *" file_name ", struct stat *" buf );
.SH DESCRIPCIÓN
.PP
Estas funciones devuelven información del fichero especificado. No
se necesitan derechos de acceso al fichero para conseguir la información
pero sí se necesitan derechos de búsqueda para todos los directorios
del camino al fichero.
.PP
.B stat
examina el fichero al que apunta
.I file_name
y llena
.IR buf .

.B lstat
es idéntico a
.BR stat ,
salvo en caso de que se trate de un enlace simbólico, en cuyo caso se examina el enlace mismo,
no el fichero al que hace referencia.

.B fstat
es idéntico a 
.BR stat, 
pero sólo el fichero abierto apuntado por
.I filedes
(tal y como lo devuelve
.BR open (2))
es examinado en lugar de
.IR file_name .

.PP
Todos devuelven una estructura
.IR stat ,
que contien los siguientes campos:
.PP
.RS
.nf
struct stat {
    dev_t         st_dev;      /* dispositivo */
    ino_t         st_ino;      /* inodo */
    mode_t        st_mode;     /* protección */
    nlink_t       st_nlink;    /* número de enlaces físicos */
    uid_t         st_uid;      /* ID del usuario propietario */
    gid_t         st_gid;      /* ID del grupo propietario */
    dev_t         st_rdev;     /* tipo dispositivo (si es
                                  dispositivo inodo) */
    off_t         st_size;     /* tamaño total, en bytes */
    blksize_t     st_blksize;  /* tamaño de bloque para el
                                  sistema de ficheros de E/S */
    blkcnt_t      st_blocks;   /* número de bloques asignados */
    time_t        st_atime;    /* hora último acceso */
    time_t        st_mtime;    /* hora última modificación */
    time_t        st_ctime;    /* hora último cambio */
};
.fi
.RE
.PP
El valor
.I st_size
da el tamaño del fichero (si es un fichero regular o un enlace simbólico)
en bytes. El tamaño de un enlace simbólico es la longitud del nombre de ruta
que contiene, sin contar el caracter NUL final.

El valor
.I st_blocks
da el tamaño del fichero en bloques de 512 bytes. 
(Éste puede ser menor que
.IR st_size /512
p.e. cuando el fichero tenga huecos.)
El valor
.IR st_blksize
da el tamaño de bloque "preferido" para operaciones de E/S eficientes sobre
el sistema de ficheros.  (Escribir en un fichero en porciones más pequeñas
puede producir una secuencia leer-modificar-reescribir ineficiente).
.PP
No todos los sistemas de ficheros en Linux implementan todos los campos de hora. 
Algunos tipos de sistemas de ficheros permiten el montaje de tal manera
que los accesos al fichero no provocan una actualización del campo
.I st_atime
(Vea `noatime' en
.BR mount (8).)

El campo
.I st_atime
es modificado por accesos al fichero, p.e. por
.BR execve (2),
.BR mknod (2),
.BR pipe (2),
.BR utime (2)
y
.BR read (2)
(de más de cero bytes). Otras rutinas, como
.BR mmap (2),
pueden o no actualizar
.IR st_atime .

El campo
.I st_mtime
es modificado por cambios en el fichero, p.e. por
.BR mknod (2),
.BR truncate (2),
.BR utime (2)
y
.BR write (2)
(de más de cero bytes).
Además, el campo
.I st_mtime
de un directorio es modificado por la creación o borrado de ficheros
en dicho directorio.
El campo
.I st_mtime
.I no
es modificado por cambios en el propietario, grupo, contador de enlaces duros, o modo.

El campo
.I st_ctime
es modificado por la escritura o por cambiar información del inodo
(es decir, propietario, grupo, contador de enlaces, modo, etc.).
.PP
Se definen las siguientes macros POSIX para comprobar el tipo de fichero:
.RS
.TP 1.2i
S_ISLNK(m)
es un enlace simbólico?
.TP
S_ISREG(m)
un fichero regular?
.TP
S_ISDIR(m)
un directorio?
.TP
S_ISCHR(m)
un dispositivo de caracteres?
.TP
S_ISBLK(m)
un dispositivo de bloques?
.TP
S_ISFIFO(m)
una tubería nombrada (fifo)?
.TP
S_ISLNK(m)
un enlace simbólico? (No presente en POSIX.1-1996.)
.TP
S_ISSOCK(m)
un conector (socket)? (No presente en POSIX.1-1996.)
.RE
.PP
Se definen las siguientes banderas para el campo
.IR st_mode :
.P
.TS
l l l.
S_IFMT	0017000	máscara de bits para los campos de bit del tipo
		de fichero (no POSIX)
S_IFSOCK	0140000	conector (no POSIX)
S_IFLNK	0120000	enlace simbólico (no POSIX)
S_IFREG	0100000	fichero regular (no POSIX)
S_IFBLK	0060000	dispositivo de bloques (no POSIX)
S_IFDIR	0040000	directorio (no POSIX)
S_IFCHR	0020000	dispositivo de caracteres (no POSIX)
S_IFIFO	0010000	fifo o tubería nombrada (no POSIX)
S_ISUID	0004000	poner bit UID
S_ISGID	0002000	poner bit GID
S_ISVTX	0001000	sticky bit (no POSIX)
S_IRWXU	00700	usuario (propietario del fichero) tiene permisos
		de lectura, escritura y ejecución
S_IRUSR	00400	usuario tiene premiso de lectura (igual que
		S_IREAD, que no es POSIX)
S_IWUSR	00200	usuario tiene premiso de escritura (igual que
		S_IWRITE, que no es POSIX)
S_IXUSR	00100	usuario tiene premiso de ejecución (igual que
		S_IEXEC, que no es POSIX)
S_IRWXG	00070	grupo tiene permisos de lectura, escritura y
		ejecución
S_IRGRP	00040	grupo tiene permiso de lectura
S_IWGRP	00020	grupo tiene permiso de escritura
S_IXGRP	00010	grupo tiene permiso de ejecución
S_IRWXO	00007	otros tienen permisos de lectura, escritura y
		ejecución
S_IROTH	00004	otros tienen permiso de lectura
S_IWOTH	00002	otros tienen permiso de escritura
S_IXOTH	00001	otros tienen permiso de ejecución
.TE
.P
El bit SETGID (S_ISGID) tiene varios usos especiales:
para un directorio, indica que se va a usar la semántica BSD para el
directorio: los ficheros creados allí heredarán su GID del directorio, no
del GID efectivo del proceso que crea cada fichero, y los directorios
creados allí también tendrán el bit S_ISGID activo.
Para un fichero que no tiene el bit de ejecución del grupo (S_IXGRP) activo,
indica bloqueo obligatorio de ficheros/registros.
.P
El bit `sticky' (S_ISVTX) en un directorio significa que un fichero de ese
directorio sólo puede ser renombrado o borrado por el propietario del
fichero, por el propietario del directorio y por el superusuario.
.SH "VALOR DEVUELTO"
Se devuelve cero si hubo éxito. Si hubo error, se devuelve \-1, y
.I errno
es actualizado apropiadamente.
.SH ERRORES
.TP
.B EBADF
.I filedes
incorrecto.
.TP
.B ENOENT
No existe un componente del camino
.I file_name
o el camino es una cadena vacía.
.TP
.B ENOTDIR
Un componente del camino no es un directorio.
.TP
.B ELOOP
Se han encontrado demasiados enlaces simbólicos al recorrer el camino.
.TP
.B EFAULT
Dirección errónea.
.TP
.B EACCES
Permiso denegado.
.TP
.B ENOMEM
Fuera de memoria (es decir, memoria del núcleo).
.TP
.B ENAMETOOLONG
Nombre de fichero demasiado largo.
.SH "CONFORME A"
Las llamadas
.B stat
y
.B fstat
conforman con
SVr4, SVID, POSIX, X/OPEN y BSD 4.3. La llamada
.B lstat
conforma con 4.3BSD y SVr4.
SVr4 documenta condiciones de error adicionales de
.BR fstat :
EINTR, ENOLINK y EOVERFLOW.  SVr4
documenta condiciones de error adicionales de
.B stat
y
.BR lstat :
EACCES, EINTR, EMULTIHOP, ENOLINK y EOVERFLOW.
El uso de los campos
.I st_blocks
y
.I st_blksize
puede ser poco portable. (Fueron introducidos en BSD. No están especificados
por POSIX. La interpretación difiere entre sistemas y posiblemente en un
mismo sistema cuando están involucrados montajes NFS).
.LP
POSIX no describe los bits S_IFMT, S_IFSOCK, S_IFLNK, S_IFREG, S_IFBLK,
S_IFDIR, S_IFCHR, S_IFIFO y S_ISVTX, pero en su lugar demanda el uso de las
macros S_ISDIR(), etc. Las macros S_ISLNK y S_ISSOCK no están en
POSIX.1-1996, pero ambas formarán parte del próximo estándar POSIX;
la primera es de SVID 4v2, la última de SUSv2.
.LP
Unix V7 (y sistemas posteriores) tenían S_IREAD, S_IWRITE, S_IEXEC, donde POSIX
prescribe los sinónimos S_IRUSR, S_IWUSR, S_IXUSR.
.SH "OTROS SISTEMAS"
Valores que han estado (o están) en uso en varios sistemas:
.P
.TS
l l l l l.
hex	nombre	ls	octal	descripción
f000	S_IFMT		170000	Máscara para el tipo de fichero
0000			000000	SCO: nodo-i fuera de servicio
 				BSD: tipo desconocido
 				SVID-v2 y XPG2: tienen tanto 0 como
 				0100000 para ficheros ordinarios
1000	S_IFIFO	p|	010000	Fifo (tubería con nombre)
2000	S_IFCHR	c	020000	V7: fichero especial de caracteres
3000	S_IFMPC		030000	V7: fichero especial de caracteres
 				multiplexados
4000	S_IFDIR	d/	040000	V7: directorio
5000	S_IFNAM		050000	XENIX: fichero especial con nombre
 				con dos subtipos, distinguidos
 				por los valores st_rdev 1, 2:
0001	S_INSEM	s	000001	XENIX: subtipo semáforo de IFNAM
0002	S_INSHD	m	000002	XENIX: subtipo datos compartidos
				de IFNAM
6000	S_IFBLK	b	060000	V7: fichero especial de bloques
7000	S_IFMPB		070000	V7: fichero especial de bloques
 				multiplexados
8000	S_IFREG	-	100000	V7: fichero regular
9000	S_IFCMP		110000	VxFS: fichero comprimido
9000	S_IFNWK	n	110000	HP-UX: fichero especial de red
a000	S_IFLNK	l@	120000	BSD: enlace simbólico
b000	S_IFSHAD		130000	Solaris: nodo-i sombra para ACL
 				(no visto por el espacio de usuario) 
c000	S_IFSOCK	s=	140000	BSD: conector (también "S_IFSOC" en VxFS)
d000	S_IFDOOR	D>	150000	Solaris: puerta
e000	S_IFWHT	w%	160000	BSD: `whiteout'(no usado para nodos-i)
0200	S_ISVTX		001000	V7: `sticky bit': salvar el código
	 			intercambiado incluso después de usarse
 				SVID-v2: reservado
	 			SunOS: En ficheros no directorios: no
				colocar en cache este fichero
 				SVID-v4.2: En directorios: opción de
				elminación restringida
0400	S_ISGID		002000	V7: SETGID al ejecuctar
	 			Para directorios: usar semántica BSD
 				para propagación del GID
0400	S_ENFMT		002000	SysV: Aplicar el bloqueo del fichero
 				(compartido con S_ISGID)
0800	S_ISUID		004000	V7: SETUID al ejecutar
0800	S_CDF		004000	HP-UX: el directorio es un fichero
 				dependiente del contexto
.TE

Una orden `sticky' apareción en AT&T UNIX Version 32V.

.SH "VÉASE TAMBIÉN"
.BR chmod (2),
.BR chown (2),
.BR readlink (2),
.BR utime (2)