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.

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.

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.

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_MOUNT_POINT

Nuevo en la versión 3.8.