Take out just about everything and refer the reader to the os module.

1 files changed, 15 insertions, 516 deletions

diff --git a/Doc/lib/libposix.tex b/Doc/lib/libposix.tex
index 834b934..8431599 100644
--- a/Doc/lib/libposix.tex
+++ b/Doc/lib/libposix.tex
@@ -7,7 +7,7 @@ via module \module{os}).}
 
 
 This module provides access to operating system functionality that is
-standardized by the \C{} Standard and the \POSIX{} standard (a thinly
+standardized by the C Standard and the \POSIX{} standard (a thinly
 disguised \UNIX{} interface).
 
 \strong{Do not import this module directly.}  Instead, import the
@@ -37,7 +37,7 @@ type errors, while errors reported by the system calls raise
 \sectionauthor{Steve Clift}{clift@mail.anacapa.net}
 
 Several operating systems (including AIX, HPUX, Irix and Solaris)
-provide support for files that are larger than 2 Gb from a \C{}
+provide support for files that are larger than 2 Gb from a C
 programming model where \ctype{int} and \ctype{long} are 32-bit
 values. This is typically accomplished by defining the relevant size
 and offset types as 64-bit values. Such files are sometimes referred
@@ -60,13 +60,13 @@ CFLAGS="-D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64" OPT="-g -O2 $CFLAGS" \
 
 \subsection{\module{posix} Module Contents \label{posix-contents}}
 
-Module \module{posix} defines the following data items:
+Module \module{posix} defines the following data item:
 
 \begin{datadesc}{environ}
-A dictionary or dictionary look-alike representing the string
-environment at the time the interpreter was started. For example,
-\code{posix.environ['HOME']} is the pathname of your home directory,
-equivalent to \code{getenv("HOME")} in \C{}.
+A dictionary representing the string environment at the time the
+interpreter was started. For example, \code{environ['HOME']} is the
+pathname of your home directory, equivalent to \code{getenv("HOME")}
+in C.
 
 Modifying this dictionary does not affect the string environment
 passed on by \function{execv()}, \function{popen()} or
@@ -75,514 +75,13 @@ passed on by \function{execv()}, \function{popen()} or
 export statements to the command string for \function{system()} or
 \function{popen()}.
 
-\emph{However:} If you are using this module via the \module{os}
-module (as you should -- see the introduction above), \code{environ}
-is a a mapping object that behaves almost like a dictionary but
-invokes \function{putenv()} automatically whenever an item is changed.
+\strong{Note:} The \module{os} module provides an alternate
+implementation of \code{environ} which updates the environment on
+modification.  Note also that updating \code{os.environ} will render
+this dictionary obsolete.  Use of the \module{os} for this is
+recommended over direct access to the \module{posix} module.
 \end{datadesc}
 
-\begin{excdesc}{error}
-This exception is raised when a \POSIX{} function returns a
-\POSIX{}-related error (e.g., not for illegal argument types).  The
-accompanying value is a pair containing the numeric error code from
-\cdata{errno} and the corresponding string, as would be printed by the
-\C{} function \cfunction{perror()}.  See the module
-\module{errno}\refbimodindex{errno}, which contains names for the
-error codes defined by the underlying operating system.
-
-When exceptions are classes, this exception carries two attributes,
-\member{errno} and \member{strerror}.  The first holds the value of
-the \C{} \cdata{errno} variable, and the latter holds the
-corresponding error message from \cfunction{strerror()}.  For
-exceptions that involve a file system path (e.g. \code{chdir} or
-\code{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}
-
-It defines the following functions and constants when the operating
-system provides them directly or provides the means to emulate them:
-
-\begin{funcdesc}{access}{path, mode}
-Check read/write/execute permissions for this process or extance of file
-\var{path}.  Return \code{1} if access is granted, \code{0} if not.
-See the \UNIX{} manual for the semantics.
-\end{funcdesc}
-
-\begin{funcdesc}{chdir}{path}
-Change the current working directory to \var{path}.
-\end{funcdesc}
-
-\begin{funcdesc}{chmod}{path, mode}
-Change the mode of \var{path} to the numeric \var{mode}.
-\end{funcdesc}
-
-\begin{funcdesc}{chown}{path, uid, gid}
-Change the owner and group id of \var{path} to the numeric \var{uid}
-and \var{gid}.
-(Not on MS-DOS.)
-\end{funcdesc}
-
-\begin{funcdesc}{close}{fd}
-Close file descriptor \var{fd}.
-
-Note: this function is intended for low-level I/O and must be applied
-to a file descriptor as returned by \function{open()} or
-\function{pipe()}.  To close a ``file object'' returned by the
-built-in function \function{open()} or by \function{popen()} or
-\function{fdopen()}, use its \method{close()} method.
-\end{funcdesc}
-
-\begin{funcdesc}{dup}{fd}
-Return a duplicate of file descriptor \var{fd}.
-\end{funcdesc}
-
-\begin{funcdesc}{dup2}{fd, fd2}
-Duplicate file descriptor \var{fd} to \var{fd2}, closing the latter
-first if necessary.
-\end{funcdesc}
-
-\begin{funcdesc}{execv}{path, args}
-Execute the executable \var{path} with argument list \var{args},
-replacing the current process (i.e., the Python interpreter).
-The argument list may be a tuple or list of strings.
-(Not on MS-DOS.)
-\end{funcdesc}
-
-\begin{funcdesc}{execve}{path, args, env}
-Execute the executable \var{path} with argument list \var{args},
-and environment \var{env},
-replacing the current process (i.e., the Python interpreter).
-The argument list may be a tuple or list of strings.
-The environment must be a dictionary mapping strings to strings.
-(Not on MS-DOS.)
-\end{funcdesc}
-
-\begin{funcdesc}{_exit}{n}
-Exit to the system with status \var{n}, without calling cleanup
-handlers, flushing stdio buffers, etc.
-(Not on MS-DOS.)
-
-Note: the standard way to exit is \code{sys.exit(\var{n})}.
-\function{_exit()} should normally only be used in the child process
-after a \function{fork()}.
-\end{funcdesc}
-
-\begin{funcdesc}{fdopen}{fd\optional{, mode\optional{, bufsize}}}
-Return an open file object connected to the file descriptor \var{fd}.
-The \var{mode} and \var{bufsize} arguments have the same meaning as
-the corresponding arguments to the built-in \function{open()} function.
-\end{funcdesc}
-
-\begin{funcdesc}{fork}{}
-Fork a child process.  Return \code{0} in the child, the child's
-process id in the parent.
-(Not on MS-DOS.)
-\end{funcdesc}
-
-\begin{funcdesc}{fstat}{fd}
-Return status for file descriptor \var{fd}, like \function{stat()}.
-\end{funcdesc}
-
-\begin{funcdesc}{fstatvfs}{fd}
-Return information about the filesystem containing the file associated
-with file descriptor \var{fd}, like \function{statvfs()}.
-\end{funcdesc}
-
-\begin{funcdesc}{ftruncate}{fd, length}
-Truncate the file corresponding to file descriptor \var{fd}, 
-so that it is at most \var{length} bytes in size.
-\end{funcdesc}
-
-\begin{funcdesc}{getcwd}{}
-Return a string representing the current working directory.
-\end{funcdesc}
-
-\begin{funcdesc}{getegid}{}
-Return the current process' effective group id.
-(Not on MS-DOS.)
-\end{funcdesc}
-
-\begin{funcdesc}{geteuid}{}
-Return the current process' effective user id.
-(Not on MS-DOS.)
-\end{funcdesc}
-
-\begin{funcdesc}{getgid}{}
-Return the current process' group id.
-(Not on MS-DOS.)
-\end{funcdesc}
-
-\begin{funcdesc}{getpgrp}{}
-\index{process!group}
-Return the current process group id.
-(Not on MS-DOS.)
-\end{funcdesc}
-
-\begin{funcdesc}{getpid}{}
-\index{process!id}
-Return the current process id.
-(Not on MS-DOS.)
-\end{funcdesc}
-
-\begin{funcdesc}{getppid}{}
-\index{process!id of parent}
-Return the parent's process id.
-(Not on MS-DOS.)
-\end{funcdesc}
-
-\begin{funcdesc}{getuid}{}
-\index{user id}
-Return the current process' user id.
-(Not on MS-DOS.)
-\end{funcdesc}
-
-\begin{funcdesc}{kill}{pid, sig}
-\index{process!killing}
-\index{process!signalling}
-Kill the process \var{pid} with signal \var{sig}.
-(Not on MS-DOS.)
-\end{funcdesc}
-
-\begin{funcdesc}{link}{src, dst}
-Create a hard link pointing to \var{src} named \var{dst}.
-(Not on MS-DOS.)
-\end{funcdesc}
-
-\begin{funcdesc}{listdir}{path}
-Return a list containing the names of the entries in the directory.
-The list is in arbitrary order.  It does not include the special
-entries \code{'.'} and \code{'..'} even if they are present in the
-directory.
-\end{funcdesc}
-
-\begin{funcdesc}{lseek}{fd, pos, how}
-Set the current position of file descriptor \var{fd} to position
-\var{pos}, modified by \var{how}: \code{0} to set the position
-relative to the beginning of the file; \code{1} to set it relative to
-the current position; \code{2} to set it relative to the end of the
-file.
-\end{funcdesc}
-
-\begin{funcdesc}{lstat}{path}
-Like \function{stat()}, but do not follow symbolic links.  (On systems
-without symbolic links, this is identical to \function{stat()}.)
-\end{funcdesc}
-
-\begin{funcdesc}{mkfifo}{path\optional{, mode}}
-Create a FIFO (a \POSIX{} named pipe) named \var{path} with numeric mode
-\var{mode}.  The default \var{mode} is \code{0666} (octal).  The current
-umask value is first masked out from the mode.
-(Not on MS-DOS.)
-
-FIFOs are pipes that can be accessed like regular files.  FIFOs exist
-until they are deleted (for example with \function{os.unlink()}).
-Generally, FIFOs are used as rendezvous between ``client'' and
-``server'' type processes: the server opens the FIFO for reading, and
-the client opens it for writing.  Note that \function{mkfifo()}
-doesn't open the FIFO --- it just creates the rendezvous point.
-\end{funcdesc}
-
-\begin{funcdesc}{mkdir}{path\optional{, mode}}
-Create a directory named \var{path} with numeric mode \var{mode}.
-The default \var{mode} is \code{0777} (octal).  On some systems,
-\var{mode} is ignored.  Where it is used, the current umask value is
-first masked out.
-\end{funcdesc}
-
-\begin{funcdesc}{nice}{increment}
-Add \var{increment} to the process' ``niceness''.  Return the new
-niceness.  (Not on MS-DOS.)
-\end{funcdesc}
-
-\begin{funcdesc}{open}{file, flags\optional{, mode}}
-Open the file \var{file} and set various flags according to
-\var{flags} and possibly its mode according to \var{mode}.
-The default \var{mode} is \code{0777} (octal), and the current umask
-value is first masked out.  Return the file descriptor for the newly
-opened file.
-
-For a description of the flag and mode values, see the \UNIX{} or \C{}
-run-time documentation; flag constants (like \constant{O_RDONLY} and
-\constant{O_WRONLY}) are defined in this module too (see below).
-
-Note: this function is intended for low-level I/O.  For normal usage,
-use the built-in function \function{open()}, which returns a ``file
-object'' with \method{read()} and \method{write()} methods (and many
-more).
-\end{funcdesc}
-
-\begin{funcdesc}{pipe}{}
-Create a pipe.  Return a pair of file descriptors \code{(\var{r},
-\var{w})} usable for reading and writing, respectively.
-(Not on MS-DOS.)
-\end{funcdesc}
-
-\begin{funcdesc}{plock}{op}
-Lock program segments into memory.  The value of \var{op}
-(defined in \code{<sys/lock.h>}) determines which segments are locked.
-(Not on MS-DOS.)
-\end{funcdesc}
-
-\begin{funcdesc}{popen}{command\optional{, mode\optional{, bufsize}}}
-Open a pipe to or from \var{command}.  The return value is an open
-file object connected to the pipe, which can be read or written
-depending on whether \var{mode} is \code{'r'} (default) or \code{'w'}.
-The \var{bufsize} argument has the same meaning as the corresponding
-argument to the built-in \function{open()} function.  The exit status of
-the command (encoded in the format specified for \function{wait()}) is
-available as the return value of the \method{close()} method of the file
-object, except that when the exit status is zero (termination without
-errors), \code{None} is returned.
-(Not on MS-DOS.)
-\end{funcdesc}
-
-\begin{funcdesc}{putenv}{varname, value}
-\index{environment variables!setting}
-Set the environment variable named \var{varname} to the string
-\var{value}.  Such changes to the environment affect subprocesses
-started with \function{os.system()}, \function{os.popen()} or
-\function{os.fork()} and \function{os.execv()}.  (Not on all systems.)
-
-When \function{putenv()} is
-supported, assignments to items in \code{os.environ} are automatically
-translated into corresponding calls to \function{putenv()}; however,
-calls to \function{putenv()} don't update \code{os.environ}, so it is
-actually preferable to assign to items of \code{os.environ}.  
-\end{funcdesc}
-
-\begin{funcdesc}{strerror}{code}
-Return the error message corresponding to the error code in \var{code}.
-\end{funcdesc}
-
-\begin{funcdesc}{ttyname}{fd}
-Return a string which specifies the terminal device associated with
-file-descriptor \var{fd}.  If \var{fd} is not associated with a terminal
-device, an exception is raised.
-\end{funcdesc}
-
-\begin{funcdesc}{read}{fd, n}
-Read at most \var{n} bytes from file descriptor \var{fd}.
-Return a string containing the bytes read.
-
-Note: this function is intended for low-level I/O and must be applied
-to a file descriptor as returned by \function{open()} or
-\function{pipe()}.  To read a ``file object'' returned by the
-built-in function \function{open()} or by \function{popen()} or
-\function{fdopen()}, or \code{sys.stdin}, use its
-\method{read()} or \method{readline()} methods.
-\end{funcdesc}
-
-\begin{funcdesc}{readlink}{path}
-Return a string representing the path to which the symbolic link
-points.  (On systems without symbolic links, this always raises
-\exception{error}.)
-\end{funcdesc}
-
-\begin{funcdesc}{remove}{path}
-Remove the file \var{path}.  See \function{rmdir()} below to remove a
-directory.  This is identical to the \function{unlink()} function
-documented below.
-\end{funcdesc}
-
-\begin{funcdesc}{rename}{src, dst}
-Rename the file or directory \var{src} to \var{dst}.
-\end{funcdesc}
-
-\begin{funcdesc}{rmdir}{path}
-Remove the directory \var{path}.
-\end{funcdesc}
-
-\begin{funcdesc}{setgid}{gid}
-Set the current process' group id.
-(Not on MS-DOS.)
-\end{funcdesc}
-
-\begin{funcdesc}{setpgrp}{}
-Calls the system call \cfunction{setpgrp()} or \cfunction{setpgrp(0,
-0)} depending on which version is implemented (if any).  See the
-\UNIX{} manual for the semantics.
-(Not on MS-DOS.)
-\end{funcdesc}
-
-\begin{funcdesc}{setpgid}{pid, pgrp}
-Calls the system call \cfunction{setpgid()}.  See the \UNIX{} manual
-for the semantics.
-(Not on MS-DOS.)
-\end{funcdesc}
-
-\begin{funcdesc}{setsid}{}
-Calls the system call \cfunction{setsid()}.  See the \UNIX{} manual
-for the semantics.
-(Not on MS-DOS.)
-\end{funcdesc}
-
-\begin{funcdesc}{setuid}{uid}
-Set the current process' user id.
-(Not on MS-DOS.)
-\end{funcdesc}
-
-\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
-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}.
-More items may be added at the end by some implementations.
-(On MS-DOS, some items are filled with dummy values.)
-
-Note: The standard module \module{stat}\refstmodindex{stat} defines
-functions and constants that are useful for extracting information
-from a \ctype{stat} structure.
-\end{funcdesc}
-
-\begin{funcdesc}{statvfs}{path}
-Perform a \cfunction{statvfs()} system call on the given path.  The
-return value is a tuple of 11 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_fsid},
-\code{f_flag},
-\code{f_namemax}.
-
-Note: The standard module \module{statvfs}\refstmodindex{statvfs}
-defines constants that are useful for extracting information
-from a \ctype{statvfs} structure.
-\end{funcdesc}
-
-\begin{funcdesc}{symlink}{src, dst}
-Create a symbolic link pointing to \var{src} named \var{dst}.  (On
-systems without symbolic links, this always raises \exception{error}.)
-\end{funcdesc}
-
-\begin{funcdesc}{system}{command}
-Execute the command (a string) in a subshell.  This is implemented by
-calling the Standard \C{} function \cfunction{system()}, and has the
-same limitations.  Changes to \code{posix.environ}, \code{sys.stdin}
-etc.\ are not reflected in the environment of the executed command.
-The return value is the exit status of the process encoded in the
-format specified for \function{wait()}.
-\end{funcdesc}
-
-\begin{funcdesc}{tcgetpgrp}{fd}
-Return the process group associated with the terminal given by
-\var{fd} (an open file descriptor as returned by \function{open()}).
-(Not on MS-DOS.)
-\end{funcdesc}
-
-\begin{funcdesc}{tcsetpgrp}{fd, pg}
-Set the process group associated with the terminal given by
-\var{fd} (an open file descriptor as returned by \function{open()})
-to \var{pg}.
-(Not on MS-DOS.)
-\end{funcdesc}
-
-\begin{funcdesc}{times}{}
-Return a 5-tuple of floating point numbers indicating accumulated (CPU
-or other)
-times, in seconds.  The items are: user time, system time, children's
-user time, children's system time, and elapsed real time since a fixed
-point in the past, in that order.  See the \UNIX{}
-manual page \manpage{times}{2}.  (Not on MS-DOS.)
-\end{funcdesc}
-
-\begin{funcdesc}{umask}{mask}
-Set the current numeric umask and returns the previous umask.
-(Not on MS-DOS.)
-\end{funcdesc}
-
-\begin{funcdesc}{uname}{}
-Return a 5-tuple containing information identifying the current
-operating system.  The tuple contains 5 strings:
-\code{(\var{sysname}, \var{nodename}, \var{release}, \var{version},
-\var{machine})}.  Some systems truncate the nodename to 8
-characters or to the leading component; a better way to get the
-hostname is \function{socket.gethostname()}%
-\withsubitem{(in module socket)}{\ttindex{gethostname()}}
-or even
-\code{socket.gethostbyaddr(socket.gethostname())}%
-\withsubitem{(in module socket)}{\ttindex{gethostbyaddr()}}.
-(Not on MS-DOS, nor on older \UNIX{} systems.)
-\end{funcdesc}
-
-\begin{funcdesc}{unlink}{path}
-Remove the file \var{path}.  This is the same function as \code{remove};
-the \code{unlink} name is its traditional \UNIX{} name.
-\end{funcdesc}
-
-\begin{funcdesc}{utime}{path, (atime, mtime)}
-Set the access and modified time of the file to the given values.
-(The second argument is a tuple of two items.)
-\end{funcdesc}
-
-\begin{funcdesc}{wait}{}
-Wait for completion of a child process, and return a tuple containing
-its pid and exit status indication: a 16-bit number, whose low byte is
-the signal number that killed the process, and whose high byte is the
-exit status (if the signal number is zero); the high bit of the low
-byte is set if a core file was produced.  (Not on MS-DOS.)
-\end{funcdesc}
-
-\begin{funcdesc}{waitpid}{pid, options}
-Wait for completion of a child process given by proces id, and return
-a tuple containing its pid and exit status indication (encoded as for
-\function{wait()}).  The semantics of the call are affected by the
-value of the integer \var{options}, which should be \code{0} for
-normal operation.  (If the system does not support
-\function{waitpid()}, this always raises \exception{error}.  Not on
-MS-DOS.)
-\end{funcdesc}
-
-\begin{funcdesc}{write}{fd, str}
-Write the string \var{str} to file descriptor \var{fd}.
-Return the number of bytes actually written.
-
-Note: this function is intended for low-level I/O and must be applied
-to a file descriptor as returned by \function{open()} or
-\function{pipe()}.  To write a ``file object'' returned by the
-built-in function \function{open()} or by \function{popen()} or
-\function{fdopen()}, or \code{sys.stdout} or \code{sys.stderr}, use
-its \method{write()} method.
-\end{funcdesc}
-
-\begin{datadesc}{WNOHANG}
-The option for \function{waitpid()} to avoid hanging if no child
-process status is available immediately.
-\end{datadesc}
-
-
-\begin{datadesc}{O_RDONLY}
-\dataline{O_WRONLY}
-\dataline{O_RDWR}
-\dataline{O_NDELAY}
-\dataline{O_NONBLOCK}
-\dataline{O_APPEND}
-\dataline{O_DSYNC}
-\dataline{O_RSYNC}
-\dataline{O_SYNC}
-\dataline{O_NOCTTY}
-\dataline{O_CREAT}
-\dataline{O_EXCL}
-\dataline{O_TRUNC}
-Options for the \code{flag} argument to the \function{open()} function.
-These can be bit-wise OR'd together.
-\end{datadesc}
+Additional contents of this module should only be accessed via the
+\module{os} module; refer to the documentation for that module for
+further information.