Doc/lib/libstat.tex

   1 \section{\module{stat} ---
   2          Interpreting \function{stat()} results}
   3
   4 \declaremodule{standard}{stat}
   5 \modulesynopsis{Utilities for interpreting the results of
   6   \function{os.stat()}, \function{os.lstat()} and \function{os.fstat()}.}
   7 \sectionauthor{Skip Montanaro}{skip@automatrix.com}
   8
   9
  10 The \module{stat} module defines constants and functions for
  11 interpreting the results of \function{os.stat()},
  12 \function{os.fstat()} and \function{os.lstat()} (if they exist).  For
  13 complete details about the \cfunction{stat()}, \cfunction{fstat()} and
  14 \cfunction{lstat()} calls, consult the documentation for your system.
  15
  16 The \module{stat} module defines the following functions to test for
  17 specific file types:
  18
  19
  20 \begin{funcdesc}{S_ISDIR}{mode}
  21 Return non-zero if the mode is from a directory.
  22 \end{funcdesc}
  23
  24 \begin{funcdesc}{S_ISCHR}{mode}
  25 Return non-zero if the mode is from a character special device file.
  26 \end{funcdesc}
  27
  28 \begin{funcdesc}{S_ISBLK}{mode}
  29 Return non-zero if the mode is from a block special device file.
  30 \end{funcdesc}
  31
  32 \begin{funcdesc}{S_ISREG}{mode}
  33 Return non-zero if the mode is from a regular file.
  34 \end{funcdesc}
  35
  36 \begin{funcdesc}{S_ISFIFO}{mode}
  37 Return non-zero if the mode is from a FIFO (named pipe).
  38 \end{funcdesc}
  39
  40 \begin{funcdesc}{S_ISLNK}{mode}
  41 Return non-zero if the mode is from a symbolic link.
  42 \end{funcdesc}
  43
  44 \begin{funcdesc}{S_ISSOCK}{mode}
  45 Return non-zero if the mode is from a socket.
  46 \end{funcdesc}
  47
  48 Two additional functions are defined for more general manipulation of
  49 the file's mode:
  50
  51 \begin{funcdesc}{S_IMODE}{mode}
  52 Return the portion of the file's mode that can be set by
  53 \function{os.chmod()}---that is, the file's permission bits, plus the
  54 sticky bit, set-group-id, and set-user-id bits (on systems that support
  55 them).
  56 \end{funcdesc}
  57
  58 \begin{funcdesc}{S_IFMT}{mode}
  59 Return the portion of the file's mode that describes the file type (used
  60 by the \function{S_IS*()} functions above).
  61 \end{funcdesc}
  62
  63 Normally, you would use the \function{os.path.is*()} functions for
  64 testing the type of a file; the functions here are useful when you are
  65 doing multiple tests of the same file and wish to avoid the overhead of
  66 the \cfunction{stat()} system call for each test.  These are also
  67 useful when checking for information about a file that isn't handled
  68 by \refmodule{os.path}, like the tests for block and character
  69 devices.
  70
  71 All the variables below are simply symbolic indexes into the 10-tuple
  72 returned by \function{os.stat()}, \function{os.fstat()} or
  73 \function{os.lstat()}.
  74
  75 \begin{datadesc}{ST_MODE}
  76 Inode protection mode.
  77 \end{datadesc}
  78
  79 \begin{datadesc}{ST_INO}
  80 Inode number.
  81 \end{datadesc}
  82
  83 \begin{datadesc}{ST_DEV}
  84 Device inode resides on.
  85 \end{datadesc}
  86
  87 \begin{datadesc}{ST_NLINK}
  88 Number of links to the inode.
  89 \end{datadesc}
  90
  91 \begin{datadesc}{ST_UID}
  92 User id of the owner.
  93 \end{datadesc}
  94
  95 \begin{datadesc}{ST_GID}
  96 Group id of the owner.
  97 \end{datadesc}
  98
  99 \begin{datadesc}{ST_SIZE}
 100 Size in bytes of a plain file; amount of data waiting on some special
 101 files.
 102 \end{datadesc}
 103
 104 \begin{datadesc}{ST_ATIME}
 105 Time of last access.
 106 \end{datadesc}
 107
 108 \begin{datadesc}{ST_MTIME}
 109 Time of last modification.
 110 \end{datadesc}
 111
 112 \begin{datadesc}{ST_CTIME}
 113 The ``ctime'' as reported by the operating system.  On some systems
 114 (like \UNIX) is the time of the last metadata change, and, on others
 115 (like Windows), is the creation time (see platform documentation for
 116 details).
 117 \end{datadesc}
 118
 119 The interpretation of ``file size'' changes according to the file
 120 type.  For plain files this is the size of the file in bytes.  For
 121 FIFOs and sockets under most flavors of \UNIX{} (including Linux in
 122 particular), the ``size'' is the number of bytes waiting to be read at
 123 the time of the call to \function{os.stat()}, \function{os.fstat()},
 124 or \function{os.lstat()}; this can sometimes be useful, especially for
 125 polling one of these special files after a non-blocking open.  The
 126 meaning of the size field for other character and block devices varies
 127 more, depending on the implementation of the underlying system call.
 128
 129 Example:
 130
 131 \begin{verbatim}
 132 import os, sys
 133 from stat import *
 134
 135 def walktree(top, callback):
 136     '''recursively descend the directory tree rooted at top,
 137        calling the callback function for each regular file'''
 138
 139     for f in os.listdir(top):
 140         pathname = os.path.join(top, f)
 141         mode = os.stat(pathname)[ST_MODE]
 142         if S_ISDIR(mode):
 143             # It's a directory, recurse into it
 144             walktree(pathname, callback)
 145         elif S_ISREG(mode):
 146             # It's a file, call the callback function
 147             callback(pathname)
 148         else:
 149             # Unknown file type, print a message
 150             print 'Skipping %s' % pathname
 151
 152 def visitfile(file):
 153     print 'visiting', file
 154
 155 if __name__ == '__main__':
 156     walktree(sys.argv[1], visitfile)
 157 \end{verbatim}