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