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