stat — Interpretando resultados de stat()

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.

Adicionado na versão 3.4.

stat.S_ISPORT(mode)

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

Adicionado na versão 3.4.

stat.S_ISWHT(mode)

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

Adicionado 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)

Retorna a parte do modo do arquivo que descreve o tipo de arquivo (usado pelas funções S_IS*() acima).

Normalmente, você usaria as funções os.path.is*() para testar o tipo de um arquivo; as funções aqui são úteis quando você está fazendo vários testes do mesmo arquivo e deseja evitar a sobrecarga da chamada de sistema stat() para cada teste. Eles também são úteis ao verificar informações sobre um arquivo que não é manipulado por os.path, como os testes para dispositivos de blocos e caracteres.

Exemplo:

import os, sys
from stat import *

def walktree(top, callback):
    '''desce recursivamente a árvore de diretórios com raiz no topo,
     chamando a função de retorno de chamada para cada arquivo regular'''

    for f in os.listdir(top):
        pathname = os.path.join(top, f)
        mode = os.lstat(pathname).st_mode
        if S_ISDIR(mode):
            # É um diretório, percorre recursivamente nele
            walktree(pathname, callback)
        elif S_ISREG(mode):
            # É um arquivo, chama a função de retorno
            callback(pathname)
        else:
            # Tipo de arquivo desconhecido, imprime uma mensagem
            print('Pulando %s' % pathname)

def visitfile(file):
    print('visitando, 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’.

Adicionado 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.

Adicionado na versão 3.4.

stat.S_IFPORT

Porta de eventos.

Adicionado na versão 3.4.

stat.S_IFWHT

Apagamento.

Adicionado 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_SETTABLE

Todos os sinalizadores definíveis pelo usuário

Adicionado na versão 3.13.

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_TRACKED

Usado para manipular IDs de documentos (macOS)

Adicionado na versão 3.13.

stat.UF_DATAVAULT

O arquivo precisa de direito para leitura ou gravação (macOS 10.13+)

Adicionado na versão 3.13.

stat.UF_HIDDEN

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

stat.SF_SETTABLE

Todos os sinalizadores mutáveis ​​de superusuário

Adicionado na versão 3.13.

stat.SF_SUPPORTED

Todos os sinalizadores válidos ​de superusuário

Disponibilidade

Adicionado na versão 3.13.

stat.SF_SYNTHETIC

Todos os sinalizadores sintéticos de somente leitura ​de superusuário

Disponibilidade

Adicionado na versão 3.13.

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.

stat.SF_RESTRICTED

O arquivo precisa de um direito para ser escrito (macOS 10.13+)

Adicionado na versão 3.13.

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

stat.SF_SNAPSHOT

O arquivo é um arquivo de captura (snapshot).

O arquivo é um firmlink (macOS 10.15+)

Adicionado na versão 3.13.

stat.SF_DATALESS

O arquivo é um objeto sem dados (macOS 10.15+)

Adicionado na versão 3.13.

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

Adicionado 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

Adicionado na versão 3.8.