| 1 |
:mod:`!stat` --- Interpreting :func:`~os.stat` results |
| 2 |
====================================================== |
| 3 |
|
| 4 |
.. module:: stat |
| 5 |
:synopsis: Utilities for interpreting the results of os.stat(), |
| 6 |
os.lstat() and os.fstat(). |
| 7 |
|
| 8 |
.. sectionauthor:: Skip Montanaro <[email protected]> |
| 9 |
|
| 10 |
**Source code:** :source:`Lib/stat.py` |
| 11 |
|
| 12 |
-------------- |
| 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 |
| 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. |
| 18 |
|
| 19 |
.. versionchanged:: 3.4 |
| 20 |
The stat module is backed by a C implementation. |
| 21 |
|
| 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 |
|
| 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 |
|
| 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 |
| 85 |
:func:`os.chmod`\ ---that is, the file's permission bits, plus the sticky |
| 86 |
bit, set-group-id, and 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 |
| 96 |
the same file and wish to avoid the overhead of the :c:func:`stat` system call |
| 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 |
|
| 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) |
| 112 |
mode = os.lstat(pathname).st_mode |
| 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 |
|
| 129 |
An additional utility function is provided to convert a file's mode in a human |
| 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 |
|
| 138 |
.. versionchanged:: 3.4 |
| 139 |
The function supports :data:`S_IFDOOR`, :data:`S_IFPORT` and |
| 140 |
:data:`S_IFWHT`. |
| 141 |
|
| 142 |
|
| 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 |
|
| 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 |
|
| 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 |
|
| 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 |
|
| 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 |
|
| 351 |
The following flags can be used in the *flags* argument of :func:`os.chflags`: |
| 352 |
|
| 353 |
.. data:: UF_SETTABLE |
| 354 |
|
| 355 |
All user settable flags. |
| 356 |
|
| 357 |
.. versionadded:: 3.13 |
| 358 |
|
| 359 |
.. data:: UF_NODUMP |
| 360 |
|
| 361 |
Do not dump the file. |
| 362 |
|
| 363 |
.. data:: UF_IMMUTABLE |
| 364 |
|
| 365 |
The file may not be changed. |
| 366 |
|
| 367 |
.. data:: UF_APPEND |
| 368 |
|
| 369 |
The file may only be appended to. |
| 370 |
|
| 371 |
.. data:: UF_OPAQUE |
| 372 |
|
| 373 |
The directory is opaque when viewed through a union stack. |
| 374 |
|
| 375 |
.. data:: UF_NOUNLINK |
| 376 |
|
| 377 |
The file may not be renamed or deleted. |
| 378 |
|
| 379 |
.. data:: UF_COMPRESSED |
| 380 |
|
| 381 |
The file is stored compressed (macOS 10.6+). |
| 382 |
|
| 383 |
.. data:: UF_TRACKED |
| 384 |
|
| 385 |
Used for handling document IDs (macOS) |
| 386 |
|
| 387 |
.. versionadded:: 3.13 |
| 388 |
|
| 389 |
.. data:: UF_DATAVAULT |
| 390 |
|
| 391 |
The file needs an entitlement for reading or writing (macOS 10.13+) |
| 392 |
|
| 393 |
.. versionadded:: 3.13 |
| 394 |
|
| 395 |
.. data:: UF_HIDDEN |
| 396 |
|
| 397 |
The file should not be displayed in a GUI (macOS 10.5+). |
| 398 |
|
| 399 |
.. data:: SF_SETTABLE |
| 400 |
|
| 401 |
All super-user changeable flags |
| 402 |
|
| 403 |
.. versionadded:: 3.13 |
| 404 |
|
| 405 |
.. data:: SF_SUPPORTED |
| 406 |
|
| 407 |
All super-user supported flags |
| 408 |
|
| 409 |
.. availability:: macOS |
| 410 |
|
| 411 |
.. versionadded:: 3.13 |
| 412 |
|
| 413 |
.. data:: SF_SYNTHETIC |
| 414 |
|
| 415 |
All super-user read-only synthetic flags |
| 416 |
|
| 417 |
.. availability:: macOS |
| 418 |
|
| 419 |
.. versionadded:: 3.13 |
| 420 |
|
| 421 |
.. data:: SF_ARCHIVED |
| 422 |
|
| 423 |
The file may be archived. |
| 424 |
|
| 425 |
.. data:: SF_IMMUTABLE |
| 426 |
|
| 427 |
The file may not be changed. |
| 428 |
|
| 429 |
.. data:: SF_APPEND |
| 430 |
|
| 431 |
The file may only be appended to. |
| 432 |
|
| 433 |
.. data:: SF_RESTRICTED |
| 434 |
|
| 435 |
The file needs an entitlement to write to (macOS 10.13+) |
| 436 |
|
| 437 |
.. versionadded:: 3.13 |
| 438 |
|
| 439 |
.. data:: SF_NOUNLINK |
| 440 |
|
| 441 |
The file may not be renamed or deleted. |
| 442 |
|
| 443 |
.. data:: SF_SNAPSHOT |
| 444 |
|
| 445 |
The file is a snapshot file. |
| 446 |
|
| 447 |
.. data:: SF_FIRMLINK |
| 448 |
|
| 449 |
The file is a firmlink (macOS 10.15+) |
| 450 |
|
| 451 |
.. versionadded:: 3.13 |
| 452 |
|
| 453 |
.. data:: SF_DATALESS |
| 454 |
|
| 455 |
The file is a dataless object (macOS 10.15+) |
| 456 |
|
| 457 |
.. versionadded:: 3.13 |
| 458 |
|
| 459 |
See the \*BSD or macOS systems man page :manpage:`chflags(2)` for more information. |
| 460 |
|
| 461 |
On Windows, the following file attribute constants are available for use when |
| 462 |
testing bits in the ``st_file_attributes`` member returned by :func:`os.stat`. |
| 463 |
See the `Windows API documentation |
| 464 |
<https://msdn.microsoft.com/en-us/library/windows/desktop/gg258117.aspx>`_ |
| 465 |
for more detail on the meaning of these constants. |
| 466 |
|
| 467 |
.. data:: FILE_ATTRIBUTE_ARCHIVE |
| 468 |
FILE_ATTRIBUTE_COMPRESSED |
| 469 |
FILE_ATTRIBUTE_DEVICE |
| 470 |
FILE_ATTRIBUTE_DIRECTORY |
| 471 |
FILE_ATTRIBUTE_ENCRYPTED |
| 472 |
FILE_ATTRIBUTE_HIDDEN |
| 473 |
FILE_ATTRIBUTE_INTEGRITY_STREAM |
| 474 |
FILE_ATTRIBUTE_NORMAL |
| 475 |
FILE_ATTRIBUTE_NOT_CONTENT_INDEXED |
| 476 |
FILE_ATTRIBUTE_NO_SCRUB_DATA |
| 477 |
FILE_ATTRIBUTE_OFFLINE |
| 478 |
FILE_ATTRIBUTE_READONLY |
| 479 |
FILE_ATTRIBUTE_REPARSE_POINT |
| 480 |
FILE_ATTRIBUTE_SPARSE_FILE |
| 481 |
FILE_ATTRIBUTE_SYSTEM |
| 482 |
FILE_ATTRIBUTE_TEMPORARY |
| 483 |
FILE_ATTRIBUTE_VIRTUAL |
| 484 |
|
| 485 |
.. versionadded:: 3.5 |
| 486 |
|
| 487 |
On Windows, the following constants are available for comparing against the |
| 488 |
``st_reparse_tag`` member returned by :func:`os.lstat`. These are well-known |
| 489 |
constants, but are not an exhaustive list. |
| 490 |
|
| 491 |
.. data:: IO_REPARSE_TAG_SYMLINK |
| 492 |
IO_REPARSE_TAG_MOUNT_POINT |
| 493 |
IO_REPARSE_TAG_APPEXECLINK |
| 494 |
|
| 495 |
.. versionadded:: 3.8 |