6.4 stat -- Interpreting stat() results
Keywords: lib

# 6.4 `stat` -- Interpreting `stat()` results

The `stat` module defines constants and functions for interpreting the results of `os.stat()`, `os.fstat()` and `os.lstat()` (if they exist). For complete details about the `stat()`, `fstat()` and `lstat()` calls, consult the documentation for your system.

The `stat` module defines the following functions to test for specific file types:

`S_ISDIR` (mode)
  Return non-zero if the mode is from a directory.

`S_ISCHR` (mode)
  Return non-zero if the mode is from a character special device file.

`S_ISBLK` (mode)
  Return non-zero if the mode is from a block special device file.

`S_ISREG` (mode)
  Return non-zero if the mode is from a regular file.

`S_ISFIFO` (mode)
  Return non-zero if the mode is from a FIFO (named pipe).

`S_ISLNK` (mode)
  Return non-zero if the mode is from a symbolic link.

`S_ISSOCK` (mode)
  Return non-zero if the mode is from a socket.

Two additional functions are defined for more general manipulation of the file's mode:

`S_IMODE` (mode)
  Return the portion of the file's mode that can be set by `os.chmod()`--that is, the file's permission bits, plus the sticky bit, set-group-id, and set-user-id bits (on systems that support them).

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

All the variables below are simply symbolic indexes into the 10-tuple returned by `os.stat()`, `os.fstat()` or `os.lstat()`.

`ST_MODE`
  Inode protection mode.

`ST_INO`
  Inode number.

`ST_DEV`
  Device inode resides on.

`ST_NLINK`
  Number of links to the inode.

`ST_UID`
  User id of the owner.

`ST_GID`
  Group id of the owner.

`ST_SIZE`
  File size in bytes.

`ST_ATIME`
  Time of last access.

`ST_MTIME`
  Time of last modification.

`ST_CTIME`
  Time of last status change (see manual pages for details).

Example:

      import os, sys
      from stat import *

      def walktree(dir, callback):
          '''recursively descend the directory rooted at dir,
             calling the callback function for each regular file'''

          for f in os.listdir(dir):
              pathname = '%s/%s' % (dir, f)
              mode = os.stat(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)