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'}, |
| 67 | \code{'nt'}, \code{'dos'}, \code{'mac'}, \code{'os2'}, \code{'ce'}, |
| 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 |
| 96 | the mapping is modified. |
| 97 | |
| 98 | If \function{putenv()} is not provided, this mapping may be passed to |
Tim Peters | ab034fa | 2002-02-01 11:27:43 +0000 | [diff] [blame] | 99 | the appropriate process-creation functions to cause child processes to |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 100 | use a modified environment. |
| 101 | \end{datadesc} |
| 102 | |
Fred Drake | 6db897c | 1999-07-12 16:49:30 +0000 | [diff] [blame] | 103 | \begin{funcdescni}{chdir}{path} |
Fred Drake | e19a5bc | 2002-04-15 19:46:40 +0000 | [diff] [blame] | 104 | \funclineni{fchdir}{fd} |
Fred Drake | 6db897c | 1999-07-12 16:49:30 +0000 | [diff] [blame] | 105 | \funclineni{getcwd}{} |
| 106 | These functions are described in ``Files and Directories'' (section |
| 107 | \ref{os-file-dir}). |
| 108 | \end{funcdescni} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 109 | |
Fred Drake | 18f7a45 | 1999-12-09 22:11:43 +0000 | [diff] [blame] | 110 | \begin{funcdesc}{ctermid}{} |
| 111 | Return the filename corresponding to the controlling terminal of the |
| 112 | process. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 113 | Availability: \UNIX. |
Fred Drake | 18f7a45 | 1999-12-09 22:11:43 +0000 | [diff] [blame] | 114 | \end{funcdesc} |
| 115 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 116 | \begin{funcdesc}{getegid}{} |
| 117 | Return the current process' effective group id. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 118 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 119 | \end{funcdesc} |
| 120 | |
| 121 | \begin{funcdesc}{geteuid}{} |
Fred Drake | 6b330ba8 | 1999-05-25 13:42:26 +0000 | [diff] [blame] | 122 | \index{user!effective id} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 123 | Return the current process' effective user id. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 124 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 125 | \end{funcdesc} |
| 126 | |
| 127 | \begin{funcdesc}{getgid}{} |
Fred Drake | 6b330ba8 | 1999-05-25 13:42:26 +0000 | [diff] [blame] | 128 | \index{process!group} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 129 | Return the current process' group id. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 130 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 131 | \end{funcdesc} |
| 132 | |
Fred Drake | 88f6ca2 | 1999-12-15 19:39:04 +0000 | [diff] [blame] | 133 | \begin{funcdesc}{getgroups}{} |
| 134 | Return list of supplemental group ids associated with the current |
| 135 | process. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 136 | Availability: \UNIX. |
Fred Drake | 88f6ca2 | 1999-12-15 19:39:04 +0000 | [diff] [blame] | 137 | \end{funcdesc} |
| 138 | |
| 139 | \begin{funcdesc}{getlogin}{} |
| 140 | Return the actual login name for the current process, even if there |
| 141 | are multiple login names which map to the same user id. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 142 | Availability: \UNIX. |
Fred Drake | 88f6ca2 | 1999-12-15 19:39:04 +0000 | [diff] [blame] | 143 | \end{funcdesc} |
| 144 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 145 | \begin{funcdesc}{getpgrp}{} |
| 146 | \index{process!group} |
| 147 | Return the current process group id. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 148 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 149 | \end{funcdesc} |
| 150 | |
| 151 | \begin{funcdesc}{getpid}{} |
| 152 | \index{process!id} |
| 153 | Return the current process id. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 154 | Availability: \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 155 | \end{funcdesc} |
| 156 | |
| 157 | \begin{funcdesc}{getppid}{} |
| 158 | \index{process!id of parent} |
| 159 | Return the parent's process id. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 160 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 161 | \end{funcdesc} |
| 162 | |
| 163 | \begin{funcdesc}{getuid}{} |
Fred Drake | 6b330ba8 | 1999-05-25 13:42:26 +0000 | [diff] [blame] | 164 | \index{user!id} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 165 | Return the current process' user id. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 166 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 167 | \end{funcdesc} |
| 168 | |
Fred Drake | 81e142b | 2001-05-31 20:27:46 +0000 | [diff] [blame] | 169 | \begin{funcdesc}{getenv}{varname\optional{, value}} |
| 170 | Return the value of the environment variable \var{varname} if it |
| 171 | exists, or \var{value} if it doesn't. \var{value} defaults to |
| 172 | \code{None}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 173 | Availability: most flavors of \UNIX, Windows. |
Fred Drake | 81e142b | 2001-05-31 20:27:46 +0000 | [diff] [blame] | 174 | \end{funcdesc} |
| 175 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 176 | \begin{funcdesc}{putenv}{varname, value} |
| 177 | \index{environment variables!setting} |
| 178 | Set the environment variable named \var{varname} to the string |
| 179 | \var{value}. Such changes to the environment affect subprocesses |
| 180 | started with \function{os.system()}, \function{popen()} or |
| 181 | \function{fork()} and \function{execv()}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 182 | Availability: most flavors of \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 183 | |
| 184 | When \function{putenv()} is |
| 185 | supported, assignments to items in \code{os.environ} are automatically |
| 186 | translated into corresponding calls to \function{putenv()}; however, |
| 187 | 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] | 188 | actually preferable to assign to items of \code{os.environ}. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 189 | \end{funcdesc} |
| 190 | |
Andrew M. Kuchling | 8d2f2b2 | 2000-07-13 01:26:58 +0000 | [diff] [blame] | 191 | \begin{funcdesc}{setegid}{egid} |
| 192 | Set the current process's effective group id. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 193 | Availability: \UNIX. |
Andrew M. Kuchling | 8d2f2b2 | 2000-07-13 01:26:58 +0000 | [diff] [blame] | 194 | \end{funcdesc} |
| 195 | |
| 196 | \begin{funcdesc}{seteuid}{euid} |
| 197 | Set the current process's effective user id. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 198 | Availability: \UNIX. |
Andrew M. Kuchling | 8d2f2b2 | 2000-07-13 01:26:58 +0000 | [diff] [blame] | 199 | \end{funcdesc} |
| 200 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 201 | \begin{funcdesc}{setgid}{gid} |
| 202 | Set the current process' group id. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 203 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 204 | \end{funcdesc} |
| 205 | |
Martin v. Löwis | 61c5edf | 2001-10-18 04:06:00 +0000 | [diff] [blame] | 206 | \begin{funcdesc}{setgroups}{groups} |
Martin v. Löwis | c405133 | 2001-10-18 14:07:12 +0000 | [diff] [blame] | 207 | Set the list of supplemental group ids associated with the current |
| 208 | process to \var{groups}. \var{groups} must be a sequence, and each |
| 209 | element must be an integer identifying a group. This operation is |
| 210 | typical available only to the superuser. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 211 | Availability: \UNIX. |
Martin v. Löwis | 61c5edf | 2001-10-18 04:06:00 +0000 | [diff] [blame] | 212 | \versionadded{2.2} |
| 213 | \end{funcdesc} |
| 214 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 215 | \begin{funcdesc}{setpgrp}{} |
| 216 | Calls the system call \cfunction{setpgrp()} or \cfunction{setpgrp(0, |
| 217 | 0)} depending on which version is implemented (if any). See the |
| 218 | \UNIX{} manual for the semantics. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 219 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 220 | \end{funcdesc} |
| 221 | |
| 222 | \begin{funcdesc}{setpgid}{pid, pgrp} |
| 223 | Calls the system call \cfunction{setpgid()}. See the \UNIX{} manual |
| 224 | for the semantics. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 225 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 226 | \end{funcdesc} |
| 227 | |
Andrew M. Kuchling | 8d2f2b2 | 2000-07-13 01:26:58 +0000 | [diff] [blame] | 228 | \begin{funcdesc}{setreuid}{ruid, euid} |
| 229 | Set the current process's real and effective user ids. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 230 | Availability: \UNIX. |
Andrew M. Kuchling | 8d2f2b2 | 2000-07-13 01:26:58 +0000 | [diff] [blame] | 231 | \end{funcdesc} |
| 232 | |
| 233 | \begin{funcdesc}{setregid}{rgid, egid} |
| 234 | Set the current process's real and effective group ids. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 235 | Availability: \UNIX. |
Andrew M. Kuchling | 8d2f2b2 | 2000-07-13 01:26:58 +0000 | [diff] [blame] | 236 | \end{funcdesc} |
| 237 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 238 | \begin{funcdesc}{setsid}{} |
| 239 | Calls the system call \cfunction{setsid()}. See the \UNIX{} manual |
| 240 | for the semantics. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 241 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 242 | \end{funcdesc} |
| 243 | |
| 244 | \begin{funcdesc}{setuid}{uid} |
Fred Drake | 6b330ba8 | 1999-05-25 13:42:26 +0000 | [diff] [blame] | 245 | \index{user!id, setting} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 246 | Set the current process' user id. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 247 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 248 | \end{funcdesc} |
| 249 | |
| 250 | % placed in this section since it relates to errno.... a little weak ;-( |
| 251 | \begin{funcdesc}{strerror}{code} |
| 252 | Return the error message corresponding to the error code in |
| 253 | \var{code}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 254 | Availability: \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 255 | \end{funcdesc} |
| 256 | |
| 257 | \begin{funcdesc}{umask}{mask} |
| 258 | Set the current numeric umask and returns the previous umask. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 259 | Availability: \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 260 | \end{funcdesc} |
| 261 | |
| 262 | \begin{funcdesc}{uname}{} |
| 263 | Return a 5-tuple containing information identifying the current |
| 264 | operating system. The tuple contains 5 strings: |
| 265 | \code{(\var{sysname}, \var{nodename}, \var{release}, \var{version}, |
| 266 | \var{machine})}. Some systems truncate the nodename to 8 |
| 267 | characters or to the leading component; a better way to get the |
| 268 | hostname is \function{socket.gethostname()} |
| 269 | \withsubitem{(in module socket)}{\ttindex{gethostname()}} |
| 270 | or even |
| 271 | \withsubitem{(in module socket)}{\ttindex{gethostbyaddr()}} |
| 272 | \code{socket.gethostbyaddr(socket.gethostname())}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 273 | Availability: recent flavors of \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 274 | \end{funcdesc} |
| 275 | |
| 276 | |
| 277 | |
| 278 | \subsection{File Object Creation \label{os-newstreams}} |
| 279 | |
| 280 | These functions create new file objects. |
| 281 | |
| 282 | |
| 283 | \begin{funcdesc}{fdopen}{fd\optional{, mode\optional{, bufsize}}} |
| 284 | Return an open file object connected to the file descriptor \var{fd}. |
Fred Drake | 8c9fc00 | 1999-08-05 13:41:31 +0000 | [diff] [blame] | 285 | \index{I/O control!buffering} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 286 | The \var{mode} and \var{bufsize} arguments have the same meaning as |
| 287 | the corresponding arguments to the built-in \function{open()} |
| 288 | function. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 289 | Availability: Macintosh, \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 290 | \end{funcdesc} |
| 291 | |
| 292 | \begin{funcdesc}{popen}{command\optional{, mode\optional{, bufsize}}} |
| 293 | Open a pipe to or from \var{command}. The return value is an open |
| 294 | file object connected to the pipe, which can be read or written |
| 295 | depending on whether \var{mode} is \code{'r'} (default) or \code{'w'}. |
| 296 | The \var{bufsize} argument has the same meaning as the corresponding |
| 297 | argument to the built-in \function{open()} function. The exit status of |
| 298 | the command (encoded in the format specified for \function{wait()}) is |
| 299 | available as the return value of the \method{close()} method of the file |
| 300 | object, except that when the exit status is zero (termination without |
Fred Drake | 1319e3e | 2000-10-03 17:14:27 +0000 | [diff] [blame] | 301 | errors), \code{None} is returned. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 302 | Availability: \UNIX, Windows. |
Fred Drake | c71c23e | 2000-10-04 13:57:27 +0000 | [diff] [blame] | 303 | |
| 304 | \versionchanged[This function worked unreliably under Windows in |
| 305 | earlier versions of Python. This was due to the use of the |
| 306 | \cfunction{_popen()} function from the libraries provided with |
| 307 | Windows. Newer versions of Python do not use the broken |
| 308 | implementation from the Windows libraries]{2.0} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 309 | \end{funcdesc} |
| 310 | |
Fred Drake | 18f7a45 | 1999-12-09 22:11:43 +0000 | [diff] [blame] | 311 | \begin{funcdesc}{tmpfile}{} |
| 312 | Return a new file object opened in update mode (\samp{w+}). The file |
| 313 | has no directory entries associated with it and will be automatically |
| 314 | deleted once there are no file descriptors for the file. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 315 | Availability: \UNIX, Windows. |
Fred Drake | 18f7a45 | 1999-12-09 22:11:43 +0000 | [diff] [blame] | 316 | \end{funcdesc} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 317 | |
| 318 | |
Fred Drake | 8a9db99 | 2000-09-28 20:27:51 +0000 | [diff] [blame] | 319 | For each of these \function{popen()} variants, if \var{bufsize} is |
| 320 | specified, it specifies the buffer size for the I/O pipes. |
| 321 | \var{mode}, if provided, should be the string \code{'b'} or |
| 322 | \code{'t'}; on Windows this is needed to determine whether the file |
| 323 | objects should be opened in binary or text mode. The default value |
| 324 | for \var{mode} is \code{'t'}. |
| 325 | |
Fred Drake | 098d7fa | 2001-09-11 19:56:51 +0000 | [diff] [blame] | 326 | These methods do not make it possible to retrieve the return code from |
| 327 | the child processes. The only way to control the input and output |
| 328 | streams and also retrieve the return codes is to use the |
| 329 | \class{Popen3} and \class{Popen4} classes from the \refmodule{popen2} |
| 330 | module; these are only available on \UNIX. |
| 331 | |
Fred Drake | 046f4d8 | 2001-06-11 15:21:48 +0000 | [diff] [blame] | 332 | \begin{funcdesc}{popen2}{cmd\optional{, mode\optional{, bufsize}}} |
Fred Drake | 8a9db99 | 2000-09-28 20:27:51 +0000 | [diff] [blame] | 333 | Executes \var{cmd} as a sub-process. Returns the file objects |
| 334 | \code{(\var{child_stdin}, \var{child_stdout})}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 335 | Availability: \UNIX, Windows. |
Fred Drake | 8a9db99 | 2000-09-28 20:27:51 +0000 | [diff] [blame] | 336 | \versionadded{2.0} |
| 337 | \end{funcdesc} |
| 338 | |
Fred Drake | 046f4d8 | 2001-06-11 15:21:48 +0000 | [diff] [blame] | 339 | \begin{funcdesc}{popen3}{cmd\optional{, mode\optional{, bufsize}}} |
Fred Drake | 8a9db99 | 2000-09-28 20:27:51 +0000 | [diff] [blame] | 340 | Executes \var{cmd} as a sub-process. Returns the file objects |
| 341 | \code{(\var{child_stdin}, \var{child_stdout}, \var{child_stderr})}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 342 | Availability: \UNIX, Windows. |
Fred Drake | 8a9db99 | 2000-09-28 20:27:51 +0000 | [diff] [blame] | 343 | \versionadded{2.0} |
| 344 | \end{funcdesc} |
| 345 | |
Fred Drake | 046f4d8 | 2001-06-11 15:21:48 +0000 | [diff] [blame] | 346 | \begin{funcdesc}{popen4}{cmd\optional{, mode\optional{, bufsize}}} |
Fred Drake | 8a9db99 | 2000-09-28 20:27:51 +0000 | [diff] [blame] | 347 | Executes \var{cmd} as a sub-process. Returns the file objects |
| 348 | \code{(\var{child_stdin}, \var{child_stdout_and_stderr})}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 349 | Availability: \UNIX, Windows. |
Fred Drake | 8a9db99 | 2000-09-28 20:27:51 +0000 | [diff] [blame] | 350 | \versionadded{2.0} |
| 351 | \end{funcdesc} |
| 352 | |
| 353 | This functionality is also available in the \refmodule{popen2} module |
| 354 | using functions of the same names, but the return values of those |
| 355 | functions have a different order. |
| 356 | |
| 357 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 358 | \subsection{File Descriptor Operations \label{os-fd-ops}} |
| 359 | |
| 360 | These functions operate on I/O streams referred to |
| 361 | using file descriptors. |
| 362 | |
| 363 | |
| 364 | \begin{funcdesc}{close}{fd} |
| 365 | Close file descriptor \var{fd}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 366 | Availability: Macintosh, \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 367 | |
| 368 | Note: this function is intended for low-level I/O and must be applied |
| 369 | to a file descriptor as returned by \function{open()} or |
| 370 | \function{pipe()}. To close a ``file object'' returned by the |
| 371 | built-in function \function{open()} or by \function{popen()} or |
| 372 | \function{fdopen()}, use its \method{close()} method. |
| 373 | \end{funcdesc} |
| 374 | |
| 375 | \begin{funcdesc}{dup}{fd} |
| 376 | Return a duplicate of file descriptor \var{fd}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 377 | Availability: Macintosh, \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 378 | \end{funcdesc} |
| 379 | |
| 380 | \begin{funcdesc}{dup2}{fd, fd2} |
| 381 | Duplicate file descriptor \var{fd} to \var{fd2}, closing the latter |
| 382 | first if necessary. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 383 | Availability: \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 384 | \end{funcdesc} |
| 385 | |
Fred Drake | 88f6ca2 | 1999-12-15 19:39:04 +0000 | [diff] [blame] | 386 | \begin{funcdesc}{fpathconf}{fd, name} |
Thomas Wouters | f831663 | 2000-07-16 19:01:10 +0000 | [diff] [blame] | 387 | Return system configuration information relevant to an open file. |
Fred Drake | 88f6ca2 | 1999-12-15 19:39:04 +0000 | [diff] [blame] | 388 | \var{name} specifies the configuration value to retrieve; it may be a |
| 389 | string which is the name of a defined system value; these names are |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 390 | 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] | 391 | others). Some platforms define additional names as well. The names |
| 392 | known to the host operating system are given in the |
| 393 | \code{pathconf_names} dictionary. For configuration variables not |
| 394 | included in that mapping, passing an integer for \var{name} is also |
| 395 | accepted. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 396 | Availability: \UNIX. |
Fred Drake | 88f6ca2 | 1999-12-15 19:39:04 +0000 | [diff] [blame] | 397 | |
| 398 | If \var{name} is a string and is not known, \exception{ValueError} is |
| 399 | raised. If a specific value for \var{name} is not supported by the |
| 400 | host system, even if it is included in \code{pathconf_names}, an |
| 401 | \exception{OSError} is raised with \constant{errno.EINVAL} for the |
| 402 | error number. |
| 403 | \end{funcdesc} |
| 404 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 405 | \begin{funcdesc}{fstat}{fd} |
| 406 | Return status for file descriptor \var{fd}, like \function{stat()}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 407 | Availability: \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 408 | \end{funcdesc} |
| 409 | |
| 410 | \begin{funcdesc}{fstatvfs}{fd} |
| 411 | Return information about the filesystem containing the file associated |
| 412 | with file descriptor \var{fd}, like \function{statvfs()}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 413 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 414 | \end{funcdesc} |
| 415 | |
| 416 | \begin{funcdesc}{ftruncate}{fd, length} |
Tim Peters | ab034fa | 2002-02-01 11:27:43 +0000 | [diff] [blame] | 417 | Truncate the file corresponding to file descriptor \var{fd}, |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 418 | so that it is at most \var{length} bytes in size. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 419 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 420 | \end{funcdesc} |
| 421 | |
Skip Montanaro | d372521 | 2000-07-19 17:30:58 +0000 | [diff] [blame] | 422 | \begin{funcdesc}{isatty}{fd} |
Fred Drake | 106c1a0 | 2002-04-23 15:58:02 +0000 | [diff] [blame^] | 423 | Return \code{True} if the file descriptor \var{fd} is open and |
| 424 | connected to a tty(-like) device, else \code{False}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 425 | Availability: \UNIX. |
Skip Montanaro | d372521 | 2000-07-19 17:30:58 +0000 | [diff] [blame] | 426 | \end{funcdesc} |
| 427 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 428 | \begin{funcdesc}{lseek}{fd, pos, how} |
| 429 | Set the current position of file descriptor \var{fd} to position |
| 430 | \var{pos}, modified by \var{how}: \code{0} to set the position |
| 431 | relative to the beginning of the file; \code{1} to set it relative to |
| 432 | the current position; \code{2} to set it relative to the end of the |
| 433 | file. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 434 | Availability: Macintosh, \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 435 | \end{funcdesc} |
| 436 | |
| 437 | \begin{funcdesc}{open}{file, flags\optional{, mode}} |
| 438 | Open the file \var{file} and set various flags according to |
| 439 | \var{flags} and possibly its mode according to \var{mode}. |
| 440 | The default \var{mode} is \code{0777} (octal), and the current umask |
| 441 | value is first masked out. Return the file descriptor for the newly |
| 442 | opened file. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 443 | Availability: Macintosh, \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 444 | |
| 445 | For a description of the flag and mode values, see the C run-time |
| 446 | documentation; flag constants (like \constant{O_RDONLY} and |
| 447 | \constant{O_WRONLY}) are defined in this module too (see below). |
| 448 | |
| 449 | Note: this function is intended for low-level I/O. For normal usage, |
| 450 | use the built-in function \function{open()}, which returns a ``file |
| 451 | object'' with \method{read()} and \method{write()} methods (and many |
| 452 | more). |
| 453 | \end{funcdesc} |
| 454 | |
Fred Drake | c82634c | 2000-06-28 17:27:48 +0000 | [diff] [blame] | 455 | \begin{funcdesc}{openpty}{} |
| 456 | Open a new pseudo-terminal pair. Return a pair of file descriptors |
| 457 | \code{(\var{master}, \var{slave})} for the pty and the tty, |
| 458 | respectively. For a (slightly) more portable approach, use the |
| 459 | \refmodule{pty}\refstmodindex{pty} module. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 460 | Availability: Some flavors of \UNIX. |
Fred Drake | c82634c | 2000-06-28 17:27:48 +0000 | [diff] [blame] | 461 | \end{funcdesc} |
| 462 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 463 | \begin{funcdesc}{pipe}{} |
| 464 | Create a pipe. Return a pair of file descriptors \code{(\var{r}, |
| 465 | \var{w})} usable for reading and writing, respectively. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 466 | Availability: \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 467 | \end{funcdesc} |
| 468 | |
| 469 | \begin{funcdesc}{read}{fd, n} |
| 470 | Read at most \var{n} bytes from file descriptor \var{fd}. |
| 471 | Return a string containing the bytes read. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 472 | Availability: Macintosh, \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 473 | |
| 474 | Note: this function is intended for low-level I/O and must be applied |
| 475 | to a file descriptor as returned by \function{open()} or |
| 476 | \function{pipe()}. To read a ``file object'' returned by the |
| 477 | built-in function \function{open()} or by \function{popen()} or |
| 478 | \function{fdopen()}, or \code{sys.stdin}, use its |
| 479 | \method{read()} or \method{readline()} methods. |
| 480 | \end{funcdesc} |
| 481 | |
| 482 | \begin{funcdesc}{tcgetpgrp}{fd} |
| 483 | Return the process group associated with the terminal given by |
| 484 | \var{fd} (an open file descriptor as returned by \function{open()}). |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 485 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 486 | \end{funcdesc} |
| 487 | |
| 488 | \begin{funcdesc}{tcsetpgrp}{fd, pg} |
| 489 | Set the process group associated with the terminal given by |
| 490 | \var{fd} (an open file descriptor as returned by \function{open()}) |
| 491 | to \var{pg}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 492 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 493 | \end{funcdesc} |
| 494 | |
| 495 | \begin{funcdesc}{ttyname}{fd} |
| 496 | Return a string which specifies the terminal device associated with |
| 497 | file-descriptor \var{fd}. If \var{fd} is not associated with a terminal |
| 498 | device, an exception is raised. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 499 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 500 | \end{funcdesc} |
| 501 | |
| 502 | \begin{funcdesc}{write}{fd, str} |
| 503 | Write the string \var{str} to file descriptor \var{fd}. |
| 504 | Return the number of bytes actually written. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 505 | Availability: Macintosh, \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 506 | |
| 507 | Note: this function is intended for low-level I/O and must be applied |
| 508 | to a file descriptor as returned by \function{open()} or |
| 509 | \function{pipe()}. To write a ``file object'' returned by the |
| 510 | built-in function \function{open()} or by \function{popen()} or |
| 511 | \function{fdopen()}, or \code{sys.stdout} or \code{sys.stderr}, use |
| 512 | its \method{write()} method. |
| 513 | \end{funcdesc} |
| 514 | |
| 515 | |
| 516 | The following data items are available for use in constructing the |
| 517 | \var{flags} parameter to the \function{open()} function. |
| 518 | |
| 519 | \begin{datadesc}{O_RDONLY} |
| 520 | \dataline{O_WRONLY} |
| 521 | \dataline{O_RDWR} |
| 522 | \dataline{O_NDELAY} |
| 523 | \dataline{O_NONBLOCK} |
| 524 | \dataline{O_APPEND} |
| 525 | \dataline{O_DSYNC} |
| 526 | \dataline{O_RSYNC} |
| 527 | \dataline{O_SYNC} |
| 528 | \dataline{O_NOCTTY} |
| 529 | \dataline{O_CREAT} |
| 530 | \dataline{O_EXCL} |
| 531 | \dataline{O_TRUNC} |
| 532 | Options for the \var{flag} argument to the \function{open()} function. |
| 533 | These can be bit-wise OR'd together. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 534 | Availability: Macintosh, \UNIX, Windows. |
Tim Peters | c48a3ca | 2002-01-30 05:49:46 +0000 | [diff] [blame] | 535 | % 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] | 536 | \end{datadesc} |
| 537 | |
Fred Drake | 3ac977e | 2000-08-11 20:19:51 +0000 | [diff] [blame] | 538 | \begin{datadesc}{O_BINARY} |
| 539 | Option for the \var{flag} argument to the \function{open()} function. |
| 540 | This can be bit-wise OR'd together with those listed above. |
| 541 | Availability: Macintosh, Windows. |
| 542 | % XXX need to check on the availability of this one. |
| 543 | \end{datadesc} |
| 544 | |
Tim Peters | c48a3ca | 2002-01-30 05:49:46 +0000 | [diff] [blame] | 545 | \begin{datadesc}{O_NOINHERIT} |
| 546 | \dataline{O_SHORT_LIVED} |
| 547 | \dataline{O_TEMPORARY} |
| 548 | \dataline{O_RANDOM} |
| 549 | \dataline{O_SEQUENTIAL} |
| 550 | \dataline{O_TEXT} |
| 551 | Options for the \var{flag} argument to the \function{open()} function. |
| 552 | These can be bit-wise OR'd together. |
| 553 | Availability: Windows. |
| 554 | \end{datadesc} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 555 | |
| 556 | \subsection{Files and Directories \label{os-file-dir}} |
| 557 | |
| 558 | \begin{funcdesc}{access}{path, mode} |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 559 | Check read/write/execute permissions for this process or existence of |
| 560 | file \var{path}. \var{mode} should be \constant{F_OK} to test the |
| 561 | existence of \var{path}, or it can be the inclusive OR of one or more |
| 562 | of \constant{R_OK}, \constant{W_OK}, and \constant{X_OK} to test |
| 563 | permissions. Return \code{1} if access is allowed, \code{0} if not. |
| 564 | See the \UNIX{} man page \manpage{access}{2} for more information. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 565 | Availability: \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 566 | \end{funcdesc} |
| 567 | |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 568 | \begin{datadesc}{F_OK} |
| 569 | Value to pass as the \var{mode} parameter of \function{access()} to |
| 570 | test the existence of \var{path}. |
| 571 | \end{datadesc} |
| 572 | |
| 573 | \begin{datadesc}{R_OK} |
| 574 | Value to include in the \var{mode} parameter of \function{access()} |
| 575 | to test the readability of \var{path}. |
| 576 | \end{datadesc} |
| 577 | |
| 578 | \begin{datadesc}{W_OK} |
| 579 | Value to include in the \var{mode} parameter of \function{access()} |
| 580 | to test the writability of \var{path}. |
| 581 | \end{datadesc} |
| 582 | |
| 583 | \begin{datadesc}{X_OK} |
| 584 | Value to include in the \var{mode} parameter of \function{access()} |
| 585 | to determine if \var{path} can be executed. |
| 586 | \end{datadesc} |
| 587 | |
Fred Drake | 6db897c | 1999-07-12 16:49:30 +0000 | [diff] [blame] | 588 | \begin{funcdesc}{chdir}{path} |
| 589 | \index{directory!changing} |
| 590 | Change the current working directory to \var{path}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 591 | Availability: Macintosh, \UNIX, Windows. |
Fred Drake | 6db897c | 1999-07-12 16:49:30 +0000 | [diff] [blame] | 592 | \end{funcdesc} |
| 593 | |
Fred Drake | 1549855 | 2002-04-15 19:41:27 +0000 | [diff] [blame] | 594 | \begin{funcdesc}{fchdir}{fd} |
| 595 | Change the current working directory to the directory represented by |
| 596 | the file descriptor \var{fd}. The descriptor must refer to an opened |
| 597 | directory, not an open file. |
| 598 | Availability: \UNIX. |
| 599 | \versionadded{2.3} |
| 600 | \end{funcdesc} |
| 601 | |
Fred Drake | 6db897c | 1999-07-12 16:49:30 +0000 | [diff] [blame] | 602 | \begin{funcdesc}{getcwd}{} |
| 603 | Return a string representing the current working directory. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 604 | Availability: Macintosh, \UNIX, Windows. |
Fred Drake | 6db897c | 1999-07-12 16:49:30 +0000 | [diff] [blame] | 605 | \end{funcdesc} |
| 606 | |
Martin v. Löwis | 244edc8 | 2001-10-04 22:44:26 +0000 | [diff] [blame] | 607 | \begin{funcdesc}{chroot}{path} |
| 608 | Change the root directory of the current process to \var{path}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 609 | Availability: \UNIX. |
Martin v. Löwis | 244edc8 | 2001-10-04 22:44:26 +0000 | [diff] [blame] | 610 | \versionadded{2.2} |
| 611 | \end{funcdesc} |
| 612 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 613 | \begin{funcdesc}{chmod}{path, mode} |
| 614 | Change the mode of \var{path} to the numeric \var{mode}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 615 | Availability: \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 616 | \end{funcdesc} |
| 617 | |
| 618 | \begin{funcdesc}{chown}{path, uid, gid} |
| 619 | Change the owner and group id of \var{path} to the numeric \var{uid} |
| 620 | and \var{gid}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 621 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 622 | \end{funcdesc} |
| 623 | |
| 624 | \begin{funcdesc}{link}{src, dst} |
| 625 | Create a hard link pointing to \var{src} named \var{dst}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 626 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 627 | \end{funcdesc} |
| 628 | |
| 629 | \begin{funcdesc}{listdir}{path} |
| 630 | Return a list containing the names of the entries in the directory. |
| 631 | The list is in arbitrary order. It does not include the special |
| 632 | entries \code{'.'} and \code{'..'} even if they are present in the |
| 633 | directory. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 634 | Availability: Macintosh, \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 635 | \end{funcdesc} |
| 636 | |
| 637 | \begin{funcdesc}{lstat}{path} |
| 638 | Like \function{stat()}, but do not follow symbolic links. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 639 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 640 | \end{funcdesc} |
| 641 | |
| 642 | \begin{funcdesc}{mkfifo}{path\optional{, mode}} |
| 643 | Create a FIFO (a named pipe) named \var{path} with numeric mode |
| 644 | \var{mode}. The default \var{mode} is \code{0666} (octal). The current |
| 645 | umask value is first masked out from the mode. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 646 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 647 | |
| 648 | FIFOs are pipes that can be accessed like regular files. FIFOs exist |
| 649 | until they are deleted (for example with \function{os.unlink()}). |
| 650 | Generally, FIFOs are used as rendezvous between ``client'' and |
| 651 | ``server'' type processes: the server opens the FIFO for reading, and |
| 652 | the client opens it for writing. Note that \function{mkfifo()} |
| 653 | doesn't open the FIFO --- it just creates the rendezvous point. |
| 654 | \end{funcdesc} |
| 655 | |
Martin v. Löwis | 06a83e9 | 2002-04-14 10:19:44 +0000 | [diff] [blame] | 656 | \begin{funcdesc}{mknod}{path\optional{, mode=0600, major, minor}} |
| 657 | Create a filesystem node (file, device special file or named pipe) |
| 658 | named filename. mode specifies both the permissions to use and the |
| 659 | type of node to be created, being combined (bitwise OR) with one of |
| 660 | S_IFREG, S_IFCHR, S_IFBLK, and S_IFIFO (those constants are available |
| 661 | in \module{stat}). For S_IFCHR and S_IFBLK, major and minor define the |
| 662 | newly created device special file, otherwise they are ignored. |
| 663 | |
| 664 | \versionadded{2.3} |
| 665 | \end{funcdesc} |
| 666 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 667 | \begin{funcdesc}{mkdir}{path\optional{, mode}} |
| 668 | Create a directory named \var{path} with numeric mode \var{mode}. |
| 669 | The default \var{mode} is \code{0777} (octal). On some systems, |
| 670 | \var{mode} is ignored. Where it is used, the current umask value is |
| 671 | first masked out. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 672 | Availability: Macintosh, \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 673 | \end{funcdesc} |
| 674 | |
| 675 | \begin{funcdesc}{makedirs}{path\optional{, mode}} |
| 676 | \index{directory!creating} |
| 677 | Recursive directory creation function. Like \function{mkdir()}, |
| 678 | but makes all intermediate-level directories needed to contain the |
| 679 | leaf directory. Throws an \exception{error} exception if the leaf |
| 680 | directory already exists or cannot be created. The default \var{mode} |
Fred Drake | bbf7a40 | 2001-09-28 16:14:18 +0000 | [diff] [blame] | 681 | is \code{0777} (octal). This function does not properly handle UNC |
| 682 | paths (only relevant on Windows systems). |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 683 | \versionadded{1.5.2} |
| 684 | \end{funcdesc} |
| 685 | |
Fred Drake | 88f6ca2 | 1999-12-15 19:39:04 +0000 | [diff] [blame] | 686 | \begin{funcdesc}{pathconf}{path, name} |
Thomas Wouters | f831663 | 2000-07-16 19:01:10 +0000 | [diff] [blame] | 687 | Return system configuration information relevant to a named file. |
Fred Drake | 88f6ca2 | 1999-12-15 19:39:04 +0000 | [diff] [blame] | 688 | \var{name} specifies the configuration value to retrieve; it may be a |
| 689 | string which is the name of a defined system value; these names are |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 690 | 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] | 691 | others). Some platforms define additional names as well. The names |
| 692 | known to the host operating system are given in the |
| 693 | \code{pathconf_names} dictionary. For configuration variables not |
| 694 | included in that mapping, passing an integer for \var{name} is also |
| 695 | accepted. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 696 | Availability: \UNIX. |
Fred Drake | 88f6ca2 | 1999-12-15 19:39:04 +0000 | [diff] [blame] | 697 | |
| 698 | If \var{name} is a string and is not known, \exception{ValueError} is |
| 699 | raised. If a specific value for \var{name} is not supported by the |
| 700 | host system, even if it is included in \code{pathconf_names}, an |
| 701 | \exception{OSError} is raised with \constant{errno.EINVAL} for the |
| 702 | error number. |
| 703 | \end{funcdesc} |
| 704 | |
| 705 | \begin{datadesc}{pathconf_names} |
| 706 | Dictionary mapping names accepted by \function{pathconf()} and |
| 707 | \function{fpathconf()} to the integer values defined for those names |
| 708 | by the host operating system. This can be used to determine the set |
| 709 | of names known to the system. |
| 710 | Availability: \UNIX. |
| 711 | \end{datadesc} |
| 712 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 713 | \begin{funcdesc}{readlink}{path} |
| 714 | Return a string representing the path to which the symbolic link |
Fred Drake | dc9e7e4 | 2001-05-29 18:13:06 +0000 | [diff] [blame] | 715 | points. The result may be either an absolute or relative pathname; if |
| 716 | it is relative, it may be converted to an absolute pathname using |
| 717 | \code{os.path.join(os.path.dirname(\var{path}), \var{result})}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 718 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 719 | \end{funcdesc} |
| 720 | |
| 721 | \begin{funcdesc}{remove}{path} |
Fred Drake | dc9e7e4 | 2001-05-29 18:13:06 +0000 | [diff] [blame] | 722 | Remove the file \var{path}. If \var{path} is a directory, |
| 723 | \exception{OSError} is raised; see \function{rmdir()} below to remove |
| 724 | a directory. This is identical to the \function{unlink()} function |
| 725 | documented below. On Windows, attempting to remove a file that is in |
| 726 | use causes an exception to be raised; on \UNIX, the directory entry is |
| 727 | removed but the storage allocated to the file is not made available |
| 728 | until the original file is no longer in use. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 729 | Availability: Macintosh, \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 730 | \end{funcdesc} |
| 731 | |
| 732 | \begin{funcdesc}{removedirs}{path} |
| 733 | \index{directory!deleting} |
| 734 | Recursive directory removal function. Works like |
| 735 | \function{rmdir()} except that, if the leaf directory is |
| 736 | successfully removed, directories corresponding to rightmost path |
| 737 | segments will be pruned way until either the whole path is consumed or |
| 738 | an error is raised (which is ignored, because it generally means that |
| 739 | a parent directory is not empty). Throws an \exception{error} |
| 740 | exception if the leaf directory could not be successfully removed. |
| 741 | \versionadded{1.5.2} |
| 742 | \end{funcdesc} |
| 743 | |
| 744 | \begin{funcdesc}{rename}{src, dst} |
Fred Drake | dc9e7e4 | 2001-05-29 18:13:06 +0000 | [diff] [blame] | 745 | Rename the file or directory \var{src} to \var{dst}. If \var{dst} is |
| 746 | a directory, \exception{OSError} will be raised. On \UNIX, if |
| 747 | \var{dst} exists and is a file, it will be removed silently if the |
| 748 | user has permission. The operation may fail on some \UNIX{} flavors |
Skip Montanaro | b9d973d | 2001-06-04 15:31:17 +0000 | [diff] [blame] | 749 | if \var{src} and \var{dst} are on different filesystems. If |
Fred Drake | dc9e7e4 | 2001-05-29 18:13:06 +0000 | [diff] [blame] | 750 | successful, the renaming will be an atomic operation (this is a |
| 751 | \POSIX{} requirement). On Windows, if \var{dst} already exists, |
| 752 | \exception{OSError} will be raised even if it is a file; there may be |
| 753 | no way to implement an atomic rename when \var{dst} names an existing |
| 754 | file. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 755 | Availability: Macintosh, \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 756 | \end{funcdesc} |
| 757 | |
| 758 | \begin{funcdesc}{renames}{old, new} |
| 759 | Recursive directory or file renaming function. |
| 760 | Works like \function{rename()}, except creation of any intermediate |
| 761 | directories needed to make the new pathname good is attempted first. |
| 762 | After the rename, directories corresponding to rightmost path segments |
| 763 | of the old name will be pruned away using \function{removedirs()}. |
| 764 | |
| 765 | Note: this function can fail with the new directory structure made if |
| 766 | you lack permissions needed to remove the leaf directory or file. |
| 767 | \versionadded{1.5.2} |
| 768 | \end{funcdesc} |
| 769 | |
| 770 | \begin{funcdesc}{rmdir}{path} |
| 771 | Remove the directory \var{path}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 772 | Availability: Macintosh, \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 773 | \end{funcdesc} |
| 774 | |
| 775 | \begin{funcdesc}{stat}{path} |
| 776 | Perform a \cfunction{stat()} system call on the given path. The |
Fred Drake | 6995bb6 | 2001-11-29 20:48:44 +0000 | [diff] [blame] | 777 | return value is an object whose attributes correspond to the members of |
| 778 | the \ctype{stat} structure, namely: |
| 779 | \member{st_mode} (protection bits), |
| 780 | \member{st_ino} (inode number), |
| 781 | \member{st_dev} (device), |
| 782 | \member{st_nlink} (number of hard links, |
| 783 | \member{st_uid} (user ID of owner), |
| 784 | \member{st_gid} (group ID of owner), |
| 785 | \member{st_size} (size of file, in bytes), |
| 786 | \member{st_atime} (time of most recent access), |
| 787 | \member{st_mtime} (time of most recent content modification), |
| 788 | \member{st_ctime} |
| 789 | (time of most recent content modification or metadata change). |
| 790 | |
| 791 | On some Unix systems (such as Linux), the following attributes may |
| 792 | also be available: |
| 793 | \member{st_blocks} (number of blocks allocated for file), |
| 794 | \member{st_blksize} (filesystem blocksize), |
| 795 | \member{st_rdev} (type of device if an inode device). |
| 796 | |
| 797 | On Mac OS systems, the following attributes may also be available: |
| 798 | \member{st_rsize}, |
| 799 | \member{st_creator}, |
| 800 | \member{st_type}. |
| 801 | |
| 802 | On RISCOS systems, the following attributes are also available: |
| 803 | \member{st_ftype} (file type), |
| 804 | \member{st_attrs} (attributes), |
| 805 | \member{st_obtype} (object type). |
| 806 | |
| 807 | For backward compatibility, the return value of \function{stat()} is |
| 808 | also accessible as a tuple of at least 10 integers giving the most |
| 809 | important (and portable) members of the \ctype{stat} structure, in the |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 810 | order |
Fred Drake | 6995bb6 | 2001-11-29 20:48:44 +0000 | [diff] [blame] | 811 | \member{st_mode}, |
| 812 | \member{st_ino}, |
| 813 | \member{st_dev}, |
| 814 | \member{st_nlink}, |
| 815 | \member{st_uid}, |
| 816 | \member{st_gid}, |
| 817 | \member{st_size}, |
| 818 | \member{st_atime}, |
| 819 | \member{st_mtime}, |
| 820 | \member{st_ctime}. |
Fred Drake | 21c9df7 | 2000-10-14 05:46:11 +0000 | [diff] [blame] | 821 | More items may be added at the end by some implementations. Note that |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 822 | on the Mac OS, the time values are floating point values, like all |
| 823 | time values on the Mac OS. |
Fred Drake | 6995bb6 | 2001-11-29 20:48:44 +0000 | [diff] [blame] | 824 | The standard module \refmodule{stat}\refstmodindex{stat} defines |
| 825 | functions and constants that are useful for extracting information |
| 826 | from a \ctype{stat} structure. |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 827 | (On Windows, some items are filled with dummy values.) |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 828 | Availability: Macintosh, \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 829 | |
Fred Drake | 6995bb6 | 2001-11-29 20:48:44 +0000 | [diff] [blame] | 830 | \versionchanged |
| 831 | [Added access to values as attributes of the returned object]{2.2} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 832 | \end{funcdesc} |
| 833 | |
| 834 | \begin{funcdesc}{statvfs}{path} |
| 835 | Perform a \cfunction{statvfs()} system call on the given path. The |
Fred Drake | 6995bb6 | 2001-11-29 20:48:44 +0000 | [diff] [blame] | 836 | return value is an object whose attributes describe the filesystem on |
| 837 | the given path, and correspond to the members of the |
| 838 | \ctype{statvfs} structure, namely: |
| 839 | \member{f_frsize}, |
| 840 | \member{f_blocks}, |
| 841 | \member{f_bfree}, |
| 842 | \member{f_bavail}, |
| 843 | \member{f_files}, |
| 844 | \member{f_ffree}, |
| 845 | \member{f_favail}, |
| 846 | \member{f_flag}, |
| 847 | \member{f_namemax}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 848 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 849 | |
Fred Drake | 6995bb6 | 2001-11-29 20:48:44 +0000 | [diff] [blame] | 850 | For backward compatibility, the return value is also accessible as a |
| 851 | tuple whose values correspond to the attributes, in the order given above. |
| 852 | The standard module \refmodule{statvfs}\refstmodindex{statvfs} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 853 | defines constants that are useful for extracting information |
Fred Drake | 6995bb6 | 2001-11-29 20:48:44 +0000 | [diff] [blame] | 854 | from a \ctype{statvfs} structure when accessing it as a sequence; this |
| 855 | remains useful when writing code that needs to work with versions of |
| 856 | Python that don't support accessing the fields as attributes. |
| 857 | |
| 858 | \versionchanged |
| 859 | [Added access to values as attributes of the returned object]{2.2} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 860 | \end{funcdesc} |
| 861 | |
| 862 | \begin{funcdesc}{symlink}{src, dst} |
| 863 | Create a symbolic link pointing to \var{src} named \var{dst}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 864 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 865 | \end{funcdesc} |
| 866 | |
Fred Drake | 18f7a45 | 1999-12-09 22:11:43 +0000 | [diff] [blame] | 867 | \begin{funcdesc}{tempnam}{\optional{dir\optional{, prefix}}} |
| 868 | Return a unique path name that is reasonable for creating a temporary |
| 869 | file. This will be an absolute path that names a potential directory |
| 870 | entry in the directory \var{dir} or a common location for temporary |
| 871 | files if \var{dir} is omitted or \code{None}. If given and not |
| 872 | \code{None}, \var{prefix} is used to provide a short prefix to the |
| 873 | filename. Applications are responsible for properly creating and |
| 874 | managing files created using paths returned by \function{tempnam()}; |
| 875 | no automatic cleanup is provided. |
Fred Drake | 938a8d7 | 2001-10-09 18:07:04 +0000 | [diff] [blame] | 876 | \warning{Use of \function{tempnam()} is vulnerable to symlink attacks; |
| 877 | consider using \function{tmpfile()} instead.} |
Fred Drake | efaef13 | 2001-07-17 20:39:18 +0000 | [diff] [blame] | 878 | Availability: \UNIX, Windows. |
Fred Drake | 18f7a45 | 1999-12-09 22:11:43 +0000 | [diff] [blame] | 879 | \end{funcdesc} |
| 880 | |
| 881 | \begin{funcdesc}{tmpnam}{} |
| 882 | Return a unique path name that is reasonable for creating a temporary |
| 883 | file. This will be an absolute path that names a potential directory |
| 884 | entry in a common location for temporary files. Applications are |
| 885 | responsible for properly creating and managing files created using |
| 886 | paths returned by \function{tmpnam()}; no automatic cleanup is |
| 887 | provided. |
Fred Drake | 938a8d7 | 2001-10-09 18:07:04 +0000 | [diff] [blame] | 888 | \warning{Use of \function{tmpnam()} is vulnerable to symlink attacks; |
| 889 | consider using \function{tmpfile()} instead.} |
Fred Drake | efaef13 | 2001-07-17 20:39:18 +0000 | [diff] [blame] | 890 | Availability: \UNIX, Windows. |
Fred Drake | 18f7a45 | 1999-12-09 22:11:43 +0000 | [diff] [blame] | 891 | \end{funcdesc} |
| 892 | |
| 893 | \begin{datadesc}{TMP_MAX} |
| 894 | The maximum number of unique names that \function{tmpnam()} will |
| 895 | generate before reusing names. |
| 896 | \end{datadesc} |
| 897 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 898 | \begin{funcdesc}{unlink}{path} |
| 899 | Remove the file \var{path}. This is the same function as |
| 900 | \function{remove()}; the \function{unlink()} name is its traditional |
| 901 | \UNIX{} name. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 902 | Availability: Macintosh, \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 903 | \end{funcdesc} |
| 904 | |
Barry Warsaw | 93a8eac | 2000-05-01 16:18:22 +0000 | [diff] [blame] | 905 | \begin{funcdesc}{utime}{path, times} |
| 906 | Set the access and modified times of the file specified by \var{path}. |
| 907 | If \var{times} is \code{None}, then the file's access and modified |
| 908 | 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] | 909 | 2-tuple of numbers, of the form \code{(\var{atime}, \var{mtime})} |
| 910 | which is used to set the access and modified times, respectively. |
Fred Drake | 4a15263 | 2000-10-19 05:33:46 +0000 | [diff] [blame] | 911 | \versionchanged[Added support for \code{None} for \var{times}]{2.0} |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 912 | Availability: Macintosh, \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 913 | \end{funcdesc} |
| 914 | |
| 915 | |
| 916 | \subsection{Process Management \label{os-process}} |
| 917 | |
Fred Drake | 18f7a45 | 1999-12-09 22:11:43 +0000 | [diff] [blame] | 918 | These functions may be used to create and manage processes. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 919 | |
Fred Drake | 7be3115 | 2000-09-23 05:22:07 +0000 | [diff] [blame] | 920 | The various \function{exec*()} functions take a list of arguments for |
| 921 | the new program loaded into the process. In each case, the first of |
| 922 | these arguments is passed to the new program as its own name rather |
| 923 | than as an argument a user may have typed on a command line. For the |
| 924 | C programmer, this is the \code{argv[0]} passed to a program's |
| 925 | \cfunction{main()}. For example, \samp{os.execv('/bin/echo', ['foo', |
| 926 | 'bar'])} will only print \samp{bar} on standard output; \samp{foo} |
| 927 | will seem to be ignored. |
| 928 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 929 | |
Fred Drake | 18f7a45 | 1999-12-09 22:11:43 +0000 | [diff] [blame] | 930 | \begin{funcdesc}{abort}{} |
| 931 | Generate a \constant{SIGABRT} signal to the current process. On |
Tim Peters | ab034fa | 2002-02-01 11:27:43 +0000 | [diff] [blame] | 932 | \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] | 933 | process immediately returns an exit code of \code{3}. Be aware that |
| 934 | programs which use \function{signal.signal()} to register a handler |
| 935 | for \constant{SIGABRT} will behave differently. |
| 936 | Availability: \UNIX, Windows. |
| 937 | \end{funcdesc} |
| 938 | |
Fred Drake | db7287c | 2001-10-18 18:58:30 +0000 | [diff] [blame] | 939 | \begin{funcdesc}{execl}{path, arg0, arg1, \moreargs} |
| 940 | \funcline{execle}{path, arg0, arg1, \moreargs, env} |
| 941 | \funcline{execlp}{file, arg0, arg1, \moreargs} |
| 942 | \funcline{execlpe}{file, arg0, arg1, \moreargs, env} |
| 943 | \funcline{execv}{path, args} |
| 944 | \funcline{execve}{path, args, env} |
| 945 | \funcline{execvp}{file, args} |
| 946 | \funcline{execvpe}{file, args, env} |
| 947 | These functions all execute a new program, replacing the current |
| 948 | process; they do not return. On \UNIX, the new executable is loaded |
| 949 | into the current process, and will have the same process ID as the |
| 950 | caller. Errors will be reported as \exception{OSError} exceptions. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 951 | |
Fred Drake | db7287c | 2001-10-18 18:58:30 +0000 | [diff] [blame] | 952 | The \character{l} and \character{v} variants of the |
| 953 | \function{exec*()} functions differ in how command-line arguments are |
| 954 | passed. The \character{l} variants are perhaps the easiest to work |
| 955 | with if the number of parameters is fixed when the code is written; |
| 956 | the individual parameters simply become additional parameters to the |
| 957 | \function{execl*()} functions. The \character{v} variants are good |
| 958 | when the number of parameters is variable, with the arguments being |
| 959 | passed in a list or tuple as the \var{args} parameter. In either |
| 960 | case, the arguments to the child process must start with the name of |
| 961 | the command being run. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 962 | |
Fred Drake | db7287c | 2001-10-18 18:58:30 +0000 | [diff] [blame] | 963 | The variants which include a \character{p} near the end |
| 964 | (\function{execlp()}, \function{execlpe()}, \function{execvp()}, |
| 965 | and \function{execvpe()}) will use the \envvar{PATH} environment |
| 966 | variable to locate the program \var{file}. When the environment is |
| 967 | being replaced (using one of the \function{exec*e()} variants, |
| 968 | discussed in the next paragraph), the |
| 969 | new environment is used as the source of the \envvar{PATH} variable. |
| 970 | The other variants, \function{execl()}, \function{execle()}, |
| 971 | \function{execv()}, and \function{execve()}, will not use the |
| 972 | \envvar{PATH} variable to locate the executable; \var{path} must |
| 973 | contain an appropriate absolute or relative path. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 974 | |
Fred Drake | db7287c | 2001-10-18 18:58:30 +0000 | [diff] [blame] | 975 | For \function{execle()}, \function{execlpe()}, \function{execve()}, |
| 976 | and \function{execvpe()} (note that these all end in \character{e}), |
| 977 | the \var{env} parameter must be a mapping which is used to define the |
| 978 | environment variables for the new process; the \function{execl()}, |
| 979 | \function{execlp()}, \function{execv()}, and \function{execvp()} |
| 980 | all cause the new process to inherit the environment of the current |
| 981 | process. |
| 982 | Availability: \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 983 | \end{funcdesc} |
| 984 | |
| 985 | \begin{funcdesc}{_exit}{n} |
| 986 | Exit to the system with status \var{n}, without calling cleanup |
| 987 | handlers, flushing stdio buffers, etc. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 988 | Availability: \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 989 | |
| 990 | Note: the standard way to exit is \code{sys.exit(\var{n})}. |
| 991 | \function{_exit()} should normally only be used in the child process |
| 992 | after a \function{fork()}. |
| 993 | \end{funcdesc} |
| 994 | |
| 995 | \begin{funcdesc}{fork}{} |
| 996 | Fork a child process. Return \code{0} in the child, the child's |
| 997 | process id in the parent. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 998 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 999 | \end{funcdesc} |
| 1000 | |
Fred Drake | c82634c | 2000-06-28 17:27:48 +0000 | [diff] [blame] | 1001 | \begin{funcdesc}{forkpty}{} |
| 1002 | Fork a child process, using a new pseudo-terminal as the child's |
| 1003 | controlling terminal. Return a pair of \code{(\var{pid}, \var{fd})}, |
| 1004 | 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] | 1005 | 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] | 1006 | of the pseudo-terminal. For a more portable approach, use the |
| 1007 | \refmodule{pty} module. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1008 | Availability: Some flavors of \UNIX. |
Fred Drake | c82634c | 2000-06-28 17:27:48 +0000 | [diff] [blame] | 1009 | \end{funcdesc} |
| 1010 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1011 | \begin{funcdesc}{kill}{pid, sig} |
| 1012 | \index{process!killing} |
| 1013 | \index{process!signalling} |
Fred Drake | 5c79831 | 2001-12-21 03:58:47 +0000 | [diff] [blame] | 1014 | Kill the process \var{pid} with signal \var{sig}. Constants for the |
| 1015 | specific signals available on the host platform are defined in the |
| 1016 | \refmodule{signal} module. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1017 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1018 | \end{funcdesc} |
| 1019 | |
| 1020 | \begin{funcdesc}{nice}{increment} |
| 1021 | Add \var{increment} to the process's ``niceness''. Return the new |
| 1022 | niceness. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1023 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1024 | \end{funcdesc} |
| 1025 | |
| 1026 | \begin{funcdesc}{plock}{op} |
| 1027 | Lock program segments into memory. The value of \var{op} |
| 1028 | (defined in \code{<sys/lock.h>}) determines which segments are locked. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1029 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1030 | \end{funcdesc} |
| 1031 | |
Fred Drake | 046f4d8 | 2001-06-11 15:21:48 +0000 | [diff] [blame] | 1032 | \begin{funcdescni}{popen}{\unspecified} |
| 1033 | \funclineni{popen2}{\unspecified} |
| 1034 | \funclineni{popen3}{\unspecified} |
| 1035 | \funclineni{popen4}{\unspecified} |
| 1036 | Run child processes, returning opened pipes for communications. These |
| 1037 | functions are described in section \ref{os-newstreams}. |
| 1038 | \end{funcdescni} |
| 1039 | |
Fred Drake | 739282d | 2001-08-16 21:21:28 +0000 | [diff] [blame] | 1040 | \begin{funcdesc}{spawnl}{mode, path, \moreargs} |
| 1041 | \funcline{spawnle}{mode, path, \moreargs, env} |
Fred Drake | db7287c | 2001-10-18 18:58:30 +0000 | [diff] [blame] | 1042 | \funcline{spawnlp}{mode, file, \moreargs} |
| 1043 | \funcline{spawnlpe}{mode, file, \moreargs, env} |
Fred Drake | 739282d | 2001-08-16 21:21:28 +0000 | [diff] [blame] | 1044 | \funcline{spawnv}{mode, path, args} |
| 1045 | \funcline{spawnve}{mode, path, args, env} |
Fred Drake | db7287c | 2001-10-18 18:58:30 +0000 | [diff] [blame] | 1046 | \funcline{spawnvp}{mode, file, args} |
| 1047 | \funcline{spawnvpe}{mode, file, args, env} |
Fred Drake | 739282d | 2001-08-16 21:21:28 +0000 | [diff] [blame] | 1048 | Execute the program \var{path} in a new process. If \var{mode} is |
| 1049 | \constant{P_NOWAIT}, this function returns the process ID of the new |
Tim Peters | b404145 | 2001-12-06 23:37:17 +0000 | [diff] [blame] | 1050 | process; if \var{mode} is \constant{P_WAIT}, returns the process's |
Fred Drake | 739282d | 2001-08-16 21:21:28 +0000 | [diff] [blame] | 1051 | exit code if it exits normally, or \code{-\var{signal}}, where |
Fred Drake | 4dfb7a8 | 2002-04-01 23:30:47 +0000 | [diff] [blame] | 1052 | \var{signal} is the signal that killed the process. On Windows, the |
| 1053 | process ID will actually be the process handle, so can be used with |
| 1054 | the \function{waitpid()} function. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1055 | |
Fred Drake | 739282d | 2001-08-16 21:21:28 +0000 | [diff] [blame] | 1056 | The \character{l} and \character{v} variants of the |
| 1057 | \function{spawn*()} functions differ in how command-line arguments are |
| 1058 | passed. The \character{l} variants are perhaps the easiest to work |
| 1059 | with if the number of parameters is fixed when the code is written; |
| 1060 | the individual parameters simply become additional parameters to the |
| 1061 | \function{spawnl*()} functions. The \character{v} variants are good |
| 1062 | when the number of parameters is variable, with the arguments being |
| 1063 | passed in a list or tuple as the \var{args} parameter. In either |
| 1064 | case, the arguments to the child process must start with the name of |
| 1065 | the command being run. |
| 1066 | |
Fred Drake | db7287c | 2001-10-18 18:58:30 +0000 | [diff] [blame] | 1067 | The variants which include a second \character{p} near the end |
| 1068 | (\function{spawnlp()}, \function{spawnlpe()}, \function{spawnvp()}, |
| 1069 | and \function{spawnvpe()}) will use the \envvar{PATH} environment |
| 1070 | variable to locate the program \var{file}. When the environment is |
| 1071 | being replaced (using one of the \function{spawn*e()} variants, |
| 1072 | discussed in the next paragraph), the new environment is used as the |
| 1073 | source of the \envvar{PATH} variable. The other variants, |
| 1074 | \function{spawnl()}, \function{spawnle()}, \function{spawnv()}, and |
| 1075 | \function{spawnve()}, will not use the \envvar{PATH} variable to |
| 1076 | locate the executable; \var{path} must contain an appropriate absolute |
| 1077 | or relative path. |
| 1078 | |
| 1079 | For \function{spawnle()}, \function{spawnlpe()}, \function{spawnve()}, |
| 1080 | and \function{spawnvpe()} (note that these all end in \character{e}), |
| 1081 | the \var{env} parameter must be a mapping which is used to define the |
| 1082 | environment variables for the new process; the \function{spawnl()}, |
| 1083 | \function{spawnlp()}, \function{spawnv()}, and \function{spawnvp()} |
| 1084 | all cause the new process to inherit the environment of the current |
| 1085 | process. |
| 1086 | |
Fred Drake | 739282d | 2001-08-16 21:21:28 +0000 | [diff] [blame] | 1087 | As an example, the following calls to \function{spawnlp()} and |
| 1088 | \function{spawnvpe()} are equivalent: |
| 1089 | |
| 1090 | \begin{verbatim} |
| 1091 | import os |
| 1092 | os.spawnlp(os.P_WAIT, 'cp', 'cp', 'index.html', '/dev/null') |
| 1093 | |
| 1094 | L = ['cp', 'index.html', '/dev/null'] |
| 1095 | os.spawnvpe(os.P_WAIT, 'cp', L, os.environ) |
| 1096 | \end{verbatim} |
| 1097 | |
Fred Drake | 8c8e871 | 2001-12-20 17:24:11 +0000 | [diff] [blame] | 1098 | Availability: \UNIX, Windows. \function{spawnlp()}, |
| 1099 | \function{spawnlpe()}, \function{spawnvp()} and \function{spawnvpe()} |
| 1100 | are not available on Windows. |
Fred Drake | 0b9bc20 | 2001-06-11 18:25:34 +0000 | [diff] [blame] | 1101 | \versionadded{1.6} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1102 | \end{funcdesc} |
| 1103 | |
Fred Drake | 938a8d7 | 2001-10-09 18:07:04 +0000 | [diff] [blame] | 1104 | \begin{datadesc}{P_NOWAIT} |
Fred Drake | 9329e5e | 1999-02-16 19:40:19 +0000 | [diff] [blame] | 1105 | \dataline{P_NOWAITO} |
Fred Drake | 938a8d7 | 2001-10-09 18:07:04 +0000 | [diff] [blame] | 1106 | Possible values for the \var{mode} parameter to the \function{spawn*()} |
| 1107 | family of functions. If either of these values is given, the |
| 1108 | \function{spawn*()} functions will return as soon as the new process |
| 1109 | has been created, with the process ID as the return value. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1110 | Availability: \UNIX, Windows. |
Fred Drake | 0b9bc20 | 2001-06-11 18:25:34 +0000 | [diff] [blame] | 1111 | \versionadded{1.6} |
Fred Drake | 15861b2 | 2000-02-29 05:19:38 +0000 | [diff] [blame] | 1112 | \end{datadesc} |
| 1113 | |
Fred Drake | 938a8d7 | 2001-10-09 18:07:04 +0000 | [diff] [blame] | 1114 | \begin{datadesc}{P_WAIT} |
| 1115 | Possible value for the \var{mode} parameter to the \function{spawn*()} |
| 1116 | family of functions. If this is given as \var{mode}, the |
| 1117 | \function{spawn*()} functions will not return until the new process |
| 1118 | has run to completion and will return the exit code of the process the |
| 1119 | run is successful, or \code{-\var{signal}} if a signal kills the |
| 1120 | process. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1121 | Availability: \UNIX, Windows. |
Fred Drake | 938a8d7 | 2001-10-09 18:07:04 +0000 | [diff] [blame] | 1122 | \versionadded{1.6} |
| 1123 | \end{datadesc} |
| 1124 | |
| 1125 | \begin{datadesc}{P_DETACH} |
| 1126 | \dataline{P_OVERLAY} |
| 1127 | Possible values for the \var{mode} parameter to the |
| 1128 | \function{spawn*()} family of functions. These are less portable than |
| 1129 | those listed above. |
| 1130 | \constant{P_DETACH} is similar to \constant{P_NOWAIT}, but the new |
| 1131 | process is detached from the console of the calling process. |
| 1132 | If \constant{P_OVERLAY} is used, the current process will be replaced; |
| 1133 | the \function{spawn*()} function will not return. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1134 | Availability: Windows. |
Fred Drake | 0b9bc20 | 2001-06-11 18:25:34 +0000 | [diff] [blame] | 1135 | \versionadded{1.6} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1136 | \end{datadesc} |
| 1137 | |
Fred Drake | 4ce4f2e | 2000-09-29 04:15:19 +0000 | [diff] [blame] | 1138 | \begin{funcdesc}{startfile}{path} |
| 1139 | Start a file with its associated application. This acts like |
| 1140 | double-clicking the file in Windows Explorer, or giving the file name |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 1141 | as an argument to the \program{start} command from the interactive |
| 1142 | command shell: the file is opened with whatever application (if any) |
| 1143 | its extension is associated. |
Fred Drake | 4ce4f2e | 2000-09-29 04:15:19 +0000 | [diff] [blame] | 1144 | |
| 1145 | \function{startfile()} returns as soon as the associated application |
| 1146 | is launched. There is no option to wait for the application to close, |
| 1147 | and no way to retrieve the application's exit status. The \var{path} |
| 1148 | parameter is relative to the current directory. If you want to use an |
| 1149 | absolute path, make sure the first character is not a slash |
| 1150 | (\character{/}); the underlying Win32 \cfunction{ShellExecute()} |
Fred Drake | 8a2adcf | 2001-07-23 19:20:56 +0000 | [diff] [blame] | 1151 | 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] | 1152 | function to ensure that the path is properly encoded for Win32. |
| 1153 | Availability: Windows. |
| 1154 | \versionadded{2.0} |
| 1155 | \end{funcdesc} |
| 1156 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1157 | \begin{funcdesc}{system}{command} |
| 1158 | Execute the command (a string) in a subshell. This is implemented by |
| 1159 | calling the Standard C function \cfunction{system()}, and has the |
Fred Drake | ec6baaf | 1999-04-21 18:13:31 +0000 | [diff] [blame] | 1160 | same limitations. Changes to \code{posix.environ}, \code{sys.stdin}, |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1161 | etc.\ are not reflected in the environment of the executed command. |
| 1162 | The return value is the exit status of the process encoded in the |
Fred Drake | 7a62128 | 1999-06-10 15:07:05 +0000 | [diff] [blame] | 1163 | format specified for \function{wait()}, except on Windows 95 and 98, |
Fred Drake | a88ef00 | 1999-06-18 19:11:25 +0000 | [diff] [blame] | 1164 | where it is always \code{0}. Note that \POSIX{} does not specify the |
| 1165 | meaning of the return value of the C \cfunction{system()} function, |
| 1166 | so the return value of the Python function is system-dependent. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1167 | Availability: \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1168 | \end{funcdesc} |
| 1169 | |
| 1170 | \begin{funcdesc}{times}{} |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 1171 | Return a 5-tuple of floating point numbers indicating accumulated |
| 1172 | (processor or other) |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1173 | times, in seconds. The items are: user time, system time, children's |
| 1174 | 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] | 1175 | point in the past, in that order. See the \UNIX{} manual page |
| 1176 | \manpage{times}{2} or the corresponding Windows Platform API |
| 1177 | documentation. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1178 | Availability: \UNIX, Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1179 | \end{funcdesc} |
| 1180 | |
| 1181 | \begin{funcdesc}{wait}{} |
| 1182 | Wait for completion of a child process, and return a tuple containing |
| 1183 | its pid and exit status indication: a 16-bit number, whose low byte is |
| 1184 | the signal number that killed the process, and whose high byte is the |
| 1185 | exit status (if the signal number is zero); the high bit of the low |
| 1186 | byte is set if a core file was produced. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1187 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1188 | \end{funcdesc} |
| 1189 | |
| 1190 | \begin{funcdesc}{waitpid}{pid, options} |
Tim Peters | ab034fa | 2002-02-01 11:27:43 +0000 | [diff] [blame] | 1191 | The details of this function differ on \UNIX and Windows. |
| 1192 | |
| 1193 | On \UNIX: |
Fred Drake | 31e5e37 | 1999-08-13 13:36:33 +0000 | [diff] [blame] | 1194 | Wait for completion of a child process given by process id \var{pid}, |
| 1195 | and return a tuple containing its process id and exit status |
| 1196 | indication (encoded as for \function{wait()}). The semantics of the |
| 1197 | call are affected by the value of the integer \var{options}, which |
| 1198 | should be \code{0} for normal operation. |
Fred Drake | 31e5e37 | 1999-08-13 13:36:33 +0000 | [diff] [blame] | 1199 | |
| 1200 | If \var{pid} is greater than \code{0}, \function{waitpid()} requests |
| 1201 | status information for that specific process. If \var{pid} is |
| 1202 | \code{0}, the request is for the status of any child in the process |
| 1203 | group of the current process. If \var{pid} is \code{-1}, the request |
| 1204 | pertains to any child of the current process. If \var{pid} is less |
| 1205 | than \code{-1}, status is requested for any process in the process |
| 1206 | group \code{-\var{pid}} (the absolute value of \var{pid}). |
Tim Peters | ab034fa | 2002-02-01 11:27:43 +0000 | [diff] [blame] | 1207 | |
| 1208 | On Windows: |
Fred Drake | 4dfb7a8 | 2002-04-01 23:30:47 +0000 | [diff] [blame] | 1209 | Wait for completion of a process given by process handle \var{pid}, |
Tim Peters | ab034fa | 2002-02-01 11:27:43 +0000 | [diff] [blame] | 1210 | and return a tuple containing \var{pid}, |
| 1211 | and its exit status shifted left by 8 bits (shifting makes cross-platform |
| 1212 | use of the function easier). |
| 1213 | A \var{pid} less than or equal to \code{0} has no special meaning on |
| 1214 | Windows, and raises an exception. |
| 1215 | The value of integer \var{options} has no effect. |
| 1216 | \var{pid} can refer to any process whose id is known, not necessarily a |
| 1217 | child process. |
| 1218 | The \function{spawn()} functions called with \constant{P_NOWAIT} |
Fred Drake | 4dfb7a8 | 2002-04-01 23:30:47 +0000 | [diff] [blame] | 1219 | return suitable process handles. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1220 | \end{funcdesc} |
| 1221 | |
| 1222 | \begin{datadesc}{WNOHANG} |
| 1223 | The option for \function{waitpid()} to avoid hanging if no child |
| 1224 | process status is available immediately. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1225 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1226 | \end{datadesc} |
| 1227 | |
Fred Drake | 106c1a0 | 2002-04-23 15:58:02 +0000 | [diff] [blame^] | 1228 | \begin{datadesc}{WCONTINUED} |
| 1229 | This option causes child processes to be reported if they have been |
| 1230 | continued from a job control stop since their status was last |
| 1231 | reported. |
| 1232 | Availability: Some \UNIX{} systems. |
| 1233 | \versionadded{2.3} |
| 1234 | \end{datadesc} |
| 1235 | |
| 1236 | \begin{datadesc}{WUNTRACED} |
| 1237 | This option causes child processes to be reported if they have been |
| 1238 | stopped but their current state has not been reported since they were |
| 1239 | stopped. |
| 1240 | Availability: \UNIX. |
| 1241 | \versionadded{2.3} |
| 1242 | \end{datadesc} |
| 1243 | |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 1244 | The following functions take a process status code as returned by |
| 1245 | \function{system()}, \function{wait()}, or \function{waitpid()} as a |
| 1246 | parameter. They may be used to determine the disposition of a |
| 1247 | process. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1248 | |
Fred Drake | 106c1a0 | 2002-04-23 15:58:02 +0000 | [diff] [blame^] | 1249 | \begin{funcdesc}{WCOREDUMP}{status} |
| 1250 | Returns \code{True} if a core dump was generated for the process, |
| 1251 | otherwise it returns \code{False}. |
| 1252 | Availability: \UNIX. |
| 1253 | \versionadded{2.3} |
| 1254 | \end{funcdesc} |
| 1255 | |
| 1256 | \begin{funcdesc}{WIFCONTINUED}{status} |
| 1257 | Returns \code{True} if the process has been continued from a job |
| 1258 | control stop, otherwise it returns \code{False}. |
| 1259 | Availability: \UNIX. |
| 1260 | \versionadded{2.3} |
| 1261 | \end{funcdesc} |
| 1262 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1263 | \begin{funcdesc}{WIFSTOPPED}{status} |
Fred Drake | 106c1a0 | 2002-04-23 15:58:02 +0000 | [diff] [blame^] | 1264 | Returns \code{True} if the process has been stopped, otherwise it |
| 1265 | returns \code{False}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1266 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1267 | \end{funcdesc} |
| 1268 | |
| 1269 | \begin{funcdesc}{WIFSIGNALED}{status} |
Fred Drake | 106c1a0 | 2002-04-23 15:58:02 +0000 | [diff] [blame^] | 1270 | Returns \code{True} if the process exited due to a signal, otherwise |
| 1271 | it returns \code{False}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1272 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1273 | \end{funcdesc} |
| 1274 | |
| 1275 | \begin{funcdesc}{WIFEXITED}{status} |
Fred Drake | 106c1a0 | 2002-04-23 15:58:02 +0000 | [diff] [blame^] | 1276 | Returns \code{True} if the process exited using the \manpage{exit}{2} |
| 1277 | system call, otherwise it returns \code{False}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1278 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1279 | \end{funcdesc} |
| 1280 | |
| 1281 | \begin{funcdesc}{WEXITSTATUS}{status} |
| 1282 | If \code{WIFEXITED(\var{status})} is true, return the integer |
Tim Peters | ab034fa | 2002-02-01 11:27:43 +0000 | [diff] [blame] | 1283 | parameter to the \manpage{exit}{2} system call. Otherwise, the return |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1284 | value is meaningless. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1285 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1286 | \end{funcdesc} |
| 1287 | |
| 1288 | \begin{funcdesc}{WSTOPSIG}{status} |
Fred Drake | 35c3ffd | 1999-03-04 14:08:10 +0000 | [diff] [blame] | 1289 | Return the signal which caused the process to stop. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1290 | Availability: \UNIX. |
Fred Drake | 35c3ffd | 1999-03-04 14:08:10 +0000 | [diff] [blame] | 1291 | \end{funcdesc} |
| 1292 | |
| 1293 | \begin{funcdesc}{WTERMSIG}{status} |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1294 | Return the signal which caused the process to exit. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1295 | Availability: \UNIX. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1296 | \end{funcdesc} |
| 1297 | |
| 1298 | |
Thomas Wouters | f831663 | 2000-07-16 19:01:10 +0000 | [diff] [blame] | 1299 | \subsection{Miscellaneous System Information \label{os-path}} |
Fred Drake | 88f6ca2 | 1999-12-15 19:39:04 +0000 | [diff] [blame] | 1300 | |
| 1301 | |
| 1302 | \begin{funcdesc}{confstr}{name} |
| 1303 | Return string-valued system configuration values. |
| 1304 | \var{name} specifies the configuration value to retrieve; it may be a |
| 1305 | string which is the name of a defined system value; these names are |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 1306 | specified in a number of standards (\POSIX, \UNIX 95, \UNIX 98, and |
Fred Drake | 88f6ca2 | 1999-12-15 19:39:04 +0000 | [diff] [blame] | 1307 | others). Some platforms define additional names as well. The names |
| 1308 | known to the host operating system are given in the |
| 1309 | \code{confstr_names} dictionary. For configuration variables not |
| 1310 | included in that mapping, passing an integer for \var{name} is also |
| 1311 | accepted. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1312 | Availability: \UNIX. |
Fred Drake | 88f6ca2 | 1999-12-15 19:39:04 +0000 | [diff] [blame] | 1313 | |
| 1314 | If the configuration value specified by \var{name} isn't defined, the |
| 1315 | empty string is returned. |
| 1316 | |
| 1317 | If \var{name} is a string and is not known, \exception{ValueError} is |
| 1318 | raised. If a specific value for \var{name} is not supported by the |
| 1319 | host system, even if it is included in \code{confstr_names}, an |
| 1320 | \exception{OSError} is raised with \constant{errno.EINVAL} for the |
| 1321 | error number. |
| 1322 | \end{funcdesc} |
| 1323 | |
| 1324 | \begin{datadesc}{confstr_names} |
| 1325 | Dictionary mapping names accepted by \function{confstr()} to the |
| 1326 | integer values defined for those names by the host operating system. |
| 1327 | This can be used to determine the set of names known to the system. |
| 1328 | Availability: \UNIX. |
| 1329 | \end{datadesc} |
| 1330 | |
| 1331 | \begin{funcdesc}{sysconf}{name} |
| 1332 | Return integer-valued system configuration values. |
| 1333 | If the configuration value specified by \var{name} isn't defined, |
| 1334 | \code{-1} is returned. The comments regarding the \var{name} |
| 1335 | parameter for \function{confstr()} apply here as well; the dictionary |
| 1336 | that provides information on the known names is given by |
| 1337 | \code{sysconf_names}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 1338 | Availability: \UNIX. |
Fred Drake | 88f6ca2 | 1999-12-15 19:39:04 +0000 | [diff] [blame] | 1339 | \end{funcdesc} |
| 1340 | |
| 1341 | \begin{datadesc}{sysconf_names} |
| 1342 | Dictionary mapping names accepted by \function{sysconf()} to the |
| 1343 | integer values defined for those names by the host operating system. |
| 1344 | This can be used to determine the set of names known to the system. |
| 1345 | Availability: \UNIX. |
| 1346 | \end{datadesc} |
| 1347 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1348 | |
| 1349 | The follow data values are used to support path manipulation |
| 1350 | operations. These are defined for all platforms. |
| 1351 | |
| 1352 | Higher-level operations on pathnames are defined in the |
| 1353 | \refmodule{os.path} module. |
| 1354 | |
| 1355 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 1356 | \begin{datadesc}{curdir} |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 1357 | The constant string used by the operating system to refer to the current |
| 1358 | directory. |
Fred Drake | 907e76b | 2001-07-06 20:30:11 +0000 | [diff] [blame] | 1359 | For example: \code{'.'} for \POSIX{} or \code{':'} for the Macintosh. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 1360 | \end{datadesc} |
| 1361 | |
| 1362 | \begin{datadesc}{pardir} |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 1363 | The constant string used by the operating system to refer to the parent |
| 1364 | directory. |
Fred Drake | 907e76b | 2001-07-06 20:30:11 +0000 | [diff] [blame] | 1365 | For example: \code{'..'} for \POSIX{} or \code{'::'} for the Macintosh. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 1366 | \end{datadesc} |
| 1367 | |
| 1368 | \begin{datadesc}{sep} |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 1369 | The character used by the operating system to separate pathname components, |
Fred Drake | 907e76b | 2001-07-06 20:30:11 +0000 | [diff] [blame] | 1370 | for example, \character{/} for \POSIX{} or \character{:} for the |
| 1371 | Macintosh. Note that knowing this is not sufficient to be able to |
| 1372 | parse or concatenate pathnames --- use \function{os.path.split()} and |
Fred Drake | 1a3c2a0 | 1998-08-06 15:18:23 +0000 | [diff] [blame] | 1373 | \function{os.path.join()} --- but it is occasionally useful. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 1374 | \end{datadesc} |
| 1375 | |
Guido van Rossum | b2afc81 | 1997-08-29 22:37:44 +0000 | [diff] [blame] | 1376 | \begin{datadesc}{altsep} |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 1377 | An alternative character used by the operating system to separate pathname |
| 1378 | components, or \code{None} if only one separator character exists. This is |
| 1379 | set to \character{/} on DOS and Windows systems where \code{sep} is a |
| 1380 | backslash. |
Guido van Rossum | b2afc81 | 1997-08-29 22:37:44 +0000 | [diff] [blame] | 1381 | \end{datadesc} |
| 1382 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 1383 | \begin{datadesc}{pathsep} |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 1384 | The character conventionally used by the operating system to separate |
| 1385 | search patch components (as in \envvar{PATH}), such as \character{:} for |
| 1386 | \POSIX{} or \character{;} for DOS and Windows. |
Guido van Rossum | 9c59ce9 | 1998-06-30 15:54:27 +0000 | [diff] [blame] | 1387 | \end{datadesc} |
| 1388 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 1389 | \begin{datadesc}{defpath} |
Fred Drake | 6995bb6 | 2001-11-29 20:48:44 +0000 | [diff] [blame] | 1390 | The default search path used by \function{exec*p*()} and |
| 1391 | \function{spawn*p*()} if the environment doesn't have a \code{'PATH'} |
| 1392 | key. |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 1393 | \end{datadesc} |
| 1394 | |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1395 | \begin{datadesc}{linesep} |
| 1396 | The string used to separate (or, rather, terminate) lines on the |
Fred Drake | 907e76b | 2001-07-06 20:30:11 +0000 | [diff] [blame] | 1397 | current platform. This may be a single character, such as \code{'\e |
Fred Drake | 6995bb6 | 2001-11-29 20:48:44 +0000 | [diff] [blame] | 1398 | n'} for \POSIX{} or \code{'\e r'} for Mac OS, or multiple characters, |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 1399 | for example, \code{'\e r\e n'} for DOS and Windows. |
Fred Drake | 215fe2f | 1999-02-02 19:02:35 +0000 | [diff] [blame] | 1400 | \end{datadesc} |