blob: 74fca8a2eaa9fa2249ad108d1029a731b26ab4f8 [file] [log] [blame]
Georg Brandl8ec7f652007-08-15 14:28:01 +00001:mod:`os` --- Miscellaneous operating system interfaces
2=======================================================
3
4.. module:: os
5 :synopsis: Miscellaneous operating system interfaces.
6
7
Georg Brandl57fe0f22008-01-12 10:53:29 +00008This module provides a portable way of using operating system dependent
9functionality. If you just want to read or write a file see :func:`open`, if
10you want to manipulate paths, see the :mod:`os.path` module, and if you want to
11read all the lines in all the files on the command line see the :mod:`fileinput`
12module. For creating temporary files and directories see the :mod:`tempfile`
13module, and for high-level file and directory handling see the :mod:`shutil`
14module.
Georg Brandl8ec7f652007-08-15 14:28:01 +000015
Georg Brandl57fe0f22008-01-12 10:53:29 +000016The design of all built-in operating system dependent modules of Python is such
17that as long as the same functionality is available, it uses the same interface;
18for example, the function ``os.stat(path)`` returns stat information about
19*path* in the same format (which happens to have originated with the POSIX
Georg Brandl8ec7f652007-08-15 14:28:01 +000020interface).
21
22Extensions peculiar to a particular operating system are also available through
23the :mod:`os` module, but using them is of course a threat to portability!
24
Georg Brandl57fe0f22008-01-12 10:53:29 +000025.. note::
Georg Brandl8ec7f652007-08-15 14:28:01 +000026
Georg Brandl9af94982008-09-13 17:41:16 +000027 If not separately noted, all functions that claim "Availability: Unix" are
28 supported on Mac OS X, which builds on a Unix core.
29
30.. note::
31
Georg Brandl57fe0f22008-01-12 10:53:29 +000032 All functions in this module raise :exc:`OSError` in the case of invalid or
33 inaccessible file names and paths, or other arguments that have the correct
34 type, but are not accepted by the operating system.
Georg Brandl8ec7f652007-08-15 14:28:01 +000035
Georg Brandl8ec7f652007-08-15 14:28:01 +000036
37.. exception:: error
38
Georg Brandl57fe0f22008-01-12 10:53:29 +000039 An alias for the built-in :exc:`OSError` exception.
Georg Brandl8ec7f652007-08-15 14:28:01 +000040
41
42.. data:: name
43
44 The name of the operating system dependent module imported. The following names
45 have currently been registered: ``'posix'``, ``'nt'``, ``'mac'``, ``'os2'``,
46 ``'ce'``, ``'java'``, ``'riscos'``.
47
48
49.. data:: path
50
51 The corresponding operating system dependent standard module for pathname
Georg Brandl9af94982008-09-13 17:41:16 +000052 operations, such as :mod:`posixpath` or :mod:`ntpath`. Thus, given the proper
Georg Brandl8ec7f652007-08-15 14:28:01 +000053 imports, ``os.path.split(file)`` is equivalent to but more portable than
54 ``posixpath.split(file)``. Note that this is also an importable module: it may
55 be imported directly as :mod:`os.path`.
56
57
58.. _os-procinfo:
59
60Process Parameters
61------------------
62
63These functions and data items provide information and operate on the current
64process and user.
65
66
67.. data:: environ
68
69 A mapping object representing the string environment. For example,
70 ``environ['HOME']`` is the pathname of your home directory (on some platforms),
71 and is equivalent to ``getenv("HOME")`` in C.
72
73 This mapping is captured the first time the :mod:`os` module is imported,
74 typically during Python startup as part of processing :file:`site.py`. Changes
75 to the environment made after this time are not reflected in ``os.environ``,
76 except for changes made by modifying ``os.environ`` directly.
77
78 If the platform supports the :func:`putenv` function, this mapping may be used
79 to modify the environment as well as query the environment. :func:`putenv` will
80 be called automatically when the mapping is modified.
81
82 .. note::
83
84 Calling :func:`putenv` directly does not change ``os.environ``, so it's better
85 to modify ``os.environ``.
86
87 .. note::
88
Georg Brandl9af94982008-09-13 17:41:16 +000089 On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may
90 cause memory leaks. Refer to the system documentation for
91 :cfunc:`putenv`.
Georg Brandl8ec7f652007-08-15 14:28:01 +000092
93 If :func:`putenv` is not provided, a modified copy of this mapping may be
94 passed to the appropriate process-creation functions to cause child processes
95 to use a modified environment.
96
Georg Brandl4a212682007-09-20 17:57:59 +000097 If the platform supports the :func:`unsetenv` function, you can delete items in
Georg Brandl8ec7f652007-08-15 14:28:01 +000098 this mapping to unset environment variables. :func:`unsetenv` will be called
Georg Brandl4a212682007-09-20 17:57:59 +000099 automatically when an item is deleted from ``os.environ``, and when
Georg Brandl1a94ec22007-10-24 21:40:38 +0000100 one of the :meth:`pop` or :meth:`clear` methods is called.
Georg Brandl4a212682007-09-20 17:57:59 +0000101
102 .. versionchanged:: 2.6
Georg Brandl1a94ec22007-10-24 21:40:38 +0000103 Also unset environment variables when calling :meth:`os.environ.clear`
104 and :meth:`os.environ.pop`.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000105
106
107.. function:: chdir(path)
108 fchdir(fd)
109 getcwd()
110 :noindex:
111
112 These functions are described in :ref:`os-file-dir`.
113
114
115.. function:: ctermid()
116
117 Return the filename corresponding to the controlling terminal of the process.
118 Availability: Unix.
119
120
121.. function:: getegid()
122
123 Return the effective group id of the current process. This corresponds to the
Georg Brandlf725b952008-01-05 19:44:22 +0000124 "set id" bit on the file being executed in the current process. Availability:
Georg Brandl8ec7f652007-08-15 14:28:01 +0000125 Unix.
126
127
128.. function:: geteuid()
129
130 .. index:: single: user; effective id
131
Georg Brandlf725b952008-01-05 19:44:22 +0000132 Return the current process's effective user id. Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000133
134
135.. function:: getgid()
136
137 .. index:: single: process; group
138
139 Return the real group id of the current process. Availability: Unix.
140
141
142.. function:: getgroups()
143
144 Return list of supplemental group ids associated with the current process.
145 Availability: Unix.
146
147
148.. function:: getlogin()
149
150 Return the name of the user logged in on the controlling terminal of the
151 process. For most purposes, it is more useful to use the environment variable
152 :envvar:`LOGNAME` to find out who the user is, or
153 ``pwd.getpwuid(os.getuid())[0]`` to get the login name of the currently
Georg Brandlf725b952008-01-05 19:44:22 +0000154 effective user id. Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000155
156
157.. function:: getpgid(pid)
158
159 Return the process group id of the process with process id *pid*. If *pid* is 0,
160 the process group id of the current process is returned. Availability: Unix.
161
162 .. versionadded:: 2.3
163
164
165.. function:: getpgrp()
166
167 .. index:: single: process; group
168
169 Return the id of the current process group. Availability: Unix.
170
171
172.. function:: getpid()
173
174 .. index:: single: process; id
175
176 Return the current process id. Availability: Unix, Windows.
177
178
179.. function:: getppid()
180
181 .. index:: single: process; id of parent
182
183 Return the parent's process id. Availability: Unix.
184
185
186.. function:: getuid()
187
188 .. index:: single: user; id
189
Georg Brandlf725b952008-01-05 19:44:22 +0000190 Return the current process's user id. Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000191
192
193.. function:: getenv(varname[, value])
194
195 Return the value of the environment variable *varname* if it exists, or *value*
196 if it doesn't. *value* defaults to ``None``. Availability: most flavors of
197 Unix, Windows.
198
199
200.. function:: putenv(varname, value)
201
202 .. index:: single: environment variables; setting
203
204 Set the environment variable named *varname* to the string *value*. Such
205 changes to the environment affect subprocesses started with :func:`os.system`,
206 :func:`popen` or :func:`fork` and :func:`execv`. Availability: most flavors of
207 Unix, Windows.
208
209 .. note::
210
Georg Brandl9af94982008-09-13 17:41:16 +0000211 On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may
212 cause memory leaks. Refer to the system documentation for putenv.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000213
214 When :func:`putenv` is supported, assignments to items in ``os.environ`` are
215 automatically translated into corresponding calls to :func:`putenv`; however,
216 calls to :func:`putenv` don't update ``os.environ``, so it is actually
217 preferable to assign to items of ``os.environ``.
218
219
220.. function:: setegid(egid)
221
222 Set the current process's effective group id. Availability: Unix.
223
224
225.. function:: seteuid(euid)
226
227 Set the current process's effective user id. Availability: Unix.
228
229
230.. function:: setgid(gid)
231
232 Set the current process' group id. Availability: Unix.
233
234
235.. function:: setgroups(groups)
236
237 Set the list of supplemental group ids associated with the current process to
238 *groups*. *groups* must be a sequence, and each element must be an integer
Georg Brandlf725b952008-01-05 19:44:22 +0000239 identifying a group. This operation is typically available only to the superuser.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000240 Availability: Unix.
241
242 .. versionadded:: 2.2
243
244
245.. function:: setpgrp()
246
Georg Brandlf725b952008-01-05 19:44:22 +0000247 Call the system call :cfunc:`setpgrp` or :cfunc:`setpgrp(0, 0)` depending on
Georg Brandl8ec7f652007-08-15 14:28:01 +0000248 which version is implemented (if any). See the Unix manual for the semantics.
249 Availability: Unix.
250
251
252.. function:: setpgid(pid, pgrp)
253
Georg Brandlf725b952008-01-05 19:44:22 +0000254 Call the system call :cfunc:`setpgid` to set the process group id of the
Georg Brandl8ec7f652007-08-15 14:28:01 +0000255 process with id *pid* to the process group with id *pgrp*. See the Unix manual
256 for the semantics. Availability: Unix.
257
258
259.. function:: setreuid(ruid, euid)
260
261 Set the current process's real and effective user ids. Availability: Unix.
262
263
264.. function:: setregid(rgid, egid)
265
266 Set the current process's real and effective group ids. Availability: Unix.
267
268
269.. function:: getsid(pid)
270
Georg Brandlf725b952008-01-05 19:44:22 +0000271 Call the system call :cfunc:`getsid`. See the Unix manual for the semantics.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000272 Availability: Unix.
273
274 .. versionadded:: 2.4
275
276
277.. function:: setsid()
278
Georg Brandlf725b952008-01-05 19:44:22 +0000279 Call the system call :cfunc:`setsid`. See the Unix manual for the semantics.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000280 Availability: Unix.
281
282
283.. function:: setuid(uid)
284
285 .. index:: single: user; id, setting
286
Georg Brandlf725b952008-01-05 19:44:22 +0000287 Set the current process's user id. Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000288
Georg Brandl8ec7f652007-08-15 14:28:01 +0000289
Georg Brandlb19be572007-12-29 10:57:00 +0000290.. placed in this section since it relates to errno.... a little weak
Georg Brandl8ec7f652007-08-15 14:28:01 +0000291.. function:: strerror(code)
292
293 Return the error message corresponding to the error code in *code*.
Georg Brandl3fc974f2008-05-11 21:16:37 +0000294 On platforms where :cfunc:`strerror` returns ``NULL`` when given an unknown
295 error number, :exc:`ValueError` is raised. Availability: Unix, Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000296
297
298.. function:: umask(mask)
299
Georg Brandlf725b952008-01-05 19:44:22 +0000300 Set the current numeric umask and return the previous umask. Availability:
Georg Brandl8ec7f652007-08-15 14:28:01 +0000301 Unix, Windows.
302
303
304.. function:: uname()
305
306 .. index::
307 single: gethostname() (in module socket)
308 single: gethostbyaddr() (in module socket)
309
310 Return a 5-tuple containing information identifying the current operating
311 system. The tuple contains 5 strings: ``(sysname, nodename, release, version,
312 machine)``. Some systems truncate the nodename to 8 characters or to the
313 leading component; a better way to get the hostname is
314 :func:`socket.gethostname` or even
315 ``socket.gethostbyaddr(socket.gethostname())``. Availability: recent flavors of
316 Unix.
317
318
319.. function:: unsetenv(varname)
320
321 .. index:: single: environment variables; deleting
322
323 Unset (delete) the environment variable named *varname*. Such changes to the
324 environment affect subprocesses started with :func:`os.system`, :func:`popen` or
325 :func:`fork` and :func:`execv`. Availability: most flavors of Unix, Windows.
326
327 When :func:`unsetenv` is supported, deletion of items in ``os.environ`` is
328 automatically translated into a corresponding call to :func:`unsetenv`; however,
329 calls to :func:`unsetenv` don't update ``os.environ``, so it is actually
330 preferable to delete items of ``os.environ``.
331
332
333.. _os-newstreams:
334
335File Object Creation
336--------------------
337
338These functions create new file objects. (See also :func:`open`.)
339
340
341.. function:: fdopen(fd[, mode[, bufsize]])
342
343 .. index:: single: I/O control; buffering
344
345 Return an open file object connected to the file descriptor *fd*. The *mode*
346 and *bufsize* arguments have the same meaning as the corresponding arguments to
Georg Brandl9af94982008-09-13 17:41:16 +0000347 the built-in :func:`open` function. Availability: Unix, Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000348
349 .. versionchanged:: 2.3
350 When specified, the *mode* argument must now start with one of the letters
351 ``'r'``, ``'w'``, or ``'a'``, otherwise a :exc:`ValueError` is raised.
352
353 .. versionchanged:: 2.5
354 On Unix, when the *mode* argument starts with ``'a'``, the *O_APPEND* flag is
355 set on the file descriptor (which the :cfunc:`fdopen` implementation already
356 does on most platforms).
357
358
359.. function:: popen(command[, mode[, bufsize]])
360
361 Open a pipe to or from *command*. The return value is an open file object
362 connected to the pipe, which can be read or written depending on whether *mode*
363 is ``'r'`` (default) or ``'w'``. The *bufsize* argument has the same meaning as
364 the corresponding argument to the built-in :func:`open` function. The exit
365 status of the command (encoded in the format specified for :func:`wait`) is
366 available as the return value of the :meth:`close` method of the file object,
367 except that when the exit status is zero (termination without errors), ``None``
Georg Brandl9af94982008-09-13 17:41:16 +0000368 is returned. Availability: Unix, Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000369
370 .. deprecated:: 2.6
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000371 This function is obsolete. Use the :mod:`subprocess` module. Check
Georg Brandl0ba92b22008-06-22 09:05:29 +0000372 especially the :ref:`subprocess-replacements` section.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000373
374 .. versionchanged:: 2.0
375 This function worked unreliably under Windows in earlier versions of Python.
376 This was due to the use of the :cfunc:`_popen` function from the libraries
377 provided with Windows. Newer versions of Python do not use the broken
378 implementation from the Windows libraries.
379
380
381.. function:: tmpfile()
382
383 Return a new file object opened in update mode (``w+b``). The file has no
384 directory entries associated with it and will be automatically deleted once
Georg Brandl9af94982008-09-13 17:41:16 +0000385 there are no file descriptors for the file. Availability: Unix,
Georg Brandl8ec7f652007-08-15 14:28:01 +0000386 Windows.
387
388There are a number of different :func:`popen\*` functions that provide slightly
389different ways to create subprocesses.
390
391.. deprecated:: 2.6
392 All of the :func:`popen\*` functions are obsolete. Use the :mod:`subprocess`
393 module.
394
395For each of the :func:`popen\*` variants, if *bufsize* is specified, it
396specifies the buffer size for the I/O pipes. *mode*, if provided, should be the
397string ``'b'`` or ``'t'``; on Windows this is needed to determine whether the
398file objects should be opened in binary or text mode. The default value for
399*mode* is ``'t'``.
400
401Also, for each of these variants, on Unix, *cmd* may be a sequence, in which
402case arguments will be passed directly to the program without shell intervention
403(as with :func:`os.spawnv`). If *cmd* is a string it will be passed to the shell
404(as with :func:`os.system`).
405
406These methods do not make it possible to retrieve the exit status from the child
407processes. The only way to control the input and output streams and also
408retrieve the return codes is to use the :mod:`subprocess` module; these are only
409available on Unix.
410
411For a discussion of possible deadlock conditions related to the use of these
412functions, see :ref:`popen2-flow-control`.
413
414
415.. function:: popen2(cmd[, mode[, bufsize]])
416
Georg Brandlf725b952008-01-05 19:44:22 +0000417 Execute *cmd* as a sub-process and return the file objects ``(child_stdin,
Georg Brandl8ec7f652007-08-15 14:28:01 +0000418 child_stdout)``.
419
420 .. deprecated:: 2.6
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000421 This function is obsolete. Use the :mod:`subprocess` module. Check
Georg Brandl0ba92b22008-06-22 09:05:29 +0000422 especially the :ref:`subprocess-replacements` section.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000423
Georg Brandl9af94982008-09-13 17:41:16 +0000424 Availability: Unix, Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000425
426 .. versionadded:: 2.0
427
428
429.. function:: popen3(cmd[, mode[, bufsize]])
430
Georg Brandlf725b952008-01-05 19:44:22 +0000431 Execute *cmd* as a sub-process and return the file objects ``(child_stdin,
Georg Brandl8ec7f652007-08-15 14:28:01 +0000432 child_stdout, child_stderr)``.
433
434 .. deprecated:: 2.6
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000435 This function is obsolete. Use the :mod:`subprocess` module. Check
Georg Brandl0ba92b22008-06-22 09:05:29 +0000436 especially the :ref:`subprocess-replacements` section.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000437
Georg Brandl9af94982008-09-13 17:41:16 +0000438 Availability: Unix, Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000439
440 .. versionadded:: 2.0
441
442
443.. function:: popen4(cmd[, mode[, bufsize]])
444
Georg Brandlf725b952008-01-05 19:44:22 +0000445 Execute *cmd* as a sub-process and return the file objects ``(child_stdin,
Georg Brandl8ec7f652007-08-15 14:28:01 +0000446 child_stdout_and_stderr)``.
447
448 .. deprecated:: 2.6
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000449 This function is obsolete. Use the :mod:`subprocess` module. Check
Georg Brandl0ba92b22008-06-22 09:05:29 +0000450 especially the :ref:`subprocess-replacements` section.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000451
Georg Brandl9af94982008-09-13 17:41:16 +0000452 Availability: Unix, Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000453
454 .. versionadded:: 2.0
455
456(Note that ``child_stdin, child_stdout, and child_stderr`` are named from the
457point of view of the child process, so *child_stdin* is the child's standard
458input.)
459
460This functionality is also available in the :mod:`popen2` module using functions
461of the same names, but the return values of those functions have a different
462order.
463
464
465.. _os-fd-ops:
466
467File Descriptor Operations
468--------------------------
469
470These functions operate on I/O streams referenced using file descriptors.
471
472File descriptors are small integers corresponding to a file that has been opened
473by the current process. For example, standard input is usually file descriptor
4740, standard output is 1, and standard error is 2. Further files opened by a
475process will then be assigned 3, 4, 5, and so forth. The name "file descriptor"
476is slightly deceptive; on Unix platforms, sockets and pipes are also referenced
477by file descriptors.
478
479
480.. function:: close(fd)
481
Georg Brandl9af94982008-09-13 17:41:16 +0000482 Close file descriptor *fd*. Availability: Unix, Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000483
484 .. note::
485
486 This function is intended for low-level I/O and must be applied to a file
487 descriptor as returned by :func:`open` or :func:`pipe`. To close a "file
488 object" returned by the built-in function :func:`open` or by :func:`popen` or
489 :func:`fdopen`, use its :meth:`close` method.
490
491
Georg Brandl309501a2008-01-19 20:22:13 +0000492.. function:: closerange(fd_low, fd_high)
493
494 Close all file descriptors from *fd_low* (inclusive) to *fd_high* (exclusive),
Georg Brandl9af94982008-09-13 17:41:16 +0000495 ignoring errors. Availability: Unix, Windows. Equivalent to::
Georg Brandl309501a2008-01-19 20:22:13 +0000496
497 for fd in xrange(fd_low, fd_high):
498 try:
499 os.close(fd)
500 except OSError:
501 pass
502
503 .. versionadded:: 2.6
504
505
Georg Brandl8ec7f652007-08-15 14:28:01 +0000506.. function:: dup(fd)
507
Georg Brandl9af94982008-09-13 17:41:16 +0000508 Return a duplicate of file descriptor *fd*. Availability: Unix,
Georg Brandl8ec7f652007-08-15 14:28:01 +0000509 Windows.
510
511
512.. function:: dup2(fd, fd2)
513
514 Duplicate file descriptor *fd* to *fd2*, closing the latter first if necessary.
Georg Brandl9af94982008-09-13 17:41:16 +0000515 Availability: Unix, Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000516
517
Christian Heimes36281872007-11-30 21:11:28 +0000518.. function:: fchmod(fd, mode)
519
520 Change the mode of the file given by *fd* to the numeric *mode*. See the docs
521 for :func:`chmod` for possible values of *mode*. Availability: Unix.
522
Georg Brandl81ddc1a2007-11-30 22:04:45 +0000523 .. versionadded:: 2.6
524
Christian Heimes36281872007-11-30 21:11:28 +0000525
526.. function:: fchown(fd, uid, gid)
527
528 Change the owner and group id of the file given by *fd* to the numeric *uid*
529 and *gid*. To leave one of the ids unchanged, set it to -1.
530 Availability: Unix.
531
Georg Brandl81ddc1a2007-11-30 22:04:45 +0000532 .. versionadded:: 2.6
533
Christian Heimes36281872007-11-30 21:11:28 +0000534
Georg Brandl8ec7f652007-08-15 14:28:01 +0000535.. function:: fdatasync(fd)
536
537 Force write of file with filedescriptor *fd* to disk. Does not force update of
538 metadata. Availability: Unix.
539
540
541.. function:: fpathconf(fd, name)
542
543 Return system configuration information relevant to an open file. *name*
544 specifies the configuration value to retrieve; it may be a string which is the
545 name of a defined system value; these names are specified in a number of
546 standards (POSIX.1, Unix 95, Unix 98, and others). Some platforms define
547 additional names as well. The names known to the host operating system are
548 given in the ``pathconf_names`` dictionary. For configuration variables not
549 included in that mapping, passing an integer for *name* is also accepted.
Georg Brandl9af94982008-09-13 17:41:16 +0000550 Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000551
552 If *name* is a string and is not known, :exc:`ValueError` is raised. If a
553 specific value for *name* is not supported by the host system, even if it is
554 included in ``pathconf_names``, an :exc:`OSError` is raised with
555 :const:`errno.EINVAL` for the error number.
556
557
558.. function:: fstat(fd)
559
560 Return status for file descriptor *fd*, like :func:`stat`. Availability:
Georg Brandl9af94982008-09-13 17:41:16 +0000561 Unix, Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000562
563
564.. function:: fstatvfs(fd)
565
566 Return information about the filesystem containing the file associated with file
567 descriptor *fd*, like :func:`statvfs`. Availability: Unix.
568
569
570.. function:: fsync(fd)
571
572 Force write of file with filedescriptor *fd* to disk. On Unix, this calls the
573 native :cfunc:`fsync` function; on Windows, the MS :cfunc:`_commit` function.
574
575 If you're starting with a Python file object *f*, first do ``f.flush()``, and
576 then do ``os.fsync(f.fileno())``, to ensure that all internal buffers associated
Georg Brandl9af94982008-09-13 17:41:16 +0000577 with *f* are written to disk. Availability: Unix, and Windows
Georg Brandl8ec7f652007-08-15 14:28:01 +0000578 starting in 2.2.3.
579
580
581.. function:: ftruncate(fd, length)
582
583 Truncate the file corresponding to file descriptor *fd*, so that it is at most
Georg Brandl9af94982008-09-13 17:41:16 +0000584 *length* bytes in size. Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000585
586
587.. function:: isatty(fd)
588
589 Return ``True`` if the file descriptor *fd* is open and connected to a
Georg Brandl9af94982008-09-13 17:41:16 +0000590 tty(-like) device, else ``False``. Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000591
592
593.. function:: lseek(fd, pos, how)
594
Georg Brandlf725b952008-01-05 19:44:22 +0000595 Set the current position of file descriptor *fd* to position *pos*, modified
596 by *how*: :const:`SEEK_SET` or ``0`` to set the position relative to the
597 beginning of the file; :const:`SEEK_CUR` or ``1`` to set it relative to the
598 current position; :const:`os.SEEK_END` or ``2`` to set it relative to the end of
Georg Brandl9af94982008-09-13 17:41:16 +0000599 the file. Availability: Unix, Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000600
601
602.. function:: open(file, flags[, mode])
603
604 Open the file *file* and set various flags according to *flags* and possibly its
605 mode according to *mode*. The default *mode* is ``0777`` (octal), and the
606 current umask value is first masked out. Return the file descriptor for the
Georg Brandl9af94982008-09-13 17:41:16 +0000607 newly opened file. Availability: Unix, Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000608
609 For a description of the flag and mode values, see the C run-time documentation;
610 flag constants (like :const:`O_RDONLY` and :const:`O_WRONLY`) are defined in
611 this module too (see below).
612
613 .. note::
614
615 This function is intended for low-level I/O. For normal usage, use the built-in
616 function :func:`open`, which returns a "file object" with :meth:`read` and
617 :meth:`write` methods (and many more). To wrap a file descriptor in a "file
618 object", use :func:`fdopen`.
619
620
621.. function:: openpty()
622
623 .. index:: module: pty
624
625 Open a new pseudo-terminal pair. Return a pair of file descriptors ``(master,
626 slave)`` for the pty and the tty, respectively. For a (slightly) more portable
Georg Brandl9af94982008-09-13 17:41:16 +0000627 approach, use the :mod:`pty` module. Availability: some flavors of
Georg Brandl8ec7f652007-08-15 14:28:01 +0000628 Unix.
629
630
631.. function:: pipe()
632
633 Create a pipe. Return a pair of file descriptors ``(r, w)`` usable for reading
Georg Brandl9af94982008-09-13 17:41:16 +0000634 and writing, respectively. Availability: Unix, Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000635
636
637.. function:: read(fd, n)
638
639 Read at most *n* bytes from file descriptor *fd*. Return a string containing the
640 bytes read. If the end of the file referred to by *fd* has been reached, an
Georg Brandl9af94982008-09-13 17:41:16 +0000641 empty string is returned. Availability: Unix, Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000642
643 .. note::
644
645 This function is intended for low-level I/O and must be applied to a file
646 descriptor as returned by :func:`open` or :func:`pipe`. To read a "file object"
647 returned by the built-in function :func:`open` or by :func:`popen` or
Georg Brandlf725b952008-01-05 19:44:22 +0000648 :func:`fdopen`, or :data:`sys.stdin`, use its :meth:`read` or :meth:`readline`
Georg Brandl8ec7f652007-08-15 14:28:01 +0000649 methods.
650
651
652.. function:: tcgetpgrp(fd)
653
654 Return the process group associated with the terminal given by *fd* (an open
Georg Brandl9af94982008-09-13 17:41:16 +0000655 file descriptor as returned by :func:`open`). Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000656
657
658.. function:: tcsetpgrp(fd, pg)
659
660 Set the process group associated with the terminal given by *fd* (an open file
Georg Brandl9af94982008-09-13 17:41:16 +0000661 descriptor as returned by :func:`open`) to *pg*. Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000662
663
664.. function:: ttyname(fd)
665
666 Return a string which specifies the terminal device associated with
Georg Brandlbb75e4e2007-10-21 10:46:24 +0000667 file descriptor *fd*. If *fd* is not associated with a terminal device, an
Georg Brandl9af94982008-09-13 17:41:16 +0000668 exception is raised. Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000669
670
671.. function:: write(fd, str)
672
673 Write the string *str* to file descriptor *fd*. Return the number of bytes
Georg Brandl9af94982008-09-13 17:41:16 +0000674 actually written. Availability: Unix, Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000675
676 .. note::
677
678 This function is intended for low-level I/O and must be applied to a file
679 descriptor as returned by :func:`open` or :func:`pipe`. To write a "file
680 object" returned by the built-in function :func:`open` or by :func:`popen` or
Georg Brandlf725b952008-01-05 19:44:22 +0000681 :func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its :meth:`write`
Georg Brandl8ec7f652007-08-15 14:28:01 +0000682 method.
683
Georg Brandl0c880bd2008-12-05 08:02:17 +0000684The following constants are options for the *flags* parameter to the
685:func:`open` function. They can be combined using the bitwise OR operator
686``|``. Some of them are not available on all platforms. For descriptions of
Georg Brandle70ff4b2008-12-05 09:25:32 +0000687their availability and use, consult the :manpage:`open(2)` manual page on Unix
688or `the MSDN <http://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>` on Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000689
690
691.. data:: O_RDONLY
692 O_WRONLY
693 O_RDWR
694 O_APPEND
695 O_CREAT
696 O_EXCL
697 O_TRUNC
698
Georg Brandl0c880bd2008-12-05 08:02:17 +0000699 These constants are available on Unix and Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000700
701
702.. data:: O_DSYNC
703 O_RSYNC
704 O_SYNC
705 O_NDELAY
706 O_NONBLOCK
707 O_NOCTTY
708 O_SHLOCK
709 O_EXLOCK
710
Georg Brandl0c880bd2008-12-05 08:02:17 +0000711 These constants are only available on Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000712
713
714.. data:: O_BINARY
Georg Brandlb67da6e2007-11-24 13:56:09 +0000715 O_NOINHERIT
Georg Brandl8ec7f652007-08-15 14:28:01 +0000716 O_SHORT_LIVED
717 O_TEMPORARY
718 O_RANDOM
719 O_SEQUENTIAL
720 O_TEXT
721
Georg Brandl0c880bd2008-12-05 08:02:17 +0000722 These constants are only available on Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000723
724
Georg Brandlae6b9f32008-05-16 13:41:26 +0000725.. data:: O_ASYNC
726 O_DIRECT
Georg Brandlb67da6e2007-11-24 13:56:09 +0000727 O_DIRECTORY
728 O_NOFOLLOW
729 O_NOATIME
730
Georg Brandl0c880bd2008-12-05 08:02:17 +0000731 These constants are GNU extensions and not present if they are not defined by
732 the C library.
Georg Brandlb67da6e2007-11-24 13:56:09 +0000733
734
Georg Brandl8ec7f652007-08-15 14:28:01 +0000735.. data:: SEEK_SET
736 SEEK_CUR
737 SEEK_END
738
739 Parameters to the :func:`lseek` function. Their values are 0, 1, and 2,
Georg Brandl9af94982008-09-13 17:41:16 +0000740 respectively. Availability: Windows, Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000741
742 .. versionadded:: 2.5
743
744
745.. _os-file-dir:
746
747Files and Directories
748---------------------
749
Georg Brandl8ec7f652007-08-15 14:28:01 +0000750.. function:: access(path, mode)
751
752 Use the real uid/gid to test for access to *path*. Note that most operations
753 will use the effective uid/gid, therefore this routine can be used in a
754 suid/sgid environment to test if the invoking user has the specified access to
755 *path*. *mode* should be :const:`F_OK` to test the existence of *path*, or it
756 can be the inclusive OR of one or more of :const:`R_OK`, :const:`W_OK`, and
757 :const:`X_OK` to test permissions. Return :const:`True` if access is allowed,
758 :const:`False` if not. See the Unix man page :manpage:`access(2)` for more
Georg Brandl9af94982008-09-13 17:41:16 +0000759 information. Availability: Unix, Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000760
761 .. note::
762
763 Using :func:`access` to check if a user is authorized to e.g. open a file before
764 actually doing so using :func:`open` creates a security hole, because the user
765 might exploit the short time interval between checking and opening the file to
766 manipulate it.
767
768 .. note::
769
770 I/O operations may fail even when :func:`access` indicates that they would
771 succeed, particularly for operations on network filesystems which may have
772 permissions semantics beyond the usual POSIX permission-bit model.
773
774
775.. data:: F_OK
776
777 Value to pass as the *mode* parameter of :func:`access` to test the existence of
778 *path*.
779
780
781.. data:: R_OK
782
783 Value to include in the *mode* parameter of :func:`access` to test the
784 readability of *path*.
785
786
787.. data:: W_OK
788
789 Value to include in the *mode* parameter of :func:`access` to test the
790 writability of *path*.
791
792
793.. data:: X_OK
794
795 Value to include in the *mode* parameter of :func:`access` to determine if
796 *path* can be executed.
797
798
799.. function:: chdir(path)
800
801 .. index:: single: directory; changing
802
Georg Brandl9af94982008-09-13 17:41:16 +0000803 Change the current working directory to *path*. Availability: Unix,
Georg Brandl8ec7f652007-08-15 14:28:01 +0000804 Windows.
805
806
807.. function:: fchdir(fd)
808
809 Change the current working directory to the directory represented by the file
810 descriptor *fd*. The descriptor must refer to an opened directory, not an open
811 file. Availability: Unix.
812
813 .. versionadded:: 2.3
814
815
816.. function:: getcwd()
817
818 Return a string representing the current working directory. Availability:
Georg Brandl9af94982008-09-13 17:41:16 +0000819 Unix, Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000820
821
822.. function:: getcwdu()
823
824 Return a Unicode object representing the current working directory.
Georg Brandl9af94982008-09-13 17:41:16 +0000825 Availability: Unix, Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000826
827 .. versionadded:: 2.3
828
829
830.. function:: chflags(path, flags)
831
832 Set the flags of *path* to the numeric *flags*. *flags* may take a combination
833 (bitwise OR) of the following values (as defined in the :mod:`stat` module):
834
835 * ``UF_NODUMP``
836 * ``UF_IMMUTABLE``
837 * ``UF_APPEND``
838 * ``UF_OPAQUE``
839 * ``UF_NOUNLINK``
840 * ``SF_ARCHIVED``
841 * ``SF_IMMUTABLE``
842 * ``SF_APPEND``
843 * ``SF_NOUNLINK``
844 * ``SF_SNAPSHOT``
845
Georg Brandl9af94982008-09-13 17:41:16 +0000846 Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000847
848 .. versionadded:: 2.6
849
850
851.. function:: chroot(path)
852
853 Change the root directory of the current process to *path*. Availability:
Georg Brandl9af94982008-09-13 17:41:16 +0000854 Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000855
856 .. versionadded:: 2.2
857
858
859.. function:: chmod(path, mode)
860
861 Change the mode of *path* to the numeric *mode*. *mode* may take one of the
Georg Brandlf725b952008-01-05 19:44:22 +0000862 following values (as defined in the :mod:`stat` module) or bitwise ORed
Georg Brandl8ec7f652007-08-15 14:28:01 +0000863 combinations of them:
864
865
866 * ``stat.S_ISUID``
867 * ``stat.S_ISGID``
868 * ``stat.S_ENFMT``
869 * ``stat.S_ISVTX``
870 * ``stat.S_IREAD``
871 * ``stat.S_IWRITE``
872 * ``stat.S_IEXEC``
873 * ``stat.S_IRWXU``
874 * ``stat.S_IRUSR``
875 * ``stat.S_IWUSR``
876 * ``stat.S_IXUSR``
877 * ``stat.S_IRWXG``
878 * ``stat.S_IRGRP``
879 * ``stat.S_IWGRP``
880 * ``stat.S_IXGRP``
881 * ``stat.S_IRWXO``
882 * ``stat.S_IROTH``
883 * ``stat.S_IWOTH``
884 * ``stat.S_IXOTH``
885
Georg Brandl9af94982008-09-13 17:41:16 +0000886 Availability: Unix, Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000887
888 .. note::
889
890 Although Windows supports :func:`chmod`, you can only set the file's read-only
891 flag with it (via the ``stat.S_IWRITE`` and ``stat.S_IREAD``
892 constants or a corresponding integer value). All other bits are
893 ignored.
894
895
896.. function:: chown(path, uid, gid)
897
898 Change the owner and group id of *path* to the numeric *uid* and *gid*. To leave
Georg Brandl9af94982008-09-13 17:41:16 +0000899 one of the ids unchanged, set it to -1. Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000900
901
902.. function:: lchflags(path, flags)
903
904 Set the flags of *path* to the numeric *flags*, like :func:`chflags`, but do not
905 follow symbolic links. Availability: Unix.
906
907 .. versionadded:: 2.6
908
909
Georg Brandl81ddc1a2007-11-30 22:04:45 +0000910.. function:: lchmod(path, mode)
911
912 Change the mode of *path* to the numeric *mode*. If path is a symlink, this
913 affects the symlink rather than the target. See the docs for :func:`chmod`
914 for possible values of *mode*. Availability: Unix.
915
916 .. versionadded:: 2.6
917
918
Georg Brandl8ec7f652007-08-15 14:28:01 +0000919.. function:: lchown(path, uid, gid)
920
Georg Brandlf725b952008-01-05 19:44:22 +0000921 Change the owner and group id of *path* to the numeric *uid* and *gid*. This
Georg Brandl9af94982008-09-13 17:41:16 +0000922 function will not follow symbolic links. Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000923
924 .. versionadded:: 2.3
925
926
927.. function:: link(src, dst)
928
Georg Brandl9af94982008-09-13 17:41:16 +0000929 Create a hard link pointing to *src* named *dst*. Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000930
931
932.. function:: listdir(path)
933
Georg Brandl62342912008-11-24 19:56:47 +0000934 Return a list containing the names of the entries in the directory given by
935 *path*. The list is in arbitrary order. It does not include the special
936 entries ``'.'`` and ``'..'`` even if they are present in the
937 directory. Availability: Unix, Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000938
939 .. versionchanged:: 2.3
940 On Windows NT/2k/XP and Unix, if *path* is a Unicode object, the result will be
941 a list of Unicode objects.
942
943
944.. function:: lstat(path)
945
Georg Brandl03b15c62007-11-01 17:19:33 +0000946 Like :func:`stat`, but do not follow symbolic links. This is an alias for
947 :func:`stat` on platforms that do not support symbolic links, such as
948 Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000949
950
951.. function:: mkfifo(path[, mode])
952
953 Create a FIFO (a named pipe) named *path* with numeric mode *mode*. The default
954 *mode* is ``0666`` (octal). The current umask value is first masked out from
Georg Brandl9af94982008-09-13 17:41:16 +0000955 the mode. Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000956
957 FIFOs are pipes that can be accessed like regular files. FIFOs exist until they
958 are deleted (for example with :func:`os.unlink`). Generally, FIFOs are used as
959 rendezvous between "client" and "server" type processes: the server opens the
960 FIFO for reading, and the client opens it for writing. Note that :func:`mkfifo`
961 doesn't open the FIFO --- it just creates the rendezvous point.
962
963
964.. function:: mknod(filename[, mode=0600, device])
965
966 Create a filesystem node (file, device special file or named pipe) named
967 *filename*. *mode* specifies both the permissions to use and the type of node to
968 be created, being combined (bitwise OR) with one of ``stat.S_IFREG``,
969 ``stat.S_IFCHR``, ``stat.S_IFBLK``,
970 and ``stat.S_IFIFO`` (those constants are available in :mod:`stat`).
971 For ``stat.S_IFCHR`` and
972 ``stat.S_IFBLK``, *device* defines the newly created device special file (probably using
973 :func:`os.makedev`), otherwise it is ignored.
974
975 .. versionadded:: 2.3
976
977
978.. function:: major(device)
979
Georg Brandlf725b952008-01-05 19:44:22 +0000980 Extract the device major number from a raw device number (usually the
Georg Brandl8ec7f652007-08-15 14:28:01 +0000981 :attr:`st_dev` or :attr:`st_rdev` field from :ctype:`stat`).
982
983 .. versionadded:: 2.3
984
985
986.. function:: minor(device)
987
Georg Brandlf725b952008-01-05 19:44:22 +0000988 Extract the device minor number from a raw device number (usually the
Georg Brandl8ec7f652007-08-15 14:28:01 +0000989 :attr:`st_dev` or :attr:`st_rdev` field from :ctype:`stat`).
990
991 .. versionadded:: 2.3
992
993
994.. function:: makedev(major, minor)
995
Georg Brandlf725b952008-01-05 19:44:22 +0000996 Compose a raw device number from the major and minor device numbers.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000997
998 .. versionadded:: 2.3
999
1000
1001.. function:: mkdir(path[, mode])
1002
1003 Create a directory named *path* with numeric mode *mode*. The default *mode* is
1004 ``0777`` (octal). On some systems, *mode* is ignored. Where it is used, the
Georg Brandl9af94982008-09-13 17:41:16 +00001005 current umask value is first masked out. Availability: Unix, Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001006
Mark Summerfieldac3d4292007-11-02 08:24:59 +00001007 It is also possible to create temporary directories; see the
1008 :mod:`tempfile` module's :func:`tempfile.mkdtemp` function.
1009
Georg Brandl8ec7f652007-08-15 14:28:01 +00001010
1011.. function:: makedirs(path[, mode])
1012
1013 .. index::
1014 single: directory; creating
1015 single: UNC paths; and os.makedirs()
1016
1017 Recursive directory creation function. Like :func:`mkdir`, but makes all
1018 intermediate-level directories needed to contain the leaf directory. Throws an
1019 :exc:`error` exception if the leaf directory already exists or cannot be
1020 created. The default *mode* is ``0777`` (octal). On some systems, *mode* is
1021 ignored. Where it is used, the current umask value is first masked out.
1022
1023 .. note::
1024
1025 :func:`makedirs` will become confused if the path elements to create include
Georg Brandlf725b952008-01-05 19:44:22 +00001026 :data:`os.pardir`.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001027
1028 .. versionadded:: 1.5.2
1029
1030 .. versionchanged:: 2.3
1031 This function now handles UNC paths correctly.
1032
1033
1034.. function:: pathconf(path, name)
1035
1036 Return system configuration information relevant to a named file. *name*
1037 specifies the configuration value to retrieve; it may be a string which is the
1038 name of a defined system value; these names are specified in a number of
1039 standards (POSIX.1, Unix 95, Unix 98, and others). Some platforms define
1040 additional names as well. The names known to the host operating system are
1041 given in the ``pathconf_names`` dictionary. For configuration variables not
1042 included in that mapping, passing an integer for *name* is also accepted.
Georg Brandl9af94982008-09-13 17:41:16 +00001043 Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001044
1045 If *name* is a string and is not known, :exc:`ValueError` is raised. If a
1046 specific value for *name* is not supported by the host system, even if it is
1047 included in ``pathconf_names``, an :exc:`OSError` is raised with
1048 :const:`errno.EINVAL` for the error number.
1049
1050
1051.. data:: pathconf_names
1052
1053 Dictionary mapping names accepted by :func:`pathconf` and :func:`fpathconf` to
1054 the integer values defined for those names by the host operating system. This
1055 can be used to determine the set of names known to the system. Availability:
Georg Brandl9af94982008-09-13 17:41:16 +00001056 Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001057
1058
1059.. function:: readlink(path)
1060
1061 Return a string representing the path to which the symbolic link points. The
1062 result may be either an absolute or relative pathname; if it is relative, it may
1063 be converted to an absolute pathname using ``os.path.join(os.path.dirname(path),
1064 result)``.
1065
1066 .. versionchanged:: 2.6
1067 If the *path* is a Unicode object the result will also be a Unicode object.
1068
Georg Brandl9af94982008-09-13 17:41:16 +00001069 Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001070
1071
1072.. function:: remove(path)
1073
1074 Remove the file *path*. If *path* is a directory, :exc:`OSError` is raised; see
1075 :func:`rmdir` below to remove a directory. This is identical to the
1076 :func:`unlink` function documented below. On Windows, attempting to remove a
1077 file that is in use causes an exception to be raised; on Unix, the directory
1078 entry is removed but the storage allocated to the file is not made available
Georg Brandl9af94982008-09-13 17:41:16 +00001079 until the original file is no longer in use. Availability: Unix,
Georg Brandl8ec7f652007-08-15 14:28:01 +00001080 Windows.
1081
1082
1083.. function:: removedirs(path)
1084
1085 .. index:: single: directory; deleting
1086
Georg Brandlf725b952008-01-05 19:44:22 +00001087 Remove directories recursively. Works like :func:`rmdir` except that, if the
Georg Brandl8ec7f652007-08-15 14:28:01 +00001088 leaf directory is successfully removed, :func:`removedirs` tries to
1089 successively remove every parent directory mentioned in *path* until an error
1090 is raised (which is ignored, because it generally means that a parent directory
1091 is not empty). For example, ``os.removedirs('foo/bar/baz')`` will first remove
1092 the directory ``'foo/bar/baz'``, and then remove ``'foo/bar'`` and ``'foo'`` if
1093 they are empty. Raises :exc:`OSError` if the leaf directory could not be
1094 successfully removed.
1095
1096 .. versionadded:: 1.5.2
1097
1098
1099.. function:: rename(src, dst)
1100
1101 Rename the file or directory *src* to *dst*. If *dst* is a directory,
1102 :exc:`OSError` will be raised. On Unix, if *dst* exists and is a file, it will
Georg Brandlf725b952008-01-05 19:44:22 +00001103 be replaced silently if the user has permission. The operation may fail on some
Georg Brandl8ec7f652007-08-15 14:28:01 +00001104 Unix flavors if *src* and *dst* are on different filesystems. If successful,
1105 the renaming will be an atomic operation (this is a POSIX requirement). On
1106 Windows, if *dst* already exists, :exc:`OSError` will be raised even if it is a
1107 file; there may be no way to implement an atomic rename when *dst* names an
Georg Brandl9af94982008-09-13 17:41:16 +00001108 existing file. Availability: Unix, Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001109
1110
1111.. function:: renames(old, new)
1112
1113 Recursive directory or file renaming function. Works like :func:`rename`, except
1114 creation of any intermediate directories needed to make the new pathname good is
1115 attempted first. After the rename, directories corresponding to rightmost path
1116 segments of the old name will be pruned away using :func:`removedirs`.
1117
1118 .. versionadded:: 1.5.2
1119
1120 .. note::
1121
1122 This function can fail with the new directory structure made if you lack
1123 permissions needed to remove the leaf directory or file.
1124
1125
1126.. function:: rmdir(path)
1127
Georg Brandl9af94982008-09-13 17:41:16 +00001128 Remove the directory *path*. Availability: Unix, Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001129
1130
1131.. function:: stat(path)
1132
1133 Perform a :cfunc:`stat` system call on the given path. The return value is an
1134 object whose attributes correspond to the members of the :ctype:`stat`
1135 structure, namely: :attr:`st_mode` (protection bits), :attr:`st_ino` (inode
1136 number), :attr:`st_dev` (device), :attr:`st_nlink` (number of hard links),
Georg Brandlf725b952008-01-05 19:44:22 +00001137 :attr:`st_uid` (user id of owner), :attr:`st_gid` (group id of owner),
Georg Brandl8ec7f652007-08-15 14:28:01 +00001138 :attr:`st_size` (size of file, in bytes), :attr:`st_atime` (time of most recent
1139 access), :attr:`st_mtime` (time of most recent content modification),
1140 :attr:`st_ctime` (platform dependent; time of most recent metadata change on
1141 Unix, or the time of creation on Windows)::
1142
1143 >>> import os
1144 >>> statinfo = os.stat('somefile.txt')
1145 >>> statinfo
1146 (33188, 422511L, 769L, 1, 1032, 100, 926L, 1105022698,1105022732, 1105022732)
1147 >>> statinfo.st_size
1148 926L
1149 >>>
1150
1151 .. versionchanged:: 2.3
Georg Brandlf725b952008-01-05 19:44:22 +00001152 If :func:`stat_float_times` returns ``True``, the time values are floats, measuring
Georg Brandl8ec7f652007-08-15 14:28:01 +00001153 seconds. Fractions of a second may be reported if the system supports that. On
1154 Mac OS, the times are always floats. See :func:`stat_float_times` for further
1155 discussion.
1156
1157 On some Unix systems (such as Linux), the following attributes may also be
1158 available: :attr:`st_blocks` (number of blocks allocated for file),
1159 :attr:`st_blksize` (filesystem blocksize), :attr:`st_rdev` (type of device if an
1160 inode device). :attr:`st_flags` (user defined flags for file).
1161
1162 On other Unix systems (such as FreeBSD), the following attributes may be
1163 available (but may be only filled out if root tries to use them): :attr:`st_gen`
1164 (file generation number), :attr:`st_birthtime` (time of file creation).
1165
1166 On Mac OS systems, the following attributes may also be available:
1167 :attr:`st_rsize`, :attr:`st_creator`, :attr:`st_type`.
1168
1169 On RISCOS systems, the following attributes are also available: :attr:`st_ftype`
1170 (file type), :attr:`st_attrs` (attributes), :attr:`st_obtype` (object type).
1171
1172 .. index:: module: stat
1173
1174 For backward compatibility, the return value of :func:`stat` is also accessible
1175 as a tuple of at least 10 integers giving the most important (and portable)
1176 members of the :ctype:`stat` structure, in the order :attr:`st_mode`,
1177 :attr:`st_ino`, :attr:`st_dev`, :attr:`st_nlink`, :attr:`st_uid`,
1178 :attr:`st_gid`, :attr:`st_size`, :attr:`st_atime`, :attr:`st_mtime`,
1179 :attr:`st_ctime`. More items may be added at the end by some implementations.
1180 The standard module :mod:`stat` defines functions and constants that are useful
1181 for extracting information from a :ctype:`stat` structure. (On Windows, some
1182 items are filled with dummy values.)
1183
1184 .. note::
1185
1186 The exact meaning and resolution of the :attr:`st_atime`, :attr:`st_mtime`, and
1187 :attr:`st_ctime` members depends on the operating system and the file system.
1188 For example, on Windows systems using the FAT or FAT32 file systems,
1189 :attr:`st_mtime` has 2-second resolution, and :attr:`st_atime` has only 1-day
1190 resolution. See your operating system documentation for details.
1191
Georg Brandl9af94982008-09-13 17:41:16 +00001192 Availability: Unix, Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001193
1194 .. versionchanged:: 2.2
1195 Added access to values as attributes of the returned object.
1196
1197 .. versionchanged:: 2.5
Georg Brandlf725b952008-01-05 19:44:22 +00001198 Added :attr:`st_gen` and :attr:`st_birthtime`.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001199
1200
1201.. function:: stat_float_times([newvalue])
1202
1203 Determine whether :class:`stat_result` represents time stamps as float objects.
1204 If *newvalue* is ``True``, future calls to :func:`stat` return floats, if it is
1205 ``False``, future calls return ints. If *newvalue* is omitted, return the
1206 current setting.
1207
1208 For compatibility with older Python versions, accessing :class:`stat_result` as
1209 a tuple always returns integers.
1210
1211 .. versionchanged:: 2.5
1212 Python now returns float values by default. Applications which do not work
1213 correctly with floating point time stamps can use this function to restore the
1214 old behaviour.
1215
1216 The resolution of the timestamps (that is the smallest possible fraction)
1217 depends on the system. Some systems only support second resolution; on these
1218 systems, the fraction will always be zero.
1219
1220 It is recommended that this setting is only changed at program startup time in
1221 the *__main__* module; libraries should never change this setting. If an
1222 application uses a library that works incorrectly if floating point time stamps
1223 are processed, this application should turn the feature off until the library
1224 has been corrected.
1225
1226
1227.. function:: statvfs(path)
1228
1229 Perform a :cfunc:`statvfs` system call on the given path. The return value is
1230 an object whose attributes describe the filesystem on the given path, and
1231 correspond to the members of the :ctype:`statvfs` structure, namely:
1232 :attr:`f_bsize`, :attr:`f_frsize`, :attr:`f_blocks`, :attr:`f_bfree`,
1233 :attr:`f_bavail`, :attr:`f_files`, :attr:`f_ffree`, :attr:`f_favail`,
1234 :attr:`f_flag`, :attr:`f_namemax`. Availability: Unix.
1235
1236 .. index:: module: statvfs
1237
1238 For backward compatibility, the return value is also accessible as a tuple whose
1239 values correspond to the attributes, in the order given above. The standard
1240 module :mod:`statvfs` defines constants that are useful for extracting
1241 information from a :ctype:`statvfs` structure when accessing it as a sequence;
1242 this remains useful when writing code that needs to work with versions of Python
1243 that don't support accessing the fields as attributes.
1244
1245 .. versionchanged:: 2.2
1246 Added access to values as attributes of the returned object.
1247
1248
1249.. function:: symlink(src, dst)
1250
1251 Create a symbolic link pointing to *src* named *dst*. Availability: Unix.
1252
1253
1254.. function:: tempnam([dir[, prefix]])
1255
1256 Return a unique path name that is reasonable for creating a temporary file.
1257 This will be an absolute path that names a potential directory entry in the
1258 directory *dir* or a common location for temporary files if *dir* is omitted or
1259 ``None``. If given and not ``None``, *prefix* is used to provide a short prefix
1260 to the filename. Applications are responsible for properly creating and
1261 managing files created using paths returned by :func:`tempnam`; no automatic
1262 cleanup is provided. On Unix, the environment variable :envvar:`TMPDIR`
Georg Brandlf725b952008-01-05 19:44:22 +00001263 overrides *dir*, while on Windows :envvar:`TMP` is used. The specific
Georg Brandl8ec7f652007-08-15 14:28:01 +00001264 behavior of this function depends on the C library implementation; some aspects
1265 are underspecified in system documentation.
1266
1267 .. warning::
1268
1269 Use of :func:`tempnam` is vulnerable to symlink attacks; consider using
1270 :func:`tmpfile` (section :ref:`os-newstreams`) instead.
1271
Georg Brandl9af94982008-09-13 17:41:16 +00001272 Availability: Unix, Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001273
1274
1275.. function:: tmpnam()
1276
1277 Return a unique path name that is reasonable for creating a temporary file.
1278 This will be an absolute path that names a potential directory entry in a common
1279 location for temporary files. Applications are responsible for properly
1280 creating and managing files created using paths returned by :func:`tmpnam`; no
1281 automatic cleanup is provided.
1282
1283 .. warning::
1284
1285 Use of :func:`tmpnam` is vulnerable to symlink attacks; consider using
1286 :func:`tmpfile` (section :ref:`os-newstreams`) instead.
1287
1288 Availability: Unix, Windows. This function probably shouldn't be used on
1289 Windows, though: Microsoft's implementation of :func:`tmpnam` always creates a
1290 name in the root directory of the current drive, and that's generally a poor
1291 location for a temp file (depending on privileges, you may not even be able to
1292 open a file using this name).
1293
1294
1295.. data:: TMP_MAX
1296
1297 The maximum number of unique names that :func:`tmpnam` will generate before
1298 reusing names.
1299
1300
1301.. function:: unlink(path)
1302
1303 Remove the file *path*. This is the same function as :func:`remove`; the
Georg Brandl9af94982008-09-13 17:41:16 +00001304 :func:`unlink` name is its traditional Unix name. Availability: Unix,
Georg Brandl8ec7f652007-08-15 14:28:01 +00001305 Windows.
1306
1307
1308.. function:: utime(path, times)
1309
Benjamin Peterson5b02ef32008-08-16 03:13:07 +00001310 Set the access and modified times of the file specified by *path*. If *times*
1311 is ``None``, then the file's access and modified times are set to the current
1312 time. (The effect is similar to running the Unix program :program:`touch` on
1313 the path.) Otherwise, *times* must be a 2-tuple of numbers, of the form
1314 ``(atime, mtime)`` which is used to set the access and modified times,
1315 respectively. Whether a directory can be given for *path* depends on whether
1316 the operating system implements directories as files (for example, Windows
1317 does not). Note that the exact times you set here may not be returned by a
1318 subsequent :func:`stat` call, depending on the resolution with which your
1319 operating system records access and modification times; see :func:`stat`.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001320
1321 .. versionchanged:: 2.0
1322 Added support for ``None`` for *times*.
1323
Georg Brandl9af94982008-09-13 17:41:16 +00001324 Availability: Unix, Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001325
1326
1327.. function:: walk(top[, topdown=True [, onerror=None[, followlinks=False]]])
1328
1329 .. index::
1330 single: directory; walking
1331 single: directory; traversal
1332
Georg Brandlf725b952008-01-05 19:44:22 +00001333 Generate the file names in a directory tree by walking the tree
1334 either top-down or bottom-up. For each directory in the tree rooted at directory
Georg Brandl8ec7f652007-08-15 14:28:01 +00001335 *top* (including *top* itself), it yields a 3-tuple ``(dirpath, dirnames,
1336 filenames)``.
1337
1338 *dirpath* is a string, the path to the directory. *dirnames* is a list of the
1339 names of the subdirectories in *dirpath* (excluding ``'.'`` and ``'..'``).
1340 *filenames* is a list of the names of the non-directory files in *dirpath*.
1341 Note that the names in the lists contain no path components. To get a full path
1342 (which begins with *top*) to a file or directory in *dirpath*, do
1343 ``os.path.join(dirpath, name)``.
1344
Georg Brandlf725b952008-01-05 19:44:22 +00001345 If optional argument *topdown* is ``True`` or not specified, the triple for a
Georg Brandl8ec7f652007-08-15 14:28:01 +00001346 directory is generated before the triples for any of its subdirectories
Georg Brandlf725b952008-01-05 19:44:22 +00001347 (directories are generated top-down). If *topdown* is ``False``, the triple for a
Georg Brandl8ec7f652007-08-15 14:28:01 +00001348 directory is generated after the triples for all of its subdirectories
Georg Brandlf725b952008-01-05 19:44:22 +00001349 (directories are generated bottom-up).
Georg Brandl8ec7f652007-08-15 14:28:01 +00001350
Georg Brandlf725b952008-01-05 19:44:22 +00001351 When *topdown* is ``True``, the caller can modify the *dirnames* list in-place
Georg Brandl8ec7f652007-08-15 14:28:01 +00001352 (perhaps using :keyword:`del` or slice assignment), and :func:`walk` will only
1353 recurse into the subdirectories whose names remain in *dirnames*; this can be
1354 used to prune the search, impose a specific order of visiting, or even to inform
1355 :func:`walk` about directories the caller creates or renames before it resumes
Georg Brandlf725b952008-01-05 19:44:22 +00001356 :func:`walk` again. Modifying *dirnames* when *topdown* is ``False`` is
Georg Brandl8ec7f652007-08-15 14:28:01 +00001357 ineffective, because in bottom-up mode the directories in *dirnames* are
1358 generated before *dirpath* itself is generated.
1359
Georg Brandlf725b952008-01-05 19:44:22 +00001360 By default errors from the :func:`listdir` call are ignored. If optional
Georg Brandl8ec7f652007-08-15 14:28:01 +00001361 argument *onerror* is specified, it should be a function; it will be called with
1362 one argument, an :exc:`OSError` instance. It can report the error to continue
1363 with the walk, or raise the exception to abort the walk. Note that the filename
1364 is available as the ``filename`` attribute of the exception object.
1365
1366 By default, :func:`walk` will not walk down into symbolic links that resolve to
Georg Brandlf725b952008-01-05 19:44:22 +00001367 directories. Set *followlinks* to ``True`` to visit directories pointed to by
Georg Brandl8ec7f652007-08-15 14:28:01 +00001368 symlinks, on systems that support them.
1369
1370 .. versionadded:: 2.6
1371 The *followlinks* parameter.
1372
1373 .. note::
1374
Georg Brandlf725b952008-01-05 19:44:22 +00001375 Be aware that setting *followlinks* to ``True`` can lead to infinite recursion if a
Georg Brandl8ec7f652007-08-15 14:28:01 +00001376 link points to a parent directory of itself. :func:`walk` does not keep track of
1377 the directories it visited already.
1378
1379 .. note::
1380
1381 If you pass a relative pathname, don't change the current working directory
1382 between resumptions of :func:`walk`. :func:`walk` never changes the current
1383 directory, and assumes that its caller doesn't either.
1384
1385 This example displays the number of bytes taken by non-directory files in each
1386 directory under the starting directory, except that it doesn't look under any
1387 CVS subdirectory::
1388
1389 import os
1390 from os.path import join, getsize
1391 for root, dirs, files in os.walk('python/Lib/email'):
1392 print root, "consumes",
1393 print sum(getsize(join(root, name)) for name in files),
1394 print "bytes in", len(files), "non-directory files"
1395 if 'CVS' in dirs:
1396 dirs.remove('CVS') # don't visit CVS directories
1397
Georg Brandlf725b952008-01-05 19:44:22 +00001398 In the next example, walking the tree bottom-up is essential: :func:`rmdir`
Georg Brandl8ec7f652007-08-15 14:28:01 +00001399 doesn't allow deleting a directory before the directory is empty::
1400
Georg Brandlf725b952008-01-05 19:44:22 +00001401 # Delete everything reachable from the directory named in "top",
Georg Brandl8ec7f652007-08-15 14:28:01 +00001402 # assuming there are no symbolic links.
1403 # CAUTION: This is dangerous! For example, if top == '/', it
1404 # could delete all your disk files.
1405 import os
1406 for root, dirs, files in os.walk(top, topdown=False):
1407 for name in files:
1408 os.remove(os.path.join(root, name))
1409 for name in dirs:
1410 os.rmdir(os.path.join(root, name))
1411
1412 .. versionadded:: 2.3
1413
1414
1415.. _os-process:
1416
1417Process Management
1418------------------
1419
1420These functions may be used to create and manage processes.
1421
1422The various :func:`exec\*` functions take a list of arguments for the new
1423program loaded into the process. In each case, the first of these arguments is
1424passed to the new program as its own name rather than as an argument a user may
1425have typed on a command line. For the C programmer, this is the ``argv[0]``
1426passed to a program's :cfunc:`main`. For example, ``os.execv('/bin/echo',
1427['foo', 'bar'])`` will only print ``bar`` on standard output; ``foo`` will seem
1428to be ignored.
1429
1430
1431.. function:: abort()
1432
1433 Generate a :const:`SIGABRT` signal to the current process. On Unix, the default
1434 behavior is to produce a core dump; on Windows, the process immediately returns
1435 an exit code of ``3``. Be aware that programs which use :func:`signal.signal`
1436 to register a handler for :const:`SIGABRT` will behave differently.
Georg Brandl9af94982008-09-13 17:41:16 +00001437 Availability: Unix, Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001438
1439
1440.. function:: execl(path, arg0, arg1, ...)
1441 execle(path, arg0, arg1, ..., env)
1442 execlp(file, arg0, arg1, ...)
1443 execlpe(file, arg0, arg1, ..., env)
1444 execv(path, args)
1445 execve(path, args, env)
1446 execvp(file, args)
1447 execvpe(file, args, env)
1448
1449 These functions all execute a new program, replacing the current process; they
1450 do not return. On Unix, the new executable is loaded into the current process,
Georg Brandlf725b952008-01-05 19:44:22 +00001451 and will have the same process id as the caller. Errors will be reported as
Georg Brandlc62ef8b2009-01-03 20:55:06 +00001452 :exc:`OSError` exceptions.
Andrew M. Kuchlingac771662008-09-28 00:15:27 +00001453
1454 The current process is replaced immediately. Open file objects and
1455 descriptors are not flushed, so if there may be data buffered
1456 on these open files, you should flush them using
1457 :func:`sys.stdout.flush` or :func:`os.fsync` before calling an
1458 :func:`exec\*` function.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001459
Georg Brandlf725b952008-01-05 19:44:22 +00001460 The "l" and "v" variants of the :func:`exec\*` functions differ in how
1461 command-line arguments are passed. The "l" variants are perhaps the easiest
Georg Brandl8ec7f652007-08-15 14:28:01 +00001462 to work with if the number of parameters is fixed when the code is written; the
1463 individual parameters simply become additional parameters to the :func:`execl\*`
Georg Brandlf725b952008-01-05 19:44:22 +00001464 functions. The "v" variants are good when the number of parameters is
Georg Brandl8ec7f652007-08-15 14:28:01 +00001465 variable, with the arguments being passed in a list or tuple as the *args*
1466 parameter. In either case, the arguments to the child process should start with
1467 the name of the command being run, but this is not enforced.
1468
Georg Brandlf725b952008-01-05 19:44:22 +00001469 The variants which include a "p" near the end (:func:`execlp`,
Georg Brandl8ec7f652007-08-15 14:28:01 +00001470 :func:`execlpe`, :func:`execvp`, and :func:`execvpe`) will use the
1471 :envvar:`PATH` environment variable to locate the program *file*. When the
1472 environment is being replaced (using one of the :func:`exec\*e` variants,
1473 discussed in the next paragraph), the new environment is used as the source of
1474 the :envvar:`PATH` variable. The other variants, :func:`execl`, :func:`execle`,
1475 :func:`execv`, and :func:`execve`, will not use the :envvar:`PATH` variable to
1476 locate the executable; *path* must contain an appropriate absolute or relative
1477 path.
1478
1479 For :func:`execle`, :func:`execlpe`, :func:`execve`, and :func:`execvpe` (note
Georg Brandlf725b952008-01-05 19:44:22 +00001480 that these all end in "e"), the *env* parameter must be a mapping which is
Georg Brandlfb246c42008-04-19 16:58:28 +00001481 used to define the environment variables for the new process (these are used
1482 instead of the current process' environment); the functions :func:`execl`,
Georg Brandl8ec7f652007-08-15 14:28:01 +00001483 :func:`execlp`, :func:`execv`, and :func:`execvp` all cause the new process to
Georg Brandlc62ef8b2009-01-03 20:55:06 +00001484 inherit the environment of the current process.
Andrew M. Kuchlingac771662008-09-28 00:15:27 +00001485
1486 Availability: Unix, Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001487
1488
1489.. function:: _exit(n)
1490
1491 Exit to the system with status *n*, without calling cleanup handlers, flushing
Georg Brandl9af94982008-09-13 17:41:16 +00001492 stdio buffers, etc. Availability: Unix, Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001493
1494 .. note::
1495
1496 The standard way to exit is ``sys.exit(n)``. :func:`_exit` should normally only
1497 be used in the child process after a :func:`fork`.
1498
Georg Brandlf725b952008-01-05 19:44:22 +00001499The following exit codes are defined and can be used with :func:`_exit`,
Georg Brandl8ec7f652007-08-15 14:28:01 +00001500although they are not required. These are typically used for system programs
1501written in Python, such as a mail server's external command delivery program.
1502
1503.. note::
1504
1505 Some of these may not be available on all Unix platforms, since there is some
1506 variation. These constants are defined where they are defined by the underlying
1507 platform.
1508
1509
1510.. data:: EX_OK
1511
Georg Brandl9af94982008-09-13 17:41:16 +00001512 Exit code that means no error occurred. Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001513
1514 .. versionadded:: 2.3
1515
1516
1517.. data:: EX_USAGE
1518
1519 Exit code that means the command was used incorrectly, such as when the wrong
Georg Brandl9af94982008-09-13 17:41:16 +00001520 number of arguments are given. Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001521
1522 .. versionadded:: 2.3
1523
1524
1525.. data:: EX_DATAERR
1526
Georg Brandl9af94982008-09-13 17:41:16 +00001527 Exit code that means the input data was incorrect. Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001528
1529 .. versionadded:: 2.3
1530
1531
1532.. data:: EX_NOINPUT
1533
1534 Exit code that means an input file did not exist or was not readable.
Georg Brandl9af94982008-09-13 17:41:16 +00001535 Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001536
1537 .. versionadded:: 2.3
1538
1539
1540.. data:: EX_NOUSER
1541
Georg Brandl9af94982008-09-13 17:41:16 +00001542 Exit code that means a specified user did not exist. Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001543
1544 .. versionadded:: 2.3
1545
1546
1547.. data:: EX_NOHOST
1548
Georg Brandl9af94982008-09-13 17:41:16 +00001549 Exit code that means a specified host did not exist. Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001550
1551 .. versionadded:: 2.3
1552
1553
1554.. data:: EX_UNAVAILABLE
1555
1556 Exit code that means that a required service is unavailable. Availability:
Georg Brandl9af94982008-09-13 17:41:16 +00001557 Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001558
1559 .. versionadded:: 2.3
1560
1561
1562.. data:: EX_SOFTWARE
1563
1564 Exit code that means an internal software error was detected. Availability:
Georg Brandl9af94982008-09-13 17:41:16 +00001565 Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001566
1567 .. versionadded:: 2.3
1568
1569
1570.. data:: EX_OSERR
1571
1572 Exit code that means an operating system error was detected, such as the
Georg Brandl9af94982008-09-13 17:41:16 +00001573 inability to fork or create a pipe. Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001574
1575 .. versionadded:: 2.3
1576
1577
1578.. data:: EX_OSFILE
1579
1580 Exit code that means some system file did not exist, could not be opened, or had
Georg Brandl9af94982008-09-13 17:41:16 +00001581 some other kind of error. Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001582
1583 .. versionadded:: 2.3
1584
1585
1586.. data:: EX_CANTCREAT
1587
1588 Exit code that means a user specified output file could not be created.
Georg Brandl9af94982008-09-13 17:41:16 +00001589 Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001590
1591 .. versionadded:: 2.3
1592
1593
1594.. data:: EX_IOERR
1595
1596 Exit code that means that an error occurred while doing I/O on some file.
Georg Brandl9af94982008-09-13 17:41:16 +00001597 Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001598
1599 .. versionadded:: 2.3
1600
1601
1602.. data:: EX_TEMPFAIL
1603
1604 Exit code that means a temporary failure occurred. This indicates something
1605 that may not really be an error, such as a network connection that couldn't be
Georg Brandl9af94982008-09-13 17:41:16 +00001606 made during a retryable operation. Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001607
1608 .. versionadded:: 2.3
1609
1610
1611.. data:: EX_PROTOCOL
1612
1613 Exit code that means that a protocol exchange was illegal, invalid, or not
Georg Brandl9af94982008-09-13 17:41:16 +00001614 understood. Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001615
1616 .. versionadded:: 2.3
1617
1618
1619.. data:: EX_NOPERM
1620
1621 Exit code that means that there were insufficient permissions to perform the
Georg Brandl9af94982008-09-13 17:41:16 +00001622 operation (but not intended for file system problems). Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001623
1624 .. versionadded:: 2.3
1625
1626
1627.. data:: EX_CONFIG
1628
1629 Exit code that means that some kind of configuration error occurred.
Georg Brandl9af94982008-09-13 17:41:16 +00001630 Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001631
1632 .. versionadded:: 2.3
1633
1634
1635.. data:: EX_NOTFOUND
1636
1637 Exit code that means something like "an entry was not found". Availability:
Georg Brandl9af94982008-09-13 17:41:16 +00001638 Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001639
1640 .. versionadded:: 2.3
1641
1642
1643.. function:: fork()
1644
Georg Brandlf725b952008-01-05 19:44:22 +00001645 Fork a child process. Return ``0`` in the child and the child's process id in the
Skip Montanaro75e51682008-03-15 02:32:49 +00001646 parent. If an error occurs :exc:`OSError` is raised.
Gregory P. Smith08067492008-09-30 20:41:13 +00001647
1648 Note that some platforms including FreeBSD <= 6.3, Cygwin and OS/2 EMX have
1649 known issues when using fork() from a thread.
1650
Georg Brandl9af94982008-09-13 17:41:16 +00001651 Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001652
1653
1654.. function:: forkpty()
1655
1656 Fork a child process, using a new pseudo-terminal as the child's controlling
1657 terminal. Return a pair of ``(pid, fd)``, where *pid* is ``0`` in the child, the
1658 new child's process id in the parent, and *fd* is the file descriptor of the
1659 master end of the pseudo-terminal. For a more portable approach, use the
Skip Montanaro75e51682008-03-15 02:32:49 +00001660 :mod:`pty` module. If an error occurs :exc:`OSError` is raised.
Georg Brandl9af94982008-09-13 17:41:16 +00001661 Availability: some flavors of Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001662
1663
1664.. function:: kill(pid, sig)
1665
1666 .. index::
1667 single: process; killing
1668 single: process; signalling
1669
1670 Send signal *sig* to the process *pid*. Constants for the specific signals
1671 available on the host platform are defined in the :mod:`signal` module.
Georg Brandl9af94982008-09-13 17:41:16 +00001672 Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001673
1674
1675.. function:: killpg(pgid, sig)
1676
1677 .. index::
1678 single: process; killing
1679 single: process; signalling
1680
Georg Brandl9af94982008-09-13 17:41:16 +00001681 Send the signal *sig* to the process group *pgid*. Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001682
1683 .. versionadded:: 2.3
1684
1685
1686.. function:: nice(increment)
1687
1688 Add *increment* to the process's "niceness". Return the new niceness.
Georg Brandl9af94982008-09-13 17:41:16 +00001689 Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001690
1691
1692.. function:: plock(op)
1693
1694 Lock program segments into memory. The value of *op* (defined in
Georg Brandl9af94982008-09-13 17:41:16 +00001695 ``<sys/lock.h>``) determines which segments are locked. Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001696
1697
1698.. function:: popen(...)
1699 popen2(...)
1700 popen3(...)
1701 popen4(...)
1702 :noindex:
1703
1704 Run child processes, returning opened pipes for communications. These functions
1705 are described in section :ref:`os-newstreams`.
1706
1707
1708.. function:: spawnl(mode, path, ...)
1709 spawnle(mode, path, ..., env)
1710 spawnlp(mode, file, ...)
1711 spawnlpe(mode, file, ..., env)
1712 spawnv(mode, path, args)
1713 spawnve(mode, path, args, env)
1714 spawnvp(mode, file, args)
1715 spawnvpe(mode, file, args, env)
1716
1717 Execute the program *path* in a new process.
1718
1719 (Note that the :mod:`subprocess` module provides more powerful facilities for
1720 spawning new processes and retrieving their results; using that module is
Georg Brandlc62ef8b2009-01-03 20:55:06 +00001721 preferable to using these functions. Check specially the *Replacing Older
Facundo Batista74a6ba82008-06-21 19:48:19 +00001722 Functions with the subprocess Module* section in that documentation page.)
Georg Brandl8ec7f652007-08-15 14:28:01 +00001723
Georg Brandlf725b952008-01-05 19:44:22 +00001724 If *mode* is :const:`P_NOWAIT`, this function returns the process id of the new
Georg Brandl8ec7f652007-08-15 14:28:01 +00001725 process; if *mode* is :const:`P_WAIT`, returns the process's exit code if it
1726 exits normally, or ``-signal``, where *signal* is the signal that killed the
Georg Brandlf725b952008-01-05 19:44:22 +00001727 process. On Windows, the process id will actually be the process handle, so can
Georg Brandl8ec7f652007-08-15 14:28:01 +00001728 be used with the :func:`waitpid` function.
1729
Georg Brandlf725b952008-01-05 19:44:22 +00001730 The "l" and "v" variants of the :func:`spawn\*` functions differ in how
1731 command-line arguments are passed. The "l" variants are perhaps the easiest
Georg Brandl8ec7f652007-08-15 14:28:01 +00001732 to work with if the number of parameters is fixed when the code is written; the
1733 individual parameters simply become additional parameters to the
Georg Brandlf725b952008-01-05 19:44:22 +00001734 :func:`spawnl\*` functions. The "v" variants are good when the number of
Georg Brandl8ec7f652007-08-15 14:28:01 +00001735 parameters is variable, with the arguments being passed in a list or tuple as
1736 the *args* parameter. In either case, the arguments to the child process must
1737 start with the name of the command being run.
1738
Georg Brandlf725b952008-01-05 19:44:22 +00001739 The variants which include a second "p" near the end (:func:`spawnlp`,
Georg Brandl8ec7f652007-08-15 14:28:01 +00001740 :func:`spawnlpe`, :func:`spawnvp`, and :func:`spawnvpe`) will use the
1741 :envvar:`PATH` environment variable to locate the program *file*. When the
1742 environment is being replaced (using one of the :func:`spawn\*e` variants,
1743 discussed in the next paragraph), the new environment is used as the source of
1744 the :envvar:`PATH` variable. The other variants, :func:`spawnl`,
1745 :func:`spawnle`, :func:`spawnv`, and :func:`spawnve`, will not use the
1746 :envvar:`PATH` variable to locate the executable; *path* must contain an
1747 appropriate absolute or relative path.
1748
1749 For :func:`spawnle`, :func:`spawnlpe`, :func:`spawnve`, and :func:`spawnvpe`
Georg Brandlf725b952008-01-05 19:44:22 +00001750 (note that these all end in "e"), the *env* parameter must be a mapping
Georg Brandlfb246c42008-04-19 16:58:28 +00001751 which is used to define the environment variables for the new process (they are
1752 used instead of the current process' environment); the functions
Georg Brandl8ec7f652007-08-15 14:28:01 +00001753 :func:`spawnl`, :func:`spawnlp`, :func:`spawnv`, and :func:`spawnvp` all cause
1754 the new process to inherit the environment of the current process.
1755
1756 As an example, the following calls to :func:`spawnlp` and :func:`spawnvpe` are
1757 equivalent::
1758
1759 import os
1760 os.spawnlp(os.P_WAIT, 'cp', 'cp', 'index.html', '/dev/null')
1761
1762 L = ['cp', 'index.html', '/dev/null']
1763 os.spawnvpe(os.P_WAIT, 'cp', L, os.environ)
1764
1765 Availability: Unix, Windows. :func:`spawnlp`, :func:`spawnlpe`, :func:`spawnvp`
1766 and :func:`spawnvpe` are not available on Windows.
1767
1768 .. versionadded:: 1.6
1769
1770
1771.. data:: P_NOWAIT
1772 P_NOWAITO
1773
1774 Possible values for the *mode* parameter to the :func:`spawn\*` family of
1775 functions. If either of these values is given, the :func:`spawn\*` functions
Georg Brandlf725b952008-01-05 19:44:22 +00001776 will return as soon as the new process has been created, with the process id as
Georg Brandl9af94982008-09-13 17:41:16 +00001777 the return value. Availability: Unix, Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001778
1779 .. versionadded:: 1.6
1780
1781
1782.. data:: P_WAIT
1783
1784 Possible value for the *mode* parameter to the :func:`spawn\*` family of
1785 functions. If this is given as *mode*, the :func:`spawn\*` functions will not
1786 return until the new process has run to completion and will return the exit code
1787 of the process the run is successful, or ``-signal`` if a signal kills the
Georg Brandl9af94982008-09-13 17:41:16 +00001788 process. Availability: Unix, Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001789
1790 .. versionadded:: 1.6
1791
1792
1793.. data:: P_DETACH
1794 P_OVERLAY
1795
1796 Possible values for the *mode* parameter to the :func:`spawn\*` family of
1797 functions. These are less portable than those listed above. :const:`P_DETACH`
1798 is similar to :const:`P_NOWAIT`, but the new process is detached from the
1799 console of the calling process. If :const:`P_OVERLAY` is used, the current
1800 process will be replaced; the :func:`spawn\*` function will not return.
1801 Availability: Windows.
1802
1803 .. versionadded:: 1.6
1804
1805
1806.. function:: startfile(path[, operation])
1807
1808 Start a file with its associated application.
1809
1810 When *operation* is not specified or ``'open'``, this acts like double-clicking
1811 the file in Windows Explorer, or giving the file name as an argument to the
1812 :program:`start` command from the interactive command shell: the file is opened
1813 with whatever application (if any) its extension is associated.
1814
1815 When another *operation* is given, it must be a "command verb" that specifies
1816 what should be done with the file. Common verbs documented by Microsoft are
1817 ``'print'`` and ``'edit'`` (to be used on files) as well as ``'explore'`` and
1818 ``'find'`` (to be used on directories).
1819
1820 :func:`startfile` returns as soon as the associated application is launched.
1821 There is no option to wait for the application to close, and no way to retrieve
1822 the application's exit status. The *path* parameter is relative to the current
1823 directory. If you want to use an absolute path, make sure the first character
1824 is not a slash (``'/'``); the underlying Win32 :cfunc:`ShellExecute` function
1825 doesn't work if it is. Use the :func:`os.path.normpath` function to ensure that
1826 the path is properly encoded for Win32. Availability: Windows.
1827
1828 .. versionadded:: 2.0
1829
1830 .. versionadded:: 2.5
1831 The *operation* parameter.
1832
1833
1834.. function:: system(command)
1835
1836 Execute the command (a string) in a subshell. This is implemented by calling
1837 the Standard C function :cfunc:`system`, and has the same limitations. Changes
Georg Brandlf725b952008-01-05 19:44:22 +00001838 to :data:`os.environ`, :data:`sys.stdin`, etc. are not reflected in the
1839 environment of the executed command.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001840
1841 On Unix, the return value is the exit status of the process encoded in the
1842 format specified for :func:`wait`. Note that POSIX does not specify the meaning
1843 of the return value of the C :cfunc:`system` function, so the return value of
1844 the Python function is system-dependent.
1845
1846 On Windows, the return value is that returned by the system shell after running
1847 *command*, given by the Windows environment variable :envvar:`COMSPEC`: on
1848 :program:`command.com` systems (Windows 95, 98 and ME) this is always ``0``; on
1849 :program:`cmd.exe` systems (Windows NT, 2000 and XP) this is the exit status of
1850 the command run; on systems using a non-native shell, consult your shell
1851 documentation.
1852
Georg Brandl9af94982008-09-13 17:41:16 +00001853 Availability: Unix, Windows.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001854
1855 The :mod:`subprocess` module provides more powerful facilities for spawning new
1856 processes and retrieving their results; using that module is preferable to using
Georg Brandl0ba92b22008-06-22 09:05:29 +00001857 this function. Use the :mod:`subprocess` module. Check especially the
1858 :ref:`subprocess-replacements` section.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001859
1860
1861.. function:: times()
1862
1863 Return a 5-tuple of floating point numbers indicating accumulated (processor or
1864 other) times, in seconds. The items are: user time, system time, children's
1865 user time, children's system time, and elapsed real time since a fixed point in
1866 the past, in that order. See the Unix manual page :manpage:`times(2)` or the
Georg Brandl9af94982008-09-13 17:41:16 +00001867 corresponding Windows Platform API documentation. Availability: Unix,
Georg Brandl0a40ffb2008-02-13 07:20:22 +00001868 Windows. On Windows, only the first two items are filled, the others are zero.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001869
1870
1871.. function:: wait()
1872
1873 Wait for completion of a child process, and return a tuple containing its pid
1874 and exit status indication: a 16-bit number, whose low byte is the signal number
1875 that killed the process, and whose high byte is the exit status (if the signal
1876 number is zero); the high bit of the low byte is set if a core file was
Georg Brandl9af94982008-09-13 17:41:16 +00001877 produced. Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001878
1879
1880.. function:: waitpid(pid, options)
1881
1882 The details of this function differ on Unix and Windows.
1883
1884 On Unix: Wait for completion of a child process given by process id *pid*, and
1885 return a tuple containing its process id and exit status indication (encoded as
1886 for :func:`wait`). The semantics of the call are affected by the value of the
1887 integer *options*, which should be ``0`` for normal operation.
1888
1889 If *pid* is greater than ``0``, :func:`waitpid` requests status information for
1890 that specific process. If *pid* is ``0``, the request is for the status of any
1891 child in the process group of the current process. If *pid* is ``-1``, the
1892 request pertains to any child of the current process. If *pid* is less than
1893 ``-1``, status is requested for any process in the process group ``-pid`` (the
1894 absolute value of *pid*).
1895
Gregory P. Smith59de7f52008-08-15 23:14:00 +00001896 An :exc:`OSError` is raised with the value of errno when the syscall
1897 returns -1.
1898
Georg Brandl8ec7f652007-08-15 14:28:01 +00001899 On Windows: Wait for completion of a process given by process handle *pid*, and
1900 return a tuple containing *pid*, and its exit status shifted left by 8 bits
1901 (shifting makes cross-platform use of the function easier). A *pid* less than or
1902 equal to ``0`` has no special meaning on Windows, and raises an exception. The
1903 value of integer *options* has no effect. *pid* can refer to any process whose
1904 id is known, not necessarily a child process. The :func:`spawn` functions called
1905 with :const:`P_NOWAIT` return suitable process handles.
1906
1907
1908.. function:: wait3([options])
1909
1910 Similar to :func:`waitpid`, except no process id argument is given and a
1911 3-element tuple containing the child's process id, exit status indication, and
1912 resource usage information is returned. Refer to :mod:`resource`.\
1913 :func:`getrusage` for details on resource usage information. The option
1914 argument is the same as that provided to :func:`waitpid` and :func:`wait4`.
1915 Availability: Unix.
1916
1917 .. versionadded:: 2.5
1918
1919
1920.. function:: wait4(pid, options)
1921
1922 Similar to :func:`waitpid`, except a 3-element tuple, containing the child's
1923 process id, exit status indication, and resource usage information is returned.
1924 Refer to :mod:`resource`.\ :func:`getrusage` for details on resource usage
1925 information. The arguments to :func:`wait4` are the same as those provided to
1926 :func:`waitpid`. Availability: Unix.
1927
1928 .. versionadded:: 2.5
1929
1930
1931.. data:: WNOHANG
1932
1933 The option for :func:`waitpid` to return immediately if no child process status
1934 is available immediately. The function returns ``(0, 0)`` in this case.
Georg Brandl9af94982008-09-13 17:41:16 +00001935 Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001936
1937
1938.. data:: WCONTINUED
1939
1940 This option causes child processes to be reported if they have been continued
1941 from a job control stop since their status was last reported. Availability: Some
1942 Unix systems.
1943
1944 .. versionadded:: 2.3
1945
1946
1947.. data:: WUNTRACED
1948
1949 This option causes child processes to be reported if they have been stopped but
1950 their current state has not been reported since they were stopped. Availability:
Georg Brandl9af94982008-09-13 17:41:16 +00001951 Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001952
1953 .. versionadded:: 2.3
1954
1955The following functions take a process status code as returned by
1956:func:`system`, :func:`wait`, or :func:`waitpid` as a parameter. They may be
1957used to determine the disposition of a process.
1958
1959
1960.. function:: WCOREDUMP(status)
1961
Georg Brandlf725b952008-01-05 19:44:22 +00001962 Return ``True`` if a core dump was generated for the process, otherwise
Georg Brandl9af94982008-09-13 17:41:16 +00001963 return ``False``. Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001964
1965 .. versionadded:: 2.3
1966
1967
1968.. function:: WIFCONTINUED(status)
1969
Georg Brandlf725b952008-01-05 19:44:22 +00001970 Return ``True`` if the process has been continued from a job control stop,
1971 otherwise return ``False``. Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001972
1973 .. versionadded:: 2.3
1974
1975
1976.. function:: WIFSTOPPED(status)
1977
Georg Brandlf725b952008-01-05 19:44:22 +00001978 Return ``True`` if the process has been stopped, otherwise return
Georg Brandl8ec7f652007-08-15 14:28:01 +00001979 ``False``. Availability: Unix.
1980
1981
1982.. function:: WIFSIGNALED(status)
1983
Georg Brandlf725b952008-01-05 19:44:22 +00001984 Return ``True`` if the process exited due to a signal, otherwise return
Georg Brandl9af94982008-09-13 17:41:16 +00001985 ``False``. Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001986
1987
1988.. function:: WIFEXITED(status)
1989
Georg Brandlf725b952008-01-05 19:44:22 +00001990 Return ``True`` if the process exited using the :manpage:`exit(2)` system call,
Georg Brandl9af94982008-09-13 17:41:16 +00001991 otherwise return ``False``. Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001992
1993
1994.. function:: WEXITSTATUS(status)
1995
1996 If ``WIFEXITED(status)`` is true, return the integer parameter to the
1997 :manpage:`exit(2)` system call. Otherwise, the return value is meaningless.
Georg Brandl9af94982008-09-13 17:41:16 +00001998 Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001999
2000
2001.. function:: WSTOPSIG(status)
2002
Georg Brandl9af94982008-09-13 17:41:16 +00002003 Return the signal which caused the process to stop. Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00002004
2005
2006.. function:: WTERMSIG(status)
2007
Georg Brandl9af94982008-09-13 17:41:16 +00002008 Return the signal which caused the process to exit. Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00002009
2010
2011.. _os-path:
2012
2013Miscellaneous System Information
2014--------------------------------
2015
2016
2017.. function:: confstr(name)
2018
2019 Return string-valued system configuration values. *name* specifies the
2020 configuration value to retrieve; it may be a string which is the name of a
2021 defined system value; these names are specified in a number of standards (POSIX,
2022 Unix 95, Unix 98, and others). Some platforms define additional names as well.
2023 The names known to the host operating system are given as the keys of the
2024 ``confstr_names`` dictionary. For configuration variables not included in that
2025 mapping, passing an integer for *name* is also accepted. Availability:
Georg Brandl9af94982008-09-13 17:41:16 +00002026 Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00002027
2028 If the configuration value specified by *name* isn't defined, ``None`` is
2029 returned.
2030
2031 If *name* is a string and is not known, :exc:`ValueError` is raised. If a
2032 specific value for *name* is not supported by the host system, even if it is
2033 included in ``confstr_names``, an :exc:`OSError` is raised with
2034 :const:`errno.EINVAL` for the error number.
2035
2036
2037.. data:: confstr_names
2038
2039 Dictionary mapping names accepted by :func:`confstr` to the integer values
2040 defined for those names by the host operating system. This can be used to
Georg Brandl9af94982008-09-13 17:41:16 +00002041 determine the set of names known to the system. Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00002042
2043
2044.. function:: getloadavg()
2045
Georg Brandl57fe0f22008-01-12 10:53:29 +00002046 Return the number of processes in the system run queue averaged over the last
2047 1, 5, and 15 minutes or raises :exc:`OSError` if the load average was
Georg Brandl6bb7bcf2008-05-30 19:12:13 +00002048 unobtainable. Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00002049
2050 .. versionadded:: 2.3
2051
2052
2053.. function:: sysconf(name)
2054
2055 Return integer-valued system configuration values. If the configuration value
2056 specified by *name* isn't defined, ``-1`` is returned. The comments regarding
2057 the *name* parameter for :func:`confstr` apply here as well; the dictionary that
2058 provides information on the known names is given by ``sysconf_names``.
Georg Brandl9af94982008-09-13 17:41:16 +00002059 Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00002060
2061
2062.. data:: sysconf_names
2063
2064 Dictionary mapping names accepted by :func:`sysconf` to the integer values
2065 defined for those names by the host operating system. This can be used to
Georg Brandl9af94982008-09-13 17:41:16 +00002066 determine the set of names known to the system. Availability: Unix.
Georg Brandl8ec7f652007-08-15 14:28:01 +00002067
Georg Brandlf725b952008-01-05 19:44:22 +00002068The following data values are used to support path manipulation operations. These
Georg Brandl8ec7f652007-08-15 14:28:01 +00002069are defined for all platforms.
2070
2071Higher-level operations on pathnames are defined in the :mod:`os.path` module.
2072
2073
2074.. data:: curdir
2075
2076 The constant string used by the operating system to refer to the current
Georg Brandl9af94982008-09-13 17:41:16 +00002077 directory. This is ``'.'`` for Windows and POSIX. Also available via
2078 :mod:`os.path`.
Georg Brandl8ec7f652007-08-15 14:28:01 +00002079
2080
2081.. data:: pardir
2082
2083 The constant string used by the operating system to refer to the parent
Georg Brandl9af94982008-09-13 17:41:16 +00002084 directory. This is ``'..'`` for Windows and POSIX. Also available via
2085 :mod:`os.path`.
Georg Brandl8ec7f652007-08-15 14:28:01 +00002086
2087
2088.. data:: sep
2089
Georg Brandl9af94982008-09-13 17:41:16 +00002090 The character used by the operating system to separate pathname components.
2091 This is ``'/'`` for POSIX and ``'\\'`` for Windows. Note that knowing this
2092 is not sufficient to be able to parse or concatenate pathnames --- use
Georg Brandl8ec7f652007-08-15 14:28:01 +00002093 :func:`os.path.split` and :func:`os.path.join` --- but it is occasionally
2094 useful. Also available via :mod:`os.path`.
2095
2096
2097.. data:: altsep
2098
2099 An alternative character used by the operating system to separate pathname
2100 components, or ``None`` if only one separator character exists. This is set to
2101 ``'/'`` on Windows systems where ``sep`` is a backslash. Also available via
2102 :mod:`os.path`.
2103
2104
2105.. data:: extsep
2106
2107 The character which separates the base filename from the extension; for example,
2108 the ``'.'`` in :file:`os.py`. Also available via :mod:`os.path`.
2109
2110 .. versionadded:: 2.2
2111
2112
2113.. data:: pathsep
2114
2115 The character conventionally used by the operating system to separate search
2116 path components (as in :envvar:`PATH`), such as ``':'`` for POSIX or ``';'`` for
2117 Windows. Also available via :mod:`os.path`.
2118
2119
2120.. data:: defpath
2121
2122 The default search path used by :func:`exec\*p\*` and :func:`spawn\*p\*` if the
2123 environment doesn't have a ``'PATH'`` key. Also available via :mod:`os.path`.
2124
2125
2126.. data:: linesep
2127
2128 The string used to separate (or, rather, terminate) lines on the current
Georg Brandl9af94982008-09-13 17:41:16 +00002129 platform. This may be a single character, such as ``'\n'`` for POSIX, or
2130 multiple characters, for example, ``'\r\n'`` for Windows. Do not use
2131 *os.linesep* as a line terminator when writing files opened in text mode (the
2132 default); use a single ``'\n'`` instead, on all platforms.
Georg Brandl8ec7f652007-08-15 14:28:01 +00002133
2134
2135.. data:: devnull
2136
Georg Brandl9af94982008-09-13 17:41:16 +00002137 The file path of the null device. For example: ``'/dev/null'`` for POSIX.
2138 Also available via :mod:`os.path`.
Georg Brandl8ec7f652007-08-15 14:28:01 +00002139
2140 .. versionadded:: 2.4
2141
2142
2143.. _os-miscfunc:
2144
2145Miscellaneous Functions
2146-----------------------
2147
2148
2149.. function:: urandom(n)
2150
2151 Return a string of *n* random bytes suitable for cryptographic use.
2152
2153 This function returns random bytes from an OS-specific randomness source. The
2154 returned data should be unpredictable enough for cryptographic applications,
2155 though its exact quality depends on the OS implementation. On a UNIX-like
2156 system this will query /dev/urandom, and on Windows it will use CryptGenRandom.
2157 If a randomness source is not found, :exc:`NotImplementedError` will be raised.
2158
2159 .. versionadded:: 2.4
2160