• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 <skip@automatrix.com>
9
10**Source code:** :source:`Lib/stat.py`
11
12--------------
13
14The :mod:`stat` module defines constants and functions for interpreting the
15results of :func:`os.stat`, :func:`os.fstat` and :func:`os.lstat` (if they
16exist).  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
22The :mod:`stat` module defines the following functions to test for specific file
23types:
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
78Two additional functions are defined for more general manipulation of the file's
79mode:
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
94Normally, you would use the :func:`os.path.is\*` functions for testing the type
95of a file; the functions here are useful when you are doing multiple tests of
96the same file and wish to avoid the overhead of the :c:func:`stat` system call
97for each test.  These are also useful when checking for information about a file
98that isn't handled by :mod:`os.path`, like the tests for block and character
99devices.
100
101Example::
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.stat(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
129An additional utility function is provided to convert a file's mode in a human
130readable 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
143All the variables below are simply symbolic indexes into the 10-tuple returned
144by :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
198The interpretation of "file size" changes according to the file type.  For plain
199files this is the size of the file in bytes.  For FIFOs and sockets under most
200flavors of Unix (including Linux in particular), the "size" is the number of
201bytes 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
203for polling one of these special files after a non-blocking open.  The meaning
204of the size field for other character and block devices varies more, depending
205on the implementation of the underlying system call.
206
207The variables below define the flags used in the :data:`ST_MODE` field.
208
209Use 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
262The 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
351The following flags can be used in the *flags* argument of :func:`os.chflags`:
352
353.. data:: UF_NODUMP
354
355   Do not dump the file.
356
357.. data:: UF_IMMUTABLE
358
359   The file may not be changed.
360
361.. data:: UF_APPEND
362
363   The file may only be appended to.
364
365.. data:: UF_OPAQUE
366
367   The directory is opaque when viewed through a union stack.
368
369.. data:: UF_NOUNLINK
370
371   The file may not be renamed or deleted.
372
373.. data:: UF_COMPRESSED
374
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+).
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
401See the \*BSD or Mac OS systems man page :manpage:`chflags(2)` for more information.
402
403On Windows, the following file attribute constants are available for use when
404testing bits in the ``st_file_attributes`` member returned by :func:`os.stat`.
405See the `Windows API documentation
406<https://msdn.microsoft.com/en-us/library/windows/desktop/gg258117.aspx>`_
407for 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
428