Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(158415)

Side by Side Diff: Doc/library/os.rst

Issue 19207: Improve cross-references in os documentation
Patch Set: Created 6 years, 2 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View unified diff | Download patch
OLDNEW
1 :mod:`os` --- Miscellaneous operating system interfaces 1 :mod:`os` --- Miscellaneous operating system interfaces
2 ======================================================= 2 =======================================================
3 3
4 .. module:: os 4 .. module:: os
5 :synopsis: Miscellaneous operating system interfaces. 5 :synopsis: Miscellaneous operating system interfaces.
6 6
7 7
8 This module provides a portable way of using operating system dependent 8 This module provides a portable way of using operating system dependent
9 functionality. If you just want to read or write a file see :func:`open`, if 9 functionality. If you just want to read or write a file see :func:`open`, if
10 you want to manipulate paths, see the :mod:`os.path` module, and if you want to 10 you want to manipulate paths, see the :mod:`os.path` module, and if you want to
(...skipping 625 matching lines...) Expand 10 before | Expand all | Expand 10 after
636 636
637 These functions operate on I/O streams referenced using file descriptors. 637 These functions operate on I/O streams referenced using file descriptors.
638 638
639 File descriptors are small integers corresponding to a file that has been opened 639 File descriptors are small integers corresponding to a file that has been opened
640 by the current process. For example, standard input is usually file descriptor 640 by the current process. For example, standard input is usually file descriptor
641 0, standard output is 1, and standard error is 2. Further files opened by a 641 0, standard output is 1, and standard error is 2. Further files opened by a
642 process will then be assigned 3, 4, 5, and so forth. The name "file descriptor" 642 process will then be assigned 3, 4, 5, and so forth. The name "file descriptor"
643 is slightly deceptive; on Unix platforms, sockets and pipes are also referenced 643 is slightly deceptive; on Unix platforms, sockets and pipes are also referenced
644 by file descriptors. 644 by file descriptors.
645 645
646 The :meth:`~file.fileno` method can be used to obtain the file descriptor 646 The :meth:`~io.IOBase.fileno` method can be used to obtain the file descriptor
647 associated with a :term:`file object` when required. Note that using the file 647 associated with a :term:`file object` when required. Note that using the file
648 descriptor directly will bypass the file object methods, ignoring aspects such 648 descriptor directly will bypass the file object methods, ignoring aspects such
649 as internal buffering of data. 649 as internal buffering of data.
650 650
651 651
652 .. function:: close(fd) 652 .. function:: close(fd)
653 653
654 Close file descriptor *fd*. 654 Close file descriptor *fd*.
655 655
656 Availability: Unix, Windows. 656 Availability: Unix, Windows.
657 657
658 .. note:: 658 .. note::
659 659
660 This function is intended for low-level I/O and must be applied to a file 660 This function is intended for low-level I/O and must be applied to a file
661 descriptor as returned by :func:`os.open` or :func:`pipe`. To close a "fi le 661 descriptor as returned by :func:`os.open` or :func:`pipe`. To close a "fi le
662 object" returned by the built-in function :func:`open` or by :func:`popen` or 662 object" returned by the built-in function :func:`open` or by :func:`popen` or
663 :func:`fdopen`, use its :meth:`~file.close` method. 663 :func:`fdopen`, use its :meth:`~io.IOBase.close` method.
664 664
665 665
666 .. function:: closerange(fd_low, fd_high) 666 .. function:: closerange(fd_low, fd_high)
667 667
668 Close all file descriptors from *fd_low* (inclusive) to *fd_high* (exclusive) , 668 Close all file descriptors from *fd_low* (inclusive) to *fd_high* (exclusive) ,
669 ignoring errors. Equivalent to (but much faster than):: 669 ignoring errors. Equivalent to (but much faster than)::
670 670
671 for fd in range(fd_low, fd_high): 671 for fd in range(fd_low, fd_high):
672 try: 672 try:
673 os.close(fd) 673 os.close(fd)
(...skipping 153 matching lines...) Expand 10 before | Expand all | Expand 10 after
827 Availability: Unix. 827 Availability: Unix.
828 828
829 .. versionadded:: 3.3 829 .. versionadded:: 3.3
830 830
831 831
832 .. function:: lseek(fd, pos, how) 832 .. function:: lseek(fd, pos, how)
833 833
834 Set the current position of file descriptor *fd* to position *pos*, modified 834 Set the current position of file descriptor *fd* to position *pos*, modified
835 by *how*: :const:`SEEK_SET` or ``0`` to set the position relative to the 835 by *how*: :const:`SEEK_SET` or ``0`` to set the position relative to the
836 beginning of the file; :const:`SEEK_CUR` or ``1`` to set it relative to the 836 beginning of the file; :const:`SEEK_CUR` or ``1`` to set it relative to the
837 current position; :const:`os.SEEK_END` or ``2`` to set it relative to the end of 837 current position; :const:`SEEK_END` or ``2`` to set it relative to the end of
838 the file. Return the new cursor position in bytes, starting from the beginnin g. 838 the file. Return the new cursor position in bytes, starting from the beginnin g.
839 839
840 Availability: Unix, Windows. 840 Availability: Unix, Windows.
841 841
842 842
843 .. data:: SEEK_SET 843 .. data:: SEEK_SET
844 SEEK_CUR 844 SEEK_CUR
845 SEEK_END 845 SEEK_END
846 846
847 Parameters to the :func:`lseek` function. Their values are 0, 1, and 2, 847 Parameters to the :func:`lseek` function. Their values are 0, 1, and 2,
(...skipping 362 matching lines...) Expand 10 before | Expand all | Expand 10 after
1210 1210
1211 A file descriptor has an "inheritable" flag which indicates if the file descript or 1211 A file descriptor has an "inheritable" flag which indicates if the file descript or
1212 can be inherited by child processes. Since Python 3.4, file descriptors 1212 can be inherited by child processes. Since Python 3.4, file descriptors
1213 created by Python are non-inheritable by default. 1213 created by Python are non-inheritable by default.
1214 1214
1215 On UNIX, non-inheritable file descriptors are closed in child processes at the 1215 On UNIX, non-inheritable file descriptors are closed in child processes at the
1216 execution of a new program, other file descriptors are inherited. 1216 execution of a new program, other file descriptors are inherited.
1217 1217
1218 On Windows, non-inheritable handles and file descriptors are closed in child 1218 On Windows, non-inheritable handles and file descriptors are closed in child
1219 processes, except for standard streams (file descriptors 0, 1 and 2: stdin, stdo ut 1219 processes, except for standard streams (file descriptors 0, 1 and 2: stdin, stdo ut
1220 and stderr), which are always inherited. Using :func:`os.spawn*` functions, 1220 and stderr), which are always inherited. Using :func:`spawn\* <spawnl>` functio ns,
1221 all inheritable handles and all inheritable file descriptors are inherited. 1221 all inheritable handles and all inheritable file descriptors are inherited.
1222 Using the :mod:`subprocess` module, all file descriptors except standard 1222 Using the :mod:`subprocess` module, all file descriptors except standard
1223 streams are closed, and inheritable handles are only inherited if the 1223 streams are closed, and inheritable handles are only inherited if the
1224 *close_fds* parameter is ``False``. 1224 *close_fds* parameter is ``False``.
1225 1225
1226 .. function:: get_inheritable(fd) 1226 .. function:: get_inheritable(fd)
1227 1227
1228 Get the "inheritable" flag of the specified file descriptor (a boolean). 1228 Get the "inheritable" flag of the specified file descriptor (a boolean).
1229 1229
1230 .. function:: set_inheritable(fd, inheritable) 1230 .. function:: set_inheritable(fd, inheritable)
(...skipping 755 matching lines...) Expand 10 before | Expand all | Expand 10 after
1986 The :const:`ST_RDONLY` and :const:`ST_NOSUID` constants were added. 1986 The :const:`ST_RDONLY` and :const:`ST_NOSUID` constants were added.
1987 1987
1988 Availability: Unix. 1988 Availability: Unix.
1989 1989
1990 .. versionadded:: 3.3 1990 .. versionadded:: 3.3
1991 Added support for specifying an open file descriptor for *path*. 1991 Added support for specifying an open file descriptor for *path*.
1992 1992
1993 1993
1994 .. data:: supports_dir_fd 1994 .. data:: supports_dir_fd
1995 1995
1996 A :class:`~collections.Set` object indicating which functions in the 1996 A :class:`~collections.abc.Set` object indicating which functions in the
1997 :mod:`os` module permit use of their *dir_fd* parameter. Different platforms 1997 :mod:`os` module permit use of their *dir_fd* parameter. Different platforms
1998 provide different functionality, and an option that might work on one might 1998 provide different functionality, and an option that might work on one might
1999 be unsupported on another. For consistency's sakes, functions that support 1999 be unsupported on another. For consistency's sakes, functions that support
2000 *dir_fd* always allow specifying the parameter, but will raise an exception 2000 *dir_fd* always allow specifying the parameter, but will raise an exception
2001 if the functionality is not actually available. 2001 if the functionality is not actually available.
2002 2002
2003 To check whether a particular function permits use of its *dir_fd* 2003 To check whether a particular function permits use of its *dir_fd*
2004 parameter, use the ``in`` operator on ``supports_dir_fd``. As an example, 2004 parameter, use the ``in`` operator on ``supports_dir_fd``. As an example,
2005 this expression determines whether the *dir_fd* parameter of :func:`os.stat` 2005 this expression determines whether the *dir_fd* parameter of :func:`os.stat`
2006 is locally available:: 2006 is locally available::
2007 2007
2008 os.stat in os.supports_dir_fd 2008 os.stat in os.supports_dir_fd
2009 2009
2010 Currently *dir_fd* parameters only work on Unix platforms; none of them work 2010 Currently *dir_fd* parameters only work on Unix platforms; none of them work
2011 on Windows. 2011 on Windows.
2012 2012
2013 .. versionadded:: 3.3 2013 .. versionadded:: 3.3
2014 2014
2015 2015
2016 .. data:: supports_effective_ids 2016 .. data:: supports_effective_ids
2017 2017
2018 A :class:`~collections.Set` object indicating which functions in the 2018 A :class:`~collections.abc.Set` object indicating which functions in the
2019 :mod:`os` module permit use of the *effective_ids* parameter for 2019 :mod:`os` module permit use of the *effective_ids* parameter for
2020 :func:`os.access`. If the local platform supports it, the collection will 2020 :func:`os.access`. If the local platform supports it, the collection will
2021 contain :func:`os.access`, otherwise it will be empty. 2021 contain :func:`os.access`, otherwise it will be empty.
2022 2022
2023 To check whether you can use the *effective_ids* parameter for 2023 To check whether you can use the *effective_ids* parameter for
2024 :func:`os.access`, use the ``in`` operator on ``supports_dir_fd``, like so:: 2024 :func:`os.access`, use the ``in`` operator on ``supports_dir_fd``, like so::
2025 2025
2026 os.access in os.supports_effective_ids 2026 os.access in os.supports_effective_ids
2027 2027
2028 Currently *effective_ids* only works on Unix platforms; it does not work on 2028 Currently *effective_ids* only works on Unix platforms; it does not work on
2029 Windows. 2029 Windows.
2030 2030
2031 .. versionadded:: 3.3 2031 .. versionadded:: 3.3
2032 2032
2033 2033
2034 .. data:: supports_fd 2034 .. data:: supports_fd
2035 2035
2036 A :class:`~collections.Set` object indicating which functions in the 2036 A :class:`~collections.abc.Set` object indicating which functions in the
2037 :mod:`os` module permit specifying their *path* parameter as an open file 2037 :mod:`os` module permit specifying their *path* parameter as an open file
2038 descriptor. Different platforms provide different functionality, and an 2038 descriptor. Different platforms provide different functionality, and an
2039 option that might work on one might be unsupported on another. For 2039 option that might work on one might be unsupported on another. For
2040 consistency's sakes, functions that support *fd* always allow specifying 2040 consistency's sakes, functions that support *fd* always allow specifying
2041 the parameter, but will raise an exception if the functionality is not 2041 the parameter, but will raise an exception if the functionality is not
2042 actually available. 2042 actually available.
2043 2043
2044 To check whether a particular function permits specifying an open file 2044 To check whether a particular function permits specifying an open file
2045 descriptor for its *path* parameter, use the ``in`` operator on 2045 descriptor for its *path* parameter, use the ``in`` operator on
2046 ``supports_fd``. As an example, this expression determines whether 2046 ``supports_fd``. As an example, this expression determines whether
2047 :func:`os.chdir` accepts open file descriptors when called on your local 2047 :func:`os.chdir` accepts open file descriptors when called on your local
2048 platform:: 2048 platform::
2049 2049
2050 os.chdir in os.supports_fd 2050 os.chdir in os.supports_fd
2051 2051
2052 .. versionadded:: 3.3 2052 .. versionadded:: 3.3
2053 2053
2054 2054
2055 .. data:: supports_follow_symlinks 2055 .. data:: supports_follow_symlinks
2056 2056
2057 A :class:`~collections.Set` object indicating which functions in the 2057 A :class:`~collections.abc.Set` object indicating which functions in the
2058 :mod:`os` module permit use of their *follow_symlinks* parameter. Different 2058 :mod:`os` module permit use of their *follow_symlinks* parameter. Different
2059 platforms provide different functionality, and an option that might work on 2059 platforms provide different functionality, and an option that might work on
2060 one might be unsupported on another. For consistency's sakes, functions that 2060 one might be unsupported on another. For consistency's sakes, functions that
2061 support *follow_symlinks* always allow specifying the parameter, but will 2061 support *follow_symlinks* always allow specifying the parameter, but will
2062 raise an exception if the functionality is not actually available. 2062 raise an exception if the functionality is not actually available.
2063 2063
2064 To check whether a particular function permits use of its *follow_symlinks* 2064 To check whether a particular function permits use of its *follow_symlinks*
2065 parameter, use the ``in`` operator on ``supports_follow_symlinks``. As an 2065 parameter, use the ``in`` operator on ``supports_follow_symlinks``. As an
2066 example, this expression determines whether the *follow_symlinks* parameter 2066 example, this expression determines whether the *follow_symlinks* parameter
2067 of :func:`os.stat` is locally available:: 2067 of :func:`os.stat` is locally available::
(...skipping 328 matching lines...) Expand 10 before | Expand all | Expand 10 after
2396 indicates the operation must replace an existing attribute. 2396 indicates the operation must replace an existing attribute.
2397 2397
2398 2398
2399 .. _os-process: 2399 .. _os-process:
2400 2400
2401 Process Management 2401 Process Management
2402 ------------------ 2402 ------------------
2403 2403
2404 These functions may be used to create and manage processes. 2404 These functions may be used to create and manage processes.
2405 2405
2406 The various :func:`exec\*` functions take a list of arguments for the new 2406 The various :func:`exec\* <execl>` functions take a list of arguments for the ne w
2407 program loaded into the process. In each case, the first of these arguments is 2407 program loaded into the process. In each case, the first of these arguments is
2408 passed to the new program as its own name rather than as an argument a user may 2408 passed to the new program as its own name rather than as an argument a user may
2409 have typed on a command line. For the C programmer, this is the ``argv[0]`` 2409 have typed on a command line. For the C programmer, this is the ``argv[0]``
2410 passed to a program's :c:func:`main`. For example, ``os.execv('/bin/echo', 2410 passed to a program's :c:func:`main`. For example, ``os.execv('/bin/echo',
2411 ['foo', 'bar'])`` will only print ``bar`` on standard output; ``foo`` will seem 2411 ['foo', 'bar'])`` will only print ``bar`` on standard output; ``foo`` will seem
2412 to be ignored. 2412 to be ignored.
2413 2413
2414 2414
2415 .. function:: abort() 2415 .. function:: abort()
2416 2416
(...skipping 17 matching lines...) Expand all
2434 2434
2435 These functions all execute a new program, replacing the current process; the y 2435 These functions all execute a new program, replacing the current process; the y
2436 do not return. On Unix, the new executable is loaded into the current proces s, 2436 do not return. On Unix, the new executable is loaded into the current proces s,
2437 and will have the same process id as the caller. Errors will be reported as 2437 and will have the same process id as the caller. Errors will be reported as
2438 :exc:`OSError` exceptions. 2438 :exc:`OSError` exceptions.
2439 2439
2440 The current process is replaced immediately. Open file objects and 2440 The current process is replaced immediately. Open file objects and
2441 descriptors are not flushed, so if there may be data buffered 2441 descriptors are not flushed, so if there may be data buffered
2442 on these open files, you should flush them using 2442 on these open files, you should flush them using
2443 :func:`sys.stdout.flush` or :func:`os.fsync` before calling an 2443 :func:`sys.stdout.flush` or :func:`os.fsync` before calling an
2444 :func:`exec\*` function. 2444 :func:`exec\* <execl>` function.
2445 2445
2446 The "l" and "v" variants of the :func:`exec\*` functions differ in how 2446 The "l" and "v" variants of the :func:`exec\* <execl>` functions differ in ho w
2447 command-line arguments are passed. The "l" variants are perhaps the easiest 2447 command-line arguments are passed. The "l" variants are perhaps the easiest
2448 to work with if the number of parameters is fixed when the code is written; t he 2448 to work with if the number of parameters is fixed when the code is written; t he
2449 individual parameters simply become additional parameters to the :func:`execl \*` 2449 individual parameters simply become additional parameters to the :func:`execl \* <execl>`
2450 functions. The "v" variants are good when the number of parameters is 2450 functions. The "v" variants are good when the number of parameters is
2451 variable, with the arguments being passed in a list or tuple as the *args* 2451 variable, with the arguments being passed in a list or tuple as the *args*
2452 parameter. In either case, the arguments to the child process should start w ith 2452 parameter. In either case, the arguments to the child process should start w ith
2453 the name of the command being run, but this is not enforced. 2453 the name of the command being run, but this is not enforced.
2454 2454
2455 The variants which include a "p" near the end (:func:`execlp`, 2455 The variants which include a "p" near the end (:func:`execlp`,
2456 :func:`execlpe`, :func:`execvp`, and :func:`execvpe`) will use the 2456 :func:`execlpe`, :func:`execvp`, and :func:`execvpe`) will use the
2457 :envvar:`PATH` environment variable to locate the program *file*. When the 2457 :envvar:`PATH` environment variable to locate the program *file*. When the
2458 environment is being replaced (using one of the :func:`exec\*e` variants, 2458 environment is being replaced (using one of the :func:`exec\*e <execl>` varia nts,
2459 discussed in the next paragraph), the new environment is used as the source o f 2459 discussed in the next paragraph), the new environment is used as the source o f
2460 the :envvar:`PATH` variable. The other variants, :func:`execl`, :func:`execle `, 2460 the :envvar:`PATH` variable. The other variants, :func:`execl`, :func:`execle `,
2461 :func:`execv`, and :func:`execve`, will not use the :envvar:`PATH` variable t o 2461 :func:`execv`, and :func:`execve`, will not use the :envvar:`PATH` variable t o
2462 locate the executable; *path* must contain an appropriate absolute or relativ e 2462 locate the executable; *path* must contain an appropriate absolute or relativ e
2463 path. 2463 path.
2464 2464
2465 For :func:`execle`, :func:`execlpe`, :func:`execve`, and :func:`execvpe` (not e 2465 For :func:`execle`, :func:`execlpe`, :func:`execve`, and :func:`execvpe` (not e
2466 that these all end in "e"), the *env* parameter must be a mapping which is 2466 that these all end in "e"), the *env* parameter must be a mapping which is
2467 used to define the environment variables for the new process (these are used 2467 used to define the environment variables for the new process (these are used
2468 instead of the current process' environment); the functions :func:`execl`, 2468 instead of the current process' environment); the functions :func:`execl`,
(...skipping 225 matching lines...) Expand 10 before | Expand all | Expand 10 after
2694 2694
2695 .. function:: plock(op) 2695 .. function:: plock(op)
2696 2696
2697 Lock program segments into memory. The value of *op* (defined in 2697 Lock program segments into memory. The value of *op* (defined in
2698 ``<sys/lock.h>``) determines which segments are locked. 2698 ``<sys/lock.h>``) determines which segments are locked.
2699 2699
2700 Availability: Unix. 2700 Availability: Unix.
2701 2701
2702 2702
2703 .. function:: popen(...) 2703 .. function:: popen(...)
2704 :noindex:
2705 2704
2706 Run child processes, returning opened pipes for communications. These functi ons 2705 Run child processes, returning opened pipes for communications. These functi ons
2707 are described in section :ref:`os-newstreams`. 2706 are described in section :ref:`os-newstreams`.
2708 2707
2709
2710 .. function:: spawnl(mode, path, ...) 2708 .. function:: spawnl(mode, path, ...)
2711 spawnle(mode, path, ..., env) 2709 spawnle(mode, path, ..., env)
2712 spawnlp(mode, file, ...) 2710 spawnlp(mode, file, ...)
2713 spawnlpe(mode, file, ..., env) 2711 spawnlpe(mode, file, ..., env)
2714 spawnv(mode, path, args) 2712 spawnv(mode, path, args)
2715 spawnve(mode, path, args, env) 2713 spawnve(mode, path, args, env)
2716 spawnvp(mode, file, args) 2714 spawnvp(mode, file, args)
2717 spawnvpe(mode, file, args, env) 2715 spawnvpe(mode, file, args, env)
2718 2716
2719 Execute the program *path* in a new process. 2717 Execute the program *path* in a new process.
2720 2718
2721 (Note that the :mod:`subprocess` module provides more powerful facilities for 2719 (Note that the :mod:`subprocess` module provides more powerful facilities for
2722 spawning new processes and retrieving their results; using that module is 2720 spawning new processes and retrieving their results; using that module is
2723 preferable to using these functions. Check especially the 2721 preferable to using these functions. Check especially the
2724 :ref:`subprocess-replacements` section.) 2722 :ref:`subprocess-replacements` section.)
2725 2723
2726 If *mode* is :const:`P_NOWAIT`, this function returns the process id of the n ew 2724 If *mode* is :const:`P_NOWAIT`, this function returns the process id of the n ew
2727 process; if *mode* is :const:`P_WAIT`, returns the process's exit code if it 2725 process; if *mode* is :const:`P_WAIT`, returns the process's exit code if it
2728 exits normally, or ``-signal``, where *signal* is the signal that killed the 2726 exits normally, or ``-signal``, where *signal* is the signal that killed the
2729 process. On Windows, the process id will actually be the process handle, so can 2727 process. On Windows, the process id will actually be the process handle, so can
2730 be used with the :func:`waitpid` function. 2728 be used with the :func:`waitpid` function.
2731 2729
2732 The "l" and "v" variants of the :func:`spawn\*` functions differ in how 2730 The "l" and "v" variants of the :func:`spawn\* <spawnl>` functions differ in how
2733 command-line arguments are passed. The "l" variants are perhaps the easiest 2731 command-line arguments are passed. The "l" variants are perhaps the easiest
2734 to work with if the number of parameters is fixed when the code is written; t he 2732 to work with if the number of parameters is fixed when the code is written; t he
2735 individual parameters simply become additional parameters to the 2733 individual parameters simply become additional parameters to the
2736 :func:`spawnl\*` functions. The "v" variants are good when the number of 2734 :func:`spawnl\* <spawnl>` functions. The "v" variants are good when the numb er of
2737 parameters is variable, with the arguments being passed in a list or tuple as 2735 parameters is variable, with the arguments being passed in a list or tuple as
2738 the *args* parameter. In either case, the arguments to the child process mus t 2736 the *args* parameter. In either case, the arguments to the child process mus t
2739 start with the name of the command being run. 2737 start with the name of the command being run.
2740 2738
2741 The variants which include a second "p" near the end (:func:`spawnlp`, 2739 The variants which include a second "p" near the end (:func:`spawnlp`,
2742 :func:`spawnlpe`, :func:`spawnvp`, and :func:`spawnvpe`) will use the 2740 :func:`spawnlpe`, :func:`spawnvp`, and :func:`spawnvpe`) will use the
2743 :envvar:`PATH` environment variable to locate the program *file*. When the 2741 :envvar:`PATH` environment variable to locate the program *file*. When the
2744 environment is being replaced (using one of the :func:`spawn\*e` variants, 2742 environment is being replaced (using one of the :func:`spawn\*e <spawnl>` var iants,
2745 discussed in the next paragraph), the new environment is used as the source o f 2743 discussed in the next paragraph), the new environment is used as the source o f
2746 the :envvar:`PATH` variable. The other variants, :func:`spawnl`, 2744 the :envvar:`PATH` variable. The other variants, :func:`spawnl`,
2747 :func:`spawnle`, :func:`spawnv`, and :func:`spawnve`, will not use the 2745 :func:`spawnle`, :func:`spawnv`, and :func:`spawnve`, will not use the
2748 :envvar:`PATH` variable to locate the executable; *path* must contain an 2746 :envvar:`PATH` variable to locate the executable; *path* must contain an
2749 appropriate absolute or relative path. 2747 appropriate absolute or relative path.
2750 2748
2751 For :func:`spawnle`, :func:`spawnlpe`, :func:`spawnve`, and :func:`spawnvpe` 2749 For :func:`spawnle`, :func:`spawnlpe`, :func:`spawnve`, and :func:`spawnvpe`
2752 (note that these all end in "e"), the *env* parameter must be a mapping 2750 (note that these all end in "e"), the *env* parameter must be a mapping
2753 which is used to define the environment variables for the new process (they a re 2751 which is used to define the environment variables for the new process (they a re
2754 used instead of the current process' environment); the functions 2752 used instead of the current process' environment); the functions
(...skipping 13 matching lines...) Expand all
2768 2766
2769 Availability: Unix, Windows. :func:`spawnlp`, :func:`spawnlpe`, :func:`spawn vp` 2767 Availability: Unix, Windows. :func:`spawnlp`, :func:`spawnlpe`, :func:`spawn vp`
2770 and :func:`spawnvpe` are not available on Windows. :func:`spawnle` and 2768 and :func:`spawnvpe` are not available on Windows. :func:`spawnle` and
2771 :func:`spawnve` are not thread-safe on Windows; we advise you to use the 2769 :func:`spawnve` are not thread-safe on Windows; we advise you to use the
2772 :mod:`subprocess` module instead. 2770 :mod:`subprocess` module instead.
2773 2771
2774 2772
2775 .. data:: P_NOWAIT 2773 .. data:: P_NOWAIT
2776 P_NOWAITO 2774 P_NOWAITO
2777 2775
2778 Possible values for the *mode* parameter to the :func:`spawn\*` family of 2776 Possible values for the *mode* parameter to the :func:`spawn\* <spawnl>` fami ly of
2779 functions. If either of these values is given, the :func:`spawn\*` functions 2777 functions. If either of these values is given, the :func:`spawn\* <spawnl>` functions
Georg 2013/10/12 18:28:38 the second is not needed
2780 will return as soon as the new process has been created, with the process id as 2778 will return as soon as the new process has been created, with the process id as
2781 the return value. 2779 the return value.
2782 2780
2783 Availability: Unix, Windows. 2781 Availability: Unix, Windows.
2784 2782
2785 2783
2786 .. data:: P_WAIT 2784 .. data:: P_WAIT
2787 2785
2788 Possible value for the *mode* parameter to the :func:`spawn\*` family of 2786 Possible value for the *mode* parameter to the :func:`spawn\* <spawnl>` famil y of
2789 functions. If this is given as *mode*, the :func:`spawn\*` functions will no t 2787 functions. If this is given as *mode*, the :func:`spawn\* <spawnl>` function s will not
Georg 2013/10/12 18:28:38 etc
2790 return until the new process has run to completion and will return the exit c ode 2788 return until the new process has run to completion and will return the exit c ode
2791 of the process the run is successful, or ``-signal`` if a signal kills the 2789 of the process the run is successful, or ``-signal`` if a signal kills the
2792 process. 2790 process.
2793 2791
2794 Availability: Unix, Windows. 2792 Availability: Unix, Windows.
2795 2793
2796 2794
2797 .. data:: P_DETACH 2795 .. data:: P_DETACH
2798 P_OVERLAY 2796 P_OVERLAY
2799 2797
2800 Possible values for the *mode* parameter to the :func:`spawn\*` family of 2798 Possible values for the *mode* parameter to the :func:`spawn\* <spawnl>` fami ly of
2801 functions. These are less portable than those listed above. :const:`P_DETACH ` 2799 functions. These are less portable than those listed above. :const:`P_DETACH `
2802 is similar to :const:`P_NOWAIT`, but the new process is detached from the 2800 is similar to :const:`P_NOWAIT`, but the new process is detached from the
2803 console of the calling process. If :const:`P_OVERLAY` is used, the current 2801 console of the calling process. If :const:`P_OVERLAY` is used, the current
2804 process will be replaced; the :func:`spawn\*` function will not return. 2802 process will be replaced; the :func:`spawn\* <spawnl>` function will not retu rn.
2805 2803
2806 Availability: Windows. 2804 Availability: Windows.
2807 2805
2808 2806
2809 .. function:: startfile(path[, operation]) 2807 .. function:: startfile(path[, operation])
2810 2808
2811 Start a file with its associated application. 2809 Start a file with its associated application.
2812 2810
2813 When *operation* is not specified or ``'open'``, this acts like double-clicki ng 2811 When *operation* is not specified or ``'open'``, this acts like double-clicki ng
2814 the file in Windows Explorer, or giving the file name as an argument to the 2812 the file in Windows Explorer, or giving the file name as an argument to the
(...skipping 151 matching lines...) Expand 10 before | Expand all | Expand 10 after
2966 absolute value of *pid*). 2964 absolute value of *pid*).
2967 2965
2968 An :exc:`OSError` is raised with the value of errno when the syscall 2966 An :exc:`OSError` is raised with the value of errno when the syscall
2969 returns -1. 2967 returns -1.
2970 2968
2971 On Windows: Wait for completion of a process given by process handle *pid*, a nd 2969 On Windows: Wait for completion of a process given by process handle *pid*, a nd
2972 return a tuple containing *pid*, and its exit status shifted left by 8 bits 2970 return a tuple containing *pid*, and its exit status shifted left by 8 bits
2973 (shifting makes cross-platform use of the function easier). A *pid* less than or 2971 (shifting makes cross-platform use of the function easier). A *pid* less than or
2974 equal to ``0`` has no special meaning on Windows, and raises an exception. Th e 2972 equal to ``0`` has no special meaning on Windows, and raises an exception. Th e
2975 value of integer *options* has no effect. *pid* can refer to any process whos e 2973 value of integer *options* has no effect. *pid* can refer to any process whos e
2976 id is known, not necessarily a child process. The :func:`spawn` functions cal led 2974 id is known, not necessarily a child process. The :func:`spawn\* <spawnl>` fu nctions called
2977 with :const:`P_NOWAIT` return suitable process handles. 2975 with :const:`P_NOWAIT` return suitable process handles.
2978 2976
2979 2977
2980 .. function:: wait3(options) 2978 .. function:: wait3(options)
2981 2979
2982 Similar to :func:`waitpid`, except no process id argument is given and a 2980 Similar to :func:`waitpid`, except no process id argument is given and a
2983 3-element tuple containing the child's process id, exit status indication, an d 2981 3-element tuple containing the child's process id, exit status indication, an d
2984 resource usage information is returned. Refer to :mod:`resource`.\ 2982 resource usage information is returned. Refer to :mod:`resource`.\
2985 :func:`getrusage` for details on resource usage information. The option 2983 :func:`~resource.getrusage` for details on resource usage information. The o ption
2986 argument is the same as that provided to :func:`waitpid` and :func:`wait4`. 2984 argument is the same as that provided to :func:`waitpid` and :func:`wait4`.
2987 2985
2988 Availability: Unix. 2986 Availability: Unix.
2989 2987
2990 2988
2991 .. function:: wait4(pid, options) 2989 .. function:: wait4(pid, options)
2992 2990
2993 Similar to :func:`waitpid`, except a 3-element tuple, containing the child's 2991 Similar to :func:`waitpid`, except a 3-element tuple, containing the child's
2994 process id, exit status indication, and resource usage information is returne d. 2992 process id, exit status indication, and resource usage information is returne d.
2995 Refer to :mod:`resource`.\ :func:`getrusage` for details on resource usage 2993 Refer to :mod:`resource`.\ :func:`~resource.getrusage` for details on resourc e usage
2996 information. The arguments to :func:`wait4` are the same as those provided t o 2994 information. The arguments to :func:`wait4` are the same as those provided t o
2997 :func:`waitpid`. 2995 :func:`waitpid`.
2998 2996
2999 Availability: Unix. 2997 Availability: Unix.
3000 2998
3001 2999
3002 .. data:: WNOHANG 3000 .. data:: WNOHANG
3003 3001
3004 The option for :func:`waitpid` to return immediately if no child process stat us 3002 The option for :func:`waitpid` to return immediately if no child process stat us
3005 is available immediately. The function returns ``(0, 0)`` in this case. 3003 is available immediately. The function returns ``(0, 0)`` in this case.
(...skipping 317 matching lines...) Expand 10 before | Expand all | Expand 10 after
3323 3321
3324 .. data:: pathsep 3322 .. data:: pathsep
3325 3323
3326 The character conventionally used by the operating system to separate search 3324 The character conventionally used by the operating system to separate search
3327 path components (as in :envvar:`PATH`), such as ``':'`` for POSIX or ``';'`` for 3325 path components (as in :envvar:`PATH`), such as ``':'`` for POSIX or ``';'`` for
3328 Windows. Also available via :mod:`os.path`. 3326 Windows. Also available via :mod:`os.path`.
3329 3327
3330 3328
3331 .. data:: defpath 3329 .. data:: defpath
3332 3330
3333 The default search path used by :func:`exec\*p\*` and :func:`spawn\*p\*` if t he 3331 The default search path used by :func:`exec\*p\* <execl>` and :func:`spawn\*p \* <spawnl>` if the
3334 environment doesn't have a ``'PATH'`` key. Also available via :mod:`os.path`. 3332 environment doesn't have a ``'PATH'`` key. Also available via :mod:`os.path`.
3335 3333
3336 3334
3337 .. data:: linesep 3335 .. data:: linesep
3338 3336
3339 The string used to separate (or, rather, terminate) lines on the current 3337 The string used to separate (or, rather, terminate) lines on the current
3340 platform. This may be a single character, such as ``'\n'`` for POSIX, or 3338 platform. This may be a single character, such as ``'\n'`` for POSIX, or
3341 multiple characters, for example, ``'\r\n'`` for Windows. Do not use 3339 multiple characters, for example, ``'\r\n'`` for Windows. Do not use
3342 *os.linesep* as a line terminator when writing files opened in text mode (the 3340 *os.linesep* as a line terminator when writing files opened in text mode (the
3343 default); use a single ``'\n'`` instead, on all platforms. 3341 default); use a single ``'\n'`` instead, on all platforms.
(...skipping 30 matching lines...) Expand all
3374 3372
3375 This function returns random bytes from an OS-specific randomness source. Th e 3373 This function returns random bytes from an OS-specific randomness source. Th e
3376 returned data should be unpredictable enough for cryptographic applications, 3374 returned data should be unpredictable enough for cryptographic applications,
3377 though its exact quality depends on the OS implementation. On a Unix-like 3375 though its exact quality depends on the OS implementation. On a Unix-like
3378 system this will query ``/dev/urandom``, and on Windows it will use 3376 system this will query ``/dev/urandom``, and on Windows it will use
3379 ``CryptGenRandom()``. If a randomness source is not found, 3377 ``CryptGenRandom()``. If a randomness source is not found,
3380 :exc:`NotImplementedError` will be raised. 3378 :exc:`NotImplementedError` will be raised.
3381 3379
3382 For an easy-to-use interface to the random number generator 3380 For an easy-to-use interface to the random number generator
3383 provided by your platform, please see :class:`random.SystemRandom`. 3381 provided by your platform, please see :class:`random.SystemRandom`.
OLDNEW
« Doc/library/os.path.rst ('K') | « Doc/library/os.path.rst ('k') | Doc/library/posix.rst » ('j') | no next file with comments »

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+