\section{\module{stat} ---
         Interpreting \function{stat()} results}

\declaremodule{standard}{stat}
\modulesynopsis{Utilities for interpreting the results of
  \function{os.stat()}, \function{os.lstat()} and \function{os.fstat()}.}
\sectionauthor{Skip Montanaro}{skip@automatrix.com}


The \module{stat} module defines constants and functions for
interpreting the results of \function{os.stat()},
\function{os.fstat()} and \function{os.lstat()} (if they exist).  For
complete details about the \cfunction{stat()}, \cfunction{fstat()} and
\cfunction{lstat()} calls, consult the documentation for your system.

The \module{stat} module defines the following functions to test for
specific file types:


\begin{funcdesc}{S_ISDIR}{mode}
Return non-zero if the mode is from a directory.
\end{funcdesc}

\begin{funcdesc}{S_ISCHR}{mode}
Return non-zero if the mode is from a character special device file.
\end{funcdesc}

\begin{funcdesc}{S_ISBLK}{mode}
Return non-zero if the mode is from a block special device file.
\end{funcdesc}

\begin{funcdesc}{S_ISREG}{mode}
Return non-zero if the mode is from a regular file.
\end{funcdesc}

\begin{funcdesc}{S_ISFIFO}{mode}
Return non-zero if the mode is from a FIFO (named pipe).
\end{funcdesc}

\begin{funcdesc}{S_ISLNK}{mode}
Return non-zero if the mode is from a symbolic link.
\end{funcdesc}

\begin{funcdesc}{S_ISSOCK}{mode}
Return non-zero if the mode is from a socket.
\end{funcdesc}

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

\begin{funcdesc}{S_IMODE}{mode}
Return the portion of the file's mode that can be set by
\function{os.chmod()}---that is, the file's permission bits, plus the
sticky bit, set-group-id, and set-user-id bits (on systems that support
them).
\end{funcdesc}

\begin{funcdesc}{S_IFMT}{mode}
Return the portion of the file's mode that describes the file type (used
by the \function{S_IS*()} functions above).
\end{funcdesc}

Normally, you would use the \function{os.path.is*()} functions for
testing the type of a file; the functions here are useful when you are
doing multiple tests of the same file and wish to avoid the overhead of
the \cfunction{stat()} system call for each test.  These are also
useful when checking for information about a file that isn't handled
by \refmodule{os.path}, like the tests for block and character
devices.

All the variables below are simply symbolic indexes into the 10-tuple
returned by \function{os.stat()}, \function{os.fstat()} or
\function{os.lstat()}.

\begin{datadesc}{ST_MODE}
Inode protection mode.
\end{datadesc}

\begin{datadesc}{ST_INO}
Inode number.
\end{datadesc}

\begin{datadesc}{ST_DEV}
Device inode resides on.
\end{datadesc}

\begin{datadesc}{ST_NLINK}
Number of links to the inode.
\end{datadesc}

\begin{datadesc}{ST_UID}
User id of the owner.
\end{datadesc}

\begin{datadesc}{ST_GID}
Group id of the owner.
\end{datadesc}

\begin{datadesc}{ST_SIZE}
Size in bytes of a plain file; amount of data waiting on some special
files.
\end{datadesc}

\begin{datadesc}{ST_ATIME}
Time of last access.
\end{datadesc}

\begin{datadesc}{ST_MTIME}
Time of last modification.
\end{datadesc}

\begin{datadesc}{ST_CTIME}
Time of last status change (see manual pages for details).
\end{datadesc}

The interpretation of ``file size'' changes according to the file
type.  For plain files this is the size of the file in bytes.  For
FIFOs and sockets under most flavors of \UNIX{} (including Linux in
particular), the ``size'' is the number of bytes waiting to be read at
the time of the call to \function{os.stat()}, \function{os.fstat()},
or \function{os.lstat()}; this can sometimes be useful, especially for
polling one of these special files after a non-blocking open.  The
meaning of the size field for other character and block devices varies
more, depending on the implementation of the underlying system call.

Example:

\begin{verbatim}
import os, sys
from stat import *

def walktree(top, callback):
    '''recursively descend the directory tree rooted at top,
       calling the callback function for each regular file'''

    for f in os.listdir(top):
        pathname = os.path.join(top, f)
        mode = os.stat(pathname)[ST_MODE]
        if S_ISDIR(mode):
            # It's a directory, recurse into it
            walktree(pathname, callback)
        elif S_ISREG(mode):
            # It's a file, call the callback function
            callback(pathname)
        else:
            # Unknown file type, print a message
            print 'Skipping %s' % pathname

def visitfile(file):
    print 'visiting', file

if __name__ == '__main__':
    walktree(sys.argv[1], visitfile)
\end{verbatim}