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