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 File size in bytes.
 101 \end{datadesc}
 102
 103 \begin{datadesc}{ST_ATIME}
 104 Time of last access.
 105 \end{datadesc}
 106
 107 \begin{datadesc}{ST_MTIME}
 108 Time of last modification.
 109 \end{datadesc}
 110
 111 \begin{datadesc}{ST_CTIME}
 112 Time of last status change (see manual pages for details).
 113 \end{datadesc}
 114
 115 Example:
 116
 117 \begin{verbatim}
 118 import os, sys
 119 from stat import *
 120
 121 def walktree(dir, callback):
 122     '''recursively descend the directory rooted at dir,
 123        calling the callback function for each regular file'''
 124
 125     for f in os.listdir(dir):
 126         pathname = '%s/%s' % (dir, f)
 127         mode = os.stat(pathname)[ST_MODE]
 128         if S_ISDIR(mode):
 129             # It's a directory, recurse into it
 130             walktree(pathname, callback)
 131         elif S_ISREG(mode):
 132             # It's a file, call the callback function
 133             callback(pathname)
 134         else:
 135             # Unknown file type, print a message
 136             print 'Skipping %s' % pathname
 137
 138 def visitfile(file):
 139     print 'visiting', file
 140
 141 if __name__ == '__main__':
 142     walktree(sys.argv[1], visitfile)
 143 \end{verbatim}