Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 1 | \section{\module{os} --- |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 2 | Miscellaneous operating system interfaces} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 3 | |
Fred Drake | ec6baaf | 1999-04-21 18:13:31 +0000 | [diff] [blame] | 4 | \declaremodule{standard}{os} |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 5 | \modulesynopsis{Miscellaneous operating system interfaces.} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 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 |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 9 | dependent functionality than importing a operating system dependent |
| 10 | built-in module like \refmodule{posix} or \module{nt}. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 11 | |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 12 | This module searches for an operating system dependent built-in module like |
Fred Drake | 2f97901 | 1999-06-11 18:28:37 +0000 | [diff] [blame] | 13 | \module{mac} or \refmodule{posix} and exports the same functions and data |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 14 | as found there. The design of all Python's built-in operating system dependent |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 15 | modules is such that as long as the same functionality is available, |
Fred Drake | 907e76b | 2001-07-06 20:30:11 +0000 | [diff] [blame] | 16 | it uses the same interface; for example, the function |
Fred Drake | ec6baaf | 1999-04-21 18:13:31 +0000 | [diff] [blame] | 17 | \code{os.stat(\var{path})} returns stat information about \var{path} in |
| 18 | the same format (which happens to have originated with the |
| 19 | \POSIX{} interface). |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 20 | |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 21 | Extensions peculiar to a particular operating system are also |
| 22 | available through the \module{os} module, but using them is of course a |
| 23 | threat to 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} |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 27 | instead of directly from the operating system dependent built-in module, |
| 28 | so there should be \emph{no} reason not to use \module{os}! |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 29 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 30 | |
Fred Drake | 859dc53 | 1999-07-01 13:54:40 +0000 | [diff] [blame] | 31 | % Frank Stajano <fstajano@uk.research.att.com> complained that it |
| 32 | % wasn't clear that the entries described in the subsections were all |
| 33 | % available at the module level (most uses of subsections are |
| 34 | % different); I think this is only a problem for the HTML version, |
| 35 | % where the relationship may not be as clear. |
| 36 | % |
| 37 | \ifhtml |
| 38 | The \module{os} module contains many functions and data values. |
| 39 | The items below and in the following sub-sections are all available |
| 40 | directly from the \module{os} module. |
| 41 | \fi |
| 42 | |
| 43 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 44 | \begin{excdesc}{error} |
Fred Drake | 907e76b | 2001-07-06 20:30:11 +0000 | [diff] [blame] | 45 | This exception is raised when a function returns a system-related |
| 46 | error (not for illegal argument types or other incidental errors). |
| 47 | This is also known as the built-in exception \exception{OSError}. The |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 48 | accompanying value is a pair containing the numeric error code from |
| 49 | \cdata{errno} and the corresponding string, as would be printed by the |
| 50 | C function \cfunction{perror()}. See the module |
| 51 | \refmodule{errno}\refbimodindex{errno}, which contains names for the |
| 52 | error codes defined by the underlying operating system. |
| 53 | |
| 54 | When exceptions are classes, this exception carries two attributes, |
| 55 | \member{errno} and \member{strerror}. The first holds the value of |
| 56 | the C \cdata{errno} variable, and the latter holds the corresponding |
| 57 | error message from \cfunction{strerror()}. For exceptions that |
Fred Drake | 907e76b | 2001-07-06 20:30:11 +0000 | [diff] [blame] | 58 | involve a file system path (such as \function{chdir()} or |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 59 | \function{unlink()}), the exception instance will contain a third |
| 60 | attribute, \member{filename}, which is the file name passed to the |
| 61 | function. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 62 | \end{excdesc} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 63 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 64 | \begin{datadesc}{name} |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 65 | The name of the operating system dependent module imported. The |
Fred Drake | 6995bb6 | 2001-11-29 20:48:44 +0000 | [diff] [blame] | 66 | following names have currently been registered: \code{'posix'}, |
Martin v. Löwis | 36a4d8c | 2002-10-10 18:24:54 +0000 | [diff] [blame] | 67 | \code{'nt'}, \code{'mac'}, \code{'os2'}, \code{'ce'}, |
Fred Drake | 6995bb6 | 2001-11-29 20:48:44 +0000 | [diff] [blame] | 68 | \code{'java'}, \code{'riscos'}. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 69 | \end{datadesc} |
| 70 | |
| 71 | \begin{datadesc}{path} |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 72 | The corresponding operating system dependent standard module for pathname |
Fred Drake | 907e76b | 2001-07-06 20:30:11 +0000 | [diff] [blame] | 73 | operations, such as \module{posixpath} or \module{macpath}. Thus, |
| 74 | given the proper imports, \code{os.path.split(\var{file})} is |
| 75 | equivalent to but more portable than |
| 76 | \code{posixpath.split(\var{file})}. Note that this is also an |
| 77 | importable module: it may be imported directly as |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 78 | \refmodule{os.path}. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 79 | \end{datadesc} |
| 80 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 81 | |
| 82 | |
| 83 | \subsection{Process Parameters \label{os-procinfo}} |
| 84 | |
| 85 | These functions and data items provide information and operate on the |
| 86 | current process and user. |
| 87 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 88 | \begin{datadesc}{environ} |
Fred Drake | 0e1de8b | 1999-04-29 12:57:32 +0000 | [diff] [blame] | 89 | A mapping object representing the string environment. For example, |
| 90 | \code{environ['HOME']} is the pathname of your home directory (on some |
| 91 | platforms), and is equivalent to \code{getenv("HOME")} in C. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 92 | |
| 93 | If the platform supports the \function{putenv()} function, this |
| 94 | mapping may be used to modify the environment as well as query the |
| 95 | environment. \function{putenv()} will be called automatically when |
Neal Norwitz | 2b09bc4 | 2003-02-07 02:27:36 +0000 | [diff] [blame] | 96 | the mapping is modified. \note{On some platforms, including |
| 97 | FreeBSD and Mac OS X, setting \code{environ} may cause memory leaks. |
| 98 | Refer to the system documentation for putenv.} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 99 | |
| 100 | If \function{putenv()} is not provided, this mapping may be passed to |
Tim Peters | ab034fa | 2002-02-01 11:27:43 +0000 | [diff] [blame] | 101 | the appropriate process-creation functions to cause child processes to |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 102 | use a modified environment. |
| 103 | \end{datadesc} |
| 104 | |
Fred Drake | 6db897c | 1999-07-12 16:49:30 +0000 | [diff] [blame] | 105 | \begin{funcdescni}{chdir}{path} |
Fred Drake | e19a5bc | 2002-04-15 19:46:40 +0000 | [diff] [blame] | 106 | \funclineni{fchdir}{fd} |
Fred Drake | 6db897c | 1999-07-12 16:49:30 +0000 | [diff] [blame] | 107 | \funclineni{getcwd}{} |
| 108 | These functions are described in ``Files and Directories'' (section |
| 109 | \ref{os-file-dir}). |
| 110 | \end{funcdescni} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 111 | |
Fred Drake | 18f7a45 | 1999-12-09 22:11:43 +0000 | [diff] [blame] | 112 | \begin{funcdesc}{ctermid}{} |
| 113 | Return the filename corresponding to the controlling terminal of the |
| 114 | process. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 115 | Availability: \UNIX. |
Fred Drake | 18f7a45 | 1999-12-09 22:11:43 +0000 | [diff] [blame] | 116 | \end{funcdesc} |
| 117 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 118 | \begin{funcdesc}{getegid}{} |
Fred Drake | d3e6678 | 2002-04-26 20:59:40 +0000 | [diff] [blame] | 119 | Return the effective group id of the current process. This |
| 120 | corresponds to the `set id' bit on the file being executed in the |
| 121 | current process. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 122 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 123 | \end{funcdesc} |
| 124 | |
| 125 | \begin{funcdesc}{geteuid}{} |
Fred Drake | 6b330ba8 | 1999-05-25 13:42:26 +0000 | [diff] [blame] | 126 | \index{user!effective id} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 127 | Return the current process' effective user id. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 128 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 129 | \end{funcdesc} |
| 130 | |
| 131 | \begin{funcdesc}{getgid}{} |
Fred Drake | 6b330ba8 | 1999-05-25 13:42:26 +0000 | [diff] [blame] | 132 | \index{process!group} |
Fred Drake | d3e6678 | 2002-04-26 20:59:40 +0000 | [diff] [blame] | 133 | Return the real group id of the current process. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 134 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 135 | \end{funcdesc} |
| 136 | |
Fred Drake | 88f6ca2 | 1999-12-15 19:39:04 +0000 | [diff] [blame] | 137 | \begin{funcdesc}{getgroups}{} |
| 138 | Return list of supplemental group ids associated with the current |
| 139 | process. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 140 | Availability: \UNIX. |
Fred Drake | 88f6ca2 | 1999-12-15 19:39:04 +0000 | [diff] [blame] | 141 | \end{funcdesc} |
| 142 | |
| 143 | \begin{funcdesc}{getlogin}{} |
Jeremy Hylton | 403e351 | 2002-07-24 15:32:25 +0000 | [diff] [blame] | 144 | Return the name of the user logged in on the controlling terminal of |
| 145 | the process. For most purposes, it is more useful to use the |
Andrew M. Kuchling | 4b37364 | 2003-02-03 15:36:26 +0000 | [diff] [blame] | 146 | environment variable \envvar{LOGNAME} to find out who the user is, |
| 147 | or \code{pwd.getpwuid(os.getuid())[0]} to get the login name |
| 148 | of the currently effective user ID. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 149 | Availability: \UNIX. |
Fred Drake | 88f6ca2 | 1999-12-15 19:39:04 +0000 | [diff] [blame] | 150 | \end{funcdesc} |
| 151 | |
Martin v. Löwis | 606edc1 | 2002-06-13 21:09:11 +0000 | [diff] [blame] | 152 | \begin{funcdesc}{getpgid}{pid} |
| 153 | Return the process group id of the process with process id \var{pid}. |
| 154 | If \var{pid} is 0, the process group id of the current process is |
| 155 | returned. Availability: \UNIX. |
Neal Norwitz | cc5c694 | 2002-06-13 21:19:25 +0000 | [diff] [blame] | 156 | \versionadded{2.3} |
Martin v. Löwis | 606edc1 | 2002-06-13 21:09:11 +0000 | [diff] [blame] | 157 | \end{funcdesc} |
| 158 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 159 | \begin{funcdesc}{getpgrp}{} |
| 160 | \index{process!group} |
Fred Drake | d3e6678 | 2002-04-26 20:59:40 +0000 | [diff] [blame] | 161 | Return the id of the current process group. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 162 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 163 | \end{funcdesc} |
| 164 | |
| 165 | \begin{funcdesc}{getpid}{} |
| 166 | \index{process!id} |
| 167 | Return the current process id. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 168 | Availability: \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 169 | \end{funcdesc} |
| 170 | |
| 171 | \begin{funcdesc}{getppid}{} |
| 172 | \index{process!id of parent} |
| 173 | Return the parent's process id. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 174 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 175 | \end{funcdesc} |
| 176 | |
| 177 | \begin{funcdesc}{getuid}{} |
Fred Drake | 6b330ba8 | 1999-05-25 13:42:26 +0000 | [diff] [blame] | 178 | \index{user!id} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 179 | Return the current process' user id. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 180 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 181 | \end{funcdesc} |
| 182 | |
Fred Drake | 81e142b | 2001-05-31 20:27:46 +0000 | [diff] [blame] | 183 | \begin{funcdesc}{getenv}{varname\optional{, value}} |
| 184 | Return the value of the environment variable \var{varname} if it |
| 185 | exists, or \var{value} if it doesn't. \var{value} defaults to |
| 186 | \code{None}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 187 | Availability: most flavors of \UNIX, Windows. |
Fred Drake | 81e142b | 2001-05-31 20:27:46 +0000 | [diff] [blame] | 188 | \end{funcdesc} |
| 189 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 190 | \begin{funcdesc}{putenv}{varname, value} |
| 191 | \index{environment variables!setting} |
| 192 | Set the environment variable named \var{varname} to the string |
| 193 | \var{value}. Such changes to the environment affect subprocesses |
| 194 | started with \function{os.system()}, \function{popen()} or |
| 195 | \function{fork()} and \function{execv()}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 196 | Availability: most flavors of \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 197 | |
Neal Norwitz | 2b09bc4 | 2003-02-07 02:27:36 +0000 | [diff] [blame] | 198 | \note{On some platforms, including FreeBSD and Mac OS X, |
| 199 | setting \code{environ} may cause memory leaks. |
| 200 | Refer to the system documentation for putenv.} |
| 201 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 202 | When \function{putenv()} is |
| 203 | supported, assignments to items in \code{os.environ} are automatically |
| 204 | translated into corresponding calls to \function{putenv()}; however, |
| 205 | calls to \function{putenv()} don't update \code{os.environ}, so it is |
Tim Peters | ab034fa | 2002-02-01 11:27:43 +0000 | [diff] [blame] | 206 | actually preferable to assign to items of \code{os.environ}. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 207 | \end{funcdesc} |
| 208 | |
Andrew M. Kuchling | 8d2f2b2 | 2000-07-13 01:26:58 +0000 | [diff] [blame] | 209 | \begin{funcdesc}{setegid}{egid} |
| 210 | Set the current process's effective group id. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 211 | Availability: \UNIX. |
Andrew M. Kuchling | 8d2f2b2 | 2000-07-13 01:26:58 +0000 | [diff] [blame] | 212 | \end{funcdesc} |
| 213 | |
| 214 | \begin{funcdesc}{seteuid}{euid} |
| 215 | Set the current process's effective user id. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 216 | Availability: \UNIX. |
Andrew M. Kuchling | 8d2f2b2 | 2000-07-13 01:26:58 +0000 | [diff] [blame] | 217 | \end{funcdesc} |
| 218 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 219 | \begin{funcdesc}{setgid}{gid} |
| 220 | Set the current process' group id. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 221 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 222 | \end{funcdesc} |
| 223 | |
Martin v. Löwis | 61c5edf | 2001-10-18 04:06:00 +0000 | [diff] [blame] | 224 | \begin{funcdesc}{setgroups}{groups} |
Martin v. Löwis | c405133 | 2001-10-18 14:07:12 +0000 | [diff] [blame] | 225 | Set the list of supplemental group ids associated with the current |
| 226 | process to \var{groups}. \var{groups} must be a sequence, and each |
| 227 | element must be an integer identifying a group. This operation is |
| 228 | typical available only to the superuser. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 229 | Availability: \UNIX. |
Martin v. Löwis | 61c5edf | 2001-10-18 04:06:00 +0000 | [diff] [blame] | 230 | \versionadded{2.2} |
| 231 | \end{funcdesc} |
| 232 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 233 | \begin{funcdesc}{setpgrp}{} |
| 234 | Calls the system call \cfunction{setpgrp()} or \cfunction{setpgrp(0, |
| 235 | 0)} depending on which version is implemented (if any). See the |
| 236 | \UNIX{} manual for the semantics. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 237 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 238 | \end{funcdesc} |
| 239 | |
Fred Drake | d3e6678 | 2002-04-26 20:59:40 +0000 | [diff] [blame] | 240 | \begin{funcdesc}{setpgid}{pid, pgrp} Calls the system call |
| 241 | \cfunction{setpgid()} to set the process group id of the process with |
| 242 | id \var{pid} to the process group with id \var{pgrp}. See the \UNIX{} |
| 243 | manual for the semantics. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 244 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 245 | \end{funcdesc} |
| 246 | |
Andrew M. Kuchling | 8d2f2b2 | 2000-07-13 01:26:58 +0000 | [diff] [blame] | 247 | \begin{funcdesc}{setreuid}{ruid, euid} |
| 248 | Set the current process's real and effective user ids. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 249 | Availability: \UNIX. |
Andrew M. Kuchling | 8d2f2b2 | 2000-07-13 01:26:58 +0000 | [diff] [blame] | 250 | \end{funcdesc} |
| 251 | |
| 252 | \begin{funcdesc}{setregid}{rgid, egid} |
| 253 | Set the current process's real and effective group ids. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 254 | Availability: \UNIX. |
Andrew M. Kuchling | 8d2f2b2 | 2000-07-13 01:26:58 +0000 | [diff] [blame] | 255 | \end{funcdesc} |
| 256 | |
Martin v. Löwis | 49ee14d | 2003-11-10 06:35:36 +0000 | [diff] [blame] | 257 | \begin{funcdesc}{getsid}{pid} |
| 258 | Calls the system call \cfunction{getsid()}. See the \UNIX{} manual |
| 259 | for the semantics. |
Martin v. Löwis | 75aa4db | 2003-11-10 06:46:15 +0000 | [diff] [blame] | 260 | Availability: \UNIX. \versionadded{2.4} |
Martin v. Löwis | 49ee14d | 2003-11-10 06:35:36 +0000 | [diff] [blame] | 261 | \end{funcdesc} |
| 262 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 263 | \begin{funcdesc}{setsid}{} |
| 264 | Calls the system call \cfunction{setsid()}. See the \UNIX{} manual |
| 265 | for the semantics. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 266 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 267 | \end{funcdesc} |
| 268 | |
| 269 | \begin{funcdesc}{setuid}{uid} |
Fred Drake | 6b330ba8 | 1999-05-25 13:42:26 +0000 | [diff] [blame] | 270 | \index{user!id, setting} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 271 | Set the current process' user id. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 272 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 273 | \end{funcdesc} |
| 274 | |
Raymond Hettinger | 9b4dab4 | 2003-12-31 18:37:28 +0000 | [diff] [blame] | 275 | % placed in this section since it relates to errno.... a little weak |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 276 | \begin{funcdesc}{strerror}{code} |
| 277 | Return the error message corresponding to the error code in |
| 278 | \var{code}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 279 | Availability: \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 280 | \end{funcdesc} |
| 281 | |
| 282 | \begin{funcdesc}{umask}{mask} |
| 283 | Set the current numeric umask and returns the previous umask. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 284 | Availability: \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 285 | \end{funcdesc} |
| 286 | |
| 287 | \begin{funcdesc}{uname}{} |
| 288 | Return a 5-tuple containing information identifying the current |
| 289 | operating system. The tuple contains 5 strings: |
| 290 | \code{(\var{sysname}, \var{nodename}, \var{release}, \var{version}, |
| 291 | \var{machine})}. Some systems truncate the nodename to 8 |
| 292 | characters or to the leading component; a better way to get the |
| 293 | hostname is \function{socket.gethostname()} |
| 294 | \withsubitem{(in module socket)}{\ttindex{gethostname()}} |
| 295 | or even |
| 296 | \withsubitem{(in module socket)}{\ttindex{gethostbyaddr()}} |
| 297 | \code{socket.gethostbyaddr(socket.gethostname())}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 298 | Availability: recent flavors of \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 299 | \end{funcdesc} |
| 300 | |
| 301 | |
| 302 | |
| 303 | \subsection{File Object Creation \label{os-newstreams}} |
| 304 | |
| 305 | These functions create new file objects. |
| 306 | |
| 307 | |
| 308 | \begin{funcdesc}{fdopen}{fd\optional{, mode\optional{, bufsize}}} |
| 309 | Return an open file object connected to the file descriptor \var{fd}. |
Fred Drake | 8c9fc00 | 1999-08-05 13:41:31 +0000 | [diff] [blame] | 310 | \index{I/O control!buffering} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 311 | The \var{mode} and \var{bufsize} arguments have the same meaning as |
| 312 | the corresponding arguments to the built-in \function{open()} |
| 313 | function. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 314 | Availability: Macintosh, \UNIX, Windows. |
Thomas Heller | 5b470e0 | 2002-11-07 16:33:44 +0000 | [diff] [blame] | 315 | |
| 316 | \versionchanged[When specified, the \var{mode} argument must now start |
Fred Drake | b5f41de | 2002-11-07 17:13:03 +0000 | [diff] [blame] | 317 | with one of the letters \character{r}, \character{w}, or \character{a}, |
| 318 | otherwise a \exception{ValueError} is raised]{2.3} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 319 | \end{funcdesc} |
| 320 | |
| 321 | \begin{funcdesc}{popen}{command\optional{, mode\optional{, bufsize}}} |
| 322 | Open a pipe to or from \var{command}. The return value is an open |
| 323 | file object connected to the pipe, which can be read or written |
| 324 | depending on whether \var{mode} is \code{'r'} (default) or \code{'w'}. |
| 325 | The \var{bufsize} argument has the same meaning as the corresponding |
| 326 | argument to the built-in \function{open()} function. The exit status of |
| 327 | the command (encoded in the format specified for \function{wait()}) is |
| 328 | available as the return value of the \method{close()} method of the file |
| 329 | object, except that when the exit status is zero (termination without |
Fred Drake | 1319e3e | 2000-10-03 17:14:27 +0000 | [diff] [blame] | 330 | errors), \code{None} is returned. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 331 | Availability: \UNIX, Windows. |
Fred Drake | c71c23e | 2000-10-04 13:57:27 +0000 | [diff] [blame] | 332 | |
| 333 | \versionchanged[This function worked unreliably under Windows in |
| 334 | earlier versions of Python. This was due to the use of the |
| 335 | \cfunction{_popen()} function from the libraries provided with |
| 336 | Windows. Newer versions of Python do not use the broken |
| 337 | implementation from the Windows libraries]{2.0} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 338 | \end{funcdesc} |
| 339 | |
Fred Drake | 18f7a45 | 1999-12-09 22:11:43 +0000 | [diff] [blame] | 340 | \begin{funcdesc}{tmpfile}{} |
Guido van Rossum | db9198a | 2002-06-10 19:23:22 +0000 | [diff] [blame] | 341 | Return a new file object opened in update mode (\samp{w+b}). The file |
Fred Drake | 18f7a45 | 1999-12-09 22:11:43 +0000 | [diff] [blame] | 342 | has no directory entries associated with it and will be automatically |
| 343 | deleted once there are no file descriptors for the file. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 344 | Availability: \UNIX, Windows. |
Fred Drake | 18f7a45 | 1999-12-09 22:11:43 +0000 | [diff] [blame] | 345 | \end{funcdesc} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 346 | |
| 347 | |
Fred Drake | 8a9db99 | 2000-09-28 20:27:51 +0000 | [diff] [blame] | 348 | For each of these \function{popen()} variants, if \var{bufsize} is |
| 349 | specified, it specifies the buffer size for the I/O pipes. |
| 350 | \var{mode}, if provided, should be the string \code{'b'} or |
| 351 | \code{'t'}; on Windows this is needed to determine whether the file |
| 352 | objects should be opened in binary or text mode. The default value |
| 353 | for \var{mode} is \code{'t'}. |
| 354 | |
Fred Drake | 098d7fa | 2001-09-11 19:56:51 +0000 | [diff] [blame] | 355 | These methods do not make it possible to retrieve the return code from |
| 356 | the child processes. The only way to control the input and output |
| 357 | streams and also retrieve the return codes is to use the |
| 358 | \class{Popen3} and \class{Popen4} classes from the \refmodule{popen2} |
| 359 | module; these are only available on \UNIX. |
| 360 | |
Fred Drake | 08d10f9 | 2002-12-06 16:45:05 +0000 | [diff] [blame] | 361 | For a discussion of possible deadlock conditions related to the use |
Fred Drake | 9ea01d4 | 2002-06-18 20:30:37 +0000 | [diff] [blame] | 362 | of these functions, see ``\ulink{Flow Control |
| 363 | Issues}{popen2-flow-control.html}'' |
| 364 | (section~\ref{popen2-flow-control}). |
| 365 | |
Fred Drake | 046f4d8 | 2001-06-11 15:21:48 +0000 | [diff] [blame] | 366 | \begin{funcdesc}{popen2}{cmd\optional{, mode\optional{, bufsize}}} |
Fred Drake | 8a9db99 | 2000-09-28 20:27:51 +0000 | [diff] [blame] | 367 | Executes \var{cmd} as a sub-process. Returns the file objects |
| 368 | \code{(\var{child_stdin}, \var{child_stdout})}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 369 | Availability: \UNIX, Windows. |
Fred Drake | 8a9db99 | 2000-09-28 20:27:51 +0000 | [diff] [blame] | 370 | \versionadded{2.0} |
| 371 | \end{funcdesc} |
| 372 | |
Fred Drake | 046f4d8 | 2001-06-11 15:21:48 +0000 | [diff] [blame] | 373 | \begin{funcdesc}{popen3}{cmd\optional{, mode\optional{, bufsize}}} |
Fred Drake | 8a9db99 | 2000-09-28 20:27:51 +0000 | [diff] [blame] | 374 | Executes \var{cmd} as a sub-process. Returns the file objects |
| 375 | \code{(\var{child_stdin}, \var{child_stdout}, \var{child_stderr})}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 376 | Availability: \UNIX, Windows. |
Fred Drake | 8a9db99 | 2000-09-28 20:27:51 +0000 | [diff] [blame] | 377 | \versionadded{2.0} |
| 378 | \end{funcdesc} |
| 379 | |
Fred Drake | 046f4d8 | 2001-06-11 15:21:48 +0000 | [diff] [blame] | 380 | \begin{funcdesc}{popen4}{cmd\optional{, mode\optional{, bufsize}}} |
Fred Drake | 8a9db99 | 2000-09-28 20:27:51 +0000 | [diff] [blame] | 381 | Executes \var{cmd} as a sub-process. Returns the file objects |
| 382 | \code{(\var{child_stdin}, \var{child_stdout_and_stderr})}. |
Andrew M. Kuchling | e1ca355 | 2004-06-05 19:25:30 +0000 | [diff] [blame] | 383 | |
| 384 | (Note that \code{\var{child_stdin}, \var{child_stdout}, and |
| 385 | \var{child_stderr}} are named from the point of view of the child |
| 386 | process, i.e. \var{child_stdin} is the child's standard input.) |
| 387 | |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 388 | Availability: \UNIX, Windows. |
Fred Drake | 8a9db99 | 2000-09-28 20:27:51 +0000 | [diff] [blame] | 389 | \versionadded{2.0} |
| 390 | \end{funcdesc} |
| 391 | |
| 392 | This functionality is also available in the \refmodule{popen2} module |
| 393 | using functions of the same names, but the return values of those |
| 394 | functions have a different order. |
| 395 | |
| 396 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 397 | \subsection{File Descriptor Operations \label{os-fd-ops}} |
| 398 | |
| 399 | These functions operate on I/O streams referred to |
| 400 | using file descriptors. |
| 401 | |
| 402 | |
| 403 | \begin{funcdesc}{close}{fd} |
| 404 | Close file descriptor \var{fd}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 405 | Availability: Macintosh, \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 406 | |
Fred Drake | 0ed6634 | 2004-04-16 15:20:01 +0000 | [diff] [blame] | 407 | \begin{notice} |
| 408 | This function is intended for low-level I/O and must be applied |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 409 | to a file descriptor as returned by \function{open()} or |
| 410 | \function{pipe()}. To close a ``file object'' returned by the |
| 411 | built-in function \function{open()} or by \function{popen()} or |
| 412 | \function{fdopen()}, use its \method{close()} method. |
Fred Drake | 0ed6634 | 2004-04-16 15:20:01 +0000 | [diff] [blame] | 413 | \end{notice} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 414 | \end{funcdesc} |
| 415 | |
| 416 | \begin{funcdesc}{dup}{fd} |
| 417 | Return a duplicate of file descriptor \var{fd}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 418 | Availability: Macintosh, \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 419 | \end{funcdesc} |
| 420 | |
| 421 | \begin{funcdesc}{dup2}{fd, fd2} |
| 422 | Duplicate file descriptor \var{fd} to \var{fd2}, closing the latter |
| 423 | first if necessary. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 424 | Availability: \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 425 | \end{funcdesc} |
| 426 | |
Raymond Hettinger | 3cfdc34 | 2002-08-07 15:48:17 +0000 | [diff] [blame] | 427 | \begin{funcdesc}{fdatasync}{fd} |
| 428 | Force write of file with filedescriptor \var{fd} to disk. |
| 429 | Does not force update of metadata. |
| 430 | Availability: \UNIX. |
| 431 | \end{funcdesc} |
| 432 | |
Fred Drake | 88f6ca2 | 1999-12-15 19:39:04 +0000 | [diff] [blame] | 433 | \begin{funcdesc}{fpathconf}{fd, name} |
Thomas Wouters | f831663 | 2000-07-16 19:01:10 +0000 | [diff] [blame] | 434 | Return system configuration information relevant to an open file. |
Fred Drake | 88f6ca2 | 1999-12-15 19:39:04 +0000 | [diff] [blame] | 435 | \var{name} specifies the configuration value to retrieve; it may be a |
| 436 | string which is the name of a defined system value; these names are |
Raymond Hettinger | b67449d | 2003-09-08 18:52:18 +0000 | [diff] [blame] | 437 | specified in a number of standards (\POSIX.1, \UNIX{} 95, \UNIX{} 98, and |
Fred Drake | 88f6ca2 | 1999-12-15 19:39:04 +0000 | [diff] [blame] | 438 | others). Some platforms define additional names as well. The names |
| 439 | known to the host operating system are given in the |
| 440 | \code{pathconf_names} dictionary. For configuration variables not |
| 441 | included in that mapping, passing an integer for \var{name} is also |
| 442 | accepted. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 443 | Availability: \UNIX. |
Fred Drake | 88f6ca2 | 1999-12-15 19:39:04 +0000 | [diff] [blame] | 444 | |
| 445 | If \var{name} is a string and is not known, \exception{ValueError} is |
| 446 | raised. If a specific value for \var{name} is not supported by the |
| 447 | host system, even if it is included in \code{pathconf_names}, an |
| 448 | \exception{OSError} is raised with \constant{errno.EINVAL} for the |
| 449 | error number. |
| 450 | \end{funcdesc} |
| 451 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 452 | \begin{funcdesc}{fstat}{fd} |
| 453 | Return status for file descriptor \var{fd}, like \function{stat()}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 454 | Availability: \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 455 | \end{funcdesc} |
| 456 | |
| 457 | \begin{funcdesc}{fstatvfs}{fd} |
| 458 | Return information about the filesystem containing the file associated |
| 459 | with file descriptor \var{fd}, like \function{statvfs()}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 460 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 461 | \end{funcdesc} |
| 462 | |
Raymond Hettinger | 3cfdc34 | 2002-08-07 15:48:17 +0000 | [diff] [blame] | 463 | \begin{funcdesc}{fsync}{fd} |
Tim Peters | 2d1c846 | 2003-04-23 19:47:14 +0000 | [diff] [blame] | 464 | Force write of file with filedescriptor \var{fd} to disk. On \UNIX, |
| 465 | this calls the native \cfunction{fsync()} function; on Windows, the |
| 466 | MS \cfunction{_commit()} function. |
Tim Peters | 11b2306 | 2003-04-23 02:39:17 +0000 | [diff] [blame] | 467 | |
Tim Peters | 2d1c846 | 2003-04-23 19:47:14 +0000 | [diff] [blame] | 468 | If you're starting with a Python file object \var{f}, first do |
Raymond Hettinger | 52136a8 | 2003-05-10 03:35:37 +0000 | [diff] [blame] | 469 | \code{\var{f}.flush()}, and then do \code{os.fsync(\var{f}.fileno())}, |
Tim Peters | 11b2306 | 2003-04-23 02:39:17 +0000 | [diff] [blame] | 470 | to ensure that all internal buffers associated with \var{f} are written |
| 471 | to disk. |
Tim Peters | 2d1c846 | 2003-04-23 19:47:14 +0000 | [diff] [blame] | 472 | Availability: \UNIX, and Windows starting in 2.2.3. |
Raymond Hettinger | 3cfdc34 | 2002-08-07 15:48:17 +0000 | [diff] [blame] | 473 | \end{funcdesc} |
| 474 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 475 | \begin{funcdesc}{ftruncate}{fd, length} |
Tim Peters | ab034fa | 2002-02-01 11:27:43 +0000 | [diff] [blame] | 476 | Truncate the file corresponding to file descriptor \var{fd}, |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 477 | so that it is at most \var{length} bytes in size. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 478 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 479 | \end{funcdesc} |
| 480 | |
Skip Montanaro | d372521 | 2000-07-19 17:30:58 +0000 | [diff] [blame] | 481 | \begin{funcdesc}{isatty}{fd} |
Fred Drake | 106c1a0 | 2002-04-23 15:58:02 +0000 | [diff] [blame] | 482 | Return \code{True} if the file descriptor \var{fd} is open and |
| 483 | connected to a tty(-like) device, else \code{False}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 484 | Availability: \UNIX. |
Skip Montanaro | d372521 | 2000-07-19 17:30:58 +0000 | [diff] [blame] | 485 | \end{funcdesc} |
| 486 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 487 | \begin{funcdesc}{lseek}{fd, pos, how} |
| 488 | Set the current position of file descriptor \var{fd} to position |
| 489 | \var{pos}, modified by \var{how}: \code{0} to set the position |
| 490 | relative to the beginning of the file; \code{1} to set it relative to |
| 491 | the current position; \code{2} to set it relative to the end of the |
| 492 | file. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 493 | Availability: Macintosh, \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 494 | \end{funcdesc} |
| 495 | |
| 496 | \begin{funcdesc}{open}{file, flags\optional{, mode}} |
| 497 | Open the file \var{file} and set various flags according to |
| 498 | \var{flags} and possibly its mode according to \var{mode}. |
| 499 | The default \var{mode} is \code{0777} (octal), and the current umask |
| 500 | value is first masked out. Return the file descriptor for the newly |
| 501 | opened file. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 502 | Availability: Macintosh, \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 503 | |
| 504 | For a description of the flag and mode values, see the C run-time |
| 505 | documentation; flag constants (like \constant{O_RDONLY} and |
| 506 | \constant{O_WRONLY}) are defined in this module too (see below). |
| 507 | |
Fred Drake | 0ed6634 | 2004-04-16 15:20:01 +0000 | [diff] [blame] | 508 | \begin{notice} |
| 509 | This function is intended for low-level I/O. For normal usage, |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 510 | use the built-in function \function{open()}, which returns a ``file |
| 511 | object'' with \method{read()} and \method{write()} methods (and many |
| 512 | more). |
Fred Drake | 0ed6634 | 2004-04-16 15:20:01 +0000 | [diff] [blame] | 513 | \end{notice} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 514 | \end{funcdesc} |
| 515 | |
Fred Drake | c82634c | 2000-06-28 17:27:48 +0000 | [diff] [blame] | 516 | \begin{funcdesc}{openpty}{} |
| 517 | Open a new pseudo-terminal pair. Return a pair of file descriptors |
| 518 | \code{(\var{master}, \var{slave})} for the pty and the tty, |
| 519 | respectively. For a (slightly) more portable approach, use the |
| 520 | \refmodule{pty}\refstmodindex{pty} module. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 521 | Availability: Some flavors of \UNIX. |
Fred Drake | c82634c | 2000-06-28 17:27:48 +0000 | [diff] [blame] | 522 | \end{funcdesc} |
| 523 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 524 | \begin{funcdesc}{pipe}{} |
| 525 | Create a pipe. Return a pair of file descriptors \code{(\var{r}, |
| 526 | \var{w})} usable for reading and writing, respectively. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 527 | Availability: \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 528 | \end{funcdesc} |
| 529 | |
| 530 | \begin{funcdesc}{read}{fd, n} |
| 531 | Read at most \var{n} bytes from file descriptor \var{fd}. |
Fred Drake | a65375c | 2002-05-01 03:31:42 +0000 | [diff] [blame] | 532 | Return a string containing the bytes read. If the end of the file |
| 533 | referred to by \var{fd} has been reached, an empty string is |
| 534 | returned. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 535 | Availability: Macintosh, \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 536 | |
Fred Drake | 0ed6634 | 2004-04-16 15:20:01 +0000 | [diff] [blame] | 537 | \begin{notice} |
| 538 | This function is intended for low-level I/O and must be applied |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 539 | to a file descriptor as returned by \function{open()} or |
| 540 | \function{pipe()}. To read a ``file object'' returned by the |
| 541 | built-in function \function{open()} or by \function{popen()} or |
| 542 | \function{fdopen()}, or \code{sys.stdin}, use its |
| 543 | \method{read()} or \method{readline()} methods. |
Fred Drake | 0ed6634 | 2004-04-16 15:20:01 +0000 | [diff] [blame] | 544 | \end{notice} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 545 | \end{funcdesc} |
| 546 | |
| 547 | \begin{funcdesc}{tcgetpgrp}{fd} |
| 548 | Return the process group associated with the terminal given by |
| 549 | \var{fd} (an open file descriptor as returned by \function{open()}). |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 550 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 551 | \end{funcdesc} |
| 552 | |
| 553 | \begin{funcdesc}{tcsetpgrp}{fd, pg} |
| 554 | Set the process group associated with the terminal given by |
| 555 | \var{fd} (an open file descriptor as returned by \function{open()}) |
| 556 | to \var{pg}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 557 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 558 | \end{funcdesc} |
| 559 | |
| 560 | \begin{funcdesc}{ttyname}{fd} |
| 561 | Return a string which specifies the terminal device associated with |
| 562 | file-descriptor \var{fd}. If \var{fd} is not associated with a terminal |
| 563 | device, an exception is raised. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 564 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 565 | \end{funcdesc} |
| 566 | |
| 567 | \begin{funcdesc}{write}{fd, str} |
| 568 | Write the string \var{str} to file descriptor \var{fd}. |
| 569 | Return the number of bytes actually written. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 570 | Availability: Macintosh, \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 571 | |
Fred Drake | 0ed6634 | 2004-04-16 15:20:01 +0000 | [diff] [blame] | 572 | \begin{notice} |
| 573 | This function is intended for low-level I/O and must be applied |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 574 | to a file descriptor as returned by \function{open()} or |
| 575 | \function{pipe()}. To write a ``file object'' returned by the |
| 576 | built-in function \function{open()} or by \function{popen()} or |
| 577 | \function{fdopen()}, or \code{sys.stdout} or \code{sys.stderr}, use |
| 578 | its \method{write()} method. |
Fred Drake | 0ed6634 | 2004-04-16 15:20:01 +0000 | [diff] [blame] | 579 | \end{notice} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 580 | \end{funcdesc} |
| 581 | |
| 582 | |
| 583 | The following data items are available for use in constructing the |
| 584 | \var{flags} parameter to the \function{open()} function. |
| 585 | |
| 586 | \begin{datadesc}{O_RDONLY} |
| 587 | \dataline{O_WRONLY} |
| 588 | \dataline{O_RDWR} |
| 589 | \dataline{O_NDELAY} |
| 590 | \dataline{O_NONBLOCK} |
| 591 | \dataline{O_APPEND} |
| 592 | \dataline{O_DSYNC} |
| 593 | \dataline{O_RSYNC} |
| 594 | \dataline{O_SYNC} |
| 595 | \dataline{O_NOCTTY} |
| 596 | \dataline{O_CREAT} |
| 597 | \dataline{O_EXCL} |
| 598 | \dataline{O_TRUNC} |
| 599 | Options for the \var{flag} argument to the \function{open()} function. |
| 600 | These can be bit-wise OR'd together. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 601 | Availability: Macintosh, \UNIX, Windows. |
Tim Peters | c48a3ca | 2002-01-30 05:49:46 +0000 | [diff] [blame] | 602 | % XXX O_NDELAY, O_NONBLOCK, O_DSYNC, O_RSYNC, O_SYNC, O_NOCTTY are not on Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 603 | \end{datadesc} |
| 604 | |
Fred Drake | 3ac977e | 2000-08-11 20:19:51 +0000 | [diff] [blame] | 605 | \begin{datadesc}{O_BINARY} |
| 606 | Option for the \var{flag} argument to the \function{open()} function. |
| 607 | This can be bit-wise OR'd together with those listed above. |
| 608 | Availability: Macintosh, Windows. |
| 609 | % XXX need to check on the availability of this one. |
| 610 | \end{datadesc} |
| 611 | |
Tim Peters | c48a3ca | 2002-01-30 05:49:46 +0000 | [diff] [blame] | 612 | \begin{datadesc}{O_NOINHERIT} |
| 613 | \dataline{O_SHORT_LIVED} |
| 614 | \dataline{O_TEMPORARY} |
| 615 | \dataline{O_RANDOM} |
| 616 | \dataline{O_SEQUENTIAL} |
| 617 | \dataline{O_TEXT} |
| 618 | Options for the \var{flag} argument to the \function{open()} function. |
| 619 | These can be bit-wise OR'd together. |
| 620 | Availability: Windows. |
| 621 | \end{datadesc} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 622 | |
| 623 | \subsection{Files and Directories \label{os-file-dir}} |
| 624 | |
| 625 | \begin{funcdesc}{access}{path, mode} |
Fred Drake | 7f59124 | 2002-06-18 16:15:51 +0000 | [diff] [blame] | 626 | Use the real uid/gid to test for access to \var{path}. Note that most |
| 627 | operations will use the effective uid/gid, therefore this routine can |
| 628 | be used in a suid/sgid environment to test if the invoking user has the |
| 629 | specified access to \var{path}. \var{mode} should be \constant{F_OK} |
| 630 | to test the existence of \var{path}, or it can be the inclusive OR of |
| 631 | one or more of \constant{R_OK}, \constant{W_OK}, and \constant{X_OK} to |
Raymond Hettinger | 9b4dab4 | 2003-12-31 18:37:28 +0000 | [diff] [blame] | 632 | test permissions. Return \constant{True} if access is allowed, |
| 633 | \constant{False} if not. |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 634 | See the \UNIX{} man page \manpage{access}{2} for more information. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 635 | Availability: \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 636 | \end{funcdesc} |
| 637 | |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 638 | \begin{datadesc}{F_OK} |
| 639 | Value to pass as the \var{mode} parameter of \function{access()} to |
| 640 | test the existence of \var{path}. |
| 641 | \end{datadesc} |
| 642 | |
| 643 | \begin{datadesc}{R_OK} |
| 644 | Value to include in the \var{mode} parameter of \function{access()} |
| 645 | to test the readability of \var{path}. |
| 646 | \end{datadesc} |
| 647 | |
| 648 | \begin{datadesc}{W_OK} |
| 649 | Value to include in the \var{mode} parameter of \function{access()} |
| 650 | to test the writability of \var{path}. |
| 651 | \end{datadesc} |
| 652 | |
| 653 | \begin{datadesc}{X_OK} |
| 654 | Value to include in the \var{mode} parameter of \function{access()} |
| 655 | to determine if \var{path} can be executed. |
| 656 | \end{datadesc} |
| 657 | |
Fred Drake | 6db897c | 1999-07-12 16:49:30 +0000 | [diff] [blame] | 658 | \begin{funcdesc}{chdir}{path} |
| 659 | \index{directory!changing} |
| 660 | Change the current working directory to \var{path}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 661 | Availability: Macintosh, \UNIX, Windows. |
Fred Drake | 6db897c | 1999-07-12 16:49:30 +0000 | [diff] [blame] | 662 | \end{funcdesc} |
| 663 | |
Fred Drake | 1549855 | 2002-04-15 19:41:27 +0000 | [diff] [blame] | 664 | \begin{funcdesc}{fchdir}{fd} |
| 665 | Change the current working directory to the directory represented by |
| 666 | the file descriptor \var{fd}. The descriptor must refer to an opened |
| 667 | directory, not an open file. |
| 668 | Availability: \UNIX. |
| 669 | \versionadded{2.3} |
| 670 | \end{funcdesc} |
| 671 | |
Fred Drake | 6db897c | 1999-07-12 16:49:30 +0000 | [diff] [blame] | 672 | \begin{funcdesc}{getcwd}{} |
| 673 | Return a string representing the current working directory. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 674 | Availability: Macintosh, \UNIX, Windows. |
Fred Drake | 6db897c | 1999-07-12 16:49:30 +0000 | [diff] [blame] | 675 | \end{funcdesc} |
| 676 | |
Martin v. Löwis | a844f2d | 2002-10-05 09:46:48 +0000 | [diff] [blame] | 677 | \begin{funcdesc}{getcwdu}{} |
| 678 | Return a Unicode object representing the current working directory. |
| 679 | Availability: \UNIX, Windows. |
| 680 | \versionadded{2.3} |
| 681 | \end{funcdesc} |
| 682 | |
Martin v. Löwis | 244edc8 | 2001-10-04 22:44:26 +0000 | [diff] [blame] | 683 | \begin{funcdesc}{chroot}{path} |
| 684 | Change the root directory of the current process to \var{path}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 685 | Availability: \UNIX. |
Martin v. Löwis | 244edc8 | 2001-10-04 22:44:26 +0000 | [diff] [blame] | 686 | \versionadded{2.2} |
| 687 | \end{funcdesc} |
| 688 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 689 | \begin{funcdesc}{chmod}{path, mode} |
| 690 | Change the mode of \var{path} to the numeric \var{mode}. |
Raymond Hettinger | 0a6aa28 | 2003-08-31 05:09:52 +0000 | [diff] [blame] | 691 | \var{mode} may take one of the following values |
| 692 | (as defined in the \module{stat} module): |
Raymond Hettinger | 9f5b07d | 2003-01-06 13:31:26 +0000 | [diff] [blame] | 693 | \begin{itemize} |
| 694 | \item \code{S_ISUID} |
| 695 | \item \code{S_ISGID} |
| 696 | \item \code{S_ENFMT} |
| 697 | \item \code{S_ISVTX} |
| 698 | \item \code{S_IREAD} |
| 699 | \item \code{S_IWRITE} |
| 700 | \item \code{S_IEXEC} |
| 701 | \item \code{S_IRWXU} |
| 702 | \item \code{S_IRUSR} |
| 703 | \item \code{S_IWUSR} |
| 704 | \item \code{S_IXUSR} |
| 705 | \item \code{S_IRWXG} |
| 706 | \item \code{S_IRGRP} |
| 707 | \item \code{S_IWGRP} |
| 708 | \item \code{S_IXGRP} |
| 709 | \item \code{S_IRWXO} |
| 710 | \item \code{S_IROTH} |
| 711 | \item \code{S_IWOTH} |
| 712 | \item \code{S_IXOTH} |
| 713 | \end{itemize} |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 714 | Availability: \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 715 | \end{funcdesc} |
| 716 | |
| 717 | \begin{funcdesc}{chown}{path, uid, gid} |
| 718 | Change the owner and group id of \var{path} to the numeric \var{uid} |
| 719 | and \var{gid}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 720 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 721 | \end{funcdesc} |
| 722 | |
Martin v. Löwis | 0cec0ff | 2002-07-28 16:33:45 +0000 | [diff] [blame] | 723 | \begin{funcdesc}{lchown}{path, uid, gid} |
| 724 | Change the owner and group id of \var{path} to the numeric \var{uid} |
| 725 | and gid. This function will not follow symbolic links. |
| 726 | Availability: \UNIX. |
| 727 | \versionadded{2.3} |
| 728 | \end{funcdesc} |
| 729 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 730 | \begin{funcdesc}{link}{src, dst} |
| 731 | Create a hard link pointing to \var{src} named \var{dst}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 732 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 733 | \end{funcdesc} |
| 734 | |
| 735 | \begin{funcdesc}{listdir}{path} |
| 736 | Return a list containing the names of the entries in the directory. |
| 737 | The list is in arbitrary order. It does not include the special |
| 738 | entries \code{'.'} and \code{'..'} even if they are present in the |
| 739 | directory. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 740 | Availability: Macintosh, \UNIX, Windows. |
Martin v. Löwis | a844f2d | 2002-10-05 09:46:48 +0000 | [diff] [blame] | 741 | |
Fred Drake | 5c7b248 | 2003-03-20 17:39:38 +0000 | [diff] [blame] | 742 | \versionchanged[On Windows NT/2k/XP and Unix, if \var{path} is a Unicode |
Just van Rossum | 96b1c90 | 2003-03-03 17:32:15 +0000 | [diff] [blame] | 743 | object, the result will be a list of Unicode objects.]{2.3} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 744 | \end{funcdesc} |
| 745 | |
| 746 | \begin{funcdesc}{lstat}{path} |
| 747 | Like \function{stat()}, but do not follow symbolic links. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 748 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 749 | \end{funcdesc} |
| 750 | |
| 751 | \begin{funcdesc}{mkfifo}{path\optional{, mode}} |
| 752 | Create a FIFO (a named pipe) named \var{path} with numeric mode |
| 753 | \var{mode}. The default \var{mode} is \code{0666} (octal). The current |
| 754 | umask value is first masked out from the mode. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 755 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 756 | |
| 757 | FIFOs are pipes that can be accessed like regular files. FIFOs exist |
| 758 | until they are deleted (for example with \function{os.unlink()}). |
| 759 | Generally, FIFOs are used as rendezvous between ``client'' and |
| 760 | ``server'' type processes: the server opens the FIFO for reading, and |
| 761 | the client opens it for writing. Note that \function{mkfifo()} |
| 762 | doesn't open the FIFO --- it just creates the rendezvous point. |
| 763 | \end{funcdesc} |
| 764 | |
Martin v. Löwis | dbe3f76 | 2002-10-10 14:27:30 +0000 | [diff] [blame] | 765 | \begin{funcdesc}{mknod}{path\optional{, mode=0600, device}} |
Martin v. Löwis | 06a83e9 | 2002-04-14 10:19:44 +0000 | [diff] [blame] | 766 | Create a filesystem node (file, device special file or named pipe) |
Martin v. Löwis | dbe3f76 | 2002-10-10 14:27:30 +0000 | [diff] [blame] | 767 | named filename. \var{mode} specifies both the permissions to use and |
| 768 | the type of node to be created, being combined (bitwise OR) with one |
| 769 | of S_IFREG, S_IFCHR, S_IFBLK, and S_IFIFO (those constants are |
| 770 | available in \module{stat}). For S_IFCHR and S_IFBLK, \var{device} |
| 771 | defines the newly created device special file (probably using |
| 772 | \function{os.makedev()}), otherwise it is ignored. |
Martin v. Löwis | dbe3f76 | 2002-10-10 14:27:30 +0000 | [diff] [blame] | 773 | \versionadded{2.3} |
| 774 | \end{funcdesc} |
| 775 | |
| 776 | \begin{funcdesc}{major}{device} |
| 777 | Extracts a device major number from a raw device number. |
Martin v. Löwis | dbe3f76 | 2002-10-10 14:27:30 +0000 | [diff] [blame] | 778 | \versionadded{2.3} |
| 779 | \end{funcdesc} |
| 780 | |
| 781 | \begin{funcdesc}{minor}{device} |
| 782 | Extracts a device minor number from a raw device number. |
Martin v. Löwis | dbe3f76 | 2002-10-10 14:27:30 +0000 | [diff] [blame] | 783 | \versionadded{2.3} |
| 784 | \end{funcdesc} |
| 785 | |
| 786 | \begin{funcdesc}{makedev}{major, minor} |
| 787 | Composes a raw device number from the major and minor device numbers. |
Martin v. Löwis | 06a83e9 | 2002-04-14 10:19:44 +0000 | [diff] [blame] | 788 | \versionadded{2.3} |
| 789 | \end{funcdesc} |
| 790 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 791 | \begin{funcdesc}{mkdir}{path\optional{, mode}} |
| 792 | Create a directory named \var{path} with numeric mode \var{mode}. |
| 793 | The default \var{mode} is \code{0777} (octal). On some systems, |
| 794 | \var{mode} is ignored. Where it is used, the current umask value is |
| 795 | first masked out. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 796 | Availability: Macintosh, \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 797 | \end{funcdesc} |
| 798 | |
| 799 | \begin{funcdesc}{makedirs}{path\optional{, mode}} |
Fred Drake | 5c7b248 | 2003-03-20 17:39:38 +0000 | [diff] [blame] | 800 | Recursive directory creation function.\index{directory!creating} |
| 801 | \index{UNC paths!and \function{os.makedirs()}} |
| 802 | Like \function{mkdir()}, |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 803 | but makes all intermediate-level directories needed to contain the |
| 804 | leaf directory. Throws an \exception{error} exception if the leaf |
| 805 | directory already exists or cannot be created. The default \var{mode} |
Fred Drake | bbf7a40 | 2001-09-28 16:14:18 +0000 | [diff] [blame] | 806 | is \code{0777} (octal). This function does not properly handle UNC |
Fred Drake | 5c7b248 | 2003-03-20 17:39:38 +0000 | [diff] [blame] | 807 | paths (only relevant on Windows systems; Universal Naming Convention |
| 808 | paths are those that use the `\code{\e\e host\e path}' syntax). |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 809 | \versionadded{1.5.2} |
| 810 | \end{funcdesc} |
| 811 | |
Fred Drake | 88f6ca2 | 1999-12-15 19:39:04 +0000 | [diff] [blame] | 812 | \begin{funcdesc}{pathconf}{path, name} |
Thomas Wouters | f831663 | 2000-07-16 19:01:10 +0000 | [diff] [blame] | 813 | Return system configuration information relevant to a named file. |
Fred Drake | 88f6ca2 | 1999-12-15 19:39:04 +0000 | [diff] [blame] | 814 | \var{name} specifies the configuration value to retrieve; it may be a |
| 815 | string which is the name of a defined system value; these names are |
Raymond Hettinger | b67449d | 2003-09-08 18:52:18 +0000 | [diff] [blame] | 816 | specified in a number of standards (\POSIX.1, \UNIX{} 95, \UNIX{} 98, and |
Fred Drake | 88f6ca2 | 1999-12-15 19:39:04 +0000 | [diff] [blame] | 817 | others). Some platforms define additional names as well. The names |
| 818 | known to the host operating system are given in the |
| 819 | \code{pathconf_names} dictionary. For configuration variables not |
| 820 | included in that mapping, passing an integer for \var{name} is also |
| 821 | accepted. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 822 | Availability: \UNIX. |
Fred Drake | 88f6ca2 | 1999-12-15 19:39:04 +0000 | [diff] [blame] | 823 | |
| 824 | If \var{name} is a string and is not known, \exception{ValueError} is |
| 825 | raised. If a specific value for \var{name} is not supported by the |
| 826 | host system, even if it is included in \code{pathconf_names}, an |
| 827 | \exception{OSError} is raised with \constant{errno.EINVAL} for the |
| 828 | error number. |
| 829 | \end{funcdesc} |
| 830 | |
| 831 | \begin{datadesc}{pathconf_names} |
| 832 | Dictionary mapping names accepted by \function{pathconf()} and |
| 833 | \function{fpathconf()} to the integer values defined for those names |
| 834 | by the host operating system. This can be used to determine the set |
| 835 | of names known to the system. |
| 836 | Availability: \UNIX. |
| 837 | \end{datadesc} |
| 838 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 839 | \begin{funcdesc}{readlink}{path} |
| 840 | Return a string representing the path to which the symbolic link |
Fred Drake | dc9e7e4 | 2001-05-29 18:13:06 +0000 | [diff] [blame] | 841 | points. The result may be either an absolute or relative pathname; if |
| 842 | it is relative, it may be converted to an absolute pathname using |
| 843 | \code{os.path.join(os.path.dirname(\var{path}), \var{result})}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 844 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 845 | \end{funcdesc} |
| 846 | |
| 847 | \begin{funcdesc}{remove}{path} |
Fred Drake | dc9e7e4 | 2001-05-29 18:13:06 +0000 | [diff] [blame] | 848 | Remove the file \var{path}. If \var{path} is a directory, |
| 849 | \exception{OSError} is raised; see \function{rmdir()} below to remove |
| 850 | a directory. This is identical to the \function{unlink()} function |
| 851 | documented below. On Windows, attempting to remove a file that is in |
| 852 | use causes an exception to be raised; on \UNIX, the directory entry is |
| 853 | removed but the storage allocated to the file is not made available |
| 854 | until the original file is no longer in use. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 855 | Availability: Macintosh, \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 856 | \end{funcdesc} |
| 857 | |
| 858 | \begin{funcdesc}{removedirs}{path} |
| 859 | \index{directory!deleting} |
Fred Drake | 2c22e85 | 2002-07-02 21:03:49 +0000 | [diff] [blame] | 860 | Removes directories recursively. Works like |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 861 | \function{rmdir()} except that, if the leaf directory is |
| 862 | successfully removed, directories corresponding to rightmost path |
| 863 | segments will be pruned way until either the whole path is consumed or |
| 864 | an error is raised (which is ignored, because it generally means that |
| 865 | a parent directory is not empty). Throws an \exception{error} |
| 866 | exception if the leaf directory could not be successfully removed. |
| 867 | \versionadded{1.5.2} |
| 868 | \end{funcdesc} |
| 869 | |
| 870 | \begin{funcdesc}{rename}{src, dst} |
Fred Drake | dc9e7e4 | 2001-05-29 18:13:06 +0000 | [diff] [blame] | 871 | Rename the file or directory \var{src} to \var{dst}. If \var{dst} is |
| 872 | a directory, \exception{OSError} will be raised. On \UNIX, if |
| 873 | \var{dst} exists and is a file, it will be removed silently if the |
| 874 | user has permission. The operation may fail on some \UNIX{} flavors |
Skip Montanaro | b9d973d | 2001-06-04 15:31:17 +0000 | [diff] [blame] | 875 | if \var{src} and \var{dst} are on different filesystems. If |
Fred Drake | dc9e7e4 | 2001-05-29 18:13:06 +0000 | [diff] [blame] | 876 | successful, the renaming will be an atomic operation (this is a |
| 877 | \POSIX{} requirement). On Windows, if \var{dst} already exists, |
| 878 | \exception{OSError} will be raised even if it is a file; there may be |
| 879 | no way to implement an atomic rename when \var{dst} names an existing |
| 880 | file. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 881 | Availability: Macintosh, \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 882 | \end{funcdesc} |
| 883 | |
| 884 | \begin{funcdesc}{renames}{old, new} |
| 885 | Recursive directory or file renaming function. |
| 886 | Works like \function{rename()}, except creation of any intermediate |
| 887 | directories needed to make the new pathname good is attempted first. |
| 888 | After the rename, directories corresponding to rightmost path segments |
| 889 | of the old name will be pruned away using \function{removedirs()}. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 890 | \versionadded{1.5.2} |
Fred Drake | 0ed6634 | 2004-04-16 15:20:01 +0000 | [diff] [blame] | 891 | |
| 892 | \begin{notice} |
| 893 | This function can fail with the new directory structure made if |
| 894 | you lack permissions needed to remove the leaf directory or file. |
| 895 | \end{notice} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 896 | \end{funcdesc} |
| 897 | |
| 898 | \begin{funcdesc}{rmdir}{path} |
| 899 | Remove the directory \var{path}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 900 | Availability: Macintosh, \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 901 | \end{funcdesc} |
| 902 | |
| 903 | \begin{funcdesc}{stat}{path} |
| 904 | Perform a \cfunction{stat()} system call on the given path. The |
Fred Drake | 6995bb6 | 2001-11-29 20:48:44 +0000 | [diff] [blame] | 905 | return value is an object whose attributes correspond to the members of |
| 906 | the \ctype{stat} structure, namely: |
| 907 | \member{st_mode} (protection bits), |
| 908 | \member{st_ino} (inode number), |
| 909 | \member{st_dev} (device), |
Raymond Hettinger | 52136a8 | 2003-05-10 03:35:37 +0000 | [diff] [blame] | 910 | \member{st_nlink} (number of hard links), |
Fred Drake | 6995bb6 | 2001-11-29 20:48:44 +0000 | [diff] [blame] | 911 | \member{st_uid} (user ID of owner), |
| 912 | \member{st_gid} (group ID of owner), |
| 913 | \member{st_size} (size of file, in bytes), |
| 914 | \member{st_atime} (time of most recent access), |
| 915 | \member{st_mtime} (time of most recent content modification), |
| 916 | \member{st_ctime} |
Fred Drake | 1cd6e4d | 2004-05-12 03:51:40 +0000 | [diff] [blame] | 917 | (platform dependent; time of most recent metadata change on \UNIX, or |
| 918 | the time of creation on Windows). |
Fred Drake | 6995bb6 | 2001-11-29 20:48:44 +0000 | [diff] [blame] | 919 | |
Martin v. Löwis | f607bda | 2002-10-16 18:27:39 +0000 | [diff] [blame] | 920 | \versionchanged [If \function{stat_float_times} returns true, the time |
| 921 | values are floats, measuring seconds. Fractions of a second may be |
| 922 | reported if the system supports that. On Mac OS, the times are always |
| 923 | floats. See \function{stat_float_times} for further discussion. ]{2.3} |
Martin v. Löwis | a32c994 | 2002-09-09 16:17:47 +0000 | [diff] [blame] | 924 | |
Fred Drake | 6995bb6 | 2001-11-29 20:48:44 +0000 | [diff] [blame] | 925 | On some Unix systems (such as Linux), the following attributes may |
| 926 | also be available: |
| 927 | \member{st_blocks} (number of blocks allocated for file), |
| 928 | \member{st_blksize} (filesystem blocksize), |
| 929 | \member{st_rdev} (type of device if an inode device). |
| 930 | |
| 931 | On Mac OS systems, the following attributes may also be available: |
| 932 | \member{st_rsize}, |
| 933 | \member{st_creator}, |
| 934 | \member{st_type}. |
| 935 | |
| 936 | On RISCOS systems, the following attributes are also available: |
| 937 | \member{st_ftype} (file type), |
| 938 | \member{st_attrs} (attributes), |
| 939 | \member{st_obtype} (object type). |
| 940 | |
| 941 | For backward compatibility, the return value of \function{stat()} is |
| 942 | also accessible as a tuple of at least 10 integers giving the most |
| 943 | important (and portable) members of the \ctype{stat} structure, in the |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 944 | order |
Fred Drake | 6995bb6 | 2001-11-29 20:48:44 +0000 | [diff] [blame] | 945 | \member{st_mode}, |
| 946 | \member{st_ino}, |
| 947 | \member{st_dev}, |
| 948 | \member{st_nlink}, |
| 949 | \member{st_uid}, |
| 950 | \member{st_gid}, |
| 951 | \member{st_size}, |
| 952 | \member{st_atime}, |
| 953 | \member{st_mtime}, |
| 954 | \member{st_ctime}. |
Tim Peters | 11b2306 | 2003-04-23 02:39:17 +0000 | [diff] [blame] | 955 | More items may be added at the end by some implementations. |
Fred Drake | 6995bb6 | 2001-11-29 20:48:44 +0000 | [diff] [blame] | 956 | The standard module \refmodule{stat}\refstmodindex{stat} defines |
| 957 | functions and constants that are useful for extracting information |
| 958 | from a \ctype{stat} structure. |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 959 | (On Windows, some items are filled with dummy values.) |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 960 | Availability: Macintosh, \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 961 | |
Fred Drake | 6995bb6 | 2001-11-29 20:48:44 +0000 | [diff] [blame] | 962 | \versionchanged |
| 963 | [Added access to values as attributes of the returned object]{2.2} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 964 | \end{funcdesc} |
| 965 | |
Martin v. Löwis | f607bda | 2002-10-16 18:27:39 +0000 | [diff] [blame] | 966 | \begin{funcdesc}{stat_float_times}{\optional{newvalue}} |
| 967 | Determine whether \class{stat_result} represents time stamps as float |
| 968 | objects. If newval is True, future calls to stat() return floats, if |
| 969 | it is False, future calls return ints. If newval is omitted, return |
| 970 | the current setting. |
| 971 | |
| 972 | For compatibility with older Python versions, accessing |
| 973 | \class{stat_result} as a tuple always returns integers. For |
| 974 | compatibility with Python 2.2, accessing the time stamps by field name |
| 975 | also returns integers. Applications that want to determine the |
| 976 | fractions of a second in a time stamp can use this function to have |
| 977 | time stamps represented as floats. Whether they will actually observe |
| 978 | non-zero fractions depends on the system. |
| 979 | |
Neal Norwitz | 6d23b17 | 2003-01-05 22:20:51 +0000 | [diff] [blame] | 980 | Future Python releases will change the default of this setting; |
Martin v. Löwis | f607bda | 2002-10-16 18:27:39 +0000 | [diff] [blame] | 981 | applications that cannot deal with floating point time stamps can then |
| 982 | use this function to turn the feature off. |
| 983 | |
| 984 | It is recommended that this setting is only changed at program startup |
| 985 | time in the \var{__main__} module; libraries should never change this |
| 986 | setting. If an application uses a library that works incorrectly if |
| 987 | floating point time stamps are processed, this application should turn |
| 988 | the feature off until the library has been corrected. |
| 989 | |
| 990 | \end{funcdesc} |
| 991 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 992 | \begin{funcdesc}{statvfs}{path} |
| 993 | Perform a \cfunction{statvfs()} system call on the given path. The |
Fred Drake | 6995bb6 | 2001-11-29 20:48:44 +0000 | [diff] [blame] | 994 | return value is an object whose attributes describe the filesystem on |
| 995 | the given path, and correspond to the members of the |
| 996 | \ctype{statvfs} structure, namely: |
| 997 | \member{f_frsize}, |
| 998 | \member{f_blocks}, |
| 999 | \member{f_bfree}, |
| 1000 | \member{f_bavail}, |
| 1001 | \member{f_files}, |
| 1002 | \member{f_ffree}, |
| 1003 | \member{f_favail}, |
| 1004 | \member{f_flag}, |
| 1005 | \member{f_namemax}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1006 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1007 | |
Fred Drake | 6995bb6 | 2001-11-29 20:48:44 +0000 | [diff] [blame] | 1008 | For backward compatibility, the return value is also accessible as a |
| 1009 | tuple whose values correspond to the attributes, in the order given above. |
| 1010 | The standard module \refmodule{statvfs}\refstmodindex{statvfs} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1011 | defines constants that are useful for extracting information |
Fred Drake | 6995bb6 | 2001-11-29 20:48:44 +0000 | [diff] [blame] | 1012 | from a \ctype{statvfs} structure when accessing it as a sequence; this |
| 1013 | remains useful when writing code that needs to work with versions of |
| 1014 | Python that don't support accessing the fields as attributes. |
| 1015 | |
| 1016 | \versionchanged |
| 1017 | [Added access to values as attributes of the returned object]{2.2} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1018 | \end{funcdesc} |
| 1019 | |
| 1020 | \begin{funcdesc}{symlink}{src, dst} |
| 1021 | Create a symbolic link pointing to \var{src} named \var{dst}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1022 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1023 | \end{funcdesc} |
| 1024 | |
Fred Drake | 18f7a45 | 1999-12-09 22:11:43 +0000 | [diff] [blame] | 1025 | \begin{funcdesc}{tempnam}{\optional{dir\optional{, prefix}}} |
| 1026 | Return a unique path name that is reasonable for creating a temporary |
| 1027 | file. This will be an absolute path that names a potential directory |
| 1028 | entry in the directory \var{dir} or a common location for temporary |
| 1029 | files if \var{dir} is omitted or \code{None}. If given and not |
| 1030 | \code{None}, \var{prefix} is used to provide a short prefix to the |
| 1031 | filename. Applications are responsible for properly creating and |
| 1032 | managing files created using paths returned by \function{tempnam()}; |
| 1033 | no automatic cleanup is provided. |
Fred Drake | 4b9ed2f | 2002-11-12 22:07:11 +0000 | [diff] [blame] | 1034 | On \UNIX, the environment variable \envvar{TMPDIR} overrides |
| 1035 | \var{dir}, while on Windows the \envvar{TMP} is used. The specific |
| 1036 | behavior of this function depends on the C library implementation; |
| 1037 | some aspects are underspecified in system documentation. |
Fred Drake | 938a8d7 | 2001-10-09 18:07:04 +0000 | [diff] [blame] | 1038 | \warning{Use of \function{tempnam()} is vulnerable to symlink attacks; |
| 1039 | consider using \function{tmpfile()} instead.} |
Fred Drake | efaef13 | 2001-07-17 20:39:18 +0000 | [diff] [blame] | 1040 | Availability: \UNIX, Windows. |
Fred Drake | 18f7a45 | 1999-12-09 22:11:43 +0000 | [diff] [blame] | 1041 | \end{funcdesc} |
| 1042 | |
| 1043 | \begin{funcdesc}{tmpnam}{} |
| 1044 | Return a unique path name that is reasonable for creating a temporary |
| 1045 | file. This will be an absolute path that names a potential directory |
| 1046 | entry in a common location for temporary files. Applications are |
| 1047 | responsible for properly creating and managing files created using |
| 1048 | paths returned by \function{tmpnam()}; no automatic cleanup is |
| 1049 | provided. |
Fred Drake | 938a8d7 | 2001-10-09 18:07:04 +0000 | [diff] [blame] | 1050 | \warning{Use of \function{tmpnam()} is vulnerable to symlink attacks; |
| 1051 | consider using \function{tmpfile()} instead.} |
Tim Peters | 5501b5e | 2003-04-28 03:13:03 +0000 | [diff] [blame] | 1052 | Availability: \UNIX, Windows. This function probably shouldn't be used |
| 1053 | on Windows, though: Microsoft's implementation of \function{tmpnam()} |
| 1054 | always creates a name in the root directory of the current drive, and |
| 1055 | that's generally a poor location for a temp file (depending on |
| 1056 | privileges, you may not even be able to open a file using this name). |
Fred Drake | 18f7a45 | 1999-12-09 22:11:43 +0000 | [diff] [blame] | 1057 | \end{funcdesc} |
| 1058 | |
| 1059 | \begin{datadesc}{TMP_MAX} |
| 1060 | The maximum number of unique names that \function{tmpnam()} will |
| 1061 | generate before reusing names. |
| 1062 | \end{datadesc} |
| 1063 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1064 | \begin{funcdesc}{unlink}{path} |
| 1065 | Remove the file \var{path}. This is the same function as |
| 1066 | \function{remove()}; the \function{unlink()} name is its traditional |
| 1067 | \UNIX{} name. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1068 | Availability: Macintosh, \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1069 | \end{funcdesc} |
| 1070 | |
Barry Warsaw | 93a8eac | 2000-05-01 16:18:22 +0000 | [diff] [blame] | 1071 | \begin{funcdesc}{utime}{path, times} |
| 1072 | Set the access and modified times of the file specified by \var{path}. |
| 1073 | If \var{times} is \code{None}, then the file's access and modified |
| 1074 | times are set to the current time. Otherwise, \var{times} must be a |
Fred Drake | e06d025 | 2000-05-02 17:29:35 +0000 | [diff] [blame] | 1075 | 2-tuple of numbers, of the form \code{(\var{atime}, \var{mtime})} |
| 1076 | which is used to set the access and modified times, respectively. |
Fred Drake | 4a15263 | 2000-10-19 05:33:46 +0000 | [diff] [blame] | 1077 | \versionchanged[Added support for \code{None} for \var{times}]{2.0} |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1078 | Availability: Macintosh, \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1079 | \end{funcdesc} |
| 1080 | |
Guido van Rossum | bf1bef8 | 2003-05-13 18:01:19 +0000 | [diff] [blame] | 1081 | \begin{funcdesc}{walk}{top\optional{, topdown\code{=True} |
| 1082 | \optional{, onerror\code{=None}}}} |
Tim Peters | c4e0940 | 2003-04-25 07:11:48 +0000 | [diff] [blame] | 1083 | \index{directory!walking} |
| 1084 | \index{directory!traversal} |
Tim Peters | bf89b3a | 2003-04-28 02:09:43 +0000 | [diff] [blame] | 1085 | \function{walk()} generates the file names in a directory tree, by |
| 1086 | walking the tree either top down or bottom up. |
Tim Peters | c4e0940 | 2003-04-25 07:11:48 +0000 | [diff] [blame] | 1087 | For each directory in the tree rooted at directory \var{top} (including |
| 1088 | \var{top} itself), it yields a 3-tuple |
| 1089 | \code{(\var{dirpath}, \var{dirnames}, \var{filenames})}. |
| 1090 | |
| 1091 | \var{dirpath} is a string, the path to the directory. \var{dirnames} is |
| 1092 | a list of the names of the subdirectories in \var{dirpath} |
| 1093 | (excluding \code{'.'} and \code{'..'}). \var{filenames} is a list of |
| 1094 | the names of the non-directory files in \var{dirpath}. Note that the |
| 1095 | names in the lists contain no path components. To get a full |
Fred Drake | 2194a4e | 2003-04-25 14:50:06 +0000 | [diff] [blame] | 1096 | path (which begins with \var{top}) to a file or directory in |
Tim Peters | c4e0940 | 2003-04-25 07:11:48 +0000 | [diff] [blame] | 1097 | \var{dirpath}, do \code{os.path.join(\var{dirpath}, \var{name})}. |
| 1098 | |
| 1099 | If optional argument \var{topdown} is true or not specified, the triple |
| 1100 | for a directory is generated before the triples for any of its |
| 1101 | subdirectories (directories are generated top down). If \var{topdown} is |
| 1102 | false, the triple for a directory is generated after the triples for all |
| 1103 | of its subdirectories (directories are generated bottom up). |
| 1104 | |
| 1105 | When \var{topdown} is true, the caller can modify the \var{dirnames} list |
Raymond Hettinger | 9756f38 | 2003-09-10 00:11:28 +0000 | [diff] [blame] | 1106 | in-place (perhaps using \keyword{del} or slice assignment), and |
Tim Peters | c4e0940 | 2003-04-25 07:11:48 +0000 | [diff] [blame] | 1107 | \function{walk()} will only recurse into the subdirectories whose names |
| 1108 | remain in \var{dirnames}; this can be used to prune the search, |
| 1109 | impose a specific order of visiting, or even to inform \function{walk()} |
| 1110 | about directories the caller creates or renames before it resumes |
| 1111 | \function{walk()} again. Modifying \var{dirnames} when \var{topdown} is |
| 1112 | false is ineffective, because in bottom-up mode the directories in |
| 1113 | \var{dirnames} are generated before \var{dirnames} itself is generated. |
| 1114 | |
Guido van Rossum | bf1bef8 | 2003-05-13 18:01:19 +0000 | [diff] [blame] | 1115 | By default errors from the \code{os.listdir()} call are ignored. If |
| 1116 | optional argument \var{onerror} is specified, it should be a function; |
| 1117 | it will be called with one argument, an os.error instance. It can |
| 1118 | report the error to continue with the walk, or raise the exception |
| 1119 | to abort the walk. Note that the filename is available as the |
| 1120 | \code{filename} attribute of the exception object. |
| 1121 | |
Tim Peters | c4e0940 | 2003-04-25 07:11:48 +0000 | [diff] [blame] | 1122 | \begin{notice} |
| 1123 | If you pass a relative pathname, don't change the current working |
Fred Drake | 2194a4e | 2003-04-25 14:50:06 +0000 | [diff] [blame] | 1124 | directory between resumptions of \function{walk()}. \function{walk()} |
Tim Peters | c4e0940 | 2003-04-25 07:11:48 +0000 | [diff] [blame] | 1125 | never changes the current directory, and assumes that its caller |
| 1126 | doesn't either. |
| 1127 | \end{notice} |
| 1128 | |
| 1129 | \begin{notice} |
| 1130 | On systems that support symbolic links, links to subdirectories appear |
| 1131 | in \var{dirnames} lists, but \function{walk()} will not visit them |
| 1132 | (infinite loops are hard to avoid when following symbolic links). |
| 1133 | To visit linked directories, you can identify them with |
Fred Drake | 2194a4e | 2003-04-25 14:50:06 +0000 | [diff] [blame] | 1134 | \code{os.path.islink(\var{path})}, and invoke \code{walk(\var{path})} |
Tim Peters | c4e0940 | 2003-04-25 07:11:48 +0000 | [diff] [blame] | 1135 | on each directly. |
| 1136 | \end{notice} |
| 1137 | |
| 1138 | This example displays the number of bytes taken by non-directory files |
| 1139 | in each directory under the starting directory, except that it doesn't |
| 1140 | look under any CVS subdirectory: |
| 1141 | |
| 1142 | \begin{verbatim} |
| 1143 | import os |
| 1144 | from os.path import join, getsize |
| 1145 | for root, dirs, files in os.walk('python/Lib/email'): |
| 1146 | print root, "consumes", |
| 1147 | print sum([getsize(join(root, name)) for name in files]), |
| 1148 | print "bytes in", len(files), "non-directory files" |
| 1149 | if 'CVS' in dirs: |
| 1150 | dirs.remove('CVS') # don't visit CVS directories |
| 1151 | \end{verbatim} |
Tim Peters | bf89b3a | 2003-04-28 02:09:43 +0000 | [diff] [blame] | 1152 | |
| 1153 | In the next example, walking the tree bottom up is essential: |
| 1154 | \function{rmdir()} doesn't allow deleting a directory before the |
| 1155 | directory is empty: |
| 1156 | |
| 1157 | \begin{verbatim} |
| 1158 | import os |
| 1159 | from os.path import join |
| 1160 | # Delete everything reachable from the directory named in 'top'. |
Tim Peters | a390c6e | 2003-04-28 19:15:10 +0000 | [diff] [blame] | 1161 | # CAUTION: This is dangerous! For example, if top == '/', it |
| 1162 | # could delete all your disk files. |
Tim Peters | bf89b3a | 2003-04-28 02:09:43 +0000 | [diff] [blame] | 1163 | for root, dirs, files in os.walk(top, topdown=False): |
| 1164 | for name in files: |
| 1165 | os.remove(join(root, name)) |
| 1166 | for name in dirs: |
| 1167 | os.rmdir(join(root, name)) |
| 1168 | \end{verbatim} |
| 1169 | |
Tim Peters | c4e0940 | 2003-04-25 07:11:48 +0000 | [diff] [blame] | 1170 | \versionadded{2.3} |
| 1171 | \end{funcdesc} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1172 | |
| 1173 | \subsection{Process Management \label{os-process}} |
| 1174 | |
Fred Drake | 18f7a45 | 1999-12-09 22:11:43 +0000 | [diff] [blame] | 1175 | These functions may be used to create and manage processes. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1176 | |
Fred Drake | 7be3115 | 2000-09-23 05:22:07 +0000 | [diff] [blame] | 1177 | The various \function{exec*()} functions take a list of arguments for |
| 1178 | the new program loaded into the process. In each case, the first of |
| 1179 | these arguments is passed to the new program as its own name rather |
| 1180 | than as an argument a user may have typed on a command line. For the |
| 1181 | C programmer, this is the \code{argv[0]} passed to a program's |
| 1182 | \cfunction{main()}. For example, \samp{os.execv('/bin/echo', ['foo', |
| 1183 | 'bar'])} will only print \samp{bar} on standard output; \samp{foo} |
| 1184 | will seem to be ignored. |
| 1185 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1186 | |
Fred Drake | 18f7a45 | 1999-12-09 22:11:43 +0000 | [diff] [blame] | 1187 | \begin{funcdesc}{abort}{} |
| 1188 | Generate a \constant{SIGABRT} signal to the current process. On |
Tim Peters | ab034fa | 2002-02-01 11:27:43 +0000 | [diff] [blame] | 1189 | \UNIX, the default behavior is to produce a core dump; on Windows, the |
Fred Drake | 18f7a45 | 1999-12-09 22:11:43 +0000 | [diff] [blame] | 1190 | process immediately returns an exit code of \code{3}. Be aware that |
| 1191 | programs which use \function{signal.signal()} to register a handler |
| 1192 | for \constant{SIGABRT} will behave differently. |
| 1193 | Availability: \UNIX, Windows. |
| 1194 | \end{funcdesc} |
| 1195 | |
Fred Drake | db7287c | 2001-10-18 18:58:30 +0000 | [diff] [blame] | 1196 | \begin{funcdesc}{execl}{path, arg0, arg1, \moreargs} |
| 1197 | \funcline{execle}{path, arg0, arg1, \moreargs, env} |
| 1198 | \funcline{execlp}{file, arg0, arg1, \moreargs} |
| 1199 | \funcline{execlpe}{file, arg0, arg1, \moreargs, env} |
| 1200 | \funcline{execv}{path, args} |
| 1201 | \funcline{execve}{path, args, env} |
| 1202 | \funcline{execvp}{file, args} |
| 1203 | \funcline{execvpe}{file, args, env} |
| 1204 | These functions all execute a new program, replacing the current |
| 1205 | process; they do not return. On \UNIX, the new executable is loaded |
| 1206 | into the current process, and will have the same process ID as the |
| 1207 | caller. Errors will be reported as \exception{OSError} exceptions. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1208 | |
Fred Drake | db7287c | 2001-10-18 18:58:30 +0000 | [diff] [blame] | 1209 | The \character{l} and \character{v} variants of the |
| 1210 | \function{exec*()} functions differ in how command-line arguments are |
| 1211 | passed. The \character{l} variants are perhaps the easiest to work |
| 1212 | with if the number of parameters is fixed when the code is written; |
| 1213 | the individual parameters simply become additional parameters to the |
| 1214 | \function{execl*()} functions. The \character{v} variants are good |
| 1215 | when the number of parameters is variable, with the arguments being |
| 1216 | passed in a list or tuple as the \var{args} parameter. In either |
| 1217 | case, the arguments to the child process must start with the name of |
| 1218 | the command being run. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1219 | |
Fred Drake | db7287c | 2001-10-18 18:58:30 +0000 | [diff] [blame] | 1220 | The variants which include a \character{p} near the end |
| 1221 | (\function{execlp()}, \function{execlpe()}, \function{execvp()}, |
| 1222 | and \function{execvpe()}) will use the \envvar{PATH} environment |
| 1223 | variable to locate the program \var{file}. When the environment is |
| 1224 | being replaced (using one of the \function{exec*e()} variants, |
| 1225 | discussed in the next paragraph), the |
| 1226 | new environment is used as the source of the \envvar{PATH} variable. |
| 1227 | The other variants, \function{execl()}, \function{execle()}, |
| 1228 | \function{execv()}, and \function{execve()}, will not use the |
| 1229 | \envvar{PATH} variable to locate the executable; \var{path} must |
| 1230 | contain an appropriate absolute or relative path. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1231 | |
Fred Drake | db7287c | 2001-10-18 18:58:30 +0000 | [diff] [blame] | 1232 | For \function{execle()}, \function{execlpe()}, \function{execve()}, |
| 1233 | and \function{execvpe()} (note that these all end in \character{e}), |
| 1234 | the \var{env} parameter must be a mapping which is used to define the |
| 1235 | environment variables for the new process; the \function{execl()}, |
| 1236 | \function{execlp()}, \function{execv()}, and \function{execvp()} |
| 1237 | all cause the new process to inherit the environment of the current |
| 1238 | process. |
| 1239 | Availability: \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1240 | \end{funcdesc} |
| 1241 | |
| 1242 | \begin{funcdesc}{_exit}{n} |
| 1243 | Exit to the system with status \var{n}, without calling cleanup |
| 1244 | handlers, flushing stdio buffers, etc. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1245 | Availability: \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1246 | |
Fred Drake | 0ed6634 | 2004-04-16 15:20:01 +0000 | [diff] [blame] | 1247 | \begin{notice} |
| 1248 | The standard way to exit is \code{sys.exit(\var{n})}. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1249 | \function{_exit()} should normally only be used in the child process |
| 1250 | after a \function{fork()}. |
Fred Drake | 0ed6634 | 2004-04-16 15:20:01 +0000 | [diff] [blame] | 1251 | \end{notice} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1252 | \end{funcdesc} |
| 1253 | |
Barry Warsaw | b6604b3 | 2003-01-07 22:43:25 +0000 | [diff] [blame] | 1254 | The following exit codes are a defined, and can be used with |
| 1255 | \function{_exit()}, although they are not required. These are |
| 1256 | typically used for system programs written in Python, such as a |
| 1257 | mail server's external command delivery program. |
| 1258 | |
| 1259 | \begin{datadesc}{EX_OK} |
| 1260 | Exit code that means no error occurred. |
| 1261 | Availability: \UNIX. |
| 1262 | \versionadded{2.3} |
| 1263 | \end{datadesc} |
| 1264 | |
| 1265 | \begin{datadesc}{EX_USAGE} |
| 1266 | Exit code that means the command was used incorrectly, such as when |
| 1267 | the wrong number of arguments are given. |
| 1268 | Availability: \UNIX. |
| 1269 | \versionadded{2.3} |
| 1270 | \end{datadesc} |
| 1271 | |
| 1272 | \begin{datadesc}{EX_DATAERR} |
| 1273 | Exit code that means the input data was incorrect. |
| 1274 | Availability: \UNIX. |
| 1275 | \versionadded{2.3} |
| 1276 | \end{datadesc} |
| 1277 | |
| 1278 | \begin{datadesc}{EX_NOINPUT} |
| 1279 | Exit code that means an input file did not exist or was not readable. |
| 1280 | Availability: \UNIX. |
| 1281 | \versionadded{2.3} |
| 1282 | \end{datadesc} |
| 1283 | |
| 1284 | \begin{datadesc}{EX_NOUSER} |
| 1285 | Exit code that means a specified user did not exist. |
| 1286 | Availability: \UNIX. |
| 1287 | \versionadded{2.3} |
| 1288 | \end{datadesc} |
| 1289 | |
| 1290 | \begin{datadesc}{EX_NOHOST} |
| 1291 | Exit code that means a specified host did not exist. |
| 1292 | Availability: \UNIX. |
| 1293 | \versionadded{2.3} |
| 1294 | \end{datadesc} |
| 1295 | |
| 1296 | \begin{datadesc}{EX_UNAVAILABLE} |
| 1297 | Exit code that means that a required service is unavailable. |
| 1298 | Availability: \UNIX. |
| 1299 | \versionadded{2.3} |
| 1300 | \end{datadesc} |
| 1301 | |
| 1302 | \begin{datadesc}{EX_SOFTWARE} |
| 1303 | Exit code that means an internal software error was detected. |
| 1304 | Availability: \UNIX. |
| 1305 | \versionadded{2.3} |
| 1306 | \end{datadesc} |
| 1307 | |
| 1308 | \begin{datadesc}{EX_OSERR} |
| 1309 | Exit code that means an operating system error was detected, such as |
| 1310 | the inability to fork or create a pipe. |
| 1311 | Availability: \UNIX. |
| 1312 | \versionadded{2.3} |
| 1313 | \end{datadesc} |
| 1314 | |
| 1315 | \begin{datadesc}{EX_OSFILE} |
| 1316 | Exit code that means some system file did not exist, could not be |
| 1317 | opened, or had some other kind of error. |
| 1318 | Availability: \UNIX. |
| 1319 | \versionadded{2.3} |
| 1320 | \end{datadesc} |
| 1321 | |
| 1322 | \begin{datadesc}{EX_CANTCREAT} |
| 1323 | Exit code that means a user specified output file could not be created. |
| 1324 | Availability: \UNIX. |
| 1325 | \versionadded{2.3} |
| 1326 | \end{datadesc} |
| 1327 | |
| 1328 | \begin{datadesc}{EX_IOERR} |
| 1329 | Exit code that means that an error occurred while doing I/O on some file. |
| 1330 | Availability: \UNIX. |
| 1331 | \versionadded{2.3} |
| 1332 | \end{datadesc} |
| 1333 | |
| 1334 | \begin{datadesc}{EX_TEMPFAIL} |
| 1335 | Exit code that means a temporary failure occurred. This indicates |
| 1336 | something that may not really be an error, such as a network |
| 1337 | connection that couldn't be made during a retryable operation. |
| 1338 | Availability: \UNIX. |
| 1339 | \versionadded{2.3} |
| 1340 | \end{datadesc} |
| 1341 | |
| 1342 | \begin{datadesc}{EX_PROTOCOL} |
| 1343 | Exit code that means that a protocol exchange was illegal, invalid, or |
| 1344 | not understood. |
| 1345 | Availability: \UNIX. |
| 1346 | \versionadded{2.3} |
| 1347 | \end{datadesc} |
| 1348 | |
| 1349 | \begin{datadesc}{EX_NOPERM} |
| 1350 | Exit code that means that there were insufficient permissions to |
| 1351 | perform the operation (but not intended for file system problems). |
| 1352 | Availability: \UNIX. |
| 1353 | \versionadded{2.3} |
| 1354 | \end{datadesc} |
| 1355 | |
| 1356 | \begin{datadesc}{EX_CONFIG} |
| 1357 | Exit code that means that some kind of configuration error occurred. |
| 1358 | Availability: \UNIX. |
| 1359 | \versionadded{2.3} |
| 1360 | \end{datadesc} |
| 1361 | |
| 1362 | \begin{datadesc}{EX_NOTFOUND} |
| 1363 | Exit code that means something like ``an entry was not found''. |
| 1364 | Availability: \UNIX. |
| 1365 | \versionadded{2.3} |
| 1366 | \end{datadesc} |
| 1367 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1368 | \begin{funcdesc}{fork}{} |
| 1369 | Fork a child process. Return \code{0} in the child, the child's |
| 1370 | process id in the parent. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1371 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1372 | \end{funcdesc} |
| 1373 | |
Fred Drake | c82634c | 2000-06-28 17:27:48 +0000 | [diff] [blame] | 1374 | \begin{funcdesc}{forkpty}{} |
| 1375 | Fork a child process, using a new pseudo-terminal as the child's |
| 1376 | controlling terminal. Return a pair of \code{(\var{pid}, \var{fd})}, |
| 1377 | where \var{pid} is \code{0} in the child, the new child's process id |
Fred Drake | 6995bb6 | 2001-11-29 20:48:44 +0000 | [diff] [blame] | 1378 | in the parent, and \var{fd} is the file descriptor of the master end |
Fred Drake | c82634c | 2000-06-28 17:27:48 +0000 | [diff] [blame] | 1379 | of the pseudo-terminal. For a more portable approach, use the |
| 1380 | \refmodule{pty} module. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1381 | Availability: Some flavors of \UNIX. |
Fred Drake | c82634c | 2000-06-28 17:27:48 +0000 | [diff] [blame] | 1382 | \end{funcdesc} |
| 1383 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1384 | \begin{funcdesc}{kill}{pid, sig} |
| 1385 | \index{process!killing} |
| 1386 | \index{process!signalling} |
Fred Drake | 5c79831 | 2001-12-21 03:58:47 +0000 | [diff] [blame] | 1387 | Kill the process \var{pid} with signal \var{sig}. Constants for the |
| 1388 | specific signals available on the host platform are defined in the |
| 1389 | \refmodule{signal} module. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1390 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1391 | \end{funcdesc} |
| 1392 | |
Martin v. Löwis | 33e9443 | 2002-12-27 10:21:19 +0000 | [diff] [blame] | 1393 | \begin{funcdesc}{killpg}{pgid, sig} |
| 1394 | \index{process!killing} |
| 1395 | \index{process!signalling} |
| 1396 | Kill the process group \var{pgid} with the signal \var{sig}. |
| 1397 | Availability: \UNIX. |
| 1398 | \versionadded{2.3} |
| 1399 | \end{funcdesc} |
| 1400 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1401 | \begin{funcdesc}{nice}{increment} |
| 1402 | Add \var{increment} to the process's ``niceness''. Return the new |
| 1403 | niceness. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1404 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1405 | \end{funcdesc} |
| 1406 | |
| 1407 | \begin{funcdesc}{plock}{op} |
| 1408 | Lock program segments into memory. The value of \var{op} |
| 1409 | (defined in \code{<sys/lock.h>}) determines which segments are locked. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1410 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1411 | \end{funcdesc} |
| 1412 | |
Fred Drake | 046f4d8 | 2001-06-11 15:21:48 +0000 | [diff] [blame] | 1413 | \begin{funcdescni}{popen}{\unspecified} |
| 1414 | \funclineni{popen2}{\unspecified} |
| 1415 | \funclineni{popen3}{\unspecified} |
| 1416 | \funclineni{popen4}{\unspecified} |
| 1417 | Run child processes, returning opened pipes for communications. These |
| 1418 | functions are described in section \ref{os-newstreams}. |
| 1419 | \end{funcdescni} |
| 1420 | |
Fred Drake | 739282d | 2001-08-16 21:21:28 +0000 | [diff] [blame] | 1421 | \begin{funcdesc}{spawnl}{mode, path, \moreargs} |
| 1422 | \funcline{spawnle}{mode, path, \moreargs, env} |
Fred Drake | db7287c | 2001-10-18 18:58:30 +0000 | [diff] [blame] | 1423 | \funcline{spawnlp}{mode, file, \moreargs} |
| 1424 | \funcline{spawnlpe}{mode, file, \moreargs, env} |
Fred Drake | 739282d | 2001-08-16 21:21:28 +0000 | [diff] [blame] | 1425 | \funcline{spawnv}{mode, path, args} |
| 1426 | \funcline{spawnve}{mode, path, args, env} |
Fred Drake | db7287c | 2001-10-18 18:58:30 +0000 | [diff] [blame] | 1427 | \funcline{spawnvp}{mode, file, args} |
| 1428 | \funcline{spawnvpe}{mode, file, args, env} |
Fred Drake | 739282d | 2001-08-16 21:21:28 +0000 | [diff] [blame] | 1429 | Execute the program \var{path} in a new process. If \var{mode} is |
| 1430 | \constant{P_NOWAIT}, this function returns the process ID of the new |
Tim Peters | b404145 | 2001-12-06 23:37:17 +0000 | [diff] [blame] | 1431 | process; if \var{mode} is \constant{P_WAIT}, returns the process's |
Fred Drake | 739282d | 2001-08-16 21:21:28 +0000 | [diff] [blame] | 1432 | exit code if it exits normally, or \code{-\var{signal}}, where |
Fred Drake | 4dfb7a8 | 2002-04-01 23:30:47 +0000 | [diff] [blame] | 1433 | \var{signal} is the signal that killed the process. On Windows, the |
| 1434 | process ID will actually be the process handle, so can be used with |
| 1435 | the \function{waitpid()} function. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1436 | |
Fred Drake | 739282d | 2001-08-16 21:21:28 +0000 | [diff] [blame] | 1437 | The \character{l} and \character{v} variants of the |
| 1438 | \function{spawn*()} functions differ in how command-line arguments are |
| 1439 | passed. The \character{l} variants are perhaps the easiest to work |
| 1440 | with if the number of parameters is fixed when the code is written; |
| 1441 | the individual parameters simply become additional parameters to the |
| 1442 | \function{spawnl*()} functions. The \character{v} variants are good |
| 1443 | when the number of parameters is variable, with the arguments being |
| 1444 | passed in a list or tuple as the \var{args} parameter. In either |
| 1445 | case, the arguments to the child process must start with the name of |
| 1446 | the command being run. |
| 1447 | |
Fred Drake | db7287c | 2001-10-18 18:58:30 +0000 | [diff] [blame] | 1448 | The variants which include a second \character{p} near the end |
| 1449 | (\function{spawnlp()}, \function{spawnlpe()}, \function{spawnvp()}, |
| 1450 | and \function{spawnvpe()}) will use the \envvar{PATH} environment |
| 1451 | variable to locate the program \var{file}. When the environment is |
| 1452 | being replaced (using one of the \function{spawn*e()} variants, |
| 1453 | discussed in the next paragraph), the new environment is used as the |
| 1454 | source of the \envvar{PATH} variable. The other variants, |
| 1455 | \function{spawnl()}, \function{spawnle()}, \function{spawnv()}, and |
| 1456 | \function{spawnve()}, will not use the \envvar{PATH} variable to |
| 1457 | locate the executable; \var{path} must contain an appropriate absolute |
| 1458 | or relative path. |
| 1459 | |
| 1460 | For \function{spawnle()}, \function{spawnlpe()}, \function{spawnve()}, |
| 1461 | and \function{spawnvpe()} (note that these all end in \character{e}), |
| 1462 | the \var{env} parameter must be a mapping which is used to define the |
| 1463 | environment variables for the new process; the \function{spawnl()}, |
| 1464 | \function{spawnlp()}, \function{spawnv()}, and \function{spawnvp()} |
| 1465 | all cause the new process to inherit the environment of the current |
| 1466 | process. |
| 1467 | |
Fred Drake | 739282d | 2001-08-16 21:21:28 +0000 | [diff] [blame] | 1468 | As an example, the following calls to \function{spawnlp()} and |
| 1469 | \function{spawnvpe()} are equivalent: |
| 1470 | |
| 1471 | \begin{verbatim} |
| 1472 | import os |
| 1473 | os.spawnlp(os.P_WAIT, 'cp', 'cp', 'index.html', '/dev/null') |
| 1474 | |
| 1475 | L = ['cp', 'index.html', '/dev/null'] |
| 1476 | os.spawnvpe(os.P_WAIT, 'cp', L, os.environ) |
| 1477 | \end{verbatim} |
| 1478 | |
Fred Drake | 8c8e871 | 2001-12-20 17:24:11 +0000 | [diff] [blame] | 1479 | Availability: \UNIX, Windows. \function{spawnlp()}, |
| 1480 | \function{spawnlpe()}, \function{spawnvp()} and \function{spawnvpe()} |
| 1481 | are not available on Windows. |
Fred Drake | 0b9bc20 | 2001-06-11 18:25:34 +0000 | [diff] [blame] | 1482 | \versionadded{1.6} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1483 | \end{funcdesc} |
| 1484 | |
Fred Drake | 938a8d7 | 2001-10-09 18:07:04 +0000 | [diff] [blame] | 1485 | \begin{datadesc}{P_NOWAIT} |
Fred Drake | 9329e5e | 1999-02-16 19:40:19 +0000 | [diff] [blame] | 1486 | \dataline{P_NOWAITO} |
Fred Drake | 938a8d7 | 2001-10-09 18:07:04 +0000 | [diff] [blame] | 1487 | Possible values for the \var{mode} parameter to the \function{spawn*()} |
| 1488 | family of functions. If either of these values is given, the |
| 1489 | \function{spawn*()} functions will return as soon as the new process |
| 1490 | has been created, with the process ID as the return value. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1491 | Availability: \UNIX, Windows. |
Fred Drake | 0b9bc20 | 2001-06-11 18:25:34 +0000 | [diff] [blame] | 1492 | \versionadded{1.6} |
Fred Drake | 15861b2 | 2000-02-29 05:19:38 +0000 | [diff] [blame] | 1493 | \end{datadesc} |
| 1494 | |
Fred Drake | 938a8d7 | 2001-10-09 18:07:04 +0000 | [diff] [blame] | 1495 | \begin{datadesc}{P_WAIT} |
| 1496 | Possible value for the \var{mode} parameter to the \function{spawn*()} |
| 1497 | family of functions. If this is given as \var{mode}, the |
| 1498 | \function{spawn*()} functions will not return until the new process |
| 1499 | has run to completion and will return the exit code of the process the |
| 1500 | run is successful, or \code{-\var{signal}} if a signal kills the |
| 1501 | process. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1502 | Availability: \UNIX, Windows. |
Fred Drake | 938a8d7 | 2001-10-09 18:07:04 +0000 | [diff] [blame] | 1503 | \versionadded{1.6} |
| 1504 | \end{datadesc} |
| 1505 | |
| 1506 | \begin{datadesc}{P_DETACH} |
| 1507 | \dataline{P_OVERLAY} |
| 1508 | Possible values for the \var{mode} parameter to the |
| 1509 | \function{spawn*()} family of functions. These are less portable than |
| 1510 | those listed above. |
| 1511 | \constant{P_DETACH} is similar to \constant{P_NOWAIT}, but the new |
| 1512 | process is detached from the console of the calling process. |
| 1513 | If \constant{P_OVERLAY} is used, the current process will be replaced; |
| 1514 | the \function{spawn*()} function will not return. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1515 | Availability: Windows. |
Fred Drake | 0b9bc20 | 2001-06-11 18:25:34 +0000 | [diff] [blame] | 1516 | \versionadded{1.6} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1517 | \end{datadesc} |
| 1518 | |
Fred Drake | 4ce4f2e | 2000-09-29 04:15:19 +0000 | [diff] [blame] | 1519 | \begin{funcdesc}{startfile}{path} |
| 1520 | Start a file with its associated application. This acts like |
| 1521 | double-clicking the file in Windows Explorer, or giving the file name |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 1522 | as an argument to the \program{start} command from the interactive |
| 1523 | command shell: the file is opened with whatever application (if any) |
| 1524 | its extension is associated. |
Fred Drake | 4ce4f2e | 2000-09-29 04:15:19 +0000 | [diff] [blame] | 1525 | |
| 1526 | \function{startfile()} returns as soon as the associated application |
| 1527 | is launched. There is no option to wait for the application to close, |
| 1528 | and no way to retrieve the application's exit status. The \var{path} |
| 1529 | parameter is relative to the current directory. If you want to use an |
| 1530 | absolute path, make sure the first character is not a slash |
| 1531 | (\character{/}); the underlying Win32 \cfunction{ShellExecute()} |
Fred Drake | 8a2adcf | 2001-07-23 19:20:56 +0000 | [diff] [blame] | 1532 | function doesn't work if it is. Use the \function{os.path.normpath()} |
Fred Drake | 4ce4f2e | 2000-09-29 04:15:19 +0000 | [diff] [blame] | 1533 | function to ensure that the path is properly encoded for Win32. |
| 1534 | Availability: Windows. |
| 1535 | \versionadded{2.0} |
| 1536 | \end{funcdesc} |
| 1537 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1538 | \begin{funcdesc}{system}{command} |
| 1539 | Execute the command (a string) in a subshell. This is implemented by |
| 1540 | calling the Standard C function \cfunction{system()}, and has the |
Fred Drake | ec6baaf | 1999-04-21 18:13:31 +0000 | [diff] [blame] | 1541 | same limitations. Changes to \code{posix.environ}, \code{sys.stdin}, |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1542 | etc.\ are not reflected in the environment of the executed command. |
Tim Peters | dbaf04e | 2003-05-20 16:15:58 +0000 | [diff] [blame] | 1543 | |
Fred Drake | 15eac1f | 2003-05-20 16:21:51 +0000 | [diff] [blame] | 1544 | On \UNIX, the return value is the exit status of the process encoded in the |
Tim Peters | dbaf04e | 2003-05-20 16:15:58 +0000 | [diff] [blame] | 1545 | format specified for \function{wait()}. Note that \POSIX{} does not |
| 1546 | specify the meaning of the return value of the C \cfunction{system()} |
| 1547 | function, so the return value of the Python function is system-dependent. |
| 1548 | |
Fred Drake | 15eac1f | 2003-05-20 16:21:51 +0000 | [diff] [blame] | 1549 | On Windows, the return value is that returned by the system shell after |
Tim Peters | dbaf04e | 2003-05-20 16:15:58 +0000 | [diff] [blame] | 1550 | running \var{command}, given by the Windows environment variable |
Fred Drake | 15eac1f | 2003-05-20 16:21:51 +0000 | [diff] [blame] | 1551 | \envvar{COMSPEC}: on \program{command.com} systems (Windows 95, 98 and ME) |
| 1552 | this is always \code{0}; on \program{cmd.exe} systems (Windows NT, 2000 |
Tim Peters | dbaf04e | 2003-05-20 16:15:58 +0000 | [diff] [blame] | 1553 | and XP) this is the exit status of the command run; on systems using |
| 1554 | a non-native shell, consult your shell documentation. |
| 1555 | |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1556 | Availability: \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1557 | \end{funcdesc} |
| 1558 | |
| 1559 | \begin{funcdesc}{times}{} |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 1560 | Return a 5-tuple of floating point numbers indicating accumulated |
| 1561 | (processor or other) |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1562 | times, in seconds. The items are: user time, system time, children's |
| 1563 | user time, children's system time, and elapsed real time since a fixed |
Fred Drake | ec6baaf | 1999-04-21 18:13:31 +0000 | [diff] [blame] | 1564 | point in the past, in that order. See the \UNIX{} manual page |
| 1565 | \manpage{times}{2} or the corresponding Windows Platform API |
| 1566 | documentation. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1567 | Availability: \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1568 | \end{funcdesc} |
| 1569 | |
| 1570 | \begin{funcdesc}{wait}{} |
| 1571 | Wait for completion of a child process, and return a tuple containing |
| 1572 | its pid and exit status indication: a 16-bit number, whose low byte is |
| 1573 | the signal number that killed the process, and whose high byte is the |
| 1574 | exit status (if the signal number is zero); the high bit of the low |
| 1575 | byte is set if a core file was produced. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1576 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1577 | \end{funcdesc} |
| 1578 | |
| 1579 | \begin{funcdesc}{waitpid}{pid, options} |
Fred Drake | 1f89e2a | 2002-05-10 12:37:56 +0000 | [diff] [blame] | 1580 | The details of this function differ on \UNIX{} and Windows. |
Tim Peters | ab034fa | 2002-02-01 11:27:43 +0000 | [diff] [blame] | 1581 | |
| 1582 | On \UNIX: |
Fred Drake | 31e5e37 | 1999-08-13 13:36:33 +0000 | [diff] [blame] | 1583 | Wait for completion of a child process given by process id \var{pid}, |
| 1584 | and return a tuple containing its process id and exit status |
| 1585 | indication (encoded as for \function{wait()}). The semantics of the |
| 1586 | call are affected by the value of the integer \var{options}, which |
| 1587 | should be \code{0} for normal operation. |
Fred Drake | 31e5e37 | 1999-08-13 13:36:33 +0000 | [diff] [blame] | 1588 | |
| 1589 | If \var{pid} is greater than \code{0}, \function{waitpid()} requests |
| 1590 | status information for that specific process. If \var{pid} is |
| 1591 | \code{0}, the request is for the status of any child in the process |
| 1592 | group of the current process. If \var{pid} is \code{-1}, the request |
| 1593 | pertains to any child of the current process. If \var{pid} is less |
| 1594 | than \code{-1}, status is requested for any process in the process |
| 1595 | group \code{-\var{pid}} (the absolute value of \var{pid}). |
Tim Peters | ab034fa | 2002-02-01 11:27:43 +0000 | [diff] [blame] | 1596 | |
| 1597 | On Windows: |
Fred Drake | 4dfb7a8 | 2002-04-01 23:30:47 +0000 | [diff] [blame] | 1598 | Wait for completion of a process given by process handle \var{pid}, |
Tim Peters | ab034fa | 2002-02-01 11:27:43 +0000 | [diff] [blame] | 1599 | and return a tuple containing \var{pid}, |
| 1600 | and its exit status shifted left by 8 bits (shifting makes cross-platform |
| 1601 | use of the function easier). |
| 1602 | A \var{pid} less than or equal to \code{0} has no special meaning on |
| 1603 | Windows, and raises an exception. |
| 1604 | The value of integer \var{options} has no effect. |
| 1605 | \var{pid} can refer to any process whose id is known, not necessarily a |
| 1606 | child process. |
| 1607 | The \function{spawn()} functions called with \constant{P_NOWAIT} |
Fred Drake | 4dfb7a8 | 2002-04-01 23:30:47 +0000 | [diff] [blame] | 1608 | return suitable process handles. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1609 | \end{funcdesc} |
| 1610 | |
| 1611 | \begin{datadesc}{WNOHANG} |
| 1612 | The option for \function{waitpid()} to avoid hanging if no child |
| 1613 | process status is available immediately. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1614 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1615 | \end{datadesc} |
| 1616 | |
Fred Drake | 106c1a0 | 2002-04-23 15:58:02 +0000 | [diff] [blame] | 1617 | \begin{datadesc}{WCONTINUED} |
| 1618 | This option causes child processes to be reported if they have been |
| 1619 | continued from a job control stop since their status was last |
| 1620 | reported. |
| 1621 | Availability: Some \UNIX{} systems. |
| 1622 | \versionadded{2.3} |
| 1623 | \end{datadesc} |
| 1624 | |
| 1625 | \begin{datadesc}{WUNTRACED} |
| 1626 | This option causes child processes to be reported if they have been |
| 1627 | stopped but their current state has not been reported since they were |
| 1628 | stopped. |
| 1629 | Availability: \UNIX. |
| 1630 | \versionadded{2.3} |
| 1631 | \end{datadesc} |
| 1632 | |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 1633 | The following functions take a process status code as returned by |
| 1634 | \function{system()}, \function{wait()}, or \function{waitpid()} as a |
| 1635 | parameter. They may be used to determine the disposition of a |
| 1636 | process. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1637 | |
Fred Drake | 106c1a0 | 2002-04-23 15:58:02 +0000 | [diff] [blame] | 1638 | \begin{funcdesc}{WCOREDUMP}{status} |
| 1639 | Returns \code{True} if a core dump was generated for the process, |
| 1640 | otherwise it returns \code{False}. |
| 1641 | Availability: \UNIX. |
| 1642 | \versionadded{2.3} |
| 1643 | \end{funcdesc} |
| 1644 | |
| 1645 | \begin{funcdesc}{WIFCONTINUED}{status} |
| 1646 | Returns \code{True} if the process has been continued from a job |
| 1647 | control stop, otherwise it returns \code{False}. |
| 1648 | Availability: \UNIX. |
| 1649 | \versionadded{2.3} |
| 1650 | \end{funcdesc} |
| 1651 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1652 | \begin{funcdesc}{WIFSTOPPED}{status} |
Fred Drake | 106c1a0 | 2002-04-23 15:58:02 +0000 | [diff] [blame] | 1653 | Returns \code{True} if the process has been stopped, otherwise it |
| 1654 | returns \code{False}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1655 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1656 | \end{funcdesc} |
| 1657 | |
| 1658 | \begin{funcdesc}{WIFSIGNALED}{status} |
Fred Drake | 106c1a0 | 2002-04-23 15:58:02 +0000 | [diff] [blame] | 1659 | Returns \code{True} if the process exited due to a signal, otherwise |
| 1660 | it returns \code{False}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1661 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1662 | \end{funcdesc} |
| 1663 | |
| 1664 | \begin{funcdesc}{WIFEXITED}{status} |
Fred Drake | 106c1a0 | 2002-04-23 15:58:02 +0000 | [diff] [blame] | 1665 | Returns \code{True} if the process exited using the \manpage{exit}{2} |
| 1666 | system call, otherwise it returns \code{False}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1667 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1668 | \end{funcdesc} |
| 1669 | |
| 1670 | \begin{funcdesc}{WEXITSTATUS}{status} |
| 1671 | If \code{WIFEXITED(\var{status})} is true, return the integer |
Tim Peters | ab034fa | 2002-02-01 11:27:43 +0000 | [diff] [blame] | 1672 | parameter to the \manpage{exit}{2} system call. Otherwise, the return |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1673 | value is meaningless. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1674 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1675 | \end{funcdesc} |
| 1676 | |
| 1677 | \begin{funcdesc}{WSTOPSIG}{status} |
Fred Drake | 35c3ffd | 1999-03-04 14:08:10 +0000 | [diff] [blame] | 1678 | Return the signal which caused the process to stop. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1679 | Availability: \UNIX. |
Fred Drake | 35c3ffd | 1999-03-04 14:08:10 +0000 | [diff] [blame] | 1680 | \end{funcdesc} |
| 1681 | |
| 1682 | \begin{funcdesc}{WTERMSIG}{status} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1683 | Return the signal which caused the process to exit. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1684 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1685 | \end{funcdesc} |
| 1686 | |
| 1687 | |
Thomas Wouters | f831663 | 2000-07-16 19:01:10 +0000 | [diff] [blame] | 1688 | \subsection{Miscellaneous System Information \label{os-path}} |
Fred Drake | 88f6ca2 | 1999-12-15 19:39:04 +0000 | [diff] [blame] | 1689 | |
| 1690 | |
| 1691 | \begin{funcdesc}{confstr}{name} |
| 1692 | Return string-valued system configuration values. |
| 1693 | \var{name} specifies the configuration value to retrieve; it may be a |
| 1694 | string which is the name of a defined system value; these names are |
Raymond Hettinger | b67449d | 2003-09-08 18:52:18 +0000 | [diff] [blame] | 1695 | specified in a number of standards (\POSIX, \UNIX{} 95, \UNIX{} 98, and |
Fred Drake | 88f6ca2 | 1999-12-15 19:39:04 +0000 | [diff] [blame] | 1696 | others). Some platforms define additional names as well. The names |
| 1697 | known to the host operating system are given in the |
| 1698 | \code{confstr_names} dictionary. For configuration variables not |
| 1699 | included in that mapping, passing an integer for \var{name} is also |
| 1700 | accepted. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1701 | Availability: \UNIX. |
Fred Drake | 88f6ca2 | 1999-12-15 19:39:04 +0000 | [diff] [blame] | 1702 | |
| 1703 | If the configuration value specified by \var{name} isn't defined, the |
| 1704 | empty string is returned. |
| 1705 | |
| 1706 | If \var{name} is a string and is not known, \exception{ValueError} is |
| 1707 | raised. If a specific value for \var{name} is not supported by the |
| 1708 | host system, even if it is included in \code{confstr_names}, an |
| 1709 | \exception{OSError} is raised with \constant{errno.EINVAL} for the |
| 1710 | error number. |
| 1711 | \end{funcdesc} |
| 1712 | |
| 1713 | \begin{datadesc}{confstr_names} |
| 1714 | Dictionary mapping names accepted by \function{confstr()} to the |
| 1715 | integer values defined for those names by the host operating system. |
| 1716 | This can be used to determine the set of names known to the system. |
| 1717 | Availability: \UNIX. |
| 1718 | \end{datadesc} |
| 1719 | |
Martin v. Löwis | 438b534 | 2002-12-27 10:16:42 +0000 | [diff] [blame] | 1720 | \begin{funcdesc}{getloadavg}{} |
| 1721 | Return the number of processes in the system run queue averaged over |
| 1722 | the last 1, 5, and 15 minutes or raises OSError if the load average |
| 1723 | was unobtainable. |
| 1724 | |
| 1725 | \versionadded{2.3} |
| 1726 | \end{funcdesc} |
| 1727 | |
Fred Drake | 88f6ca2 | 1999-12-15 19:39:04 +0000 | [diff] [blame] | 1728 | \begin{funcdesc}{sysconf}{name} |
| 1729 | Return integer-valued system configuration values. |
| 1730 | If the configuration value specified by \var{name} isn't defined, |
| 1731 | \code{-1} is returned. The comments regarding the \var{name} |
| 1732 | parameter for \function{confstr()} apply here as well; the dictionary |
| 1733 | that provides information on the known names is given by |
| 1734 | \code{sysconf_names}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1735 | Availability: \UNIX. |
Fred Drake | 88f6ca2 | 1999-12-15 19:39:04 +0000 | [diff] [blame] | 1736 | \end{funcdesc} |
| 1737 | |
| 1738 | \begin{datadesc}{sysconf_names} |
| 1739 | Dictionary mapping names accepted by \function{sysconf()} to the |
| 1740 | integer values defined for those names by the host operating system. |
| 1741 | This can be used to determine the set of names known to the system. |
| 1742 | Availability: \UNIX. |
| 1743 | \end{datadesc} |
| 1744 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1745 | |
| 1746 | The follow data values are used to support path manipulation |
| 1747 | operations. These are defined for all platforms. |
| 1748 | |
| 1749 | Higher-level operations on pathnames are defined in the |
| 1750 | \refmodule{os.path} module. |
| 1751 | |
| 1752 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 1753 | \begin{datadesc}{curdir} |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 1754 | The constant string used by the operating system to refer to the current |
| 1755 | directory. |
Fred Drake | 907e76b | 2001-07-06 20:30:11 +0000 | [diff] [blame] | 1756 | For example: \code{'.'} for \POSIX{} or \code{':'} for the Macintosh. |
Skip Montanaro | 117910d | 2003-02-14 19:35:31 +0000 | [diff] [blame] | 1757 | Also available via \module{os.path}. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 1758 | \end{datadesc} |
| 1759 | |
| 1760 | \begin{datadesc}{pardir} |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 1761 | The constant string used by the operating system to refer to the parent |
| 1762 | directory. |
Fred Drake | 907e76b | 2001-07-06 20:30:11 +0000 | [diff] [blame] | 1763 | For example: \code{'..'} for \POSIX{} or \code{'::'} for the Macintosh. |
Skip Montanaro | 117910d | 2003-02-14 19:35:31 +0000 | [diff] [blame] | 1764 | Also available via \module{os.path}. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 1765 | \end{datadesc} |
| 1766 | |
| 1767 | \begin{datadesc}{sep} |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 1768 | The character used by the operating system to separate pathname components, |
Fred Drake | 907e76b | 2001-07-06 20:30:11 +0000 | [diff] [blame] | 1769 | for example, \character{/} for \POSIX{} or \character{:} for the |
| 1770 | Macintosh. Note that knowing this is not sufficient to be able to |
| 1771 | parse or concatenate pathnames --- use \function{os.path.split()} and |
Fred Drake | 1a3c2a0 | 1998-08-06 15:18:23 +0000 | [diff] [blame] | 1772 | \function{os.path.join()} --- but it is occasionally useful. |
Skip Montanaro | 117910d | 2003-02-14 19:35:31 +0000 | [diff] [blame] | 1773 | Also available via \module{os.path}. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 1774 | \end{datadesc} |
| 1775 | |
Guido van Rossum | b2afc81 | 1997-08-29 22:37:44 +0000 | [diff] [blame] | 1776 | \begin{datadesc}{altsep} |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 1777 | An alternative character used by the operating system to separate pathname |
| 1778 | components, or \code{None} if only one separator character exists. This is |
Martin v. Löwis | 36a4d8c | 2002-10-10 18:24:54 +0000 | [diff] [blame] | 1779 | set to \character{/} on Windows systems where \code{sep} is a |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 1780 | backslash. |
Skip Montanaro | 117910d | 2003-02-14 19:35:31 +0000 | [diff] [blame] | 1781 | Also available via \module{os.path}. |
Guido van Rossum | b2afc81 | 1997-08-29 22:37:44 +0000 | [diff] [blame] | 1782 | \end{datadesc} |
| 1783 | |
Skip Montanaro | 47e46e2 | 2003-02-14 05:45:31 +0000 | [diff] [blame] | 1784 | \begin{datadesc}{extsep} |
Fred Drake | 002a5de | 2003-02-14 06:39:37 +0000 | [diff] [blame] | 1785 | The character which separates the base filename from the extension; |
| 1786 | for example, the \character{.} in \file{os.py}. |
Skip Montanaro | 117910d | 2003-02-14 19:35:31 +0000 | [diff] [blame] | 1787 | Also available via \module{os.path}. |
Fred Drake | 002a5de | 2003-02-14 06:39:37 +0000 | [diff] [blame] | 1788 | \versionadded{2.2} |
Skip Montanaro | 47e46e2 | 2003-02-14 05:45:31 +0000 | [diff] [blame] | 1789 | \end{datadesc} |
| 1790 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 1791 | \begin{datadesc}{pathsep} |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 1792 | The character conventionally used by the operating system to separate |
| 1793 | search patch components (as in \envvar{PATH}), such as \character{:} for |
Martin v. Löwis | 36a4d8c | 2002-10-10 18:24:54 +0000 | [diff] [blame] | 1794 | \POSIX{} or \character{;} for Windows. |
Skip Montanaro | 117910d | 2003-02-14 19:35:31 +0000 | [diff] [blame] | 1795 | Also available via \module{os.path}. |
Guido van Rossum | 9c59ce9 | 1998-06-30 15:54:27 +0000 | [diff] [blame] | 1796 | \end{datadesc} |
| 1797 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 1798 | \begin{datadesc}{defpath} |
Fred Drake | 6995bb6 | 2001-11-29 20:48:44 +0000 | [diff] [blame] | 1799 | The default search path used by \function{exec*p*()} and |
| 1800 | \function{spawn*p*()} if the environment doesn't have a \code{'PATH'} |
| 1801 | key. |
Skip Montanaro | 117910d | 2003-02-14 19:35:31 +0000 | [diff] [blame] | 1802 | Also available via \module{os.path}. |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 1803 | \end{datadesc} |
| 1804 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1805 | \begin{datadesc}{linesep} |
| 1806 | The string used to separate (or, rather, terminate) lines on the |
Fred Drake | 907e76b | 2001-07-06 20:30:11 +0000 | [diff] [blame] | 1807 | current platform. This may be a single character, such as \code{'\e |
Fred Drake | 6995bb6 | 2001-11-29 20:48:44 +0000 | [diff] [blame] | 1808 | n'} for \POSIX{} or \code{'\e r'} for Mac OS, or multiple characters, |
Martin v. Löwis | 36a4d8c | 2002-10-10 18:24:54 +0000 | [diff] [blame] | 1809 | for example, \code{'\e r\e n'} for Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1810 | \end{datadesc} |
Martin v. Löwis | bdec50f | 2004-06-08 08:29:33 +0000 | [diff] [blame] | 1811 | |
| 1812 | \begin{datadesc}{devnull} |
| 1813 | The file path of the null device. |
| 1814 | For example: \code{'/dev/null'} for \POSIX{} or \code{'Dev:Nul'} for the |
| 1815 | Macintosh. |
| 1816 | Also available via \module{os.path}. |
| 1817 | \versionadded{2.4} |
| 1818 | \end{datadesc} |