# `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)

  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):
        '''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.

stat.ST_NLINK

  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.

stat.UF_NOUNLINK

  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.

stat.SF_NOUNLINK

  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_SYMLINK
stat.IO_REPARSE_TAG_MOUNT_POINT
stat.IO_REPARSE_TAG_APPEXECLINK

  Novo na versão 3.8.