Various cleanups & markup fixes, mostly relating to the stat and statvfs

result object changes.

1 files changed, 77 insertions, 38 deletions

diff --git a/Doc/lib/libos.tex b/Doc/lib/libos.tex
index a1755d7..f8cda4c 100644
--- a/Doc/lib/libos.tex
+++ b/Doc/lib/libos.tex
@@ -59,15 +59,13 @@ involve a file system path (such as \function{chdir()} or
 \function{unlink()}), the exception instance will contain a third
 attribute, \member{filename}, which is the file name passed to the
 function.
-
-When exceptions are strings, the string for the exception is
-\code{'OSError'}.
 \end{excdesc}
 
 \begin{datadesc}{name}
 The name of the operating system dependent module imported.  The
-following names have currently been registered: \code{'posix'}, \code{'nt'},
-\code{'dos'}, \code{'mac'}, \code{'os2'}, \code{'ce'}, \code{'java'}.
+following names have currently been registered: \code{'posix'},
+\code{'nt'}, \code{'dos'}, \code{'mac'}, \code{'os2'}, \code{'ce'},
+\code{'java'}, \code{'riscos'}.
 \end{datadesc}
 
 \begin{datadesc}{path}
@@ -745,49 +743,89 @@ Availability: Macintosh, \UNIX, Windows.
 
 \begin{funcdesc}{stat}{path}
 Perform a \cfunction{stat()} system call on the given path.  The
-return value is a tuple of at least 10 integers giving the most
-important (and portable) members of the \emph{stat} structure, in the
+return value is an object whose attributes correspond to the members of
+the \ctype{stat} structure, namely:
+\member{st_mode} (protection bits),
+\member{st_ino} (inode number),
+\member{st_dev} (device),
+\member{st_nlink} (number of hard links,
+\member{st_uid} (user ID of owner),
+\member{st_gid} (group ID of owner),
+\member{st_size} (size of file, in bytes),
+\member{st_atime} (time of most recent access),
+\member{st_mtime} (time of most recent content modification),
+\member{st_ctime}
+(time of most recent content modification or metadata change).
+
+On some Unix systems (such as Linux), the following attributes may
+also be available:
+\member{st_blocks} (number of blocks allocated for file),
+\member{st_blksize} (filesystem blocksize),
+\member{st_rdev} (type of device if an inode device).
+
+On Mac OS systems, the following attributes may also be available:
+\member{st_rsize},
+\member{st_creator},
+\member{st_type}.
+
+On RISCOS systems, the following attributes are also available:
+\member{st_ftype} (file type),
+\member{st_attrs} (attributes),
+\member{st_obtype} (object type).
+
+For backward compatibility, the return value of \function{stat()} is
+also accessible as a tuple of at least 10 integers giving the most
+important (and portable) members of the \ctype{stat} structure, in the
 order
-\code{st_mode},
-\code{st_ino},
-\code{st_dev},
-\code{st_nlink},
-\code{st_uid},
-\code{st_gid},
-\code{st_size},
-\code{st_atime},
-\code{st_mtime},
-\code{st_ctime}.
+\member{st_mode},
+\member{st_ino},
+\member{st_dev},
+\member{st_nlink},
+\member{st_uid},
+\member{st_gid},
+\member{st_size},
+\member{st_atime},
+\member{st_mtime},
+\member{st_ctime}.
 More items may be added at the end by some implementations.  Note that
 on the Mac OS, the time values are floating point values, like all
 time values on the Mac OS.
+The standard module \refmodule{stat}\refstmodindex{stat} defines
+functions and constants that are useful for extracting information
+from a \ctype{stat} structure.
 (On Windows, some items are filled with dummy values.)
 Availability: Macintosh, \UNIX, Windows.
 
-Note: The standard module \refmodule{stat}\refstmodindex{stat} defines
-functions and constants that are useful for extracting information
-from a \ctype{stat} structure.
+\versionchanged
+[Added access to values as attributes of the returned object]{2.2}
 \end{funcdesc}
 
 \begin{funcdesc}{statvfs}{path}
 Perform a \cfunction{statvfs()} system call on the given path.  The
-return value is a tuple of 10 integers giving the most common
-members of the \ctype{statvfs} structure, in the order
-\code{f_bsize},
-\code{f_frsize},
-\code{f_blocks},
-\code{f_bfree},
-\code{f_bavail},
-\code{f_files},
-\code{f_ffree},
-\code{f_favail},
-\code{f_flag},
-\code{f_namemax}.
+return value is an object whose attributes describe the filesystem on
+the given path, and correspond to the members of the
+\ctype{statvfs} structure, namely:
+\member{f_frsize},
+\member{f_blocks},
+\member{f_bfree},
+\member{f_bavail},
+\member{f_files},
+\member{f_ffree},
+\member{f_favail},
+\member{f_flag},
+\member{f_namemax}.
 Availability: \UNIX.
 
-Note: The standard module \module{statvfs}\refstmodindex{statvfs}
+For backward compatibility, the return value is also accessible as a
+tuple whose values correspond to the attributes, in the order given above.
+The standard module \refmodule{statvfs}\refstmodindex{statvfs}
 defines constants that are useful for extracting information
-from a \ctype{statvfs} structure.
+from a \ctype{statvfs} structure when accessing it as a sequence; this
+remains useful when writing code that needs to work with versions of
+Python that don't support accessing the fields as attributes.
+
+\versionchanged
+[Added access to values as attributes of the returned object]{2.2}
 \end{funcdesc}
 
 \begin{funcdesc}{symlink}{src, dst}
@@ -933,7 +971,7 @@ Availability: \UNIX.
 Fork a child process, using a new pseudo-terminal as the child's
 controlling terminal. Return a pair of \code{(\var{pid}, \var{fd})},
 where \var{pid} is \code{0} in the child, the new child's process id
-in the parent, and \code{fd} is the file descriptor of the master end
+in the parent, and \var{fd} is the file descriptor of the master end
 of the pseudo-terminal.  For a more portable approach, use the
 \refmodule{pty} module.
 Availability: Some flavors of \UNIX.
@@ -1266,13 +1304,14 @@ search patch components (as in \envvar{PATH}), such as \character{:} for
 \end{datadesc}
 
 \begin{datadesc}{defpath}
-The default search path used by \function{exec*p*()} if the environment
-doesn't have a \code{'PATH'} key.
+The default search path used by \function{exec*p*()} and
+\function{spawn*p*()} if the environment doesn't have a \code{'PATH'}
+key.
 \end{datadesc}
 
 \begin{datadesc}{linesep}
 The string used to separate (or, rather, terminate) lines on the
 current platform.  This may be a single character, such as \code{'\e
-n'} for \POSIX{} or \code{'\e r'} for the Mac OS, or multiple characters,
+n'} for \POSIX{} or \code{'\e r'} for Mac OS, or multiple characters,
 for example, \code{'\e r\e n'} for DOS and Windows.
 \end{datadesc}