Serhiy Storchaka | bfdcd43 | 2013-10-13 23:09:14 +0300 | [diff] [blame] | 1 | :mod:`stat` --- Interpreting :func:`~os.stat` results |
| 2 | ===================================================== |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 3 | |
| 4 | .. module:: stat |
Georg Brandl | 7f01a13 | 2009-09-16 15:58:14 +0000 | [diff] [blame] | 5 | :synopsis: Utilities for interpreting the results of os.stat(), |
| 6 | os.lstat() and os.fstat(). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 7 | .. sectionauthor:: Skip Montanaro <skip@automatrix.com> |
| 8 | |
Christian Heimes | c77d9f3 | 2013-06-22 21:05:02 +0200 | [diff] [blame] | 9 | **Source code:** :source:`Modules/_stat.c` |
| 10 | :source:`Lib/stat.py` |
Raymond Hettinger | 469271d | 2011-01-27 20:38:46 +0000 | [diff] [blame] | 11 | |
| 12 | -------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 13 | |
| 14 | The :mod:`stat` module defines constants and functions for interpreting the |
| 15 | results of :func:`os.stat`, :func:`os.fstat` and :func:`os.lstat` (if they |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 16 | exist). For complete details about the :c:func:`stat`, :c:func:`fstat` and |
| 17 | :c:func:`lstat` calls, consult the documentation for your system. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 18 | |
Christian Heimes | c77d9f3 | 2013-06-22 21:05:02 +0200 | [diff] [blame] | 19 | .. versionchanged:: 3.4 |
| 20 | The stat module is backed by a C implementation. |
| 21 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 22 | The :mod:`stat` module defines the following functions to test for specific file |
| 23 | types: |
| 24 | |
| 25 | |
| 26 | .. function:: S_ISDIR(mode) |
| 27 | |
| 28 | Return non-zero if the mode is from a directory. |
| 29 | |
| 30 | |
| 31 | .. function:: S_ISCHR(mode) |
| 32 | |
| 33 | Return non-zero if the mode is from a character special device file. |
| 34 | |
| 35 | |
| 36 | .. function:: S_ISBLK(mode) |
| 37 | |
| 38 | Return non-zero if the mode is from a block special device file. |
| 39 | |
| 40 | |
| 41 | .. function:: S_ISREG(mode) |
| 42 | |
| 43 | Return non-zero if the mode is from a regular file. |
| 44 | |
| 45 | |
| 46 | .. function:: S_ISFIFO(mode) |
| 47 | |
| 48 | Return non-zero if the mode is from a FIFO (named pipe). |
| 49 | |
| 50 | |
| 51 | .. function:: S_ISLNK(mode) |
| 52 | |
| 53 | Return non-zero if the mode is from a symbolic link. |
| 54 | |
| 55 | |
| 56 | .. function:: S_ISSOCK(mode) |
| 57 | |
| 58 | Return non-zero if the mode is from a socket. |
| 59 | |
Christian Heimes | c77d9f3 | 2013-06-22 21:05:02 +0200 | [diff] [blame] | 60 | .. function:: S_ISDOOR(mode) |
| 61 | |
| 62 | Return non-zero if the mode is from a door. |
| 63 | |
| 64 | .. versionadded:: 3.4 |
| 65 | |
| 66 | .. function:: S_ISPORT(mode) |
| 67 | |
| 68 | Return non-zero if the mode is from an event port. |
| 69 | |
| 70 | .. versionadded:: 3.4 |
| 71 | |
| 72 | .. function:: S_ISWHT(mode) |
| 73 | |
| 74 | Return non-zero if the mode is from a whiteout. |
| 75 | |
| 76 | .. versionadded:: 3.4 |
| 77 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 78 | Two additional functions are defined for more general manipulation of the file's |
| 79 | mode: |
| 80 | |
| 81 | |
| 82 | .. function:: S_IMODE(mode) |
| 83 | |
| 84 | Return the portion of the file's mode that can be set by :func:`os.chmod`\ |
| 85 | ---that is, the file's permission bits, plus the sticky bit, set-group-id, and |
| 86 | set-user-id bits (on systems that support them). |
| 87 | |
| 88 | |
| 89 | .. function:: S_IFMT(mode) |
| 90 | |
| 91 | Return the portion of the file's mode that describes the file type (used by the |
| 92 | :func:`S_IS\*` functions above). |
| 93 | |
| 94 | Normally, you would use the :func:`os.path.is\*` functions for testing the type |
| 95 | of a file; the functions here are useful when you are doing multiple tests of |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 96 | the same file and wish to avoid the overhead of the :c:func:`stat` system call |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 97 | for each test. These are also useful when checking for information about a file |
| 98 | that isn't handled by :mod:`os.path`, like the tests for block and character |
| 99 | devices. |
| 100 | |
R David Murray | 3017806 | 2011-03-10 17:18:33 -0500 | [diff] [blame] | 101 | Example:: |
| 102 | |
| 103 | import os, sys |
| 104 | from stat import * |
| 105 | |
| 106 | def walktree(top, callback): |
| 107 | '''recursively descend the directory tree rooted at top, |
| 108 | calling the callback function for each regular file''' |
| 109 | |
| 110 | for f in os.listdir(top): |
| 111 | pathname = os.path.join(top, f) |
Georg Brandl | aa71583 | 2011-08-01 22:58:53 +0200 | [diff] [blame] | 112 | mode = os.stat(pathname).st_mode |
R David Murray | 3017806 | 2011-03-10 17:18:33 -0500 | [diff] [blame] | 113 | if S_ISDIR(mode): |
| 114 | # It's a directory, recurse into it |
| 115 | walktree(pathname, callback) |
| 116 | elif S_ISREG(mode): |
| 117 | # It's a file, call the callback function |
| 118 | callback(pathname) |
| 119 | else: |
| 120 | # Unknown file type, print a message |
| 121 | print('Skipping %s' % pathname) |
| 122 | |
| 123 | def visitfile(file): |
| 124 | print('visiting', file) |
| 125 | |
| 126 | if __name__ == '__main__': |
| 127 | walktree(sys.argv[1], visitfile) |
| 128 | |
Zachary Ware | 63f277b | 2014-06-19 09:46:37 -0500 | [diff] [blame] | 129 | An additional utility function is provided to convert a file's mode in a human |
Giampaolo Rodola' | ffa1d0b | 2012-05-15 15:30:25 +0200 | [diff] [blame] | 130 | readable string: |
| 131 | |
| 132 | .. function:: filemode(mode) |
| 133 | |
| 134 | Convert a file's mode to a string of the form '-rwxrwxrwx'. |
| 135 | |
| 136 | .. versionadded:: 3.3 |
| 137 | |
Christian Heimes | c77d9f3 | 2013-06-22 21:05:02 +0200 | [diff] [blame] | 138 | .. versionchanged:: 3.4 |
| 139 | The function supports :data:`S_IFDOOR`, :data:`S_IFPORT` and |
| 140 | :data:`S_IFWHT`. |
| 141 | |
Giampaolo Rodola' | ffa1d0b | 2012-05-15 15:30:25 +0200 | [diff] [blame] | 142 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 143 | All the variables below are simply symbolic indexes into the 10-tuple returned |
| 144 | by :func:`os.stat`, :func:`os.fstat` or :func:`os.lstat`. |
| 145 | |
| 146 | |
| 147 | .. data:: ST_MODE |
| 148 | |
| 149 | Inode protection mode. |
| 150 | |
| 151 | |
| 152 | .. data:: ST_INO |
| 153 | |
| 154 | Inode number. |
| 155 | |
| 156 | |
| 157 | .. data:: ST_DEV |
| 158 | |
| 159 | Device inode resides on. |
| 160 | |
| 161 | |
| 162 | .. data:: ST_NLINK |
| 163 | |
| 164 | Number of links to the inode. |
| 165 | |
| 166 | |
| 167 | .. data:: ST_UID |
| 168 | |
| 169 | User id of the owner. |
| 170 | |
| 171 | |
| 172 | .. data:: ST_GID |
| 173 | |
| 174 | Group id of the owner. |
| 175 | |
| 176 | |
| 177 | .. data:: ST_SIZE |
| 178 | |
| 179 | Size in bytes of a plain file; amount of data waiting on some special files. |
| 180 | |
| 181 | |
| 182 | .. data:: ST_ATIME |
| 183 | |
| 184 | Time of last access. |
| 185 | |
| 186 | |
| 187 | .. data:: ST_MTIME |
| 188 | |
| 189 | Time of last modification. |
| 190 | |
| 191 | |
| 192 | .. data:: ST_CTIME |
| 193 | |
| 194 | The "ctime" as reported by the operating system. On some systems (like Unix) is |
| 195 | the time of the last metadata change, and, on others (like Windows), is the |
| 196 | creation time (see platform documentation for details). |
| 197 | |
| 198 | The interpretation of "file size" changes according to the file type. For plain |
| 199 | files this is the size of the file in bytes. For FIFOs and sockets under most |
| 200 | flavors of Unix (including Linux in particular), the "size" is the number of |
| 201 | bytes waiting to be read at the time of the call to :func:`os.stat`, |
| 202 | :func:`os.fstat`, or :func:`os.lstat`; this can sometimes be useful, especially |
| 203 | for polling one of these special files after a non-blocking open. The meaning |
| 204 | of the size field for other character and block devices varies more, depending |
| 205 | on the implementation of the underlying system call. |
| 206 | |
Alexandre Vassalotti | c22c6f2 | 2009-07-21 00:51:58 +0000 | [diff] [blame] | 207 | The variables below define the flags used in the :data:`ST_MODE` field. |
| 208 | |
| 209 | Use of the functions above is more portable than use of the first set of flags: |
| 210 | |
Alexandre Vassalotti | c22c6f2 | 2009-07-21 00:51:58 +0000 | [diff] [blame] | 211 | .. data:: S_IFSOCK |
| 212 | |
| 213 | Socket. |
| 214 | |
| 215 | .. data:: S_IFLNK |
| 216 | |
| 217 | Symbolic link. |
| 218 | |
| 219 | .. data:: S_IFREG |
| 220 | |
| 221 | Regular file. |
| 222 | |
| 223 | .. data:: S_IFBLK |
| 224 | |
| 225 | Block device. |
| 226 | |
| 227 | .. data:: S_IFDIR |
| 228 | |
| 229 | Directory. |
| 230 | |
| 231 | .. data:: S_IFCHR |
| 232 | |
| 233 | Character device. |
| 234 | |
| 235 | .. data:: S_IFIFO |
| 236 | |
| 237 | FIFO. |
| 238 | |
Christian Heimes | c77d9f3 | 2013-06-22 21:05:02 +0200 | [diff] [blame] | 239 | .. data:: S_IFDOOR |
| 240 | |
| 241 | Door. |
| 242 | |
| 243 | .. versionadded:: 3.4 |
| 244 | |
| 245 | .. data:: S_IFPORT |
| 246 | |
| 247 | Event port. |
| 248 | |
| 249 | .. versionadded:: 3.4 |
| 250 | |
| 251 | .. data:: S_IFWHT |
| 252 | |
| 253 | Whiteout. |
| 254 | |
| 255 | .. versionadded:: 3.4 |
| 256 | |
| 257 | .. note:: |
| 258 | |
| 259 | :data:`S_IFDOOR`, :data:`S_IFPORT` or :data:`S_IFWHT` are defined as |
| 260 | 0 when the platform does not have support for the file types. |
| 261 | |
Alexandre Vassalotti | c22c6f2 | 2009-07-21 00:51:58 +0000 | [diff] [blame] | 262 | The following flags can also be used in the *mode* argument of :func:`os.chmod`: |
| 263 | |
| 264 | .. data:: S_ISUID |
| 265 | |
| 266 | Set UID bit. |
| 267 | |
| 268 | .. data:: S_ISGID |
| 269 | |
| 270 | Set-group-ID bit. This bit has several special uses. For a directory |
| 271 | it indicates that BSD semantics is to be used for that directory: |
| 272 | files created there inherit their group ID from the directory, not |
| 273 | from the effective group ID of the creating process, and directories |
| 274 | created there will also get the :data:`S_ISGID` bit set. For a |
| 275 | file that does not have the group execution bit (:data:`S_IXGRP`) |
| 276 | set, the set-group-ID bit indicates mandatory file/record locking |
| 277 | (see also :data:`S_ENFMT`). |
| 278 | |
| 279 | .. data:: S_ISVTX |
| 280 | |
| 281 | Sticky bit. When this bit is set on a directory it means that a file |
| 282 | in that directory can be renamed or deleted only by the owner of the |
| 283 | file, by the owner of the directory, or by a privileged process. |
| 284 | |
| 285 | .. data:: S_IRWXU |
| 286 | |
| 287 | Mask for file owner permissions. |
| 288 | |
| 289 | .. data:: S_IRUSR |
| 290 | |
| 291 | Owner has read permission. |
| 292 | |
| 293 | .. data:: S_IWUSR |
| 294 | |
| 295 | Owner has write permission. |
| 296 | |
| 297 | .. data:: S_IXUSR |
| 298 | |
| 299 | Owner has execute permission. |
| 300 | |
| 301 | .. data:: S_IRWXG |
| 302 | |
| 303 | Mask for group permissions. |
| 304 | |
| 305 | .. data:: S_IRGRP |
| 306 | |
| 307 | Group has read permission. |
| 308 | |
| 309 | .. data:: S_IWGRP |
| 310 | |
| 311 | Group has write permission. |
| 312 | |
| 313 | .. data:: S_IXGRP |
| 314 | |
| 315 | Group has execute permission. |
| 316 | |
| 317 | .. data:: S_IRWXO |
| 318 | |
| 319 | Mask for permissions for others (not in group). |
| 320 | |
| 321 | .. data:: S_IROTH |
| 322 | |
| 323 | Others have read permission. |
| 324 | |
| 325 | .. data:: S_IWOTH |
| 326 | |
| 327 | Others have write permission. |
| 328 | |
| 329 | .. data:: S_IXOTH |
| 330 | |
| 331 | Others have execute permission. |
| 332 | |
| 333 | .. data:: S_ENFMT |
| 334 | |
| 335 | System V file locking enforcement. This flag is shared with :data:`S_ISGID`: |
| 336 | file/record locking is enforced on files that do not have the group |
| 337 | execution bit (:data:`S_IXGRP`) set. |
| 338 | |
| 339 | .. data:: S_IREAD |
| 340 | |
| 341 | Unix V7 synonym for :data:`S_IRUSR`. |
| 342 | |
| 343 | .. data:: S_IWRITE |
| 344 | |
| 345 | Unix V7 synonym for :data:`S_IWUSR`. |
| 346 | |
| 347 | .. data:: S_IEXEC |
| 348 | |
| 349 | Unix V7 synonym for :data:`S_IXUSR`. |
| 350 | |
R David Murray | 3017806 | 2011-03-10 17:18:33 -0500 | [diff] [blame] | 351 | The following flags can be used in the *flags* argument of :func:`os.chflags`: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 352 | |
R David Murray | 3017806 | 2011-03-10 17:18:33 -0500 | [diff] [blame] | 353 | .. data:: UF_NODUMP |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 354 | |
R David Murray | 3017806 | 2011-03-10 17:18:33 -0500 | [diff] [blame] | 355 | Do not dump the file. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 356 | |
R David Murray | 3017806 | 2011-03-10 17:18:33 -0500 | [diff] [blame] | 357 | .. data:: UF_IMMUTABLE |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 358 | |
R David Murray | 3017806 | 2011-03-10 17:18:33 -0500 | [diff] [blame] | 359 | The file may not be changed. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 360 | |
R David Murray | 3017806 | 2011-03-10 17:18:33 -0500 | [diff] [blame] | 361 | .. data:: UF_APPEND |
| 362 | |
| 363 | The file may only be appended to. |
| 364 | |
Ned Deily | 3eb67d5 | 2011-06-28 00:00:28 -0700 | [diff] [blame] | 365 | .. data:: UF_OPAQUE |
| 366 | |
| 367 | The directory is opaque when viewed through a union stack. |
| 368 | |
Mark Dickinson | 40d9ebe | 2011-06-25 12:03:33 +0200 | [diff] [blame] | 369 | .. data:: UF_NOUNLINK |
R David Murray | 3017806 | 2011-03-10 17:18:33 -0500 | [diff] [blame] | 370 | |
| 371 | The file may not be renamed or deleted. |
| 372 | |
Ned Deily | 3eb67d5 | 2011-06-28 00:00:28 -0700 | [diff] [blame] | 373 | .. data:: UF_COMPRESSED |
R David Murray | 3017806 | 2011-03-10 17:18:33 -0500 | [diff] [blame] | 374 | |
Ned Deily | 3eb67d5 | 2011-06-28 00:00:28 -0700 | [diff] [blame] | 375 | The file is stored compressed (Mac OS X 10.6+). |
| 376 | |
| 377 | .. data:: UF_HIDDEN |
| 378 | |
| 379 | The file should not be displayed in a GUI (Mac OS X 10.5+). |
R David Murray | 3017806 | 2011-03-10 17:18:33 -0500 | [diff] [blame] | 380 | |
| 381 | .. data:: SF_ARCHIVED |
| 382 | |
| 383 | The file may be archived. |
| 384 | |
| 385 | .. data:: SF_IMMUTABLE |
| 386 | |
| 387 | The file may not be changed. |
| 388 | |
| 389 | .. data:: SF_APPEND |
| 390 | |
| 391 | The file may only be appended to. |
| 392 | |
| 393 | .. data:: SF_NOUNLINK |
| 394 | |
| 395 | The file may not be renamed or deleted. |
| 396 | |
| 397 | .. data:: SF_SNAPSHOT |
| 398 | |
| 399 | The file is a snapshot file. |
| 400 | |
| 401 | See the \*BSD or Mac OS systems man page :manpage:`chflags(2)` for more information. |
Zachary Ware | 63f277b | 2014-06-19 09:46:37 -0500 | [diff] [blame] | 402 | |
| 403 | On Windows, the following file attribute constants are available for use when |
| 404 | testing bits in the ``st_file_attributes`` member returned by :func:`os.stat`. |
| 405 | See the `Windows API documentation |
| 406 | <http://msdn.microsoft.com/en-us/library/windows/desktop/gg258117.aspx>`_ |
| 407 | for more detail on the meaning of these constants. |
| 408 | |
| 409 | .. data:: FILE_ATTRIBUTE_ARCHIVE |
| 410 | FILE_ATTRIBUTE_COMPRESSED |
| 411 | FILE_ATTRIBUTE_DEVICE |
| 412 | FILE_ATTRIBUTE_DIRECTORY |
| 413 | FILE_ATTRIBUTE_ENCRYPTED |
| 414 | FILE_ATTRIBUTE_HIDDEN |
| 415 | FILE_ATTRIBUTE_INTEGRITY_STREAM |
| 416 | FILE_ATTRIBUTE_NORMAL |
| 417 | FILE_ATTRIBUTE_NOT_CONTENT_INDEXED |
| 418 | FILE_ATTRIBUTE_NO_SCRUB_DATA |
| 419 | FILE_ATTRIBUTE_OFFLINE |
| 420 | FILE_ATTRIBUTE_READONLY |
| 421 | FILE_ATTRIBUTE_REPARSE_POINT |
| 422 | FILE_ATTRIBUTE_SPARSE_FILE |
| 423 | FILE_ATTRIBUTE_SYSTEM |
| 424 | FILE_ATTRIBUTE_TEMPORARY |
| 425 | FILE_ATTRIBUTE_VIRTUAL |
| 426 | |
| 427 | .. versionadded:: 3.5 |