1 

     2 :mod:`stat` --- Interpreting :func:`stat` results

     3 =================================================

     4 

     5 .. module:: stat

     6    :synopsis: Utilities for interpreting the results of os.stat(), os.lstat() and os.fstat().

     7 .. sectionauthor:: Skip Montanaro <skip@automatrix.com>

     8 

     9 

    10 The :mod:`stat` module defines constants and functions for interpreting the

    11 results of :func:`os.stat`, :func:`os.fstat` and :func:`os.lstat` (if they

    12 exist).  For complete details about the :cfunc:`stat`, :cfunc:`fstat` and

    13 :cfunc:`lstat` calls, consult the documentation for your system.

    14 

    15 The :mod:`stat` module defines the following functions to test for specific file

    16 types:

    17 

    18 

    19 .. function:: S_ISDIR(mode)

    20 

    21    Return non-zero if the mode is from a directory.

    22 

    23 

    24 .. function:: S_ISCHR(mode)

    25 

    26    Return non-zero if the mode is from a character special device file.

    27 

    28 

    29 .. function:: S_ISBLK(mode)

    30 

    31    Return non-zero if the mode is from a block special device file.

    32 

    33 

    34 .. function:: S_ISREG(mode)

    35 

    36    Return non-zero if the mode is from a regular file.

    37 

    38 

    39 .. function:: S_ISFIFO(mode)

    40 

    41    Return non-zero if the mode is from a FIFO (named pipe).

    42 

    43 

    44 .. function:: S_ISLNK(mode)

    45 

    46    Return non-zero if the mode is from a symbolic link.

    47 

    48 

    49 .. function:: S_ISSOCK(mode)

    50 

    51    Return non-zero if the mode is from a socket.

    52 

    53 Two additional functions are defined for more general manipulation of the file's

    54 mode:

    55 

    56 

    57 .. function:: S_IMODE(mode)

    58 

    59    Return the portion of the file's mode that can be set by :func:`os.chmod`\

    60    ---that is, the file's permission bits, plus the sticky bit, set-group-id, and

    61    set-user-id bits (on systems that support them).

    62 

    63 

    64 .. function:: S_IFMT(mode)

    65 

    66    Return the portion of the file's mode that describes the file type (used by the

    67    :func:`S_IS\*` functions above).

    68 

    69 Normally, you would use the :func:`os.path.is\*` functions for testing the type

    70 of a file; the functions here are useful when you are doing multiple tests of

    71 the same file and wish to avoid the overhead of the :cfunc:`stat` system call

    72 for each test.  These are also useful when checking for information about a file

    73 that isn't handled by :mod:`os.path`, like the tests for block and character

    74 devices.

    75 

    76 All the variables below are simply symbolic indexes into the 10-tuple returned

    77 by :func:`os.stat`, :func:`os.fstat` or :func:`os.lstat`.

    78 

    79 

    80 .. data:: ST_MODE

    81 

    82    Inode protection mode.

    83 

    84 

    85 .. data:: ST_INO

    86 

    87    Inode number.

    88 

    89 

    90 .. data:: ST_DEV

    91 

    92    Device inode resides on.

    93 

    94 

    95 .. data:: ST_NLINK

    96 

    97    Number of links to the inode.

    98 

    99 

   100 .. data:: ST_UID

   101 

   102    User id of the owner.

   103 

   104 

   105 .. data:: ST_GID

   106 

   107    Group id of the owner.

   108 

   109 

   110 .. data:: ST_SIZE

   111 

   112    Size in bytes of a plain file; amount of data waiting on some special files.

   113 

   114 

   115 .. data:: ST_ATIME

   116 

   117    Time of last access.

   118 

   119 

   120 .. data:: ST_MTIME

   121 

   122    Time of last modification.

   123 

   124 

   125 .. data:: ST_CTIME

   126 

   127    The "ctime" as reported by the operating system.  On some systems (like Unix) is

   128    the time of the last metadata change, and, on others (like Windows), is the

   129    creation time (see platform documentation for details).

   130 

   131 The interpretation of "file size" changes according to the file type.  For plain

   132 files this is the size of the file in bytes.  For FIFOs and sockets under most

   133 flavors of Unix (including Linux in particular), the "size" is the number of

   134 bytes waiting to be read at the time of the call to :func:`os.stat`,

   135 :func:`os.fstat`, or :func:`os.lstat`; this can sometimes be useful, especially

   136 for polling one of these special files after a non-blocking open.  The meaning

   137 of the size field for other character and block devices varies more, depending

   138 on the implementation of the underlying system call.

   139 

   140 Example::

   141 

   142    import os, sys

   143    from stat import *

   144 

   145    def walktree(top, callback):

   146        '''recursively descend the directory tree rooted at top,

   147           calling the callback function for each regular file'''

   148 

   149        for f in os.listdir(top):

   150            pathname = os.path.join(top, f)

   151            mode = os.stat(pathname)[ST_MODE]

   152            if S_ISDIR(mode):

   153                # It's a directory, recurse into it

   154                walktree(pathname, callback)

   155            elif S_ISREG(mode):

   156                # It's a file, call the callback function

   157                callback(pathname)

   158            else:

   159                # Unknown file type, print a message

   160                print 'Skipping %s' % pathname

   161 

   162    def visitfile(file):

   163        print 'visiting', file

   164 

   165    if __name__ == '__main__':

   166        walktree(sys.argv[1], visitfile)

   167