# `stat` — Interpretación de los resultados de `stat()`

Código fuente: Lib/stat.py

El módulo `stat` define constantes y funciones para interpretar los resultados de `os.stat()`, `os.fstat()` y `os.lstat()` (si existen). Para obtener los detalles completos sobre las llamadas a `stat()`, `fstat()` y `lstat()`, consulta la documentación de tu sistema.

Distinto en la versión 3.4: El módulo stat se apoya en una implementación en C.

El módulo `stat` define las siguientes funciones para comprobar tipos de archivo específicos:

`stat.``S_ISDIR`(mode)

  Retorna un valor no nulo si el modo es de un directorio.

`stat.``S_ISCHR`(mode)

  Retorna un valor no nulo si el modo es de un archivo de un dispositivo especial de caracteres.

`stat.``S_ISBLK`(mode)

  Retorna un valor no nulo si el modo es de un archivo de un dispositivo especial de bloques.

`stat.``S_ISREG`(mode)

  Retorna un valor no nulo si el modo es de un archivo normal.

`stat.``S_ISFIFO`(mode)

  Retorna un valor no nulo si el modo es de un FIFO (tubería con nombre).

`stat.``S_ISLNK`(mode)

  Retorna un valor no nulo si el modo es de un enlace simbólico.

`stat.``S_ISSOCK`(mode)

  Retorna un valor no nulo si el modo es de un socket.

`stat.``S_ISDOOR`(mode)

  Retorna un valor no nulo si el modo es de un door.

  Nuevo en la versión 3.4.

`stat.``S_ISPORT`(mode)

  Retorna un valor no nulo si el modo es de un event port.

  Nuevo en la versión 3.4.

`stat.``S_ISWHT`(mode)

  Retorna un valor no nulo si el modo es de un whiteout.

  Nuevo en la versión 3.4.

Se definen dos funciones adicionales para una manipulación más general del modo del archivo:

`stat.``S_IMODE`(mode)

  Retorna la porción del modo del archivo que puede ser establecida por `os.chmod()`— esto es, los bits de los permisos del archivo más los bits sticky bit, set-group-id y set-user-id (en los sistemas que lo soporten).

`stat.``S_IFMT`(mode)

  Retorna la porción del modo del archivo que describe el tipo de archivo (usado por las funciones `S_IS*()` de más arriba).

Normalmente se usarían las funciones `os.path.is*()` para comprobar el tipo de un archivo; estas funciones de aquí son útiles cuando se hacen múltiples comprobaciones sobre el mismo archivo y se desea evitar la sobrecarga causada por la llamada al sistema `stat()` en cada comprobación. También son útiles cuando se comprueba información de un archivo que no es gestionada por `os.path`, como buscar dispositivos de bloques o caracteres.

Ejemplo:

    import os, sys
    from stat import *

    def walktree(top, callback):
        '''recursively descend the directory tree rooted at top,
           calling the callback function for each regular file'''

        for f in os.listdir(top):
            pathname = os.path.join(top, f)
            mode = os.stat(pathname).st_mode
            if S_ISDIR(mode):
                # It's a directory, recurse into it
                walktree(pathname, callback)
            elif S_ISREG(mode):
                # It's a file, call the callback function
                callback(pathname)
            else:
                # Unknown file type, print a message
                print('Skipping %s' % pathname)

    def visitfile(file):
        print('visiting', file)

    if __name__ == '__main__':
        walktree(sys.argv[1], visitfile)

Se proporciona una función de utilidad adicional para convertir el modo del archivo en una cadena de caracteres legible por humanos:

`stat.``filemode`(mode)

  Convierte el modo del archivo a una cadena de caracteres de la forma “-rwxrwxrwx”.

  Nuevo en la versión 3.3.

  Distinto en la versión 3.4: La función soporta `S_IFDOOR`, `S_IFPORT` y `S_IFWHT`.

Todas las variables de debajo son simplemente índices simbólicos sobre la tupla de 10 elementos retornada por `os.stat()`, `os.fstat()` o `os.lstat()`.

`stat.``ST_MODE`

  Modo de protección del inode.

`stat.``ST_INO`

  Número del inode.

`stat.``ST_DEV`

  Dispositivo en el que reside el inode.

`stat.``ST_NLINK`

  Número de enlaces al inode.

`stat.``ST_UID`

  Id de usuario del propietario.

`stat.``ST_GID`

  Id del grupo del propietario.

`stat.``ST_SIZE`

  Tamaño en bytes de un archivo normal; cantidad de datos esperando en algunos archivos especiales.

`stat.``ST_ATIME`

  Momento del último acceso.

`stat.``ST_MTIME`

  Momento de la última modificación.

`stat.``ST_CTIME`

  El «ctime» reportado por el sistema operativo. En algunos sistemas (como Unix) es el momento del último cambio en los metadatos, y en otros (como Windows), es el momento de creación (véase la documentación de la plataforma para más detalles).

La interpretación de «tamaño de archivo» cambia dependiendo del tipo de archivo. Para archivos normales es el tamaño del archivo en bytes. En la mayoría de sistemas Unix (incluyendo Linux en particular), para FIFOs y sockets es el número de bytes que esperan ser leídos en el momento de la llamada a `os.stat()`, `os.fstat()`, o `os.lstat()`; en ocasiones, esto puede ser útil, especialmente para sondear uno de estos archivos especiales después de una apertura no bloqueante. Para otros dispositivos de caracteres y bloques el significado del campo size es más variado, dependiendo de la implementación de la llamada al sistema subyacente.

Las variables de debajo definen los flags usados en el campo `ST_MODE`.

El uso de las funciones de arriba es más portable que el uso del primer juego de flags:

`stat.``S_IFSOCK`

  Socket.

`stat.``S_IFLNK`

  Enlace simbólico.

`stat.``S_IFREG`

  Archivo normal.

`stat.``S_IFBLK`

  Dispositivo de bloques.

`stat.``S_IFDIR`

  Directorio.

`stat.``S_IFCHR`

  Dispositivo de caracteres.

`stat.``S_IFIFO`

  FIFO.

`stat.``S_IFDOOR`

  Door.

  Nuevo en la versión 3.4.

`stat.``S_IFPORT`

  Event port.

  Nuevo en la versión 3.4.

`stat.``S_IFWHT`

  Whiteout.

  Nuevo en la versión 3.4.

Nota

`S_IFDOOR`, `S_IFPORT` o `S_IFWHT` se definen como 0 cuando la plataforma no soporta los tipos de archivo.

Los siguientes flags también pueden usarse en el argumento mode de `os.chmod()`:

`stat.``S_ISUID`

  Establecer el bit UID.

`stat.``S_ISGID`

  Bit Set-group-ID. Este bit tiene varios usos especiales. Para un directorio indica que la semántica BSD debe usarse para ese directorio: los archivos creados ahí heredan el ID de grupo del directorio, no del ID de grupo efectivo del proceso que los crea, y los directorios creados ahí también tendrán activado el bit `S_ISGID`. Para un archivo que no tiene activado el bit de ejecución de grupo (`S_IXGRP`), el bit Set-group-ID indica el bloqueo obligatorio del archivo/registro (véase también `S_ENFMT`).

`stat.``S_ISVTX`

  Sticky bit. Cuando este bit está activado en un directorio, significa que un archivo dentro de ese directorio puede ser renombrado o borrado sólo por el propietario del archivo, por el propietario del directorio, o por un proceso con privilegios.

`stat.``S_IRWXU`

  Máscara para los permisos del propietario del archivo.

`stat.``S_IRUSR`

  El propietario tiene permiso de lectura.

`stat.``S_IWUSR`

  El propietario tiene permiso de escritura.

`stat.``S_IXUSR`

  El propietario tiene permiso de ejecución.

`stat.``S_IRWXG`

  Máscara para los permisos del grupo.

`stat.``S_IRGRP`

  El grupo tiene permiso de lectura.

`stat.``S_IWGRP`

  El grupo tiene permiso de escritura.

`stat.``S_IXGRP`

  El grupo tiene permiso de ejecución.

`stat.``S_IRWXO`

  Máscara para permisos de los otros (no en el grupo).

`stat.``S_IROTH`

  Los otros tienen permiso de lectura.

`stat.``S_IWOTH`

  Los otros tienen permiso de escritura.

`stat.``S_IXOTH`

  Los otros tienen permiso de ejecución.

`stat.``S_ENFMT`

  Imposición del bloqueo de archivos de System V. Este flag se comparte con `S_ISGID`: se impone el bloqueo de archivos/registros en archivos que no tengan activado el bit de ejecución por el grupo (`S_IXGRP`).

`stat.``S_IREAD`

  Sinónimo de `S_IRUSR` en Unix V7.

`stat.``S_IWRITE`

  Sinónimo de `S_IWUSR` en Unix V7.

`stat.``S_IEXEC`

  Sinónimo de `S_IXUSR` en Unix V7.

Los siguientes flags pueden usarse como argumento flags de `os.chflags()`:

`stat.``UF_NODUMP`

  No volcar el archivo.

`stat.``UF_IMMUTABLE`

  El archivo no puede ser modificado.

`stat.``UF_APPEND`

  Sólo se puede añadir al archivo.

`stat.``UF_OPAQUE`

  El directorio es opaco cuando se mira a través de un union stack.

`stat.``UF_NOUNLINK`

  El archivo no puede ser renombrado o borrado.

`stat.``UF_COMPRESSED`

  El archivo se almacena comprimido (Mac OS X 10.6+).

`stat.``UF_HIDDEN`

  El archivo no debe ser mostrado en una GUI (Mac OS X 10.5+).

`stat.``SF_ARCHIVED`

  El archivo puede ser archivado.

`stat.``SF_IMMUTABLE`

  El archivo no puede ser modificado.

`stat.``SF_APPEND`

  Sólo se puede añadir al archivo.

`stat.``SF_NOUNLINK`

  El archivo no puede ser renombrado o borrado.

`stat.``SF_SNAPSHOT`

  El archivo es una instantánea.

Véase la página de man chflags(2) de los sistemas *BSD o Mac OS para más información.

En Windows, las siguientes constantes de atributos de fichero están disponibles para ser usadas al comprobar los bits del miembro `st_file_attributes` retornado por `os.stat()`. Véase Windows API documentation para más detalles sobre el significado de estas constantes.

`stat.``FILE_ATTRIBUTE_ARCHIVE`
`stat.``FILE_ATTRIBUTE_COMPRESSED`
`stat.``FILE_ATTRIBUTE_DEVICE`
`stat.``FILE_ATTRIBUTE_DIRECTORY`
`stat.``FILE_ATTRIBUTE_ENCRYPTED`
`stat.``FILE_ATTRIBUTE_HIDDEN`
`stat.``FILE_ATTRIBUTE_INTEGRITY_STREAM`
`stat.``FILE_ATTRIBUTE_NORMAL`
`stat.``FILE_ATTRIBUTE_NOT_CONTENT_INDEXED`
`stat.``FILE_ATTRIBUTE_NO_SCRUB_DATA`
`stat.``FILE_ATTRIBUTE_OFFLINE`
`stat.``FILE_ATTRIBUTE_READONLY`
`stat.``FILE_ATTRIBUTE_REPARSE_POINT`
`stat.``FILE_ATTRIBUTE_SPARSE_FILE`
`stat.``FILE_ATTRIBUTE_SYSTEM`
`stat.``FILE_ATTRIBUTE_TEMPORARY`
`stat.``FILE_ATTRIBUTE_VIRTUAL`

  Nuevo en la versión 3.5.

En Windows, las siguientes constantes están disponibles para la comparación con el miembro `st_reparse_tag` retornado por `os.lstat()`. Estas constantes son muy conocidas, pero no se trata de una lista exhaustiva.

`stat.``IO_REPARSE_TAG_SYMLINK`
`stat.``IO_REPARSE_TAG_MOUNT_POINT`
`stat.``IO_REPARSE_TAG_APPEXECLINK`

  Nuevo en la versión 3.8.