Doc/library/stat.rst

   1
   2 :mod:`stat` --- Interpreting :func:`stat` results
   3 =================================================
   4
   5 .. module:: stat
   6    :synopsis: Utilities for interpreting the results of os.stat(), os.lstat() and os.fstat().
   7 .. sectionauthor:: Skip Montanaro <skip@automatrix.com>
   8
   9
  10 The :mod:`stat` module defines constants and functions for interpreting the
  11 results of :func:`os.stat`, :func:`os.fstat` and :func:`os.lstat` (if they
  12 exist).  For complete details about the :cfunc:`stat`, :cfunc:`fstat` and
  13 :cfunc:`lstat` calls, consult the documentation for your system.
  14
  15 The :mod:`stat` module defines the following functions to test for specific file
  16 types:
  17
  18
  19 .. function:: S_ISDIR(mode)
  20
  21    Return non-zero if the mode is from a directory.
  22
  23
  24 .. function:: S_ISCHR(mode)
  25
  26    Return non-zero if the mode is from a character special device file.
  27
  28
  29 .. function:: S_ISBLK(mode)
  30
  31    Return non-zero if the mode is from a block special device file.
  32
  33
  34 .. function:: S_ISREG(mode)
  35
  36    Return non-zero if the mode is from a regular file.
  37
  38
  39 .. function:: S_ISFIFO(mode)
  40
  41    Return non-zero if the mode is from a FIFO (named pipe).
  42
  43
  44 .. function:: S_ISLNK(mode)
  45
  46    Return non-zero if the mode is from a symbolic link.
  47
  48
  49 .. function:: S_ISSOCK(mode)
  50
  51    Return non-zero if the mode is from a socket.
  52
  53 Two additional functions are defined for more general manipulation of the file's
  54 mode:
  55
  56
  57 .. function:: S_IMODE(mode)
  58
  59    Return the portion of the file's mode that can be set by :func:`os.chmod`\
  60    ---that is, the file's permission bits, plus the sticky bit, set-group-id, and
  61    set-user-id bits (on systems that support them).
  62
  63
  64 .. function:: S_IFMT(mode)
  65
  66    Return the portion of the file's mode that describes the file type (used by the
  67    :func:`S_IS\*` functions above).
  68
  69 Normally, you would use the :func:`os.path.is\*` functions for testing the type
  70 of a file; the functions here are useful when you are doing multiple tests of
  71 the same file and wish to avoid the overhead of the :cfunc:`stat` system call
  72 for each test.  These are also useful when checking for information about a file
  73 that isn't handled by :mod:`os.path`, like the tests for block and character
  74 devices.
  75
  76 All the variables below are simply symbolic indexes into the 10-tuple returned
  77 by :func:`os.stat`, :func:`os.fstat` or :func:`os.lstat`.
  78
  79
  80 .. data:: ST_MODE
  81
  82    Inode protection mode.
  83
  84
  85 .. data:: ST_INO
  86
  87    Inode number.
  88
  89
  90 .. data:: ST_DEV
  91
  92    Device inode resides on.
  93
  94
  95 .. data:: ST_NLINK
  96
  97    Number of links to the inode.
  98
  99
 100 .. data:: ST_UID
 101
 102    User id of the owner.
 103
 104
 105 .. data:: ST_GID
 106
 107    Group id of the owner.
 108
 109
 110 .. data:: ST_SIZE
 111
 112    Size in bytes of a plain file; amount of data waiting on some special files.
 113
 114
 115 .. data:: ST_ATIME
 116
 117    Time of last access.
 118
 119
 120 .. data:: ST_MTIME
 121
 122    Time of last modification.
 123
 124
 125 .. data:: ST_CTIME
 126
 127    The "ctime" as reported by the operating system.  On some systems (like Unix) is
 128    the time of the last metadata change, and, on others (like Windows), is the
 129    creation time (see platform documentation for details).
 130
 131 The interpretation of "file size" changes according to the file type.  For plain
 132 files this is the size of the file in bytes.  For FIFOs and sockets under most
 133 flavors of Unix (including Linux in particular), the "size" is the number of
 134 bytes waiting to be read at the time of the call to :func:`os.stat`,
 135 :func:`os.fstat`, or :func:`os.lstat`; this can sometimes be useful, especially
 136 for polling one of these special files after a non-blocking open.  The meaning
 137 of the size field for other character and block devices varies more, depending
 138 on the implementation of the underlying system call.
 139
 140 Example::
 141
 142    import os, sys
 143    from stat import *
 144
 145    def walktree(top, callback):
 146        '''recursively descend the directory tree rooted at top,
 147           calling the callback function for each regular file'''
 148
 149        for f in os.listdir(top):
 150            pathname = os.path.join(top, f)
 151            mode = os.stat(pathname)[ST_MODE]
 152            if S_ISDIR(mode):
 153                # It's a directory, recurse into it
 154                walktree(pathname, callback)
 155            elif S_ISREG(mode):
 156                # It's a file, call the callback function
 157                callback(pathname)
 158            else:
 159                # Unknown file type, print a message
 160                print 'Skipping %s' % pathname
 161
 162    def visitfile(file):
 163        print 'visiting', file
 164
 165    if __name__ == '__main__':
 166        walktree(sys.argv[1], visitfile)
 167