Restructured library documentation

1 files changed, 306 insertions, 0 deletions

diff --git a/Doc/libposix.tex b/Doc/libposix.tex
new file mode 100644
index 0000000..737ddb1
--- /dev/null
+++ b/Doc/libposix.tex
@@ -0,0 +1,306 @@
+\section{Built-in Module \sectcode{posix}}
+
+\bimodindex{posix}
+
+This module provides access to operating system functionality that is
+standardized by the C Standard and the POSIX standard (a thinly diguised
+\UNIX{} interface).
+It is available in all Python versions except on the Macintosh;
+the MS-DOS version does not support certain functions.
+The descriptions below are very terse; refer to the
+corresponding \UNIX{} manual entry for more information.
+
+Errors are reported as exceptions; the usual exceptions are given
+for type errors, while errors reported by the system calls raise
+\code{posix.error}, described below.
+
+Module \code{posix} defines the following data items:
+
+\renewcommand{\indexsubitem}{(data in module posix)}
+\begin{datadesc}{environ}
+A dictionary representing the string environment at the time
+the interpreter was started.
+(Modifying this dictionary does not affect the string environment of the
+interpreter.)
+For example,
+\code{posix.environ['HOME']}
+is the pathname of your home directory, equivalent to
+\code{getenv("HOME")}
+in C.
+\end{datadesc}
+
+\renewcommand{\indexsubitem}{(exception in module posix)}
+\begin{excdesc}{error}
+This exception is raised when an POSIX function returns a
+POSIX-related error (e.g., not for illegal argument types).  Its
+string value is \code{'posix.error'}.  The accompanying value is a
+pair containing the numeric error code from \code{errno} and the
+corresponding string, as would be printed by the C function
+\code{perror()}.
+\end{excdesc}
+
+It defines the following functions:
+
+\renewcommand{\indexsubitem}{(in module posix)}
+\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}{close}{fd}
+Close file descriptor \var{fd}.
+\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.  Return \code{None}.
+\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})}.
+\code{posix._exit()} should normally only be used in the child process
+after a \code{fork()}.
+\end{funcdesc}
+
+\begin{funcdesc}{fork}{}
+Fork a child process.  Return 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 \code{stat()}.
+\end{funcdesc}
+
+\begin{funcdesc}{getcwd}{}
+Return a string representing the current working directory.
+\end{funcdesc}
+
+\begin{funcdesc}{getegid}{}
+Return the current process's effective group id.
+(Not on MS-DOS.)
+\end{funcdesc}
+
+\begin{funcdesc}{geteuid}{}
+Return the current process's effective user id.
+(Not on MS-DOS.)
+\end{funcdesc}
+
+\begin{funcdesc}{getgid}{}
+Return the current process's group id.
+(Not on MS-DOS.)
+\end{funcdesc}
+
+\begin{funcdesc}{getpid}{}
+Return the current process id.
+(Not on MS-DOS.)
+\end{funcdesc}
+
+\begin{funcdesc}{getppid}{}
+Return the parent's process id.
+(Not on MS-DOS.)
+\end{funcdesc}
+
+\begin{funcdesc}{getuid}{}
+Return the current process's user id.
+(Not on MS-DOS.)
+\end{funcdesc}
+
+\begin{funcdesc}{kill}{pid\, sig}
+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 includes the special entries
+\code{'.'} and \code{'..'} 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}: 0 to set the position relative to
+the beginning of the file; 1 to set it relative to the current
+position; 2 to set it relative to the end of the file.
+\end{funcdesc}
+
+\begin{funcdesc}{lstat}{path}
+Like \code{stat()}, but do not follow symbolic links.  (On systems
+without symbolic links, this is identical to \code{posix.stat}.)
+\end{funcdesc}
+
+\begin{funcdesc}{mkdir}{path\, mode}
+Create a directory named \var{path} with numeric mode \var{mode}.
+\end{funcdesc}
+
+\begin{funcdesc}{nice}{increment}
+Add \var{incr} to the process' ``niceness''.  Return the new niceness.
+(Not on MS-DOS.)
+\end{funcdesc}
+
+\begin{funcdesc}{open}{file\, flags\, mode}
+Open the file \var{file} and set various flags according to
+\var{flags} and possibly its mode according to \var{mode}.
+Return the file descriptor for the newly opened file.
+\end{funcdesc}
+
+\begin{funcdesc}{pipe}{}
+Create a pipe.  Return a pair of file descriptors \code{(r, w)}
+usable for reading and writing, respectively.
+(Not on MS-DOS.)
+\end{funcdesc}
+
+\begin{funcdesc}{popen}{command\, mode}
+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'} or \code{'w'}.
+(Not on MS-DOS.)
+\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.
+\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
+\code{posix.error}.)
+\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's group id.
+(Not on MS-DOS.)
+\end{funcdesc}
+
+\begin{funcdesc}{setuid}{uid}
+Set the current process's user id.
+(Not on MS-DOS.)
+\end{funcdesc}
+
+\begin{funcdesc}{stat}{path}
+Perform a {\em 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 {\em 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 \code{stat} defines functions and constants
+that are useful for extracting information from a stat 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
+\code{posix.error}.)
+\end{funcdesc}
+
+\begin{funcdesc}{system}{command}
+Execute the command (a string) in a subshell.  This is implemented by
+calling the Standard C function \code{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 as returned by Standard C
+\code{system()}.
+\end{funcdesc}
+
+\begin{funcdesc}{times}{}
+Return a 4-tuple of floating point numbers indicating accumulated CPU
+times, in seconds.  The items are: user time, system time, children's
+user time, and children's system time, in that order.  See the \UNIX{}
+manual page {\it 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; an better way to get the
+hostname is \code{socket.gethostname()}.  (Not on MS-DOS, nor on older
+\UNIX{} systems.)
+\end{funcdesc}
+
+\begin{funcdesc}{unlink}{path}
+Unlink \var{path}.
+\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 (encoded as by \UNIX{}).
+(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 by
+\UNIX{}).  The semantics of the call are affected by the value of
+the integer options, which should be 0 for normal operation.  (If the
+system does not support waitpid(), this always raises
+\code{posix.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.
+\end{funcdesc}