Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame^] | 1 | \section{\module{os} --- |
| 2 | Miscellaneous OS interfaces.} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 3 | \declaremodule{standard}{os} |
| 4 | |
| 5 | \modulesynopsis{Miscellaneous OS interfaces.} |
| 6 | |
Fred Drake | c4f15af | 1998-03-10 03:17:26 +0000 | [diff] [blame] | 7 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 8 | This module provides a more portable way of using operating system |
| 9 | (OS) dependent functionality than importing an OS dependent built-in |
Fred Drake | c4f15af | 1998-03-10 03:17:26 +0000 | [diff] [blame] | 10 | module like \module{posix}. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 11 | |
Fred Drake | c4f15af | 1998-03-10 03:17:26 +0000 | [diff] [blame] | 12 | When the optional built-in module \module{posix} is available, this |
| 13 | module exports the same functions and data as \module{posix}; otherwise, |
| 14 | it searches for an OS dependent built-in module like \module{mac} and |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 15 | exports the same functions and data as found there. The design of all |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 16 | Python's built-in OS dependent modules is such that as long as the same |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 17 | functionality is available, it uses the same interface; e.g., the |
Fred Drake | c4f15af | 1998-03-10 03:17:26 +0000 | [diff] [blame] | 18 | function \code{os.stat(\var{file})} returns stat info about \var{file} |
| 19 | in a format compatible with the \POSIX{} interface. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 20 | |
| 21 | Extensions peculiar to a particular OS are also available through the |
Fred Drake | c4f15af | 1998-03-10 03:17:26 +0000 | [diff] [blame] | 22 | \module{os} module, but using them is of course a threat to |
| 23 | portability! |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 24 | |
Fred Drake | c4f15af | 1998-03-10 03:17:26 +0000 | [diff] [blame] | 25 | Note that after the first time \module{os} is imported, there is |
| 26 | \emph{no} performance penalty in using functions from \module{os} |
| 27 | instead of directly from the OS dependent built-in module, so there |
| 28 | should be \emph{no} reason not to use \module{os}! |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 29 | |
| 30 | In addition to whatever the correct OS dependent module exports, the |
Fred Drake | c4f15af | 1998-03-10 03:17:26 +0000 | [diff] [blame] | 31 | following variables and functions are always exported by \module{os}: |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 32 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 33 | \begin{datadesc}{name} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 34 | The name of the OS dependent module imported. The following names |
| 35 | have currently been registered: \code{'posix'}, \code{'nt'}, |
| 36 | \code{'dos'}, \code{'mac'}. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 37 | \end{datadesc} |
| 38 | |
| 39 | \begin{datadesc}{path} |
| 40 | The corresponding OS dependent standard module for pathname |
Fred Drake | c4f15af | 1998-03-10 03:17:26 +0000 | [diff] [blame] | 41 | operations, e.g., \module{posixpath} or \module{macpath}. Thus, (given |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 42 | the proper imports), \code{os.path.split(\var{file})} is equivalent to but |
| 43 | more portable than \code{posixpath.split(\var{file})}. |
| 44 | \end{datadesc} |
| 45 | |
| 46 | \begin{datadesc}{curdir} |
| 47 | The constant string used by the OS to refer to the current directory, |
Fred Drake | 1a3c2a0 | 1998-08-06 15:18:23 +0000 | [diff] [blame] | 48 | e.g.\ \code{'.'} for \POSIX{} or \code{':'} for the Macintosh. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 49 | \end{datadesc} |
| 50 | |
| 51 | \begin{datadesc}{pardir} |
| 52 | The constant string used by the OS to refer to the parent directory, |
Fred Drake | 1a3c2a0 | 1998-08-06 15:18:23 +0000 | [diff] [blame] | 53 | e.g.\ \code{'..'} for \POSIX{} or \code{'::'} for the Macintosh. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 54 | \end{datadesc} |
| 55 | |
| 56 | \begin{datadesc}{sep} |
Guido van Rossum | b2afc81 | 1997-08-29 22:37:44 +0000 | [diff] [blame] | 57 | The character used by the OS to separate pathname components, |
Fred Drake | 1a3c2a0 | 1998-08-06 15:18:23 +0000 | [diff] [blame] | 58 | e.g.\ \character{/} for \POSIX{} or \character{:} for the Macintosh. |
| 59 | Note that knowing this is not sufficient to be able to parse or |
| 60 | concatenate pathnames --- use \function{os.path.split()} and |
| 61 | \function{os.path.join()} --- but it is occasionally useful. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 62 | \end{datadesc} |
| 63 | |
Guido van Rossum | b2afc81 | 1997-08-29 22:37:44 +0000 | [diff] [blame] | 64 | \begin{datadesc}{altsep} |
| 65 | An alternative character used by the OS to separate pathname components, |
| 66 | or \code{None} if only one separator character exists. This is set to |
Fred Drake | 1a3c2a0 | 1998-08-06 15:18:23 +0000 | [diff] [blame] | 67 | \character{/} on DOS/Windows systems where \code{sep} is a backslash. |
Guido van Rossum | b2afc81 | 1997-08-29 22:37:44 +0000 | [diff] [blame] | 68 | \end{datadesc} |
| 69 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 70 | \begin{datadesc}{pathsep} |
| 71 | The character conventionally used by the OS to separate search patch |
Fred Drake | 1a3c2a0 | 1998-08-06 15:18:23 +0000 | [diff] [blame] | 72 | components (as in \envvar{PATH}), e.g.\ \character{:} for \POSIX{} or |
| 73 | \character{;} for MS-DOS. |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 74 | \end{datadesc} |
| 75 | |
Guido van Rossum | 9c59ce9 | 1998-06-30 15:54:27 +0000 | [diff] [blame] | 76 | \begin{datadesc}{linesep} |
| 77 | The string used to separate (or, rather, terminate) lines on the |
| 78 | current platform. This may be a single character, e.g. \code{'\e n'} |
| 79 | for \POSIX{} or \code{'\e r'} for MacOS, or multiple characters, |
| 80 | e.g. \code{'\e r\e n'} for MS-DOS. |
| 81 | \end{datadesc} |
| 82 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 83 | \begin{datadesc}{defpath} |
Fred Drake | 1a3c2a0 | 1998-08-06 15:18:23 +0000 | [diff] [blame] | 84 | The default search path used by \function{exec*p*()} if the environment |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 85 | doesn't have a \code{'PATH'} key. |
| 86 | \end{datadesc} |
| 87 | |
Guido van Rossum | 89a79d1 | 1998-07-24 20:48:20 +0000 | [diff] [blame] | 88 | \begin{funcdesc}{makedirs}{path\optional{, mode}} |
Fred Drake | 56fa8a7 | 1998-08-06 13:45:42 +0000 | [diff] [blame] | 89 | \versionadded{1.5.2} |
Guido van Rossum | 89a79d1 | 1998-07-24 20:48:20 +0000 | [diff] [blame] | 90 | Recursive directory creation function. Like \function{mkdir()}, |
| 91 | but makes all intermediate-level directories needed to contain the |
| 92 | leaf directory. Throws an \exception{os.error} exception if the leaf |
| 93 | directory already exists or cannot be created. The default \var{mode} |
| 94 | is \code{0777} (octal). |
| 95 | \end{funcdesc} |
| 96 | |
| 97 | \begin{funcdesc}{removedirs}{path} |
Fred Drake | 56fa8a7 | 1998-08-06 13:45:42 +0000 | [diff] [blame] | 98 | \versionadded{1.5.2} |
Guido van Rossum | 89a79d1 | 1998-07-24 20:48:20 +0000 | [diff] [blame] | 99 | Recursive directory removal function. Works like |
| 100 | \function{rmdir()} except that, if the leaf directory is |
| 101 | successfully removed, directories corresponding to rightmost path |
| 102 | segments will be pruned way until either the whole path is consumed or |
| 103 | an error is raised (which is ignored, because it generally means that |
| 104 | a parent directory is not empty). Throws an \exception{os.error} |
| 105 | exception if the leaf directory could not be successfully removed. |
| 106 | \end{funcdesc} |
| 107 | |
| 108 | \begin{funcdesc}{renames}{path} |
Fred Drake | 56fa8a7 | 1998-08-06 13:45:42 +0000 | [diff] [blame] | 109 | \versionadded{1.5.2} |
Guido van Rossum | 89a79d1 | 1998-07-24 20:48:20 +0000 | [diff] [blame] | 110 | Recursive directory or file renaming function. |
| 111 | Works like \function{rename()}, except creation of any intermediate |
| 112 | directories needed to make the new pathname good is attempted first. |
| 113 | After the rename, directories corresponding to rightmost path segments |
| 114 | of the old name will be pruned away using \function{removedirs()}. |
| 115 | |
| 116 | Note: this function can fail with the new directory structure made if |
| 117 | you lack permissions needed to remove the leaf directory or file. |
| 118 | \end{funcdesc} |
| 119 | |
Fred Drake | c4f15af | 1998-03-10 03:17:26 +0000 | [diff] [blame] | 120 | \begin{funcdesc}{execl}{path, arg0, arg1, ...} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 121 | This is equivalent to |
Fred Drake | 1a3c2a0 | 1998-08-06 15:18:23 +0000 | [diff] [blame] | 122 | \samp{execv(\var{path}, (\var{arg0}, \var{arg1}, ...))}. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 123 | \end{funcdesc} |
| 124 | |
Fred Drake | c4f15af | 1998-03-10 03:17:26 +0000 | [diff] [blame] | 125 | \begin{funcdesc}{execle}{path, arg0, arg1, ..., env} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 126 | This is equivalent to |
Fred Drake | 1a3c2a0 | 1998-08-06 15:18:23 +0000 | [diff] [blame] | 127 | \samp{execve(\var{path}, (\var{arg0}, \var{arg1}, ...), \var{env})}. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 128 | \end{funcdesc} |
| 129 | |
Fred Drake | c4f15af | 1998-03-10 03:17:26 +0000 | [diff] [blame] | 130 | \begin{funcdesc}{execlp}{path, arg0, arg1, ...} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 131 | This is equivalent to |
Fred Drake | 1a3c2a0 | 1998-08-06 15:18:23 +0000 | [diff] [blame] | 132 | \samp{execvp(\var{path}, (\var{arg0}, \var{arg1}, ...))}. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 133 | \end{funcdesc} |
| 134 | |
Fred Drake | c4f15af | 1998-03-10 03:17:26 +0000 | [diff] [blame] | 135 | \begin{funcdesc}{execvp}{path, args} |
Fred Drake | 1a3c2a0 | 1998-08-06 15:18:23 +0000 | [diff] [blame] | 136 | This is like \samp{execv(\var{path}, \var{args})} but duplicates |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 137 | the shell's actions in searching for an executable file in a list of |
| 138 | directories. The directory list is obtained from |
Fred Drake | c4f15af | 1998-03-10 03:17:26 +0000 | [diff] [blame] | 139 | \code{environ['PATH']}. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 140 | \end{funcdesc} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 141 | |
Fred Drake | c4f15af | 1998-03-10 03:17:26 +0000 | [diff] [blame] | 142 | \begin{funcdesc}{execvpe}{path, args, env} |
| 143 | This is a cross between \function{execve()} and \function{execvp()}. |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 144 | The directory list is obtained from \code{\var{env}['PATH']}. |
| 145 | \end{funcdesc} |
| 146 | |
Fred Drake | 1a3c2a0 | 1998-08-06 15:18:23 +0000 | [diff] [blame] | 147 | (The functions \function{execv()} and \function{execve()} are not |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 148 | documented here, since they are implemented by the OS dependent |
| 149 | module. If the OS dependent module doesn't define either of these, |
| 150 | the functions that rely on it will raise an exception. They are |
Fred Drake | c4f15af | 1998-03-10 03:17:26 +0000 | [diff] [blame] | 151 | documented in the section on module \module{posix}, together with all |
| 152 | other functions that \module{os} imports from the OS dependent module.) |