Doc/lib/libos.tex

\section{Standard Module \module{os}}
\declaremodule{standard}{os}

\modulesynopsis{Miscellaneous OS interfaces.}


This module provides a more portable way of using operating system
(OS) dependent functionality than importing an OS dependent built-in
module like \module{posix}.

When the optional built-in module \module{posix} is available, this
module exports the same functions and data as \module{posix}; otherwise,
it searches for an OS dependent built-in module like \module{mac} and
exports the same functions and data as found there.  The design of all
Python's built-in OS dependent modules is such that as long as the same
functionality is available, it uses the same interface; e.g., the
function \code{os.stat(\var{file})} returns stat info about \var{file}
in a format compatible with the \POSIX{} interface.

Extensions peculiar to a particular OS are also available through the
\module{os} module, but using them is of course a threat to
portability!

Note that after the first time \module{os} is imported, there is
\emph{no} performance penalty in using functions from \module{os}
instead of directly from the OS dependent built-in module, so there
should be \emph{no} reason not to use \module{os}!

In addition to whatever the correct OS dependent module exports, the
following variables and functions are always exported by \module{os}:

\begin{datadesc}{name}
The name of the OS dependent module imported.  The following names
have currently been registered: \code{'posix'}, \code{'nt'},
\code{'dos'}, \code{'mac'}.
\end{datadesc}

\begin{datadesc}{path}
The corresponding OS dependent standard module for pathname
operations, e.g., \module{posixpath} or \module{macpath}.  Thus, (given
the proper imports), \code{os.path.split(\var{file})} is equivalent to but
more portable than \code{posixpath.split(\var{file})}.
\end{datadesc}

\begin{datadesc}{curdir}
The constant string used by the OS to refer to the current directory,
e.g. \code{'.'} for \POSIX{} or \code{':'} for the Macintosh.
\end{datadesc}

\begin{datadesc}{pardir}
The constant string used by the OS to refer to the parent directory,
e.g. \code{'..'} for \POSIX{} or \code{'::'} for the Macintosh.
\end{datadesc}

\begin{datadesc}{sep}
The character used by the OS to separate pathname components,
e.g. \code{'/'} for \POSIX{} or \code{':'} for the Macintosh.  Note that
knowing this is not sufficient to be able to parse or concatenate
pathnames --- better use \function{os.path.split()} and
\function{os.path.join()}---but it is occasionally useful.
\end{datadesc}

\begin{datadesc}{altsep}
An alternative character used by the OS to separate pathname components,
or \code{None} if only one separator character exists.  This is set to
\code{'/'} on DOS/Windows systems where \code{sep} is a backslash.
\end{datadesc}

\begin{datadesc}{pathsep}
The character conventionally used by the OS to separate search patch
components (as in \code{\$PATH}), e.g.\ \code{':'} for \POSIX{} or % $
\code{';'} for MS-DOS.
\end{datadesc}

\begin{datadesc}{linesep}
The string used to separate (or, rather, terminate) lines on the
current platform.  This may be a single character, e.g. \code{'\e n'}
for \POSIX{} or \code{'\e r'} for MacOS, or multiple characters,
e.g. \code{'\e r\e n'} for MS-DOS.
\end{datadesc}

\begin{datadesc}{defpath}
The default search path used by \code{exec*p*()} if the environment
doesn't have a \code{'PATH'} key.
\end{datadesc}

\begin{funcdesc}{makedirs}{path\optional{, mode}}
Recursive directory creation function.  Like \function{mkdir()},
but makes all intermediate-level directories needed to contain the
leaf directory.  Throws an \exception{os.error} exception if the leaf
directory already exists or cannot be created.  The default \var{mode}
is \code{0777} (octal).
\end{funcdesc}

\begin{funcdesc}{removedirs}{path}
Recursive directory removal function.  Works like
\function{rmdir()} except that, if the leaf directory is
successfully removed, directories corresponding to rightmost path
segments will be pruned way until either the whole path is consumed or
an error is raised (which is ignored, because it generally means that
a parent directory is not empty).  Throws an \exception{os.error}
exception if the leaf directory could not be successfully removed.
\end{funcdesc}

\begin{funcdesc}{renames}{path}
Recursive directory or file renaming function.
Works like \function{rename()}, except creation of any intermediate
directories needed to make the new pathname good is attempted first.
After the rename, directories corresponding to rightmost path segments
of the old name will be pruned away using \function{removedirs()}.

Note: this function can fail with the new directory structure made if
you lack permissions needed to remove the leaf directory or file.
\end{funcdesc}

\begin{funcdesc}{execl}{path, arg0, arg1, ...}
This is equivalent to
\code{execv(\var{path}, (\var{arg0}, \var{arg1}, ...))}.
\end{funcdesc}

\begin{funcdesc}{execle}{path, arg0, arg1, ..., env}
This is equivalent to
\code{execve(\var{path}, (\var{arg0}, \var{arg1}, ...), \var{env})}.
\end{funcdesc}

\begin{funcdesc}{execlp}{path, arg0, arg1, ...}
This is equivalent to
\code{execvp(\var{path}, (\var{arg0}, \var{arg1}, ...))}.
\end{funcdesc}

\begin{funcdesc}{execvp}{path, args}
This is like \code{execv(\var{path}, \var{args})} but duplicates
the shell's actions in searching for an executable file in a list of
directories.  The directory list is obtained from
\code{environ['PATH']}.
\end{funcdesc}

\begin{funcdesc}{execvpe}{path, args, env}
This is a cross between \function{execve()} and \function{execvp()}.
The directory list is obtained from \code{\var{env}['PATH']}.
\end{funcdesc}

(The functions \code{execv()} and \code{execve()} are not
documented here, since they are implemented by the OS dependent
module.  If the OS dependent module doesn't define either of these,
the functions that rely on it will raise an exception.  They are
documented in the section on module \module{posix}, together with all
other functions that \module{os} imports from the OS dependent module.)