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