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