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

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