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

Unified Diff: Doc/library/os.rst

Issue 19207: Improve cross-references in os documentation
Patch Set: Created 6 years, 4 months ago
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 side-by-side diff with in-line comments
Download patch
--- a/Doc/library/os.rst Wed Oct 09 14:20:37 2013 +0300
+++ b/Doc/library/os.rst Wed Oct 09 16:35:58 2013 +0300
@@ -643,7 +643,7 @@
is slightly deceptive; on Unix platforms, sockets and pipes are also referenced
by file descriptors.
-The :meth:`~file.fileno` method can be used to obtain the file descriptor
+The :meth:`~io.IOBase.fileno` method can be used to obtain the file descriptor
associated with a :term:`file object` when required. Note that using the file
descriptor directly will bypass the file object methods, ignoring aspects such
as internal buffering of data.
@@ -660,7 +660,7 @@
This function is intended for low-level I/O and must be applied to a file
descriptor as returned by :func:`os.open` or :func:`pipe`. To close a "file
object" returned by the built-in function :func:`open` or by :func:`popen` or
- :func:`fdopen`, use its :meth:`~file.close` method.
+ :func:`fdopen`, use its :meth:`~io.IOBase.close` method.
.. function:: closerange(fd_low, fd_high)
@@ -834,7 +834,7 @@
Set the current position of file descriptor *fd* to position *pos*, modified
by *how*: :const:`SEEK_SET` or ``0`` to set the position relative to the
beginning of the file; :const:`SEEK_CUR` or ``1`` to set it relative to the
- current position; :const:`os.SEEK_END` or ``2`` to set it relative to the end of
+ current position; :const:`SEEK_END` or ``2`` to set it relative to the end of
the file. Return the new cursor position in bytes, starting from the beginning.
Availability: Unix, Windows.
@@ -1217,7 +1217,7 @@
On Windows, non-inheritable handles and file descriptors are closed in child
processes, except for standard streams (file descriptors 0, 1 and 2: stdin, stdout
-and stderr), which are always inherited. Using :func:`os.spawn*` functions,
+and stderr), which are always inherited. Using :func:`spawn\* <spawnl>` functions,
all inheritable handles and all inheritable file descriptors are inherited.
Using the :mod:`subprocess` module, all file descriptors except standard
streams are closed, and inheritable handles are only inherited if the
@@ -1993,7 +1993,7 @@
.. data:: supports_dir_fd
- A :class:`~collections.Set` object indicating which functions in the
+ A :class:`~collections.abc.Set` object indicating which functions in the
:mod:`os` module permit use of their *dir_fd* parameter. Different platforms
provide different functionality, and an option that might work on one might
be unsupported on another. For consistency's sakes, functions that support
@@ -2015,7 +2015,7 @@
.. data:: supports_effective_ids
- A :class:`~collections.Set` object indicating which functions in the
+ A :class:`~collections.abc.Set` object indicating which functions in the
:mod:`os` module permit use of the *effective_ids* parameter for
:func:`os.access`. If the local platform supports it, the collection will
contain :func:`os.access`, otherwise it will be empty.
@@ -2033,7 +2033,7 @@
.. data:: supports_fd
- A :class:`~collections.Set` object indicating which functions in the
+ A :class:`~collections.abc.Set` object indicating which functions in the
:mod:`os` module permit specifying their *path* parameter as an open file
descriptor. Different platforms provide different functionality, and an
option that might work on one might be unsupported on another. For
@@ -2054,7 +2054,7 @@
.. data:: supports_follow_symlinks
- A :class:`~collections.Set` object indicating which functions in the
+ A :class:`~collections.abc.Set` object indicating which functions in the
:mod:`os` module permit use of their *follow_symlinks* parameter. Different
platforms provide different functionality, and an option that might work on
one might be unsupported on another. For consistency's sakes, functions that
@@ -2403,7 +2403,7 @@
These functions may be used to create and manage processes.
-The various :func:`exec\*` functions take a list of arguments for the new
+The various :func:`exec\* <execl>` functions take a list of arguments for the new
program loaded into the process. In each case, the first of these arguments is
passed to the new program as its own name rather than as an argument a user may
have typed on a command line. For the C programmer, this is the ``argv[0]``
@@ -2441,12 +2441,12 @@
descriptors are not flushed, so if there may be data buffered
on these open files, you should flush them using
:func:`sys.stdout.flush` or :func:`os.fsync` before calling an
- :func:`exec\*` function.
-
- The "l" and "v" variants of the :func:`exec\*` functions differ in how
+ :func:`exec\* <execl>` function.
+
+ The "l" and "v" variants of the :func:`exec\* <execl>` functions differ in how
command-line arguments are passed. The "l" variants are perhaps the easiest
to work with if the number of parameters is fixed when the code is written; the
- individual parameters simply become additional parameters to the :func:`execl\*`
+ individual parameters simply become additional parameters to the :func:`execl\* <execl>`
functions. The "v" variants are good when the number of parameters is
variable, with the arguments being passed in a list or tuple as the *args*
parameter. In either case, the arguments to the child process should start with
@@ -2455,7 +2455,7 @@
The variants which include a "p" near the end (:func:`execlp`,
:func:`execlpe`, :func:`execvp`, and :func:`execvpe`) will use the
:envvar:`PATH` environment variable to locate the program *file*. When the
- environment is being replaced (using one of the :func:`exec\*e` variants,
+ environment is being replaced (using one of the :func:`exec\*e <execl>` variants,
discussed in the next paragraph), the new environment is used as the source of
the :envvar:`PATH` variable. The other variants, :func:`execl`, :func:`execle`,
:func:`execv`, and :func:`execve`, will not use the :envvar:`PATH` variable to
@@ -2701,12 +2701,10 @@
.. function:: popen(...)
- :noindex:
Run child processes, returning opened pipes for communications. These functions
are described in section :ref:`os-newstreams`.
-
.. function:: spawnl(mode, path, ...)
spawnle(mode, path, ..., env)
spawnlp(mode, file, ...)
@@ -2729,11 +2727,11 @@
process. On Windows, the process id will actually be the process handle, so can
be used with the :func:`waitpid` function.
- The "l" and "v" variants of the :func:`spawn\*` functions differ in how
+ The "l" and "v" variants of the :func:`spawn\* <spawnl>` functions differ in how
command-line arguments are passed. The "l" variants are perhaps the easiest
to work with if the number of parameters is fixed when the code is written; the
individual parameters simply become additional parameters to the
- :func:`spawnl\*` functions. The "v" variants are good when the number of
+ :func:`spawnl\* <spawnl>` functions. The "v" variants are good when the number of
parameters is variable, with the arguments being passed in a list or tuple as
the *args* parameter. In either case, the arguments to the child process must
start with the name of the command being run.
@@ -2741,7 +2739,7 @@
The variants which include a second "p" near the end (:func:`spawnlp`,
:func:`spawnlpe`, :func:`spawnvp`, and :func:`spawnvpe`) will use the
:envvar:`PATH` environment variable to locate the program *file*. When the
- environment is being replaced (using one of the :func:`spawn\*e` variants,
+ environment is being replaced (using one of the :func:`spawn\*e <spawnl>` variants,
discussed in the next paragraph), the new environment is used as the source of
the :envvar:`PATH` variable. The other variants, :func:`spawnl`,
:func:`spawnle`, :func:`spawnv`, and :func:`spawnve`, will not use the
@@ -2775,8 +2773,8 @@
.. data:: P_NOWAIT
P_NOWAITO
- Possible values for the *mode* parameter to the :func:`spawn\*` family of
- functions. If either of these values is given, the :func:`spawn\*` functions
+ Possible values for the *mode* parameter to the :func:`spawn\* <spawnl>` family of
+ 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
will return as soon as the new process has been created, with the process id as
the return value.
@@ -2785,8 +2783,8 @@
.. data:: P_WAIT
- Possible value for the *mode* parameter to the :func:`spawn\*` family of
- functions. If this is given as *mode*, the :func:`spawn\*` functions will not
+ Possible value for the *mode* parameter to the :func:`spawn\* <spawnl>` family of
+ functions. If this is given as *mode*, the :func:`spawn\* <spawnl>` functions will not
Georg 2013/10/12 18:28:38 etc
return until the new process has run to completion and will return the exit code
of the process the run is successful, or ``-signal`` if a signal kills the
process.
@@ -2797,11 +2795,11 @@
.. data:: P_DETACH
P_OVERLAY
- Possible values for the *mode* parameter to the :func:`spawn\*` family of
+ Possible values for the *mode* parameter to the :func:`spawn\* <spawnl>` family of
functions. These are less portable than those listed above. :const:`P_DETACH`
is similar to :const:`P_NOWAIT`, but the new process is detached from the
console of the calling process. If :const:`P_OVERLAY` is used, the current
- process will be replaced; the :func:`spawn\*` function will not return.
+ process will be replaced; the :func:`spawn\* <spawnl>` function will not return.
Availability: Windows.
@@ -2973,7 +2971,7 @@
(shifting makes cross-platform use of the function easier). A *pid* less than or
equal to ``0`` has no special meaning on Windows, and raises an exception. The
value of integer *options* has no effect. *pid* can refer to any process whose
- id is known, not necessarily a child process. The :func:`spawn` functions called
+ id is known, not necessarily a child process. The :func:`spawn\* <spawnl>` functions called
with :const:`P_NOWAIT` return suitable process handles.
@@ -2982,7 +2980,7 @@
Similar to :func:`waitpid`, except no process id argument is given and a
3-element tuple containing the child's process id, exit status indication, and
resource usage information is returned. Refer to :mod:`resource`.\
- :func:`getrusage` for details on resource usage information. The option
+ :func:`~resource.getrusage` for details on resource usage information. The option
argument is the same as that provided to :func:`waitpid` and :func:`wait4`.
Availability: Unix.
@@ -2992,7 +2990,7 @@
Similar to :func:`waitpid`, except a 3-element tuple, containing the child's
process id, exit status indication, and resource usage information is returned.
- Refer to :mod:`resource`.\ :func:`getrusage` for details on resource usage
+ Refer to :mod:`resource`.\ :func:`~resource.getrusage` for details on resource usage
information. The arguments to :func:`wait4` are the same as those provided to
:func:`waitpid`.
@@ -3330,7 +3328,7 @@
.. data:: defpath
- The default search path used by :func:`exec\*p\*` and :func:`spawn\*p\*` if the
+ The default search path used by :func:`exec\*p\* <execl>` and :func:`spawn\*p\* <spawnl>` if the
environment doesn't have a ``'PATH'`` key. Also available via :mod:`os.path`.
« 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+