rest25/library/os.rst => rest262/library/os.rst
n1- 
2:mod:`os` --- Miscellaneous operating system interfaces
3=======================================================
4
5.. module:: os
6   :synopsis: Miscellaneous operating system interfaces.
7
8
n9-This module provides a more portable way of using operating system dependent
n8+This module provides a portable way of using operating system dependent
10-functionality than importing a operating system dependent built-in module like
9+functionality.  If you just want to read or write a file see :func:`open`, if
11-:mod:`posix` or :mod:`nt`.
10+you want to manipulate paths, see the :mod:`os.path` module, and if you want to
11+read all the lines in all the files on the command line see the :mod:`fileinput`
12+module.  For creating temporary files and directories see the :mod:`tempfile`
13+module, and for high-level file and directory handling see the :mod:`shutil`
14+module.
12
n13-This module searches for an operating system dependent built-in module like
14-:mod:`mac` or :mod:`posix` and exports the same functions and data as found
15-there.  The design of all Python's built-in operating system dependent modules
16+The design of all built-in operating system dependent modules of Python is such
16-is such that as long as the same functionality is available, it uses the same
17+that as long as the same functionality is available, it uses the same interface;
17-interface; for example, the function ``os.stat(path)`` returns stat information
18+for example, the function ``os.stat(path)`` returns stat information about
18-about *path* in the same format (which happens to have originated with the POSIX
19+*path* in the same format (which happens to have originated with the POSIX
19interface).
20
21Extensions peculiar to a particular operating system are also available through
22the :mod:`os` module, but using them is of course a threat to portability!
23
n24-Note that after the first time :mod:`os` is imported, there is *no* performance
n25+.. note::
25-penalty in using functions from :mod:`os` instead of directly from the operating
26-system dependent built-in module, so there should be *no* reason not to use
27-:mod:`os`!
28
n29-The :mod:`os` module contains many functions and data values. The items below
n27+   If not separately noted, all functions that claim "Availability: Unix" are
30-and in the following sub-sections are all available directly from the :mod:`os`
28+   supported on Mac OS X, which builds on a Unix core.
31-module.
32
n33-.. % Frank Stajano <fstajano@uk.research.att.com> complained that it
n30+.. note::
34-.. % wasn't clear that the entries described in the subsections were all
31+ 
35-.. % available at the module level (most uses of subsections are
32+   All functions in this module raise :exc:`OSError` in the case of invalid or
36-.. % different); I think this is only a problem for the HTML version,
33+   inaccessible file names and paths, or other arguments that have the correct
37-.. % where the relationship may not be as clear.
34+   type, but are not accepted by the operating system.
38-.. % 
39
40
41.. exception:: error
42
n43-   .. index:: module: errno
n39+   An alias for the built-in :exc:`OSError` exception.
44- 
45-   This exception is raised when a function returns a system-related error (not for
46-   illegal argument types or other incidental errors). This is also known as the
47-   built-in exception :exc:`OSError`.  The accompanying value is a pair containing
48-   the numeric error code from :cdata:`errno` and the corresponding string, as
49-   would be printed by the C function :cfunc:`perror`.  See the module
50-   :mod:`errno`, which contains names for the error codes defined by the underlying
51-   operating system.
52- 
53-   When exceptions are classes, this exception carries two attributes,
54-   :attr:`errno` and :attr:`strerror`.  The first holds the value of the C
55-   :cdata:`errno` variable, and the latter holds the corresponding error message
56-   from :cfunc:`strerror`.  For exceptions that involve a file system path (such as
57-   :func:`chdir` or :func:`unlink`), the exception instance will contain a third
58-   attribute, :attr:`filename`, which is the file name passed to the function.
59
60
61.. data:: name
62
63   The name of the operating system dependent module imported.  The following names
64   have currently been registered: ``'posix'``, ``'nt'``, ``'mac'``, ``'os2'``,
65   ``'ce'``, ``'java'``, ``'riscos'``.
n66- 
67- 
68-.. data:: path
69- 
70-   The corresponding operating system dependent standard module for pathname
71-   operations, such as :mod:`posixpath` or :mod:`macpath`.  Thus, given the proper
72-   imports, ``os.path.split(file)`` is equivalent to but more portable than
73-   ``posixpath.split(file)``.  Note that this is also an importable module: it may
74-   be imported directly as :mod:`os.path`.
75
76
77.. _os-procinfo:
78
79Process Parameters
80------------------
81
82These functions and data items provide information and operate on the current
100
101   .. note::
102
103      Calling :func:`putenv` directly does not change ``os.environ``, so it's better
104      to modify ``os.environ``.
105
106   .. note::
107
n108-      On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may cause
n80+      On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may
109-      memory leaks.  Refer to the system documentation for :cfunc:`putenv`.
81+      cause memory leaks.  Refer to the system documentation for
82+      :cfunc:`putenv`.
110
111   If :func:`putenv` is not provided, a modified copy of this mapping  may be
112   passed to the appropriate process-creation functions to cause  child processes
113   to use a modified environment.
114
n115-   If the platform supports the :func:`unsetenv` function, you can  delete items in
n88+   If the platform supports the :func:`unsetenv` function, you can delete items in
116   this mapping to unset environment variables. :func:`unsetenv` will be called
n117-   automatically when an item is deleted from ``os.environ``.
n90+   automatically when an item is deleted from ``os.environ``, and when
91+   one of the :meth:`pop` or :meth:`clear` methods is called.
92+ 
93+   .. versionchanged:: 2.6
94+      Also unset environment variables when calling :meth:`os.environ.clear`
95+      and :meth:`os.environ.pop`.
118
119
120.. function:: chdir(path)
121              fchdir(fd)
122              getcwd()
123   :noindex:
124
n125-   These functions are described in "Files and Directories" (section
n103+   These functions are described in :ref:`os-file-dir`.
126-   :ref:`os-file-dir`).
127
128
129.. function:: ctermid()
130
131   Return the filename corresponding to the controlling terminal of the process.
132   Availability: Unix.
133
134
135.. function:: getegid()
136
137   Return the effective group id of the current process.  This corresponds to the
n138-   'set id' bit on the file being executed in the current process. Availability:
n115+   "set id" bit on the file being executed in the current process. Availability:
139   Unix.
140
141
142.. function:: geteuid()
143
144   .. index:: single: user; effective id
145
n146-   Return the current process' effective user id. Availability: Unix.
n123+   Return the current process's effective user id. Availability: Unix.
147
148
149.. function:: getgid()
150
151   .. index:: single: process; group
152
153   Return the real group id of the current process. Availability: Unix.
154
160
161
162.. function:: getlogin()
163
164   Return the name of the user logged in on the controlling terminal of the
165   process.  For most purposes, it is more useful to use the environment variable
166   :envvar:`LOGNAME` to find out who the user is, or
167   ``pwd.getpwuid(os.getuid())[0]`` to get the login name of the currently
n168-   effective user ID. Availability: Unix.
n145+   effective user id. Availability: Unix.
169
170
171.. function:: getpgid(pid)
172
173   Return the process group id of the process with process id *pid*. If *pid* is 0,
174   the process group id of the current process is returned. Availability: Unix.
175
176   .. versionadded:: 2.3
196
197   Return the parent's process id. Availability: Unix.
198
199
200.. function:: getuid()
201
202   .. index:: single: user; id
203
n204-   Return the current process' user id. Availability: Unix.
n181+   Return the current process's user id. Availability: Unix.
205
206
207.. function:: getenv(varname[, value])
208
209   Return the value of the environment variable *varname* if it exists, or *value*
210   if it doesn't.  *value* defaults to ``None``. Availability: most flavors of
211   Unix, Windows.
212
217
218   Set the environment variable named *varname* to the string *value*.  Such
219   changes to the environment affect subprocesses started with :func:`os.system`,
220   :func:`popen` or :func:`fork` and :func:`execv`. Availability: most flavors of
221   Unix, Windows.
222
223   .. note::
224
n225-      On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may cause
n202+      On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may
226-      memory leaks. Refer to the system documentation for putenv.
203+      cause memory leaks. Refer to the system documentation for putenv.
227
228   When :func:`putenv` is supported, assignments to items in ``os.environ`` are
229   automatically translated into corresponding calls to :func:`putenv`; however,
230   calls to :func:`putenv` don't update ``os.environ``, so it is actually
231   preferable to assign to items of ``os.environ``.
232
233
234.. function:: setegid(egid)
245
246   Set the current process' group id. Availability: Unix.
247
248
249.. function:: setgroups(groups)
250
251   Set the list of supplemental group ids associated with the current process to
252   *groups*. *groups* must be a sequence, and each element must be an integer
n253-   identifying a group. This operation is typical available only to the superuser.
n230+   identifying a group. This operation is typically available only to the superuser.
254   Availability: Unix.
255
256   .. versionadded:: 2.2
257
258
259.. function:: setpgrp()
260
n261-   Calls the system call :cfunc:`setpgrp` or :cfunc:`setpgrp(0, 0)` depending on
n238+   Call the system call :cfunc:`setpgrp` or :cfunc:`setpgrp(0, 0)` depending on
262   which version is implemented (if any).  See the Unix manual for the semantics.
263   Availability: Unix.
264
265
266.. function:: setpgid(pid, pgrp)
267
n268-   Calls the system call :cfunc:`setpgid` to set the process group id of the
n245+   Call the system call :cfunc:`setpgid` to set the process group id of the
269   process with id *pid* to the process group with id *pgrp*.  See the Unix manual
270   for the semantics. Availability: Unix.
271
272
273.. function:: setreuid(ruid, euid)
274
275   Set the current process's real and effective user ids. Availability: Unix.
276
277
278.. function:: setregid(rgid, egid)
279
280   Set the current process's real and effective group ids. Availability: Unix.
281
282
283.. function:: getsid(pid)
284
n285-   Calls the system call :cfunc:`getsid`.  See the Unix manual for the semantics.
n262+   Call the system call :cfunc:`getsid`.  See the Unix manual for the semantics.
286   Availability: Unix.
287
288   .. versionadded:: 2.4
289
290
291.. function:: setsid()
292
n293-   Calls the system call :cfunc:`setsid`.  See the Unix manual for the semantics.
n270+   Call the system call :cfunc:`setsid`.  See the Unix manual for the semantics.
294   Availability: Unix.
295
296
297.. function:: setuid(uid)
298
299   .. index:: single: user; id, setting
300
n301-   Set the current process' user id. Availability: Unix.
n278+   Set the current process's user id. Availability: Unix.
302
n280+ 
303-.. % placed in this section since it relates to errno.... a little weak
281+.. placed in this section since it relates to errno.... a little weak
304- 
305- 
306.. function:: strerror(code)
307
308   Return the error message corresponding to the error code in *code*.
n309-   Availability: Unix, Windows.
n285+   On platforms where :cfunc:`strerror` returns ``NULL`` when given an unknown
286+   error number, :exc:`ValueError` is raised.  Availability: Unix, Windows.
310
311
312.. function:: umask(mask)
313
n314-   Set the current numeric umask and returns the previous umask. Availability:
n291+   Set the current numeric umask and return the previous umask. Availability:
315   Unix, Windows.
316
317
318.. function:: uname()
319
320   .. index::
321      single: gethostname() (in module socket)
322      single: gethostbyaddr() (in module socket)
344   preferable to delete items of ``os.environ``.
345
346
347.. _os-newstreams:
348
349File Object Creation
350--------------------
351
n352-These functions create new file objects.
n329+These functions create new file objects. (See also :func:`open`.)
353
354
355.. function:: fdopen(fd[, mode[, bufsize]])
356
357   .. index:: single: I/O control; buffering
358
359   Return an open file object connected to the file descriptor *fd*.  The *mode*
360   and *bufsize* arguments have the same meaning as the corresponding arguments to
n361-   the built-in :func:`open` function. Availability: Macintosh, Unix, Windows.
n338+   the built-in :func:`open` function. Availability: Unix, Windows.
362
363   .. versionchanged:: 2.3
364      When specified, the *mode* argument must now start with one of the letters
365      ``'r'``, ``'w'``, or ``'a'``, otherwise a :exc:`ValueError` is raised.
366
367   .. versionchanged:: 2.5
368      On Unix, when the *mode* argument starts with ``'a'``, the *O_APPEND* flag is
369      set on the file descriptor (which the :cfunc:`fdopen` implementation already
374
375   Open a pipe to or from *command*.  The return value is an open file object
376   connected to the pipe, which can be read or written depending on whether *mode*
377   is ``'r'`` (default) or ``'w'``. The *bufsize* argument has the same meaning as
378   the corresponding argument to the built-in :func:`open` function.  The exit
379   status of the command (encoded in the format specified for :func:`wait`) is
380   available as the return value of the :meth:`close` method of the file object,
381   except that when the exit status is zero (termination without errors), ``None``
n382-   is returned. Availability: Macintosh, Unix, Windows.
n359+   is returned. Availability: Unix, Windows.
360+ 
361+   .. deprecated:: 2.6
362+      This function is obsolete.  Use the :mod:`subprocess` module.  Check
363+      especially the :ref:`subprocess-replacements` section.
383
384   .. versionchanged:: 2.0
385      This function worked unreliably under Windows in earlier versions of Python.
386      This was due to the use of the :cfunc:`_popen` function from the libraries
387      provided with Windows.  Newer versions of Python do not use the broken
388      implementation from the Windows libraries.
389
390
391.. function:: tmpfile()
392
393   Return a new file object opened in update mode (``w+b``).  The file has no
394   directory entries associated with it and will be automatically deleted once
n395-   there are no file descriptors for the file. Availability: Macintosh, Unix,
n376+   there are no file descriptors for the file. Availability: Unix,
396   Windows.
397
n379+There are a number of different :func:`popen\*` functions that provide slightly
380+different ways to create subprocesses.
381+ 
382+.. deprecated:: 2.6
383+   All of the :func:`popen\*` functions are obsolete. Use the :mod:`subprocess`
384+   module.
385+ 
398-For each of the following :func:`popen` variants, if *bufsize* is specified, it
386+For each of the :func:`popen\*` variants, if *bufsize* is specified, it
399specifies the buffer size for the I/O pipes. *mode*, if provided, should be the
400string ``'b'`` or ``'t'``; on Windows this is needed to determine whether the
401file objects should be opened in binary or text mode.  The default value for
402*mode* is ``'t'``.
403
404Also, for each of these variants, on Unix, *cmd* may be a sequence, in which
405case arguments will be passed directly to the program without shell intervention
406(as with :func:`os.spawnv`). If *cmd* is a string it will be passed to the shell
407(as with :func:`os.system`).
408
409These methods do not make it possible to retrieve the exit status from the child
410processes.  The only way to control the input and output streams and also
n411-retrieve the return codes is to use the :class:`Popen3` and :class:`Popen4`
n399+retrieve the return codes is to use the :mod:`subprocess` module; these are only
412-classes from the :mod:`popen2` module; these are only available on Unix.
400+available on Unix.
413
414For a discussion of possible deadlock conditions related to the use of these
n415-functions, see "Flow Control Issues (XXX reference: popen2-flow-control.html)"
416-(section :ref:`popen2-flow-control`).
403+functions, see :ref:`popen2-flow-control`.
417
418
419.. function:: popen2(cmd[, mode[, bufsize]])
420
n421-   Executes *cmd* as a sub-process.  Returns the file objects ``(child_stdin,
n408+   Execute *cmd* as a sub-process and return the file objects ``(child_stdin,
422-   child_stdout)``. Availability: Macintosh, Unix, Windows.
409+   child_stdout)``.
410+ 
411+   .. deprecated:: 2.6
412+      This function is obsolete.  Use the :mod:`subprocess` module.  Check
413+      especially the :ref:`subprocess-replacements` section.
414+ 
415+   Availability: Unix, Windows.
423
424   .. versionadded:: 2.0
425
426
427.. function:: popen3(cmd[, mode[, bufsize]])
428
n429-   Executes *cmd* as a sub-process.  Returns the file objects ``(child_stdin,
n422+   Execute *cmd* as a sub-process and return the file objects ``(child_stdin,
430-   child_stdout, child_stderr)``. Availability: Macintosh, Unix, Windows.
423+   child_stdout, child_stderr)``.
424+ 
425+   .. deprecated:: 2.6
426+      This function is obsolete.  Use the :mod:`subprocess` module.  Check
427+      especially the :ref:`subprocess-replacements` section.
428+ 
429+   Availability: Unix, Windows.
431
432   .. versionadded:: 2.0
433
434
435.. function:: popen4(cmd[, mode[, bufsize]])
436
n437-   Executes *cmd* as a sub-process.  Returns the file objects ``(child_stdin,
n436+   Execute *cmd* as a sub-process and return the file objects ``(child_stdin,
438-   child_stdout_and_stderr)``. Availability: Macintosh, Unix, Windows.
437+   child_stdout_and_stderr)``.
438+ 
439+   .. deprecated:: 2.6
440+      This function is obsolete.  Use the :mod:`subprocess` module.  Check
441+      especially the :ref:`subprocess-replacements` section.
442+ 
443+   Availability: Unix, Windows.
439
440   .. versionadded:: 2.0
441
442(Note that ``child_stdin, child_stdout, and child_stderr`` are named from the
443point of view of the child process, so *child_stdin* is the child's standard
444input.)
445
446This functionality is also available in the :mod:`popen2` module using functions
4600, standard output is 1, and standard error is 2.  Further files opened by a
461process will then be assigned 3, 4, 5, and so forth.  The name "file descriptor"
462is slightly deceptive; on Unix platforms, sockets and pipes are also referenced
463by file descriptors.
464
465
466.. function:: close(fd)
467
n468-   Close file descriptor *fd*. Availability: Macintosh, Unix, Windows.
n473+   Close file descriptor *fd*. Availability: Unix, Windows.
469
470   .. note::
471
472      This function is intended for low-level I/O and must be applied to a file
473      descriptor as returned by :func:`open` or :func:`pipe`.  To close a "file
474      object" returned by the built-in function :func:`open` or by :func:`popen` or
475      :func:`fdopen`, use its :meth:`close` method.
476
477
n483+.. function:: closerange(fd_low, fd_high)
484+ 
485+   Close all file descriptors from *fd_low* (inclusive) to *fd_high* (exclusive),
486+   ignoring errors. Availability: Unix, Windows. Equivalent to::
487+ 
488+      for fd in xrange(fd_low, fd_high):
489+          try:
490+              os.close(fd)
491+          except OSError:
492+              pass
493+ 
494+   .. versionadded:: 2.6
495+ 
496+ 
478.. function:: dup(fd)
479
n480-   Return a duplicate of file descriptor *fd*. Availability: Macintosh, Unix,
n499+   Return a duplicate of file descriptor *fd*. Availability: Unix,
481   Windows.
482
483
484.. function:: dup2(fd, fd2)
485
486   Duplicate file descriptor *fd* to *fd2*, closing the latter first if necessary.
n487-   Availability: Macintosh, Unix, Windows.
n506+   Availability: Unix, Windows.
507+ 
508+ 
509+.. function:: fchmod(fd, mode)
510+ 
511+   Change the mode of the file given by *fd* to the numeric *mode*.  See the docs
512+   for :func:`chmod` for possible values of *mode*.  Availability: Unix.
513+ 
514+   .. versionadded:: 2.6
515+ 
516+ 
517+.. function:: fchown(fd, uid, gid)
518+ 
519+   Change the owner and group id of the file given by *fd* to the numeric *uid*
520+   and *gid*.  To leave one of the ids unchanged, set it to -1.
521+   Availability: Unix.
522+ 
523+   .. versionadded:: 2.6
488
489
490.. function:: fdatasync(fd)
491
492   Force write of file with filedescriptor *fd* to disk. Does not force update of
493   metadata. Availability: Unix.
494
495
497
498   Return system configuration information relevant to an open file. *name*
499   specifies the configuration value to retrieve; it may be a string which is the
500   name of a defined system value; these names are specified in a number of
501   standards (POSIX.1, Unix 95, Unix 98, and others).  Some platforms define
502   additional names as well.  The names known to the host operating system are
503   given in the ``pathconf_names`` dictionary.  For configuration variables not
504   included in that mapping, passing an integer for *name* is also accepted.
n505-   Availability: Macintosh, Unix.
n541+   Availability: Unix.
506
507   If *name* is a string and is not known, :exc:`ValueError` is raised.  If a
508   specific value for *name* is not supported by the host system, even if it is
509   included in ``pathconf_names``, an :exc:`OSError` is raised with
510   :const:`errno.EINVAL` for the error number.
511
512
513.. function:: fstat(fd)
514
515   Return status for file descriptor *fd*, like :func:`stat`. Availability:
n516-   Macintosh, Unix, Windows.
n552+   Unix, Windows.
517
518
519.. function:: fstatvfs(fd)
520
521   Return information about the filesystem containing the file associated with file
522   descriptor *fd*, like :func:`statvfs`. Availability: Unix.
523
524
525.. function:: fsync(fd)
526
527   Force write of file with filedescriptor *fd* to disk.  On Unix, this calls the
528   native :cfunc:`fsync` function; on Windows, the MS :cfunc:`_commit` function.
529
530   If you're starting with a Python file object *f*, first do ``f.flush()``, and
531   then do ``os.fsync(f.fileno())``, to ensure that all internal buffers associated
n532-   with *f* are written to disk. Availability: Macintosh, Unix, and Windows
n568+   with *f* are written to disk. Availability: Unix, and Windows
533   starting in 2.2.3.
534
535
536.. function:: ftruncate(fd, length)
537
538   Truncate the file corresponding to file descriptor *fd*, so that it is at most
n539-   *length* bytes in size. Availability: Macintosh, Unix.
n575+   *length* bytes in size. Availability: Unix.
540
541
542.. function:: isatty(fd)
543
544   Return ``True`` if the file descriptor *fd* is open and connected to a
n545-   tty(-like) device, else ``False``. Availability: Macintosh, Unix.
n581+   tty(-like) device, else ``False``. Availability: Unix.
546
547
548.. function:: lseek(fd, pos, how)
549
n550-   Set the current position of file descriptor *fd* to position *pos*, modified by
n586+   Set the current position of file descriptor *fd* to position *pos*, modified
551-   *how*: ``0`` to set the position relative to the beginning of the file; ``1`` to
587+   by *how*: :const:`SEEK_SET` or ``0`` to set the position relative to the
552-   set it relative to the current position; ``2`` to set it relative to the end of
588+   beginning of the file; :const:`SEEK_CUR` or ``1`` to set it relative to the
589+   current position; :const:`os.SEEK_END` or ``2`` to set it relative to the end of
553-   the file. Availability: Macintosh, Unix, Windows.
590+   the file. Availability: Unix, Windows.
554
555
556.. function:: open(file, flags[, mode])
557
558   Open the file *file* and set various flags according to *flags* and possibly its
559   mode according to *mode*. The default *mode* is ``0777`` (octal), and the
560   current umask value is first masked out.  Return the file descriptor for the
n561-   newly opened file. Availability: Macintosh, Unix, Windows.
n598+   newly opened file. Availability: Unix, Windows.
562
563   For a description of the flag and mode values, see the C run-time documentation;
564   flag constants (like :const:`O_RDONLY` and :const:`O_WRONLY`) are defined in
565   this module too (see below).
566
567   .. note::
568
569      This function is intended for low-level I/O.  For normal usage, use the built-in
573
574
575.. function:: openpty()
576
577   .. index:: module: pty
578
579   Open a new pseudo-terminal pair. Return a pair of file descriptors ``(master,
580   slave)`` for the pty and the tty, respectively. For a (slightly) more portable
n581-   approach, use the :mod:`pty` module. Availability: Macintosh, Some flavors of
n618+   approach, use the :mod:`pty` module. Availability: some flavors of
582   Unix.
583
584
585.. function:: pipe()
586
587   Create a pipe.  Return a pair of file descriptors ``(r, w)`` usable for reading
n588-   and writing, respectively. Availability: Macintosh, Unix, Windows.
n625+   and writing, respectively. Availability: Unix, Windows.
589
590
591.. function:: read(fd, n)
592
593   Read at most *n* bytes from file descriptor *fd*. Return a string containing the
594   bytes read.  If the end of the file referred to by *fd* has been reached, an
n595-   empty string is returned. Availability: Macintosh, Unix, Windows.
n632+   empty string is returned. Availability: Unix, Windows.
596
597   .. note::
598
599      This function is intended for low-level I/O and must be applied to a file
600      descriptor as returned by :func:`open` or :func:`pipe`.  To read a "file object"
601      returned by the built-in function :func:`open` or by :func:`popen` or
n602-      :func:`fdopen`, or ``sys.stdin``, use its :meth:`read` or :meth:`readline`
n639+      :func:`fdopen`, or :data:`sys.stdin`, use its :meth:`read` or :meth:`readline`
603      methods.
604
605
606.. function:: tcgetpgrp(fd)
607
608   Return the process group associated with the terminal given by *fd* (an open
n609-   file descriptor as returned by :func:`open`). Availability: Macintosh, Unix.
n646+   file descriptor as returned by :func:`open`). Availability: Unix.
610
611
612.. function:: tcsetpgrp(fd, pg)
613
614   Set the process group associated with the terminal given by *fd* (an open file
n615-   descriptor as returned by :func:`open`) to *pg*. Availability: Macintosh, Unix.
n652+   descriptor as returned by :func:`open`) to *pg*. Availability: Unix.
616
617
618.. function:: ttyname(fd)
619
n620-   Return a string which specifies the terminal device associated with file-
n657+   Return a string which specifies the terminal device associated with
621-   descriptor *fd*.  If *fd* is not associated with a terminal device, an exception
658+   file descriptor *fd*.  If *fd* is not associated with a terminal device, an
622-   is raised. Availability:Macintosh,  Unix.
659+   exception is raised. Availability: Unix.
623
624
625.. function:: write(fd, str)
626
627   Write the string *str* to file descriptor *fd*. Return the number of bytes
n628-   actually written. Availability: Macintosh, Unix, Windows.
n665+   actually written. Availability: Unix, Windows.
629
630   .. note::
631
632      This function is intended for low-level I/O and must be applied to a file
633      descriptor as returned by :func:`open` or :func:`pipe`.  To write a "file
634      object" returned by the built-in function :func:`open` or by :func:`popen` or
n635-      :func:`fdopen`, or ``sys.stdout`` or ``sys.stderr``, use its :meth:`write`
n672+      :func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its :meth:`write`
636      method.
637
n638-The following data items are available for use in constructing the *flags*
n675+The following constants are options for the *flags* parameter to the
639-parameter to the :func:`open` function.  Some items will not be available on all
676+:func:`open` function.  They can be combined using the bitwise OR operator
640-platforms.  For descriptions of their availability and use, consult
677+``|``.  Some of them are not available on all platforms.  For descriptions of
641-:manpage:`open(2)`.
678+their availability and use, consult the :manpage:`open(2)` manual page on Unix
679+or `the MSDN <http://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>` on Windows.
642
643
644.. data:: O_RDONLY
645          O_WRONLY
646          O_RDWR
647          O_APPEND
648          O_CREAT
649          O_EXCL
650          O_TRUNC
651
n652-   Options for the *flag* argument to the :func:`open` function. These can be bit-
n690+   These constants are available on Unix and Windows.
653-   wise OR'd together. Availability: Macintosh, Unix, Windows.
654
655
656.. data:: O_DSYNC
657          O_RSYNC
658          O_SYNC
659          O_NDELAY
660          O_NONBLOCK
661          O_NOCTTY
662          O_SHLOCK
663          O_EXLOCK
664
n665-   More options for the *flag* argument to the :func:`open` function. Availability:
n702+   These constants are only available on Unix.
666-   Macintosh, Unix.
667
668
669.. data:: O_BINARY
n670- 
n706+          O_NOINHERIT
671-   Option for the *flag* argument to the :func:`open` function. This can be bit-
672-   wise OR'd together with those listed above. Availability: Windows.
673- 
674-   .. % XXX need to check on the availability of this one.
675- 
676- 
677-.. data:: O_NOINHERIT
678          O_SHORT_LIVED
679          O_TEMPORARY
680          O_RANDOM
681          O_SEQUENTIAL
682          O_TEXT
683
n684-   Options for the *flag* argument to the :func:`open` function. These can be bit-
n713+   These constants are only available on Windows.
685-   wise OR'd together. Availability: Windows.
714+ 
715+ 
716+.. data:: O_ASYNC
717+          O_DIRECT
718+          O_DIRECTORY
719+          O_NOFOLLOW
720+          O_NOATIME
721+ 
722+   These constants are GNU extensions and not present if they are not defined by
723+   the C library.
686
687
688.. data:: SEEK_SET
689          SEEK_CUR
690          SEEK_END
691
692   Parameters to the :func:`lseek` function. Their values are 0, 1, and 2,
n693-   respectively. Availability: Windows, Macintosh, Unix.
n731+   respectively. Availability: Windows, Unix.
694
695   .. versionadded:: 2.5
696
697
698.. _os-file-dir:
699
700Files and Directories
701---------------------
n702- 
703
704.. function:: access(path, mode)
705
706   Use the real uid/gid to test for access to *path*.  Note that most operations
707   will use the effective uid/gid, therefore this routine can be used in a
708   suid/sgid environment to test if the invoking user has the specified access to
709   *path*.  *mode* should be :const:`F_OK` to test the existence of *path*, or it
710   can be the inclusive OR of one or more of :const:`R_OK`, :const:`W_OK`, and
711   :const:`X_OK` to test permissions.  Return :const:`True` if access is allowed,
712   :const:`False` if not. See the Unix man page :manpage:`access(2)` for more
n713-   information. Availability: Macintosh, Unix, Windows.
n750+   information. Availability: Unix, Windows.
714
715   .. note::
716
717      Using :func:`access` to check if a user is authorized to e.g. open a file before
718      actually doing so using :func:`open` creates a  security hole, because the user
719      might exploit the short time interval  between checking and opening the file to
720      manipulate it.
721
749   Value to include in the *mode* parameter of :func:`access` to determine if
750   *path* can be executed.
751
752
753.. function:: chdir(path)
754
755   .. index:: single: directory; changing
756
n757-   Change the current working directory to *path*. Availability: Macintosh, Unix,
n794+   Change the current working directory to *path*. Availability: Unix,
758   Windows.
759
760
761.. function:: fchdir(fd)
762
763   Change the current working directory to the directory represented by the file
764   descriptor *fd*.  The descriptor must refer to an opened directory, not an open
765   file. Availability: Unix.
766
767   .. versionadded:: 2.3
768
769
770.. function:: getcwd()
771
772   Return a string representing the current working directory. Availability:
n773-   Macintosh, Unix, Windows.
n810+   Unix, Windows.
774
775
776.. function:: getcwdu()
777
778   Return a Unicode object representing the current working directory.
n779-   Availability: Macintosh, Unix, Windows.
n816+   Availability: Unix, Windows.
780
n818+   .. versionadded:: 2.3
819+ 
820+ 
821+.. function:: chflags(path, flags)
822+ 
823+   Set the flags of *path* to the numeric *flags*. *flags* may take a combination
824+   (bitwise OR) of the following values (as defined in the :mod:`stat` module):
825+ 
826+   * ``UF_NODUMP``
827+   * ``UF_IMMUTABLE``
828+   * ``UF_APPEND``
829+   * ``UF_OPAQUE``
830+   * ``UF_NOUNLINK``
831+   * ``SF_ARCHIVED``
832+   * ``SF_IMMUTABLE``
833+   * ``SF_APPEND``
834+   * ``SF_NOUNLINK``
835+   * ``SF_SNAPSHOT``
836+ 
837+   Availability: Unix.
838+ 
781-   .. versionadded:: 2.3
839+   .. versionadded:: 2.6
782
783
784.. function:: chroot(path)
785
786   Change the root directory of the current process to *path*. Availability:
n787-   Macintosh, Unix.
n845+   Unix.
788
789   .. versionadded:: 2.2
790
791
792.. function:: chmod(path, mode)
793
794   Change the mode of *path* to the numeric *mode*. *mode* may take one of the
n795-   following values (as defined in the :mod:`stat` module) or bitwise or-ed
n853+   following values (as defined in the :mod:`stat` module) or bitwise ORed
796   combinations of them:
797
n856+ 
798-* ``S_ISUID``
857+   * ``stat.S_ISUID``
799- 
800-* ``S_ISGID``
858+   * ``stat.S_ISGID``
801- 
802-* ``S_ENFMT``
859+   * ``stat.S_ENFMT``
803- 
804-* ``S_ISVTX``
860+   * ``stat.S_ISVTX``
805- 
806-* ``S_IREAD``
861+   * ``stat.S_IREAD``
807- 
808-* ``S_IWRITE``
862+   * ``stat.S_IWRITE``
809- 
810-* ``S_IEXEC``
863+   * ``stat.S_IEXEC``
811- 
812-* ``S_IRWXU``
864+   * ``stat.S_IRWXU``
813- 
814-* ``S_IRUSR``
865+   * ``stat.S_IRUSR``
815- 
816-* ``S_IWUSR``
866+   * ``stat.S_IWUSR``
817- 
818-* ``S_IXUSR``
867+   * ``stat.S_IXUSR``
819- 
820-* ``S_IRWXG``
868+   * ``stat.S_IRWXG``
821- 
822-* ``S_IRGRP``
869+   * ``stat.S_IRGRP``
823- 
824-* ``S_IWGRP``
870+   * ``stat.S_IWGRP``
825- 
826-* ``S_IXGRP``
871+   * ``stat.S_IXGRP``
827- 
828-* ``S_IRWXO``
872+   * ``stat.S_IRWXO``
829- 
830-* ``S_IROTH``
873+   * ``stat.S_IROTH``
831- 
832-* ``S_IWOTH``
874+   * ``stat.S_IWOTH``
833- 
834-* ``S_IXOTH``
875+   * ``stat.S_IXOTH``
835
n836-   Availability: Macintosh, Unix, Windows.
n877+   Availability: Unix, Windows.
837
838   .. note::
839
840      Although Windows supports :func:`chmod`, you can only  set the file's read-only
n841-      flag with it (via the ``S_IWRITE``  and ``S_IREAD`` constants or a corresponding
n882+      flag with it (via the ``stat.S_IWRITE``  and ``stat.S_IREAD``
842-      integer value).  All other bits are ignored.
883+      constants or a corresponding integer value).  All other bits are
884+      ignored.
843
844
845.. function:: chown(path, uid, gid)
846
847   Change the owner and group id of *path* to the numeric *uid* and *gid*. To leave
n848-   one of the ids unchanged, set it to -1. Availability: Macintosh, Unix.
n890+   one of the ids unchanged, set it to -1. Availability: Unix.
891+ 
892+ 
893+.. function:: lchflags(path, flags)
894+ 
895+   Set the flags of *path* to the numeric *flags*, like :func:`chflags`, but do not
896+   follow symbolic links. Availability: Unix.
897+ 
898+   .. versionadded:: 2.6
899+ 
900+ 
901+.. function:: lchmod(path, mode)
902+ 
903+   Change the mode of *path* to the numeric *mode*. If path is a symlink, this
904+   affects the symlink rather than the target. See the docs for :func:`chmod`
905+   for possible values of *mode*.  Availability: Unix.
906+ 
907+   .. versionadded:: 2.6
849
850
851.. function:: lchown(path, uid, gid)
852
n853-   Change the owner and group id of *path* to the numeric *uid* and gid. This
n912+   Change the owner and group id of *path* to the numeric *uid* and *gid*. This
854-   function will not follow symbolic links. Availability: Macintosh, Unix.
913+   function will not follow symbolic links. Availability: Unix.
855
856   .. versionadded:: 2.3
857
858
859.. function:: link(src, dst)
860
n861-   Create a hard link pointing to *src* named *dst*. Availability: Macintosh, Unix.
n920+   Create a hard link pointing to *src* named *dst*. Availability: Unix.
862
863
864.. function:: listdir(path)
865
n866-   Return a list containing the names of the entries in the directory. The list is
n925+   Return a list containing the names of the entries in the directory given by
867-   in arbitrary order.  It does not include the special entries ``'.'`` and
926+   *path*.  The list is in arbitrary order.  It does not include the special
868-   ``'..'`` even if they are present in the directory. Availability: Macintosh,
927+   entries ``'.'`` and ``'..'`` even if they are present in the
869-   Unix, Windows.
928+   directory.  Availability: Unix, Windows.
870
871   .. versionchanged:: 2.3
872      On Windows NT/2k/XP and Unix, if *path* is a Unicode object, the result will be
873      a list of Unicode objects.
874
875
876.. function:: lstat(path)
877
n878-   Like :func:`stat`, but do not follow symbolic links. Availability: Macintosh,
n937+   Like :func:`stat`, but do not follow symbolic links.  This is aalias for
879-   Unix.
938+   :func:`stat` on platforms that do not support symbolic links, such as
939+   Windows.
880
881
882.. function:: mkfifo(path[, mode])
883
884   Create a FIFO (a named pipe) named *path* with numeric mode *mode*.  The default
885   *mode* is ``0666`` (octal).  The current umask value is first masked out from
n886-   the mode. Availability: Macintosh, Unix.
n946+   the mode. Availability: Unix.
887
888   FIFOs are pipes that can be accessed like regular files.  FIFOs exist until they
889   are deleted (for example with :func:`os.unlink`). Generally, FIFOs are used as
890   rendezvous between "client" and "server" type processes: the server opens the
891   FIFO for reading, and the client opens it for writing.  Note that :func:`mkfifo`
892   doesn't open the FIFO --- it just creates the rendezvous point.
893
894
895.. function:: mknod(filename[, mode=0600, device])
896
897   Create a filesystem node (file, device special file or named pipe) named
898   *filename*. *mode* specifies both the permissions to use and the type of node to
n899-   be created, being combined (bitwise OR) with one of S_IFREG, S_IFCHR, S_IFBLK,
n959+   be created, being combined (bitwise OR) with one of ``stat.S_IFREG``,
960+   ``stat.S_IFCHR``, ``stat.S_IFBLK``,
900-   and S_IFIFO (those constants are available in :mod:`stat`). For S_IFCHR and
961+   and ``stat.S_IFIFO`` (those constants are available in :mod:`stat`).
962+   For ``stat.S_IFCHR`` and
901-   S_IFBLK, *device* defines the newly created device special file (probably using
963+   ``stat.S_IFBLK``, *device* defines the newly created device special file (probably using
902   :func:`os.makedev`), otherwise it is ignored.
903
904   .. versionadded:: 2.3
905
906
907.. function:: major(device)
908
n909-   Extracts the device major number from a raw device number (usually the
n971+   Extract the device major number from a raw device number (usually the
910   :attr:`st_dev` or :attr:`st_rdev` field from :ctype:`stat`).
911
912   .. versionadded:: 2.3
913
914
915.. function:: minor(device)
916
n917-   Extracts the device minor number from a raw device number (usually the
n979+   Extract the device minor number from a raw device number (usually the
918   :attr:`st_dev` or :attr:`st_rdev` field from :ctype:`stat`).
919
920   .. versionadded:: 2.3
921
922
923.. function:: makedev(major, minor)
924
n925-   Composes a raw device number from the major and minor device numbers.
n987+   Compose a raw device number from the major and minor device numbers.
926
927   .. versionadded:: 2.3
928
929
930.. function:: mkdir(path[, mode])
931
932   Create a directory named *path* with numeric mode *mode*. The default *mode* is
933   ``0777`` (octal).  On some systems, *mode* is ignored.  Where it is used, the
n934-   current umask value is first masked out. Availability: Macintosh, Unix, Windows.
n996+   current umask value is first masked out. Availability: Unix, Windows.
997+ 
998+   It is also possible to create temporary directories; see the
999+   :mod:`tempfile` module's :func:`tempfile.mkdtemp` function.
935
936
937.. function:: makedirs(path[, mode])
938
939   .. index::
940      single: directory; creating
941      single: UNC paths; and os.makedirs()
942
944   intermediate-level directories needed to contain the leaf directory.  Throws an
945   :exc:`error` exception if the leaf directory already exists or cannot be
946   created.  The default *mode* is ``0777`` (octal).  On some systems, *mode* is
947   ignored. Where it is used, the current umask value is first masked out.
948
949   .. note::
950
951      :func:`makedirs` will become confused if the path elements to create include
n952-      *os.pardir*.
n1017+      :data:`os.pardir`.
953
954   .. versionadded:: 1.5.2
955
956   .. versionchanged:: 2.3
957      This function now handles UNC paths correctly.
958
959
960.. function:: pathconf(path, name)
961
962   Return system configuration information relevant to a named file. *name*
963   specifies the configuration value to retrieve; it may be a string which is the
964   name of a defined system value; these names are specified in a number of
965   standards (POSIX.1, Unix 95, Unix 98, and others).  Some platforms define
966   additional names as well.  The names known to the host operating system are
967   given in the ``pathconf_names`` dictionary.  For configuration variables not
968   included in that mapping, passing an integer for *name* is also accepted.
n969-   Availability: Macintosh, Unix.
n1034+   Availability: Unix.
970
971   If *name* is a string and is not known, :exc:`ValueError` is raised.  If a
972   specific value for *name* is not supported by the host system, even if it is
973   included in ``pathconf_names``, an :exc:`OSError` is raised with
974   :const:`errno.EINVAL` for the error number.
975
976
977.. data:: pathconf_names
978
979   Dictionary mapping names accepted by :func:`pathconf` and :func:`fpathconf` to
980   the integer values defined for those names by the host operating system.  This
981   can be used to determine the set of names known to the system. Availability:
n982-   Macintosh, Unix.
n1047+   Unix.
983
984
985.. function:: readlink(path)
986
987   Return a string representing the path to which the symbolic link points.  The
988   result may be either an absolute or relative pathname; if it is relative, it may
989   be converted to an absolute pathname using ``os.path.join(os.path.dirname(path),
n990-   result)``. Availability: Macintosh, Unix.
n1055+   result)``.
1056+ 
1057+   .. versionchanged:: 2.6
1058+      If the *path* is a Unicode object the result will also be a Unicode object.
1059+ 
1060+   Availability: Unix.
991
992
993.. function:: remove(path)
994
995   Remove the file *path*.  If *path* is a directory, :exc:`OSError` is raised; see
996   :func:`rmdir` below to remove a directory.  This is identical to the
997   :func:`unlink` function documented below.  On Windows, attempting to remove a
998   file that is in use causes an exception to be raised; on Unix, the directory
999   entry is removed but the storage allocated to the file is not made available
n1000-   until the original file is no longer in use. Availability: Macintosh, Unix,
n1070+   until the original file is no longer in use. Availability: Unix,
1001   Windows.
1002
1003
1004.. function:: removedirs(path)
1005
1006   .. index:: single: directory; deleting
1007
n1008-   Removes directories recursively.  Works like :func:`rmdir` except that, if the
n1078+   Remove directories recursively.  Works like :func:`rmdir` except that, if the
1009   leaf directory is successfully removed, :func:`removedirs`  tries to
1010   successively remove every parent directory mentioned in  *path* until an error
1011   is raised (which is ignored, because it generally means that a parent directory
1012   is not empty). For example, ``os.removedirs('foo/bar/baz')`` will first remove
1013   the directory ``'foo/bar/baz'``, and then remove ``'foo/bar'`` and ``'foo'`` if
1014   they are empty. Raises :exc:`OSError` if the leaf directory could not be
1015   successfully removed.
1016
1017   .. versionadded:: 1.5.2
1018
1019
1020.. function:: rename(src, dst)
1021
1022   Rename the file or directory *src* to *dst*.  If *dst* is a directory,
1023   :exc:`OSError` will be raised.  On Unix, if *dst* exists and is a file, it will
n1024-   be removed silently if the user has permission.  The operation may fail on some
n1094+   be replaced silently if the user has permission.  The operation may fail on some
1025   Unix flavors if *src* and *dst* are on different filesystems.  If successful,
1026   the renaming will be an atomic operation (this is a POSIX requirement).  On
1027   Windows, if *dst* already exists, :exc:`OSError` will be raised even if it is a
1028   file; there may be no way to implement an atomic rename when *dst* names an
n1029-   existing file. Availability: Macintosh, Unix, Windows.
n1099+   existing file. Availability: Unix, Windows.
1030
1031
1032.. function:: renames(old, new)
1033
1034   Recursive directory or file renaming function. Works like :func:`rename`, except
1035   creation of any intermediate directories needed to make the new pathname good is
1036   attempted first. After the rename, directories corresponding to rightmost path
1037   segments of the old name will be pruned away using :func:`removedirs`.
1041   .. note::
1042
1043      This function can fail with the new directory structure made if you lack
1044      permissions needed to remove the leaf directory or file.
1045
1046
1047.. function:: rmdir(path)
1048
n1049-   Remove the directory *path*. Availability: Macintosh, Unix, Windows.
n1119+   Remove the directory *path*. Availability: Unix, Windows.
1050
1051
1052.. function:: stat(path)
1053
1054   Perform a :cfunc:`stat` system call on the given path.  The return value is an
1055   object whose attributes correspond to the members of the :ctype:`stat`
1056   structure, namely: :attr:`st_mode` (protection bits), :attr:`st_ino` (inode
1057   number), :attr:`st_dev` (device), :attr:`st_nlink` (number of hard links),
n1058-   :attr:`st_uid` (user ID of owner), :attr:`st_gid` (group ID of owner),
n1128+   :attr:`st_uid` (user id of owner), :attr:`st_gid` (group id of owner),
1059   :attr:`st_size` (size of file, in bytes), :attr:`st_atime` (time of most recent
1060   access), :attr:`st_mtime` (time of most recent content modification),
1061   :attr:`st_ctime` (platform dependent; time of most recent metadata change on
1062   Unix, or the time of creation on Windows)::
1063
1064      >>> import os
1065      >>> statinfo = os.stat('somefile.txt')
1066      >>> statinfo
1067      (33188, 422511L, 769L, 1, 1032, 100, 926L, 1105022698,1105022732, 1105022732)
1068      >>> statinfo.st_size
1069      926L
1070      >>>
1071
1072   .. versionchanged:: 2.3
n1073-      If :func:`stat_float_times` returns true, the time values are floats, measuring
n1143+      If :func:`stat_float_times` returns ``True``, the time values are floats, measuring
1074      seconds. Fractions of a second may be reported if the system supports that. On
1075      Mac OS, the times are always floats. See :func:`stat_float_times` for further
1076      discussion.
1077
1078   On some Unix systems (such as Linux), the following attributes may also be
1079   available: :attr:`st_blocks` (number of blocks allocated for file),
1080   :attr:`st_blksize` (filesystem blocksize), :attr:`st_rdev` (type of device if an
1081   inode device). :attr:`st_flags` (user defined flags for file).
1105   .. note::
1106
1107      The exact meaning and resolution of the :attr:`st_atime`, :attr:`st_mtime`, and
1108      :attr:`st_ctime` members depends on the operating system and the file system.
1109      For example, on Windows systems using the FAT or FAT32 file systems,
1110      :attr:`st_mtime` has 2-second resolution, and :attr:`st_atime` has only 1-day
1111      resolution.  See your operating system documentation for details.
1112
n1113-   Availability: Macintosh, Unix, Windows.
n1183+   Availability: Unix, Windows.
1114
1115   .. versionchanged:: 2.2
1116      Added access to values as attributes of the returned object.
1117
1118   .. versionchanged:: 2.5
n1119-      Added st_gen, st_birthtime.
n1189+      Added :attr:`st_gen` and :attr:`st_birthtime`.
1120
1121
1122.. function:: stat_float_times([newvalue])
1123
1124   Determine whether :class:`stat_result` represents time stamps as float objects.
1125   If *newvalue* is ``True``, future calls to :func:`stat` return floats, if it is
1126   ``False``, future calls return ints. If *newvalue* is omitted, return the
1127   current setting.
1176
1177   Return a unique path name that is reasonable for creating a temporary file.
1178   This will be an absolute path that names a potential directory entry in the
1179   directory *dir* or a common location for temporary files if *dir* is omitted or
1180   ``None``.  If given and not ``None``, *prefix* is used to provide a short prefix
1181   to the filename.  Applications are responsible for properly creating and
1182   managing files created using paths returned by :func:`tempnam`; no automatic
1183   cleanup is provided. On Unix, the environment variable :envvar:`TMPDIR`
n1184-   overrides *dir*, while on Windows the :envvar:`TMP` is used.  The specific
n1254+   overrides *dir*, while on Windows :envvar:`TMP` is used.  The specific
1185   behavior of this function depends on the C library implementation; some aspects
1186   are underspecified in system documentation.
1187
1188   .. warning::
1189
1190      Use of :func:`tempnam` is vulnerable to symlink attacks; consider using
1191      :func:`tmpfile` (section :ref:`os-newstreams`) instead.
1192
n1193-   Availability: Macintosh, Unix, Windows.
n1263+   Availability: Unix, Windows.
1194
1195
1196.. function:: tmpnam()
1197
1198   Return a unique path name that is reasonable for creating a temporary file.
1199   This will be an absolute path that names a potential directory entry in a common
1200   location for temporary files.  Applications are responsible for properly
1201   creating and managing files created using paths returned by :func:`tmpnam`; no
1217
1218   The maximum number of unique names that :func:`tmpnam` will generate before
1219   reusing names.
1220
1221
1222.. function:: unlink(path)
1223
1224   Remove the file *path*.  This is the same function as :func:`remove`; the
n1225-   :func:`unlink` name is its traditional Unix name. Availability: Macintosh, Unix,
n1295+   :func:`unlink` name is its traditional Unix name. Availability: Unix,
1226   Windows.
1227
1228
1229.. function:: utime(path, times)
1230
n1231-   Set the access and modified times of the file specified by *path*. If *times* is
n1301+   Set the access and modified times of the file specified by *path*. If *times*
1232-   ``None``, then the file's access and modified times are set to the current time.
1302+   is ``None``, then the file's access and modified times are set to the current
1303+   time. (The effect is similar to running the Unix program :program:`touch` on
1233-   Otherwise, *times* must be a 2-tuple of numbers, of the form ``(atime, mtime)``
1304+   the path.)  Otherwise, *times* must be a 2-tuple of numbers, of the form
1234-   which is used to set the access and modified times, respectively. Whether a
1305+   ``(atime, mtime)`` which is used to set the access and modified times,
1235-   directory can be given for *path* depends on whether the operating system
1306+   respectively. Whether a directory can be given for *path* depends on whether
1236-   implements directories as files (for example, Windows does not).  Note that the
1307+   the operating system implements directories as files (for example, Windows
1237-   exact times you set here may not be returned by a subsequent :func:`stat` call,
1308+   does not).  Note that the exact times you set here may not be returned by a
1238-   depending on the resolution with which your operating system records access and
1309+   subsequent :func:`stat` call, depending on the resolution with which your
1239-   modification times; see :func:`stat`.
1310+   operating system records access and modification times; see :func:`stat`.
1240
1241   .. versionchanged:: 2.0
1242      Added support for ``None`` for *times*.
1243
n1244-   Availability: Macintosh, Unix, Windows.
n1315+   Availability: Unix, Windows.
1245
1246
n1247-.. function:: walk(top[, topdown\ ``=True`` [, onerror\ ``=None``]])
n1318+.. function:: walk(top[, topdown=True [, onerror=None[, followlinks=False]]])
1248
1249   .. index::
1250      single: directory; walking
1251      single: directory; traversal
1252
n1253-   :func:`walk` generates the file names in a directory tree, by walking the tree
n1324+   Generate the file names in a directory tree by walking the tree
1254-   either top down or bottom up. For each directory in the tree rooted at directory
1325+   either top-down or bottom-up. For each directory in the tree rooted at directory
1255   *top* (including *top* itself), it yields a 3-tuple ``(dirpath, dirnames,
1256   filenames)``.
1257
1258   *dirpath* is a string, the path to the directory.  *dirnames* is a list of the
1259   names of the subdirectories in *dirpath* (excluding ``'.'`` and ``'..'``).
1260   *filenames* is a list of the names of the non-directory files in *dirpath*.
1261   Note that the names in the lists contain no path components.  To get a full path
1262   (which begins with *top*) to a file or directory in *dirpath*, do
1263   ``os.path.join(dirpath, name)``.
1264
n1265-   If optional argument *topdown* is true or not specified, the triple for a
n1336+   If optional argument *topdown* is ``True`` or not specified, the triple for a
1266   directory is generated before the triples for any of its subdirectories
n1267-   (directories are generated top down).  If *topdown* is false, the triple for a
n1338+   (directories are generated top-down).  If *topdown* is ``False``, the triple for a
1268   directory is generated after the triples for all of its subdirectories
n1269-   (directories are generated bottom up).
n1340+   (directories are generated bottom-up).
1270
n1271-   When *topdown* is true, the caller can modify the *dirnames* list in-place
n1342+   When *topdown* is ``True``, the caller can modify the *dirnames* list in-place
1272   (perhaps using :keyword:`del` or slice assignment), and :func:`walk` will only
1273   recurse into the subdirectories whose names remain in *dirnames*; this can be
1274   used to prune the search, impose a specific order of visiting, or even to inform
1275   :func:`walk` about directories the caller creates or renames before it resumes
n1276-   :func:`walk` again.  Modifying *dirnames* when *topdown* is false is
n1347+   :func:`walk` again.  Modifying *dirnames* when *topdown* is ``False`` is
1277   ineffective, because in bottom-up mode the directories in *dirnames* are
1278   generated before *dirpath* itself is generated.
1279
n1280-   By default errors from the ``os.listdir()`` call are ignored.  If optional
n1351+   By default errors from the :func:`listdir` call are ignored.  If optional
1281   argument *onerror* is specified, it should be a function; it will be called with
1282   one argument, an :exc:`OSError` instance.  It can report the error to continue
1283   with the walk, or raise the exception to abort the walk.  Note that the filename
1284   is available as the ``filename`` attribute of the exception object.
1285
n1357+   By default, :func:`walk` will not walk down into symbolic links that resolve to
1358+   directories. Set *followlinks* to ``True`` to visit directories pointed to by
1359+   symlinks, on systems that support them.
1360+ 
1361+   .. versionadded:: 2.6
1362+      The *followlinks* parameter.
1363+ 
1364+   .. note::
1365+ 
1366+      Be aware that setting *followlinks* to ``True`` can lead to infinite recursion if a
1367+      link points to a parent directory of itself. :func:`walk` does not keep track of
1368+      the directories it visited already.
1369+ 
1286   .. note::
1287
1288      If you pass a relative pathname, don't change the current working directory
1289      between resumptions of :func:`walk`.  :func:`walk` never changes the current
1290      directory, and assumes that its caller doesn't either.
n1291- 
1292-   .. note::
1293- 
1294-      On systems that support symbolic links, links to subdirectories appear in
1295-      *dirnames* lists, but :func:`walk` will not visit them (infinite loops are hard
1296-      to avoid when following symbolic links). To visit linked directories, you can
1297-      identify them with ``os.path.islink(path)``, and invoke ``walk(path)`` on each
1298-      directly.
1299
1300   This example displays the number of bytes taken by non-directory files in each
1301   directory under the starting directory, except that it doesn't look under any
1302   CVS subdirectory::
1303
1304      import os
1305      from os.path import join, getsize
1306      for root, dirs, files in os.walk('python/Lib/email'):
1307          print root, "consumes",
1308          print sum(getsize(join(root, name)) for name in files),
1309          print "bytes in", len(files), "non-directory files"
1310          if 'CVS' in dirs:
1311              dirs.remove('CVS')  # don't visit CVS directories
1312
n1313-   In the next example, walking the tree bottom up is essential: :func:`rmdir`
n1389+   In the next example, walking the tree bottom-up is essential: :func:`rmdir`
1314   doesn't allow deleting a directory before the directory is empty::
1315
n1316-      # Delete everything reachable from the directory named in 'top',
n1392+      # Delete everything reachable from the directory named in "top",
1317      # assuming there are no symbolic links.
1318      # CAUTION:  This is dangerous!  For example, if top == '/', it
1319      # could delete all your disk files.
1320      import os
1321      for root, dirs, files in os.walk(top, topdown=False):
1322          for name in files:
1323              os.remove(os.path.join(root, name))
1324          for name in dirs:
1344
1345
1346.. function:: abort()
1347
1348   Generate a :const:`SIGABRT` signal to the current process.  On Unix, the default
1349   behavior is to produce a core dump; on Windows, the process immediately returns
1350   an exit code of ``3``.  Be aware that programs which use :func:`signal.signal`
1351   to register a handler for :const:`SIGABRT` will behave differently.
n1352-   Availability: Macintosh, Unix, Windows.
n1428+   Availability: Unix, Windows.
1353
1354
1355.. function:: execl(path, arg0, arg1, ...)
1356              execle(path, arg0, arg1, ..., env)
1357              execlp(file, arg0, arg1, ...)
1358              execlpe(file, arg0, arg1, ..., env)
1359              execv(path, args)
1360              execve(path, args, env)
1361              execvp(file, args)
1362              execvpe(file, args, env)
1363
1364   These functions all execute a new program, replacing the current process; they
1365   do not return.  On Unix, the new executable is loaded into the current process,
n1366-   and will have the same process ID as the caller.  Errors will be reported as
n1442+   and will have the same process id as the caller.  Errors will be reported as
1367   :exc:`OSError` exceptions.
1368
n1445+   The current process is replaced immediately. Open file objects and
1446+   descriptors are not flushed, so if there may be data buffered
1447+   on these open files, you should flush them using
1448+   :func:`sys.stdout.flush` or :func:`os.fsync` before calling an
1449+   :func:`exec\*` function.
1450+ 
1369-   The ``'l'`` and ``'v'`` variants of the :func:`exec\*` functions differ in how
1451+   The "l" and "v" variants of the :func:`exec\*` functions differ in how
1370-   command-line arguments are passed.  The ``'l'`` variants are perhaps the easiest
1452+   command-line arguments are passed.  The "l" variants are perhaps the easiest
1371   to work with if the number of parameters is fixed when the code is written; the
1372   individual parameters simply become additional parameters to the :func:`execl\*`
n1373-   functions.  The ``'v'`` variants are good when the number of parameters is
n1455+   functions.  The "v" variants are good when the number of parameters is
1374   variable, with the arguments being passed in a list or tuple as the *args*
1375   parameter.  In either case, the arguments to the child process should start with
1376   the name of the command being run, but this is not enforced.
1377
n1378-   The variants which include a ``'p'`` near the end (:func:`execlp`,
n1460+   The variants which include a "p" near the end (:func:`execlp`,
1379   :func:`execlpe`, :func:`execvp`, and :func:`execvpe`) will use the
1380   :envvar:`PATH` environment variable to locate the program *file*.  When the
1381   environment is being replaced (using one of the :func:`exec\*e` variants,
1382   discussed in the next paragraph), the new environment is used as the source of
1383   the :envvar:`PATH` variable. The other variants, :func:`execl`, :func:`execle`,
1384   :func:`execv`, and :func:`execve`, will not use the :envvar:`PATH` variable to
1385   locate the executable; *path* must contain an appropriate absolute or relative
1386   path.
1387
1388   For :func:`execle`, :func:`execlpe`, :func:`execve`, and :func:`execvpe` (note
n1389-   that these all end in ``'e'``), the *env* parameter must be a mapping which is
n1471+   that these all end in "e"), the *env* parameter must be a mapping which is
1390-   used to define the environment variables for the new processthe :func:`execl`,
1472+   used to define the environment variables for the new process (these are used
1473+   instead of the current process' environment); the functions :func:`execl`,
1391   :func:`execlp`, :func:`execv`, and :func:`execvp` all cause the new process to
n1392-   inherit the environment of the current process. Availability: Macintosh, Unix,
n1475+   inherit the environment of the current process.
1393-   Windows.
1476+ 
1477+   Availability: Unix, Windows.
1394
1395
1396.. function:: _exit(n)
1397
1398   Exit to the system with status *n*, without calling cleanup handlers, flushing
n1399-   stdio buffers, etc. Availability: Macintosh, Unix, Windows.
n1483+   stdio buffers, etc. Availability: Unix, Windows.
1400
1401   .. note::
1402
1403      The standard way to exit is ``sys.exit(n)``. :func:`_exit` should normally only
1404      be used in the child process after a :func:`fork`.
1405
n1406-The following exit codes are a defined, and can be used with :func:`_exit`,
n1490+The following exit codes are defined and can be used with :func:`_exit`,
1407although they are not required.  These are typically used for system programs
1408written in Python, such as a mail server's external command delivery program.
1409
1410.. note::
1411
1412   Some of these may not be available on all Unix platforms, since there is some
1413   variation.  These constants are defined where they are defined by the underlying
1414   platform.
1415
1416
1417.. data:: EX_OK
1418
n1419-   Exit code that means no error occurred. Availability: Macintosh, Unix.
n1503+   Exit code that means no error occurred. Availability: Unix.
1420
1421   .. versionadded:: 2.3
1422
1423
1424.. data:: EX_USAGE
1425
1426   Exit code that means the command was used incorrectly, such as when the wrong
n1427-   number of arguments are given. Availability: Macintosh, Unix.
n1511+   number of arguments are given. Availability: Unix.
1428
1429   .. versionadded:: 2.3
1430
1431
1432.. data:: EX_DATAERR
1433
n1434-   Exit code that means the input data was incorrect. Availability: Macintosh,
n1518+   Exit code that means the input data was incorrect. Availability: Unix.
1519+ 
1520+   .. versionadded:: 2.3
1521+ 
1522+ 
1523+.. data:: EX_NOINPUT
1524+ 
1525+   Exit code that means an input file did not exist or was not readable.
1526+   Availability: Unix.
1527+ 
1528+   .. versionadded:: 2.3
1529+ 
1530+ 
1531+.. data:: EX_NOUSER
1532+ 
1533+   Exit code that means a specified user did not exist. Availability: Unix.
1534+ 
1535+   .. versionadded:: 2.3
1536+ 
1537+ 
1538+.. data:: EX_NOHOST
1539+ 
1540+   Exit code that means a specified host did not exist. Availability: Unix.
1541+ 
1542+   .. versionadded:: 2.3
1543+ 
1544+ 
1545+.. data:: EX_UNAVAILABLE
1546+ 
1547+   Exit code that means that a required service is unavailable. Availability:
1435   Unix.
1436
1437   .. versionadded:: 2.3
1438
1439
n1440-.. data:: EX_NOINPUT
1441- 
1442-   Exit code that means an input file did not exist or was not readable.
1443-   Availability: Macintosh, Unix.
1444- 
1445-   .. versionadded:: 2.3
1446- 
1447- 
1448-.. data:: EX_NOUSER
1553+.. data:: EX_SOFTWARE
1449
n1450-   Exit code that means a specified user did not exist. Availability: Macintosh,
n1555+   Exit code that means an internal software error was detected. Availability:
1451   Unix.
1452
1453   .. versionadded:: 2.3
1454
1455
n1456-.. data:: EX_NOHOST
1457- 
1458-   Exit code that means a specified host did not exist. Availability: Macintosh,
1459-   Unix.
1460- 
1461-   .. versionadded:: 2.3
1462- 
1463- 
1464-.. data:: EX_UNAVAILABLE
1465- 
1466-   Exit code that means that a required service is unavailable. Availability:
1467-   Macintosh, Unix.
1468- 
1469-   .. versionadded:: 2.3
1470- 
1471- 
1472-.. data:: EX_SOFTWARE
1473- 
1474-   Exit code that means an internal software error was detected. Availability:
1475-   Macintosh, Unix.
1476- 
1477-   .. versionadded:: 2.3
1478- 
1479- 
1480.. data:: EX_OSERR
1481
1482   Exit code that means an operating system error was detected, such as the
n1483-   inability to fork or create a pipe. Availability: Macintosh, Unix.
n1564+   inability to fork or create a pipe. Availability: Unix.
1484
1485   .. versionadded:: 2.3
1486
1487
1488.. data:: EX_OSFILE
1489
1490   Exit code that means some system file did not exist, could not be opened, or had
n1491-   some other kind of error. Availability: Macintosh, Unix.
n1572+   some other kind of error. Availability: Unix.
1492
1493   .. versionadded:: 2.3
1494
1495
1496.. data:: EX_CANTCREAT
1497
1498   Exit code that means a user specified output file could not be created.
n1499-   Availability: Macintosh, Unix.
n1580+   Availability: Unix.
1500
1501   .. versionadded:: 2.3
1502
1503
1504.. data:: EX_IOERR
1505
1506   Exit code that means that an error occurred while doing I/O on some file.
n1507-   Availability: Macintosh, Unix.
n1588+   Availability: Unix.
1508
1509   .. versionadded:: 2.3
1510
1511
1512.. data:: EX_TEMPFAIL
1513
1514   Exit code that means a temporary failure occurred.  This indicates something
1515   that may not really be an error, such as a network connection that couldn't be
n1516-   made during a retryable operation. Availability: Macintosh, Unix.
n1597+   made during a retryable operation. Availability: Unix.
1517
1518   .. versionadded:: 2.3
1519
1520
1521.. data:: EX_PROTOCOL
1522
1523   Exit code that means that a protocol exchange was illegal, invalid, or not
n1524-   understood. Availability: Macintosh, Unix.
n1605+   understood. Availability: Unix.
1525
1526   .. versionadded:: 2.3
1527
1528
1529.. data:: EX_NOPERM
1530
1531   Exit code that means that there were insufficient permissions to perform the
n1532-   operation (but not intended for file system problems). Availability: Macintosh,
n1613+   operation (but not intended for file system problems). Availability: Unix.
1614+ 
1615+   .. versionadded:: 2.3
1616+ 
1617+ 
1618+.. data:: EX_CONFIG
1619+ 
1620+   Exit code that means that some kind of configuration error occurred.
1621+   Availability: Unix.
1622+ 
1623+   .. versionadded:: 2.3
1624+ 
1625+ 
1626+.. data:: EX_NOTFOUND
1627+ 
1628+   Exit code that means something like "an entry was not found". Availability:
1533   Unix.
1534
1535   .. versionadded:: 2.3
1536
1537
n1538-.. data:: EX_CONFIG
1539- 
1540-   Exit code that means that some kind of configuration error occurred.
1541-   Availability: Macintosh, Unix.
1542- 
1543-   .. versionadded:: 2.3
1544- 
1545- 
1546-.. data:: EX_NOTFOUND
1547- 
1548-   Exit code that means something like "an entry was not found". Availability:
1549-   Macintosh, Unix.
1550- 
1551-   .. versionadded:: 2.3
1552- 
1553- 
1554.. function:: fork()
1555
n1556-   Fork a child process.  Return ``0`` in the child, the child's process id in the
n1636+   Fork a child process.  Return ``0`` in the child and the child's process id in the
1557-   parent. Availability: Macintosh, Unix.
1637+   parent.  If an error occurs :exc:`OSError` is raised.
1638+ 
1639+   Note that some platforms including FreeBSD <= 6.3, Cygwin and OS/2 EMX have
1640+   known issues when using fork() from a thread.
1641+ 
1642+   Availability: Unix.
1558
1559
1560.. function:: forkpty()
1561
1562   Fork a child process, using a new pseudo-terminal as the child's controlling
1563   terminal. Return a pair of ``(pid, fd)``, where *pid* is ``0`` in the child, the
1564   new child's process id in the parent, and *fd* is the file descriptor of the
1565   master end of the pseudo-terminal.  For a more portable approach, use the
n1566-   :mod:`pty` module. Availability: Macintosh, Some flavors of Unix.
n1651+   :mod:`pty` module.  If an error occurs :exc:`OSError` is raised.
1652+   Availability: some flavors of Unix.
1567
1568
1569.. function:: kill(pid, sig)
1570
1571   .. index::
1572      single: process; killing
1573      single: process; signalling
1574
1575   Send signal *sig* to the process *pid*.  Constants for the specific signals
1576   available on the host platform are defined in the :mod:`signal` module.
n1577-   Availability: Macintosh, Unix.
n1663+   Availability: Unix.
1578
1579
1580.. function:: killpg(pgid, sig)
1581
1582   .. index::
1583      single: process; killing
1584      single: process; signalling
1585
n1586-   Send the signal *sig* to the process group *pgid*. Availability: Macintosh,
n1672+   Send the signal *sig* to the process group *pgid*. Availability: Unix.
1587-   Unix.
1588
1589   .. versionadded:: 2.3
1590
1591
1592.. function:: nice(increment)
1593
1594   Add *increment* to the process's "niceness".  Return the new niceness.
n1595-   Availability: Macintosh, Unix.
n1680+   Availability: Unix.
1596
1597
1598.. function:: plock(op)
1599
1600   Lock program segments into memory.  The value of *op* (defined in
n1601-   ``<sys/lock.h>``) determines which segments are locked. Availability: Macintosh,
n1686+   ``<sys/lock.h>``) determines which segments are locked. Availability: Unix.
1602-   Unix.
1603
1604
1605.. function:: popen(...)
1606              popen2(...)
1607              popen3(...)
1608              popen4(...)
1609   :noindex:
1610
1616              spawnle(mode, path, ..., env)
1617              spawnlp(mode, file, ...)
1618              spawnlpe(mode, file, ..., env)
1619              spawnv(mode, path, args)
1620              spawnve(mode, path, args, env)
1621              spawnvp(mode, file, args)
1622              spawnvpe(mode, file, args, env)
1623
n1624-   Execute the program *path* in a new process.  If *mode* is :const:`P_NOWAIT`,
n1708+   Execute the program *path* in a new process.
1625-   this function returns the process ID of the new process; if *mode* is
1709+ 
1626-   :const:`P_WAIT`, returns the process's exit code if it exits normally, or
1710+   (Note that the :mod:`subprocess` module provides more powerful facilities for
1627-   ``-signal``, where *signal* is the signal that killed the process.  On Windows,
1711+   spawning new processes and retrieving their results; using that module is
1628-   the process ID will actually be the process handle, so can be used with the
1712+   preferable to using these functions.  Check specially the *Replacing Older
1713+   Functions with the subprocess Module* section in that documentation page.)
1714+ 
1715+   If *mode* is :const:`P_NOWAIT`, this function returns the process id of the new
1716+   process; if *mode* is :const:`P_WAIT`, returns the process's exit code if it
1717+   exits normally, or ``-signal``, where *signal* is the signal that killed the
1718+   process.  On Windows, the process id will actually be the process handle, so can
1629-   :func:`waitpid` function.
1719+   be used with the :func:`waitpid` function.
1630
n1631-   The ``'l'`` and ``'v'`` variants of the :func:`spawn\*` functions differ in how
n1721+   The "l" and "v" variants of the :func:`spawn\*` functions differ in how
1632-   command-line arguments are passed.  The ``'l'`` variants are perhaps the easiest
1722+   command-line arguments are passed.  The "l" variants are perhaps the easiest
1633   to work with if the number of parameters is fixed when the code is written; the
1634   individual parameters simply become additional parameters to the
n1635-   :func:`spawnl\*` functions.  The ``'v'`` variants are good when the number of
n1725+   :func:`spawnl\*` functions.  The "v" variants are good when the number of
1636   parameters is variable, with the arguments being passed in a list or tuple as
1637   the *args* parameter.  In either case, the arguments to the child process must
1638   start with the name of the command being run.
1639
n1640-   The variants which include a second ``'p'`` near the end (:func:`spawnlp`,
n1730+   The variants which include a second "p" near the end (:func:`spawnlp`,
1641   :func:`spawnlpe`, :func:`spawnvp`, and :func:`spawnvpe`) will use the
1642   :envvar:`PATH` environment variable to locate the program *file*.  When the
1643   environment is being replaced (using one of the :func:`spawn\*e` variants,
1644   discussed in the next paragraph), the new environment is used as the source of
1645   the :envvar:`PATH` variable.  The other variants, :func:`spawnl`,
1646   :func:`spawnle`, :func:`spawnv`, and :func:`spawnve`, will not use the
1647   :envvar:`PATH` variable to locate the executable; *path* must contain an
1648   appropriate absolute or relative path.
1649
1650   For :func:`spawnle`, :func:`spawnlpe`, :func:`spawnve`, and :func:`spawnvpe`
n1651-   (note that these all end in ``'e'``), the *env* parameter must be a mapping
n1741+   (note that these all end in "e"), the *env* parameter must be a mapping
1652-   which is used to define the environment variables for the new processthe
1742+   which is used to define the environment variables for the new process (they are
1743+   used instead of the current process' environment); the functions
1653   :func:`spawnl`, :func:`spawnlp`, :func:`spawnv`, and :func:`spawnvp` all cause
n1654-   the new process to inherit the environment of the current process.
n1745+   the new process to inherit the environment of the current process.  Note that
1746+   keys and values in the *env* dictionary must be strings; invalid keys or
1747+   values will cause the function to fail, with a return value of ``127``.
1655
1656   As an example, the following calls to :func:`spawnlp` and :func:`spawnvpe` are
1657   equivalent::
1658
1659      import os
1660      os.spawnlp(os.P_WAIT, 'cp', 'cp', 'index.html', '/dev/null')
1661
1662      L = ['cp', 'index.html', '/dev/null']
1668   .. versionadded:: 1.6
1669
1670
1671.. data:: P_NOWAIT
1672          P_NOWAITO
1673
1674   Possible values for the *mode* parameter to the :func:`spawn\*` family of
1675   functions.  If either of these values is given, the :func:`spawn\*` functions
n1676-   will return as soon as the new process has been created, with the process ID as
n1769+   will return as soon as the new process has been created, with the process id as
1677-   the return value. Availability: Macintosh, Unix, Windows.
1770+   the return value. Availability: Unix, Windows.
1678
1679   .. versionadded:: 1.6
1680
1681
1682.. data:: P_WAIT
1683
1684   Possible value for the *mode* parameter to the :func:`spawn\*` family of
1685   functions.  If this is given as *mode*, the :func:`spawn\*` functions will not
1686   return until the new process has run to completion and will return the exit code
1687   of the process the run is successful, or ``-signal`` if a signal kills the
n1688-   process. Availability: Macintosh, Unix, Windows.
n1781+   process. Availability: Unix, Windows.
1689
1690   .. versionadded:: 1.6
1691
1692
1693.. data:: P_DETACH
1694          P_OVERLAY
1695
1696   Possible values for the *mode* parameter to the :func:`spawn\*` family of
1730   .. versionadded:: 2.5
1731      The *operation* parameter.
1732
1733
1734.. function:: system(command)
1735
1736   Execute the command (a string) in a subshell.  This is implemented by calling
1737   the Standard C function :cfunc:`system`, and has the same limitations.  Changes
n1738-   to ``posix.environ````sys.stdin``, etc. are not reflected in the environment
n1831+   to :data:`os.environ`, :data:`sys.stdin`, etc. are not reflected in the
1739-   of the executed command.
1832+   environment of the executed command.
1740
1741   On Unix, the return value is the exit status of the process encoded in the
1742   format specified for :func:`wait`.  Note that POSIX does not specify the meaning
1743   of the return value of the C :cfunc:`system` function, so the return value of
1744   the Python function is system-dependent.
1745
1746   On Windows, the return value is that returned by the system shell after running
1747   *command*, given by the Windows environment variable :envvar:`COMSPEC`: on
1748   :program:`command.com` systems (Windows 95, 98 and ME) this is always ``0``; on
1749   :program:`cmd.exe` systems (Windows NT, 2000 and XP) this is the exit status of
1750   the command run; on systems using a non-native shell, consult your shell
1751   documentation.
1752
n1753-   Availability: Macintosh, Unix, Windows.
n1846+   Availability: Unix, Windows.
1847+ 
1848+   The :mod:`subprocess` module provides more powerful facilities for spawning new
1849+   processes and retrieving their results; using that module is preferable to using
1850+   this function.  Use the :mod:`subprocess` module.  Check especially the
1851+   :ref:`subprocess-replacements` section.
1754
1755
1756.. function:: times()
1757
1758   Return a 5-tuple of floating point numbers indicating accumulated (processor or
1759   other) times, in seconds.  The items are: user time, system time, children's
1760   user time, children's system time, and elapsed real time since a fixed point in
1761   the past, in that order.  See the Unix manual page :manpage:`times(2)` or the
n1762-   corresponding Windows Platform API documentation. Availability: Macintosh, Unix,
n1860+   corresponding Windows Platform API documentation. Availability: Unix,
1763-   Windows.
1861+   Windows.  On Windows, only the first two items are filled, the others are zero.
1764
1765
1766.. function:: wait()
1767
1768   Wait for completion of a child process, and return a tuple containing its pid
1769   and exit status indication: a 16-bit number, whose low byte is the signal number
1770   that killed the process, and whose high byte is the exit status (if the signal
1771   number is zero); the high bit of the low byte is set if a core file was
n1772-   produced. Availability: Macintosh, Unix.
n1870+   produced. Availability: Unix.
1773
1774
1775.. function:: waitpid(pid, options)
1776
1777   The details of this function differ on Unix and Windows.
1778
1779   On Unix: Wait for completion of a child process given by process id *pid*, and
1780   return a tuple containing its process id and exit status indication (encoded as
1782   integer *options*, which should be ``0`` for normal operation.
1783
1784   If *pid* is greater than ``0``, :func:`waitpid` requests status information for
1785   that specific process.  If *pid* is ``0``, the request is for the status of any
1786   child in the process group of the current process.  If *pid* is ``-1``, the
1787   request pertains to any child of the current process.  If *pid* is less than
1788   ``-1``, status is requested for any process in the process group ``-pid`` (the
1789   absolute value of *pid*).
n1888+ 
1889+   An :exc:`OSError` is raised with the value of errno when the syscall
1890+   returns -1.
1790
1791   On Windows: Wait for completion of a process given by process handle *pid*, and
1792   return a tuple containing *pid*, and its exit status shifted left by 8 bits
1793   (shifting makes cross-platform use of the function easier). A *pid* less than or
1794   equal to ``0`` has no special meaning on Windows, and raises an exception. The
1795   value of integer *options* has no effect. *pid* can refer to any process whose
1796   id is known, not necessarily a child process. The :func:`spawn` functions called
1797   with :const:`P_NOWAIT` return suitable process handles.
1819
1820   .. versionadded:: 2.5
1821
1822
1823.. data:: WNOHANG
1824
1825   The option for :func:`waitpid` to return immediately if no child process status
1826   is available immediately. The function returns ``(0, 0)`` in this case.
n1827-   Availability: Macintosh, Unix.
n1928+   Availability: Unix.
1828
1829
1830.. data:: WCONTINUED
1831
1832   This option causes child processes to be reported if they have been continued
1833   from a job control stop since their status was last reported. Availability: Some
1834   Unix systems.
1835
1836   .. versionadded:: 2.3
1837
1838
1839.. data:: WUNTRACED
1840
1841   This option causes child processes to be reported if they have been stopped but
1842   their current state has not been reported since they were stopped. Availability:
n1843-   Macintosh, Unix.
n1944+   Unix.
1844
1845   .. versionadded:: 2.3
1846
1847The following functions take a process status code as returned by
1848:func:`system`, :func:`wait`, or :func:`waitpid` as a parameter.  They may be
1849used to determine the disposition of a process.
1850
1851
1852.. function:: WCOREDUMP(status)
1853
n1854-   Returns ``True`` if a core dump was generated for the process, otherwise it
n1955+   Return ``True`` if a core dump was generated for the process, otherwise
1855-   returns ``False``. Availability: Macintosh, Unix.
1956+   return ``False``. Availability: Unix.
1856
1857   .. versionadded:: 2.3
1858
1859
1860.. function:: WIFCONTINUED(status)
1861
n1862-   Returns ``True`` if the process has been continued from a job control stop,
n1963+   Return ``True`` if the process has been continued from a job control stop,
1863-   otherwise it returns ``False``. Availability: Unix.
1964+   otherwise return ``False``. Availability: Unix.
1864
1865   .. versionadded:: 2.3
1866
1867
1868.. function:: WIFSTOPPED(status)
1869
n1870-   Returns ``True`` if the process has been stopped, otherwise it returns
n1971+   Return ``True`` if the process has been stopped, otherwise return
1871   ``False``. Availability: Unix.
1872
1873
1874.. function:: WIFSIGNALED(status)
1875
n1876-   Returns ``True`` if the process exited due to a signal, otherwise it returns
n1977+   Return ``True`` if the process exited due to a signal, otherwise return
1877-   ``False``. Availability: Macintosh, Unix.
1978+   ``False``. Availability: Unix.
1878
1879
1880.. function:: WIFEXITED(status)
1881
n1882-   Returns ``True`` if the process exited using the :manpage:`exit(2)` system call,
n1983+   Return ``True`` if the process exited using the :manpage:`exit(2)` system call,
1883-   otherwise it returns ``False``. Availability: Macintosh, Unix.
1984+   otherwise return ``False``. Availability: Unix.
1884
1885
1886.. function:: WEXITSTATUS(status)
1887
1888   If ``WIFEXITED(status)`` is true, return the integer parameter to the
1889   :manpage:`exit(2)` system call.  Otherwise, the return value is meaningless.
n1890-   Availability: Macintosh, Unix.
n1991+   Availability: Unix.
1891
1892
1893.. function:: WSTOPSIG(status)
1894
n1895-   Return the signal which caused the process to stop. Availability: Macintosh,
n1996+   Return the signal which caused the process to stop. Availability: Unix.
1896-   Unix.
1897
1898
1899.. function:: WTERMSIG(status)
1900
n1901-   Return the signal which caused the process to exit. Availability: Macintosh,
n2001+   Return the signal which caused the process to exit. Availability: Unix.
1902-   Unix.
1903
1904
1905.. _os-path:
1906
1907Miscellaneous System Information
1908--------------------------------
1909
1910
1912
1913   Return string-valued system configuration values. *name* specifies the
1914   configuration value to retrieve; it may be a string which is the name of a
1915   defined system value; these names are specified in a number of standards (POSIX,
1916   Unix 95, Unix 98, and others).  Some platforms define additional names as well.
1917   The names known to the host operating system are given as the keys of the
1918   ``confstr_names`` dictionary.  For configuration variables not included in that
1919   mapping, passing an integer for *name* is also accepted. Availability:
n1920-   Macintosh, Unix.
n2019+   Unix.
1921
1922   If the configuration value specified by *name* isn't defined, ``None`` is
1923   returned.
1924
1925   If *name* is a string and is not known, :exc:`ValueError` is raised.  If a
1926   specific value for *name* is not supported by the host system, even if it is
1927   included in ``confstr_names``, an :exc:`OSError` is raised with
1928   :const:`errno.EINVAL` for the error number.
1929
1930
1931.. data:: confstr_names
1932
1933   Dictionary mapping names accepted by :func:`confstr` to the integer values
1934   defined for those names by the host operating system. This can be used to
n1935-   determine the set of names known to the system. Availability: Macintosh, Unix.
n2034+   determine the set of names known to the system. Availability: Unix.
1936
1937
1938.. function:: getloadavg()
1939
n1940-   Return the number of processes in the system run queue averaged over the last 1,
n2039+   Return the number of processes in the system run queue averaged over the last
1941-   5, and 15 minutes or raises :exc:`OSError` if the load  average was
2040+   1, 5, and 15 minutes or raises :exc:`OSError` if the load average was
1942-   unobtainable.
2041+   unobtainable.  Availability: Unix.
1943
1944   .. versionadded:: 2.3
1945
1946
1947.. function:: sysconf(name)
1948
1949   Return integer-valued system configuration values. If the configuration value
1950   specified by *name* isn't defined, ``-1`` is returned.  The comments regarding
1951   the *name* parameter for :func:`confstr` apply here as well; the dictionary that
1952   provides information on the known names is given by ``sysconf_names``.
n1953-   Availability: Macintosh, Unix.
n2052+   Availability: Unix.
1954
1955
1956.. data:: sysconf_names
1957
1958   Dictionary mapping names accepted by :func:`sysconf` to the integer values
1959   defined for those names by the host operating system. This can be used to
n1960-   determine the set of names known to the system. Availability: Macintosh, Unix.
n2059+   determine the set of names known to the system. Availability: Unix.
1961
n1962-The follow data values are used to support path manipulation operations.  These
n2061+The following data values are used to support path manipulation operations.  These
1963are defined for all platforms.
1964
1965Higher-level operations on pathnames are defined in the :mod:`os.path` module.
1966
1967
1968.. data:: curdir
1969
1970   The constant string used by the operating system to refer to the current
n1971-   directory. For example: ``'.'`` for POSIX or ``':'`` for Mac OS 9. Also
n2070+   directory. This is ``'.'`` for Windows and POSIX. Also available via
1972-   available via :mod:`os.path`.
2071+   :mod:`os.path`.
1973
1974
1975.. data:: pardir
1976
1977   The constant string used by the operating system to refer to the parent
n1978-   directory. For example: ``'..'`` for POSIX or ``'::'`` for Mac OS 9. Also
n2077+   directory. This is ``'..'`` for Windows and POSIX. Also available via
1979-   available via :mod:`os.path`.
2078+   :mod:`os.path`.
1980
1981
1982.. data:: sep
1983
n1984-   The character used by the operating system to separate pathname components, for
n2083+   The character used by the operating system to separate pathname components.
1985-   example, ``'/'`` for POSIX or ``':'`` for Mac OS 9.  Note that knowing this is
2084+   This is ``'/'`` for POSIX and ``'\\'`` for Windows.  Note that knowing this
1986-   not sufficient to be able to parse or concatenate pathnames --- use
2085+   is not sufficient to be able to parse or concatenate pathnames --- use
1987   :func:`os.path.split` and :func:`os.path.join` --- but it is occasionally
1988   useful. Also available via :mod:`os.path`.
1989
1990
1991.. data:: altsep
1992
1993   An alternative character used by the operating system to separate pathname
1994   components, or ``None`` if only one separator character exists.  This is set to
2015
2016   The default search path used by :func:`exec\*p\*` and :func:`spawn\*p\*` if the
2017   environment doesn't have a ``'PATH'`` key. Also available via :mod:`os.path`.
2018
2019
2020.. data:: linesep
2021
2022   The string used to separate (or, rather, terminate) lines on the current
n2023-   platform.  This may be a single character, such as ``'\ n'`` for POSIX or
n2122+   platform.  This may be a single character, such as ``'\n'`` for POSIX, or
2024-   ``'\r'`` for Mac OS, or multiple characters, for example, ``'\r\n'`` for
2123+   multiple characters, for example, ``'\r\n'`` for Windows. Do not use
2025-   Windows.
2124+   *os.linesep* as a line terminator when writing files opened in text mode (the
2125+   default); use a single ``'\n'`` instead, on all platforms.
2026
2027
2028.. data:: devnull
2029
t2030-   The file path of the null device. For example: ``'/dev/null'`` for POSIX or
t2130+   The file path of the null device. For example: ``'/dev/null'`` for POSIX.
2031-   ``'Dev:Nul'`` for Mac OS 9. Also available via :mod:`os.path`.
2131+   Also available via :mod:`os.path`.
2032
2033   .. versionadded:: 2.4
2034
2035
2036.. _os-miscfunc:
2037
2038Miscellaneous Functions
2039-----------------------
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op