stat — Interpreting stat() results

Código-fonte: Lib/stat.py

O módulo stat define constantes e funções para interpretar os resultados de os.stat(), os.fstat() e os.lstat() (se existirem). Para detalhes completos sobre chamadas stat(), fstat() e lstat(), consulte a documentação do seu sistema.

Alterado na versão 3.4: O módulo stat é apoiado por uma implementação C.

O módulo stat define as seguintes funções para testar tipos de arquivos específicos:

stat.S_ISDIR(mode)

Retorna diferente de zero se o modo for de um diretório.

stat.S_ISCHR(mode)

Retorna diferente de zero se o modo for de um arquivo de dispositivo especial de caractere.

stat.S_ISBLK(mode)

Retorna diferente de zero se o modo for de um arquivo de dispositivo especial de bloco.

stat.S_ISREG(mode)

Retorna diferente de zero se o modo for de um arquivo regular.

stat.S_ISFIFO(mode)

Retorna diferente de zero se o modo for de um FIFO (encadeamento nomeado).

stat.S_ISLNK(mode)

Retorna diferente de zero se o modo for de um link simbólico.

stat.S_ISSOCK(mode)

Retorna diferente de zero se o modo for de um soquete.

stat.S_ISDOOR(mode)

Retorna diferente de zero se o modo for de uma porta.

Novo na versão 3.4.

stat.S_ISPORT(mode)

Retorna diferente de zero se o modo for de uma porta de eventos.

Novo na versão 3.4.

stat.S_ISWHT(mode)

Retorna diferente de zero se o modo for de um apagamento.

Novo na versão 3.4.

Duas funções adicionais são definidas para manipulação mais geral do modo do arquivo:

stat.S_IMODE(mode)

Retorna a parte do modo do arquivo que pode ser definido por os.chmod() — ou seja, os bits de permissão do arquivo, mais os bits sticky bit, set-group-id e set-user-id (em sistemas que têm suporte a eles).

stat.S_IFMT(mode)

Return the portion of the file’s mode that describes the file type (used by the S_IS*() functions above).

Normally, you would use the os.path.is*() functions for testing the type of a file; the functions here are useful when you are doing multiple tests of the same file and wish to avoid the overhead of the stat() system call for each test. These are also useful when checking for information about a file that isn’t handled by os.path, like the tests for block and character devices.

Exemplo:

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.lstat(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)

Uma função utilitária adicional é fornecida para converter o modo de um arquivo em uma string legível por humanos:

stat.filemode(mode)

Converte o modo de um arquivo em uma string no formato ‘-rwxrwxrwx’.

Novo na versão 3.3.

Alterado na versão 3.4: A função tem suporte a S_IFDOOR, S_IFPORT e S_IFWHT.

Todas as variáveis ​abaixo são simplesmente índices simbólicos nas 10 tuplas retornadas por os.stat(), os.fstat() ou os.lstat().

stat.ST_MODE

Modo de proteção de nó-i.

stat.ST_INO

Número de nó-i.

stat.ST_DEV

Nó-i em que o dispositivo reside.

Número de links para o nó-i.

stat.ST_UID

O ID de usuário para o proprietário.

stat.ST_GID

O ID de grupo para o proprietário.

stat.ST_SIZE

Tamanho em bytes de um arquivo simples; quantidade de dados aguardando em alguns arquivos especiais.

stat.ST_ATIME

Hora do último acesso.

stat.ST_MTIME

Hora da última modificação.

stat.ST_CTIME

O “ctime” conforme relatado pelo sistema operacional. Em alguns sistemas (como Unix) é o horário da última alteração de metadados e, em outros (como Windows), é o horário de criação (consulte a documentação da plataforma para obter detalhes).

A interpretação do “tamanho do arquivo” muda de acordo com o tipo de arquivo. Para arquivos simples, este é o tamanho do arquivo em bytes. Para FIFOs e soquetes na maioria dos tipos de Unix (incluindo Linux em particular), o “tamanho” é o número de bytes aguardando para serem lidos no momento da chamada para os.stat(), os.fstat() ou os.lstat(); isso às vezes pode ser útil, especialmente para pesquisar um desses arquivos especiais após uma abertura sem bloqueio. O significado do campo de tamanho para outros dispositivos de caracteres e blocos varia mais, dependendo da implementação da chamada de sistema subjacente.

As variáveis ​abaixo definem os sinalizadores utilizadas no campo ST_MODE.

O uso das funções acima é mais portátil do que o uso do primeiro conjunto de sinalizadores:

stat.S_IFSOCK

Soquete.

stat.S_IFLNK

Link simbólico.

stat.S_IFREG

Arquivo regular.

stat.S_IFBLK

Dispositivo de bloco.

stat.S_IFDIR

Diretório.

stat.S_IFCHR

Dispositivo de caracteres.

stat.S_IFIFO

FIFO.

stat.S_IFDOOR

Porta.

Novo na versão 3.4.

stat.S_IFPORT

Porta de eventos.

Novo na versão 3.4.

stat.S_IFWHT

Apagamento.

Novo na versão 3.4.

Nota

S_IFDOOR, S_IFPORT ou S_IFWHT são definidos como 0 quando a plataforma não possui suporte para os tipos de arquivo.

Os seguintes sinalizadores também podem ser usados ​no argumento mode de os.chmod():

stat.S_ISUID

Define o bit de UID.

stat.S_ISGID

Bit de set-group-ID. Este bit tem vários usos especiais. Para um diretório, indica que a semântica BSD deve ser usada para esse diretório: os arquivos criados lá herdam seu ID de grupo do diretório, não do ID de grupo efetivo do processo de criação, e os diretórios criados lá também receberão o conjunto de bits S_ISGID. Para um arquivo que não possui o bit de execução de grupo (S_IXGRP) definido, o bit de set-group-ID indica trava obrigatória de arquivo/registro (veja também S_ENFMT).

stat.S_ISVTX

Sticky bit. Quando este bit é definido em um diretório, significa que um arquivo nesse diretório pode ser renomeado ou excluído apenas pelo proprietário do arquivo, pelo proprietário do diretório ou por um processo privilegiado.

stat.S_IRWXU

Máscara para permissões de proprietário de arquivo.

stat.S_IRUSR

Proprietário tem permissão de leitura.

stat.S_IWUSR

Proprietário tem permissão de escrita.

stat.S_IXUSR

Proprietário tem permissão de execução.

stat.S_IRWXG

Máscara para permissões de grupo.

stat.S_IRGRP

Grupo tem permissão de leitura.

stat.S_IWGRP

Grupo tem permissão de escrita.

stat.S_IXGRP

Grupo tem permissão de execução.

stat.S_IRWXO

Máscara para permissões para outros (não no grupo).

stat.S_IROTH

Outros têm permissão de leitura.

stat.S_IWOTH

Outros têm permissão de escrita.

stat.S_IXOTH

Outros têm permissão de execução.

stat.S_ENFMT

Aplicação de trava de arquivo do System V. Este sinalizador é compartilhada com S_ISGID: a trava de arquivo/registro é aplicada em arquivos que não possuem o bit de execução de grupo (S_IXGRP) definido.

stat.S_IREAD

Sinônimo Unix V7 para S_IRUSR.

stat.S_IWRITE

Sinônimo Unix V7 para S_IWUSR.

stat.S_IEXEC

Sinônimo Unix V7 para S_IXUSR.

Os seguintes sinalizadores podem ser usados ​no argumento flags de os.chflags():

stat.UF_NODUMP

Não despeja o arquivo.

stat.UF_IMMUTABLE

O arquivo não pode ser alterado.

stat.UF_APPEND

O arquivo só pode sofrer acréscimos.

stat.UF_OPAQUE

O diretório é opaco quando visualizado por meio de uma pilha de união.

O arquivo não pode ser renomeado ou excluído.

stat.UF_COMPRESSED

O arquivo é armazenado compactado (macOS 10.6+).

stat.UF_HIDDEN

O arquivo não deve ser exibido em uma GUI (macOS 10.5+).

stat.SF_ARCHIVED

O arquivo não pode ser arquivado.

stat.SF_IMMUTABLE

O arquivo não pode ser alterado.

stat.SF_APPEND

O arquivo só pode sofrer acréscimos.

O arquivo não pode ser renomeado ou excluído.

stat.SF_SNAPSHOT

O arquivo é um arquivo de captura (snapshot).

Consulte a página man dos sistemas *BSD ou macOS chflags(2) para obter mais informações.

No Windows, as seguintes constantes de atributos de arquivo estão disponíveis para uso ao testar bits no membro st_file_attributes retornado por os.stat(). Consulte a documentação da API do Windows para obter mais detalhes sobre o significado dessas 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

Novo na versão 3.5.

No Windows, as seguintes constantes estão disponíveis para comparação com o membro st_reparse_tag retornado por os.lstat(). Estas são constantes bem conhecidas, mas não são uma lista exaustiva.

stat.IO_REPARSE_TAG_MOUNT_POINT

Novo na versão 3.8.