Docs for stat.py -- docs by Skip Montanaro.

2 files changed, 212 insertions, 0 deletions

diff --git a/Doc/lib/libstat.tex b/Doc/lib/libstat.tex
new file mode 100644
index 0000000..67335a5
--- /dev/null
+++ b/Doc/lib/libstat.tex
@@ -0,0 +1,106 @@
+% By Skip Montanaro
+
+\section{Standard module \sectcode{stat}}
+\stmodindex{stat}
+
+The \code{stat} module defines constants and functions for interpreting the
+results of \code{os.stat} and \code{os.lstat} (if it exists).  For complete
+details about the \code{stat} and \code{lstat} system calls, consult your
+local man pages.
+
+The \code{stat} module defines the following functions:
+
+\renewcommand{\indexsubitem}{(in module stat)}
+
+\begin{funcdesc}{S_ISDIR}{mode}
+Return non-zero if the mode was gotten from a directory file.
+\end{funcdesc}
+
+\begin{funcdesc}{S_ISCHR}{mode}
+Return non-zero if the mode was gotten from a character special device.
+\end{funcdesc}
+
+\begin{funcdesc}{S_ISREG}{mode}
+Return non-zero if the mode was gotten from a regular file.
+\end{funcdesc}
+
+\begin{funcdesc}{S_ISFIFO}{mode}
+Return non-zero if the mode was gotten from a FIFO.
+\end{funcdesc}
+
+\begin{funcdesc}{S_ISLNK}{mode}
+Return non-zero if the mode was gotten from a symbolic link.
+\end{funcdesc}
+
+\begin{funcdesc}{S_ISSOCK}{mode}
+Return non-zero if the mode was gotten from a socket.
+\end{funcdesc}
+
+All the data items below are simply symbolic indexes into the 10-tuple
+returned by \code{os.stat} or \code{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}
+File size in bytes.
+\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 creation.
+\end{datadesc}
+
+Example:
+
+\begin{verbatim}
+import os, sys
+from stat import *
+
+def process(dir, func):
+    '''recursively descend the directory rooted at dir, calling func for
+       each regular file'''
+
+    for f in os.listdir(dir):
+        mode = os.stat('%s/%s' % (dir, f))[ST_MODE]
+        if S_ISDIR(mode):
+            # recurse into directory
+            process('%s/%s' % (dir, f), func)
+        elif S_ISREG(mode):
+            func('%s/%s' % (dir, f))
+        else:
+            print 'Skipping %s/%s' % (dir, f)
+
+def f(file):
+    print 'frobbed', file
+
+if __name__ == '__main__': process(sys.argv[1], f)
+\end{verbatim}
diff --git a/Doc/libstat.tex b/Doc/libstat.tex
new file mode 100644
index 0000000..67335a5
--- /dev/null
+++ b/Doc/libstat.tex
@@ -0,0 +1,106 @@
+% By Skip Montanaro
+
+\section{Standard module \sectcode{stat}}
+\stmodindex{stat}
+
+The \code{stat} module defines constants and functions for interpreting the
+results of \code{os.stat} and \code{os.lstat} (if it exists).  For complete
+details about the \code{stat} and \code{lstat} system calls, consult your
+local man pages.
+
+The \code{stat} module defines the following functions:
+
+\renewcommand{\indexsubitem}{(in module stat)}
+
+\begin{funcdesc}{S_ISDIR}{mode}
+Return non-zero if the mode was gotten from a directory file.
+\end{funcdesc}
+
+\begin{funcdesc}{S_ISCHR}{mode}
+Return non-zero if the mode was gotten from a character special device.
+\end{funcdesc}
+
+\begin{funcdesc}{S_ISREG}{mode}
+Return non-zero if the mode was gotten from a regular file.
+\end{funcdesc}
+
+\begin{funcdesc}{S_ISFIFO}{mode}
+Return non-zero if the mode was gotten from a FIFO.
+\end{funcdesc}
+
+\begin{funcdesc}{S_ISLNK}{mode}
+Return non-zero if the mode was gotten from a symbolic link.
+\end{funcdesc}
+
+\begin{funcdesc}{S_ISSOCK}{mode}
+Return non-zero if the mode was gotten from a socket.
+\end{funcdesc}
+
+All the data items below are simply symbolic indexes into the 10-tuple
+returned by \code{os.stat} or \code{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}
+File size in bytes.
+\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 creation.
+\end{datadesc}
+
+Example:
+
+\begin{verbatim}
+import os, sys
+from stat import *
+
+def process(dir, func):
+    '''recursively descend the directory rooted at dir, calling func for
+       each regular file'''
+
+    for f in os.listdir(dir):
+        mode = os.stat('%s/%s' % (dir, f))[ST_MODE]
+        if S_ISDIR(mode):
+            # recurse into directory
+            process('%s/%s' % (dir, f), func)
+        elif S_ISREG(mode):
+            func('%s/%s' % (dir, f))
+        else:
+            print 'Skipping %s/%s' % (dir, f)
+
+def f(file):
+    print 'frobbed', file
+
+if __name__ == '__main__': process(sys.argv[1], f)
+\end{verbatim}