1:mod:`stat` --- Interpreting :func:`~os.stat` results 2===================================================== 3 4.. module:: stat 5 :synopsis: Utilities for interpreting the results of os.stat(), os.lstat() and os.fstat(). 6.. sectionauthor:: Skip Montanaro <skip@automatrix.com> 7 8**Source code:** :source:`Lib/stat.py` 9 10-------------- 11 12The :mod:`stat` module defines constants and functions for interpreting the 13results of :func:`os.stat`, :func:`os.fstat` and :func:`os.lstat` (if they 14exist). For complete details about the :c:func:`stat`, :c:func:`fstat` and 15:c:func:`lstat` calls, consult the documentation for your system. 16 17The :mod:`stat` module defines the following functions to test for specific file 18types: 19 20 21.. function:: S_ISDIR(mode) 22 23 Return non-zero if the mode is from a directory. 24 25 26.. function:: S_ISCHR(mode) 27 28 Return non-zero if the mode is from a character special device file. 29 30 31.. function:: S_ISBLK(mode) 32 33 Return non-zero if the mode is from a block special device file. 34 35 36.. function:: S_ISREG(mode) 37 38 Return non-zero if the mode is from a regular file. 39 40 41.. function:: S_ISFIFO(mode) 42 43 Return non-zero if the mode is from a FIFO (named pipe). 44 45 46.. function:: S_ISLNK(mode) 47 48 Return non-zero if the mode is from a symbolic link. 49 50 51.. function:: S_ISSOCK(mode) 52 53 Return non-zero if the mode is from a socket. 54 55Two additional functions are defined for more general manipulation of the file's 56mode: 57 58 59.. function:: S_IMODE(mode) 60 61 Return the portion of the file's mode that can be set by :func:`os.chmod`\ 62 ---that is, the file's permission bits, plus the sticky bit, set-group-id, and 63 set-user-id bits (on systems that support them). 64 65 66.. function:: S_IFMT(mode) 67 68 Return the portion of the file's mode that describes the file type (used by the 69 :func:`S_IS\*` functions above). 70 71Normally, you would use the :func:`os.path.is\*` functions for testing the type 72of a file; the functions here are useful when you are doing multiple tests of 73the same file and wish to avoid the overhead of the :c:func:`stat` system call 74for each test. These are also useful when checking for information about a file 75that isn't handled by :mod:`os.path`, like the tests for block and character 76devices. 77 78Example:: 79 80 import os, sys 81 from stat import * 82 83 def walktree(top, callback): 84 '''recursively descend the directory tree rooted at top, 85 calling the callback function for each regular file''' 86 87 for f in os.listdir(top): 88 pathname = os.path.join(top, f) 89 mode = os.stat(pathname).st_mode 90 if S_ISDIR(mode): 91 # It's a directory, recurse into it 92 walktree(pathname, callback) 93 elif S_ISREG(mode): 94 # It's a file, call the callback function 95 callback(pathname) 96 else: 97 # Unknown file type, print a message 98 print 'Skipping %s' % pathname 99 100 def visitfile(file): 101 print 'visiting', file 102 103 if __name__ == '__main__': 104 walktree(sys.argv[1], visitfile) 105 106All the variables below are simply symbolic indexes into the 10-tuple returned 107by :func:`os.stat`, :func:`os.fstat` or :func:`os.lstat`. 108 109 110.. data:: ST_MODE 111 112 Inode protection mode. 113 114 115.. data:: ST_INO 116 117 Inode number. 118 119 120.. data:: ST_DEV 121 122 Device inode resides on. 123 124 125.. data:: ST_NLINK 126 127 Number of links to the inode. 128 129 130.. data:: ST_UID 131 132 User id of the owner. 133 134 135.. data:: ST_GID 136 137 Group id of the owner. 138 139 140.. data:: ST_SIZE 141 142 Size in bytes of a plain file; amount of data waiting on some special files. 143 144 145.. data:: ST_ATIME 146 147 Time of last access. 148 149 150.. data:: ST_MTIME 151 152 Time of last modification. 153 154 155.. data:: ST_CTIME 156 157 The "ctime" as reported by the operating system. On some systems (like Unix) is 158 the time of the last metadata change, and, on others (like Windows), is the 159 creation time (see platform documentation for details). 160 161The interpretation of "file size" changes according to the file type. For plain 162files this is the size of the file in bytes. For FIFOs and sockets under most 163flavors of Unix (including Linux in particular), the "size" is the number of 164bytes waiting to be read at the time of the call to :func:`os.stat`, 165:func:`os.fstat`, or :func:`os.lstat`; this can sometimes be useful, especially 166for polling one of these special files after a non-blocking open. The meaning 167of the size field for other character and block devices varies more, depending 168on the implementation of the underlying system call. 169 170The variables below define the flags used in the :data:`ST_MODE` field. 171 172Use of the functions above is more portable than use of the first set of flags: 173 174.. data:: S_IFSOCK 175 176 Socket. 177 178.. data:: S_IFLNK 179 180 Symbolic link. 181 182.. data:: S_IFREG 183 184 Regular file. 185 186.. data:: S_IFBLK 187 188 Block device. 189 190.. data:: S_IFDIR 191 192 Directory. 193 194.. data:: S_IFCHR 195 196 Character device. 197 198.. data:: S_IFIFO 199 200 FIFO. 201 202The following flags can also be used in the *mode* argument of :func:`os.chmod`: 203 204.. data:: S_ISUID 205 206 Set UID bit. 207 208.. data:: S_ISGID 209 210 Set-group-ID bit. This bit has several special uses. For a directory 211 it indicates that BSD semantics is to be used for that directory: 212 files created there inherit their group ID from the directory, not 213 from the effective group ID of the creating process, and directories 214 created there will also get the :data:`S_ISGID` bit set. For a 215 file that does not have the group execution bit (:data:`S_IXGRP`) 216 set, the set-group-ID bit indicates mandatory file/record locking 217 (see also :data:`S_ENFMT`). 218 219.. data:: S_ISVTX 220 221 Sticky bit. When this bit is set on a directory it means that a file 222 in that directory can be renamed or deleted only by the owner of the 223 file, by the owner of the directory, or by a privileged process. 224 225.. data:: S_IRWXU 226 227 Mask for file owner permissions. 228 229.. data:: S_IRUSR 230 231 Owner has read permission. 232 233.. data:: S_IWUSR 234 235 Owner has write permission. 236 237.. data:: S_IXUSR 238 239 Owner has execute permission. 240 241.. data:: S_IRWXG 242 243 Mask for group permissions. 244 245.. data:: S_IRGRP 246 247 Group has read permission. 248 249.. data:: S_IWGRP 250 251 Group has write permission. 252 253.. data:: S_IXGRP 254 255 Group has execute permission. 256 257.. data:: S_IRWXO 258 259 Mask for permissions for others (not in group). 260 261.. data:: S_IROTH 262 263 Others have read permission. 264 265.. data:: S_IWOTH 266 267 Others have write permission. 268 269.. data:: S_IXOTH 270 271 Others have execute permission. 272 273.. data:: S_ENFMT 274 275 System V file locking enforcement. This flag is shared with :data:`S_ISGID`: 276 file/record locking is enforced on files that do not have the group 277 execution bit (:data:`S_IXGRP`) set. 278 279.. data:: S_IREAD 280 281 Unix V7 synonym for :data:`S_IRUSR`. 282 283.. data:: S_IWRITE 284 285 Unix V7 synonym for :data:`S_IWUSR`. 286 287.. data:: S_IEXEC 288 289 Unix V7 synonym for :data:`S_IXUSR`. 290 291The following flags can be used in the *flags* argument of :func:`os.chflags`: 292 293.. data:: UF_NODUMP 294 295 Do not dump the file. 296 297.. data:: UF_IMMUTABLE 298 299 The file may not be changed. 300 301.. data:: UF_APPEND 302 303 The file may only be appended to. 304 305.. data:: UF_OPAQUE 306 307 The directory is opaque when viewed through a union stack. 308 309.. data:: UF_NOUNLINK 310 311 The file may not be renamed or deleted. 312 313.. data:: UF_COMPRESSED 314 315 The file is stored compressed (Mac OS X 10.6+). 316 317.. data:: UF_HIDDEN 318 319 The file should not be displayed in a GUI (Mac OS X 10.5+). 320 321.. data:: SF_ARCHIVED 322 323 The file may be archived. 324 325.. data:: SF_IMMUTABLE 326 327 The file may not be changed. 328 329.. data:: SF_APPEND 330 331 The file may only be appended to. 332 333.. data:: SF_NOUNLINK 334 335 The file may not be renamed or deleted. 336 337.. data:: SF_SNAPSHOT 338 339 The file is a snapshot file. 340 341See the \*BSD or Mac OS systems man page :manpage:`chflags(2)` for more information. 342 343