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 The variables below define the flags used in the :data:`ST_MODE` field.
 141
 142 Use of the functions above is more portable than use of the first set of flags:
 143
 144 .. data:: S_IFMT
 145
 146    Bit mask for the file type bit fields.
 147
 148 .. data:: S_IFSOCK
 149
 150    Socket.
 151
 152 .. data:: S_IFLNK
 153
 154    Symbolic link.
 155
 156 .. data:: S_IFREG
 157
 158    Regular file.
 159
 160 .. data:: S_IFBLK
 161
 162    Block device.
 163
 164 .. data:: S_IFDIR
 165
 166    Directory.
 167
 168 .. data:: S_IFCHR
 169
 170    Character device.
 171
 172 .. data:: S_IFIFO
 173
 174    FIFO.
 175
 176 The following flags can also be used in the *mode* argument of :func:`os.chmod`:
 177
 178 .. data:: S_ISUID
 179
 180    Set UID bit.
 181
 182 .. data:: S_ISGID
 183
 184    Set-group-ID bit.  This bit has several special uses.  For a directory
 185    it indicates that BSD semantics is to be used for that directory:
 186    files created there inherit their group ID from the directory, not
 187    from the effective group ID of the creating process, and directories
 188    created there will also get the :data:`S_ISGID` bit set.  For a
 189    file that does not have the group execution bit (:data:`S_IXGRP`)
 190    set, the set-group-ID bit indicates mandatory file/record locking
 191    (see also :data:`S_ENFMT`).
 192
 193 .. data:: S_ISVTX
 194
 195    Sticky bit.  When this bit is set on a directory it means that a file
 196    in that directory can be renamed or deleted only by the owner of the
 197    file, by the owner of the directory, or by a privileged process.
 198
 199 .. data:: S_IRWXU
 200
 201    Mask for file owner permissions.
 202
 203 .. data:: S_IRUSR
 204
 205    Owner has read permission.
 206
 207 .. data:: S_IWUSR
 208
 209    Owner has write permission.
 210
 211 .. data:: S_IXUSR
 212
 213    Owner has execute permission.
 214
 215 .. data:: S_IRWXG
 216
 217    Mask for group permissions.
 218
 219 .. data:: S_IRGRP
 220
 221    Group has read permission.
 222
 223 .. data:: S_IWGRP
 224
 225    Group has write permission.
 226
 227 .. data:: S_IXGRP
 228
 229    Group has execute permission.
 230
 231 .. data:: S_IRWXO
 232
 233    Mask for permissions for others (not in group).
 234
 235 .. data:: S_IROTH
 236
 237    Others have read permission.
 238
 239 .. data:: S_IWOTH
 240
 241    Others have write permission.
 242
 243 .. data:: S_IXOTH
 244
 245    Others have execute permission.
 246
 247 .. data:: S_ENFMT
 248
 249    System V file locking enforcement.  This flag is shared with :data:`S_ISGID`:
 250    file/record locking is enforced on files that do not have the group
 251    execution bit (:data:`S_IXGRP`) set.
 252
 253 .. data:: S_IREAD
 254
 255    Unix V7 synonym for :data:`S_IRUSR`.
 256
 257 .. data:: S_IWRITE
 258
 259    Unix V7 synonym for :data:`S_IWUSR`.
 260
 261 .. data:: S_IEXEC
 262
 263    Unix V7 synonym for :data:`S_IXUSR`.
 264
 265 Example::
 266
 267    import os, sys
 268    from stat import *
 269
 270    def walktree(top, callback):
 271        '''recursively descend the directory tree rooted at top,
 272           calling the callback function for each regular file'''
 273
 274        for f in os.listdir(top):
 275            pathname = os.path.join(top, f)
 276            mode = os.stat(pathname)[ST_MODE]
 277            if S_ISDIR(mode):
 278                # It's a directory, recurse into it
 279                walktree(pathname, callback)
 280            elif S_ISREG(mode):
 281                # It's a file, call the callback function
 282                callback(pathname)
 283            else:
 284                # Unknown file type, print a message
 285                print 'Skipping %s' % pathname
 286
 287    def visitfile(file):
 288        print 'visiting', file
 289
 290    if __name__ == '__main__':
 291        walktree(sys.argv[1], visitfile)
 292