Doc/libos.tex

   1 \section{Standard Module \module{os}}
   2 \label{module-os}
   3 \stmodindex{os}
   4
   5 This module provides a more portable way of using operating system
   6 (OS) dependent functionality than importing an OS dependent built-in
   7 module like \module{posix}.
   8
   9 When the optional built-in module \module{posix} is available, this
  10 module exports the same functions and data as \module{posix}; otherwise,
  11 it searches for an OS dependent built-in module like \module{mac} and
  12 exports the same functions and data as found there.  The design of all
  13 Python's built-in OS dependent modules is such that as long as the same
  14 functionality is available, it uses the same interface; e.g., the
  15 function \code{os.stat(\var{file})} returns stat info about \var{file}
  16 in a format compatible with the \POSIX{} interface.
  17
  18 Extensions peculiar to a particular OS are also available through the
  19 \module{os} module, but using them is of course a threat to
  20 portability!
  21
  22 Note that after the first time \module{os} is imported, there is
  23 \emph{no} performance penalty in using functions from \module{os}
  24 instead of directly from the OS dependent built-in module, so there
  25 should be \emph{no} reason not to use \module{os}!
  26
  27 In addition to whatever the correct OS dependent module exports, the
  28 following variables and functions are always exported by \module{os}:
  29
  30 \begin{datadesc}{name}
  31 The name of the OS dependent module imported.  The following names
  32 have currently been registered: \code{'posix'}, \code{'nt'},
  33 \code{'dos'}, \code{'mac'}.
  34 \end{datadesc}
  35
  36 \begin{datadesc}{path}
  37 The corresponding OS dependent standard module for pathname
  38 operations, e.g., \module{posixpath} or \module{macpath}.  Thus, (given
  39 the proper imports), \code{os.path.split(\var{file})} is equivalent to but
  40 more portable than \code{posixpath.split(\var{file})}.
  41 \end{datadesc}
  42
  43 \begin{datadesc}{curdir}
  44 The constant string used by the OS to refer to the current directory,
  45 e.g. \code{'.'} for \POSIX{} or \code{':'} for the Macintosh.
  46 \end{datadesc}
  47
  48 \begin{datadesc}{pardir}
  49 The constant string used by the OS to refer to the parent directory,
  50 e.g. \code{'..'} for \POSIX{} or \code{'::'} for the Macintosh.
  51 \end{datadesc}
  52
  53 \begin{datadesc}{sep}
  54 The character used by the OS to separate pathname components,
  55 e.g. \code{'/'} for \POSIX{} or \code{':'} for the Macintosh.  Note that
  56 knowing this is not sufficient to be able to parse or concatenate
  57 pathnames --- better use \function{os.path.split()} and
  58 \function{os.path.join()}---but it is occasionally useful.
  59 \end{datadesc}
  60
  61 \begin{datadesc}{altsep}
  62 An alternative character used by the OS to separate pathname components,
  63 or \code{None} if only one separator character exists.  This is set to
  64 \code{'/'} on DOS/Windows systems where \code{sep} is a backslash.
  65 \end{datadesc}
  66
  67 \begin{datadesc}{pathsep}
  68 The character conventionally used by the OS to separate search patch
  69 components (as in \code{\$PATH}), e.g.\ \code{':'} for \POSIX{} or
  70 \code{';'} for MS-DOS.
  71 \end{datadesc}
  72
  73 \begin{datadesc}{defpath}
  74 The default search path used by \code{exec*p*()} if the environment
  75 doesn't have a \code{'PATH'} key.
  76 \end{datadesc}
  77
  78 \begin{funcdesc}{execl}{path, arg0, arg1, ...}
  79 This is equivalent to
  80 \code{execv(\var{path}, (\var{arg0}, \var{arg1}, ...))}.
  81 \end{funcdesc}
  82
  83 \begin{funcdesc}{execle}{path, arg0, arg1, ..., env}
  84 This is equivalent to
  85 \code{execve(\var{path}, (\var{arg0}, \var{arg1}, ...), \var{env})}.
  86 \end{funcdesc}
  87
  88 \begin{funcdesc}{execlp}{path, arg0, arg1, ...}
  89 This is equivalent to
  90 \code{execvp(\var{path}, (\var{arg0}, \var{arg1}, ...))}.
  91 \end{funcdesc}
  92
  93 \begin{funcdesc}{execvp}{path, args}
  94 This is like \code{execv(\var{path}, \var{args})} but duplicates
  95 the shell's actions in searching for an executable file in a list of
  96 directories.  The directory list is obtained from
  97 \code{environ['PATH']}.
  98 \end{funcdesc}
  99
 100 \begin{funcdesc}{execvpe}{path, args, env}
 101 This is a cross between \function{execve()} and \function{execvp()}.
 102 The directory list is obtained from \code{\var{env}['PATH']}.
 103 \end{funcdesc}
 104
 105 (The functions \code{execv()} and \code{execve()} are not
 106 documented here, since they are implemented by the OS dependent
 107 module.  If the OS dependent module doesn't define either of these,
 108 the functions that rely on it will raise an exception.  They are
 109 documented in the section on module \module{posix}, together with all
 110 other functions that \module{os} imports from the OS dependent module.)