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 Time of last status change (see manual pages for details).
 114 \end{datadesc}
 115
 116 The interpretation of ``file size'' changes according to the file
 117 type.  For plain files this is the size of the file in bytes.  For
 118 FIFOs and sockets under most Unixes (including Linux in particular),
 119 the ``size'' is the number of bytes waiting to be read at the time of
 120 the call to \function{os.stat()}, \function{os.fstat()}, or
 121 \function{os.lstat()}; this can sometimes be useful, especially for
 122 polling one of these special files after a non-blocking open.  The
 123 meaning of the size field for other character and block devices varies
 124 more, depending on the implementation of the underlying system call.
 125
 126 Example:
 127
 128 \begin{verbatim}
 129 import os, sys
 130 from stat import *
 131
 132 def walktree(dir, callback):
 133     '''recursively descend the directory rooted at dir,
 134        calling the callback function for each regular file'''
 135
 136     for f in os.listdir(dir):
 137         pathname = '%s/%s' % (dir, f)
 138         mode = os.stat(pathname)[ST_MODE]
 139         if S_ISDIR(mode):
 140             # It's a directory, recurse into it
 141             walktree(pathname, callback)
 142         elif S_ISREG(mode):
 143             # It's a file, call the callback function
 144             callback(pathname)
 145         else:
 146             # Unknown file type, print a message
 147             print 'Skipping %s' % pathname
 148
 149 def visitfile(file):
 150     print 'visiting', file
 151
 152 if __name__ == '__main__':
 153     walktree(sys.argv[1], visitfile)
 154 \end{verbatim}