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.
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émS_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.
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.