mirror of
https://github.com/python/cpython.git
synced 2025-09-27 10:50:04 +00:00
bpo-41825: restructure docs for the os.wait*() family (GH-22356)
(cherry picked from commit 492dc02b01)
Co-authored-by: Georg Brandl <georg@python.org>
This commit is contained in:
Miss Islington (bot)
GitHub
parent
fce9516a0f
commit
1e327059a3
2 changed files with 150 additions and 98 deletions
|
|
@ -4376,6 +4376,9 @@ written in Python, such as a mail server's external command delivery program.
|
|||
number is zero); the high bit of the low byte is set if a core file was
|
||||
produced.
|
||||
|
||||
If there are no children that could be waited for, :exc:`ChildProcessError`
|
||||
is raised.
|
||||
|
||||
:func:`waitstatus_to_exitcode` can be used to convert the exit status into an
|
||||
exit code.
|
||||
|
||||
|
|
@ -4383,76 +4386,40 @@ written in Python, such as a mail server's external command delivery program.
|
|||
|
||||
.. seealso::
|
||||
|
||||
:func:`waitpid` can be used to wait for the completion of a specific
|
||||
child process and has more options.
|
||||
The other :func:`!wait*` functions documented below can be used to wait for the
|
||||
completion of a specific child process and have more options.
|
||||
:func:`waitpid` is the only one also available on Windows.
|
||||
|
||||
|
||||
.. function:: waitid(idtype, id, options, /)
|
||||
|
||||
Wait for the completion of one or more child processes.
|
||||
*idtype* can be :data:`P_PID`, :data:`P_PGID`, :data:`P_ALL`, or
|
||||
:data:`P_PIDFD` on Linux.
|
||||
*id* specifies the pid to wait on.
|
||||
*options* is constructed from the ORing of one or more of :data:`WEXITED`,
|
||||
:data:`WSTOPPED` or :data:`WCONTINUED` and additionally may be ORed with
|
||||
:data:`WNOHANG` or :data:`WNOWAIT`. The return value is an object
|
||||
representing the data contained in the :c:type:`siginfo_t` structure, namely:
|
||||
:attr:`si_pid`, :attr:`si_uid`, :attr:`si_signo`, :attr:`si_status`,
|
||||
:attr:`si_code` or ``None`` if :data:`WNOHANG` is specified and there are no
|
||||
children in a waitable state.
|
||||
Wait for the completion of a child process.
|
||||
|
||||
*idtype* can be :data:`P_PID`, :data:`P_PGID`, :data:`P_ALL`, or (on Linux) :data:`P_PIDFD`.
|
||||
The interpretation of *id* depends on it; see their individual descriptions.
|
||||
|
||||
*options* is an OR combination of flags. At least one of :data:`WEXITED`,
|
||||
:data:`WSTOPPED` or :data:`WCONTINUED` is required;
|
||||
:data:`WNOHANG` and :data:`WNOWAIT` are additional optional flags.
|
||||
|
||||
The return value is an object representing the data contained in the
|
||||
:c:type:`!siginfo_t` structure with the following attributes:
|
||||
|
||||
* :attr:`!si_pid` (process ID)
|
||||
* :attr:`!si_uid` (real user ID of the child)
|
||||
* :attr:`!si_signo` (always :data:`~signal.SIGCHLD`)
|
||||
* :attr:`!si_status` (the exit status or signal number, depending on :attr:`!si_code`)
|
||||
* :attr:`!si_code` (see :data:`CLD_EXITED` for possible values)
|
||||
|
||||
If :data:`WNOHANG` is specified and there are no matching children in the
|
||||
requested state, ``None`` is returned.
|
||||
Otherwise, if there are no matching children
|
||||
that could be waited for, :exc:`ChildProcessError` is raised.
|
||||
|
||||
.. availability:: Unix, not Emscripten, not WASI.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
.. data:: P_PID
|
||||
P_PGID
|
||||
P_ALL
|
||||
|
||||
These are the possible values for *idtype* in :func:`waitid`. They affect
|
||||
how *id* is interpreted.
|
||||
|
||||
.. availability:: Unix, not Emscripten, not WASI.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
.. data:: P_PIDFD
|
||||
|
||||
This is a Linux-specific *idtype* that indicates that *id* is a file
|
||||
descriptor that refers to a process.
|
||||
|
||||
.. availability:: Linux >= 5.4
|
||||
|
||||
.. versionadded:: 3.9
|
||||
|
||||
.. data:: WEXITED
|
||||
WSTOPPED
|
||||
WNOWAIT
|
||||
|
||||
Flags that can be used in *options* in :func:`waitid` that specify what
|
||||
child signal to wait for.
|
||||
|
||||
.. availability:: Unix, not Emscripten, not WASI.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
|
||||
.. data:: CLD_EXITED
|
||||
CLD_KILLED
|
||||
CLD_DUMPED
|
||||
CLD_TRAPPED
|
||||
CLD_STOPPED
|
||||
CLD_CONTINUED
|
||||
|
||||
These are the possible values for :attr:`si_code` in the result returned by
|
||||
:func:`waitid`.
|
||||
|
||||
.. availability:: Unix, not Emscripten, not WASI.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
.. versionchanged:: 3.9
|
||||
Added :data:`CLD_KILLED` and :data:`CLD_STOPPED` values.
|
||||
|
||||
|
||||
.. function:: waitpid(pid, options, /)
|
||||
|
||||
|
|
@ -4470,8 +4437,11 @@ written in Python, such as a mail server's external command delivery program.
|
|||
``-1``, status is requested for any process in the process group ``-pid`` (the
|
||||
absolute value of *pid*).
|
||||
|
||||
An :exc:`OSError` is raised with the value of errno when the syscall
|
||||
returns -1.
|
||||
*options* is an OR combination of flags. If it contains :data:`WNOHANG` and
|
||||
there are no matching children in the requested state, ``(0, 0)`` is
|
||||
returned. Otherwise, if there are no matching children that could be waited
|
||||
for, :exc:`ChildProcessError` is raised. Other options that can be used are
|
||||
:data:`WUNTRACED` and :data:`WCONTINUED`.
|
||||
|
||||
On Windows: Wait for completion of a process given by process handle *pid*, and
|
||||
return a tuple containing *pid*, and its exit status shifted left by 8 bits
|
||||
|
|
@ -4484,7 +4454,7 @@ written in Python, such as a mail server's external command delivery program.
|
|||
:func:`waitstatus_to_exitcode` can be used to convert the exit status into an
|
||||
exit code.
|
||||
|
||||
.. availability:: Unix, not Emscripten, not WASI.
|
||||
.. availability:: Unix, Windows, not Emscripten, not WASI.
|
||||
|
||||
.. versionchanged:: 3.5
|
||||
If the system call is interrupted and the signal handler does not raise an
|
||||
|
|
@ -4497,9 +4467,9 @@ written in Python, such as a mail server's external command delivery program.
|
|||
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:`~resource.getrusage` for details on resource usage
|
||||
information. The option argument is the same as that provided to
|
||||
:func:`waitpid` and :func:`wait4`.
|
||||
:func:`resource.getrusage` for details on resource usage information. The
|
||||
*options* argument is the same as that provided to :func:`waitpid` and
|
||||
:func:`wait4`.
|
||||
|
||||
:func:`waitstatus_to_exitcode` can be used to convert the exit status into an
|
||||
exitcode.
|
||||
|
|
@ -4510,10 +4480,10 @@ written in Python, such as a mail server's external command delivery program.
|
|||
.. function:: wait4(pid, options)
|
||||
|
||||
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:`~resource.getrusage` for details on
|
||||
resource usage information. The arguments to :func:`wait4` are the same
|
||||
as those provided to :func:`waitpid`.
|
||||
process id, exit status indication, and resource usage information is
|
||||
returned. Refer to :func:`resource.getrusage` for details on resource usage
|
||||
information. The arguments to :func:`wait4` are the same as those provided
|
||||
to :func:`waitpid`.
|
||||
|
||||
:func:`waitstatus_to_exitcode` can be used to convert the exit status into an
|
||||
exitcode.
|
||||
|
|
@ -4521,6 +4491,111 @@ written in Python, such as a mail server's external command delivery program.
|
|||
.. availability:: Unix, not Emscripten, not WASI.
|
||||
|
||||
|
||||
.. data:: P_PID
|
||||
P_PGID
|
||||
P_ALL
|
||||
P_PIDFD
|
||||
|
||||
These are the possible values for *idtype* in :func:`waitid`. They affect
|
||||
how *id* is interpreted:
|
||||
|
||||
* :data:`!P_PID` - wait for the child whose PID is *id*.
|
||||
* :data:`!P_PGID` - wait for any child whose progress group ID is *id*.
|
||||
* :data:`!P_ALL` - wait for any child; *id* is ignored.
|
||||
* :data:`!P_PIDFD` - wait for the child identified by the file descriptor
|
||||
*id* (a process file descriptor created with :func:`pidfd_open`).
|
||||
|
||||
.. availability:: Unix, not Emscripten, not WASI.
|
||||
|
||||
.. note:: :data:`!P_PIDFD` is only available on Linux >= 5.4.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
.. versionadded:: 3.9
|
||||
The :data:`!P_PIDFD` constant.
|
||||
|
||||
|
||||
.. data:: WCONTINUED
|
||||
|
||||
This *options* flag for :func:`waitpid`, :func:`wait3`, :func:`wait4`, and
|
||||
:func:`waitid` causes child processes to be reported if they have been
|
||||
continued from a job control stop since they were last reported.
|
||||
|
||||
.. availability:: Unix, not Emscripten, not WASI.
|
||||
|
||||
|
||||
.. data:: WEXITED
|
||||
|
||||
This *options* flag for :func:`waitid` causes child processes that have terminated to
|
||||
be reported.
|
||||
|
||||
The other ``wait*`` functions always report children that have terminated,
|
||||
so this option is not available for them.
|
||||
|
||||
.. availability:: Unix, not Emscripten, not WASI.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
|
||||
.. data:: WSTOPPED
|
||||
|
||||
This *options* flag for :func:`waitid` causes child processes that have been stopped
|
||||
by the delivery of a signal to be reported.
|
||||
|
||||
This option is not available for the other ``wait*`` functions.
|
||||
|
||||
.. availability:: Unix, not Emscripten, not WASI.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
|
||||
.. data:: WUNTRACED
|
||||
|
||||
This *options* flag for :func:`waitpid`, :func:`wait3`, and :func:`wait4` causes
|
||||
child processes to also be reported if they have been stopped but their
|
||||
current state has not been reported since they were stopped.
|
||||
|
||||
This option is not available for :func:`waitid`.
|
||||
|
||||
.. availability:: Unix, not Emscripten, not WASI.
|
||||
|
||||
|
||||
.. data:: WNOHANG
|
||||
|
||||
This *options* flag causes :func:`waitpid`, :func:`wait3`, :func:`wait4`, and
|
||||
:func:`waitid` to return right away if no child process status is available
|
||||
immediately.
|
||||
|
||||
.. availability:: Unix, not Emscripten, not WASI.
|
||||
|
||||
|
||||
.. data:: WNOWAIT
|
||||
|
||||
This *options* flag causes :func:`waitid` to leave the child in a waitable state, so that
|
||||
a later :func:`!wait*` call can be used to retrieve the child status information again.
|
||||
|
||||
This option is not available for the other ``wait*`` functions.
|
||||
|
||||
.. availability:: Unix, not Emscripten, not WASI.
|
||||
|
||||
|
||||
.. data:: CLD_EXITED
|
||||
CLD_KILLED
|
||||
CLD_DUMPED
|
||||
CLD_TRAPPED
|
||||
CLD_STOPPED
|
||||
CLD_CONTINUED
|
||||
|
||||
These are the possible values for :attr:`!si_code` in the result returned by
|
||||
:func:`waitid`.
|
||||
|
||||
.. availability:: Unix, not Emscripten, not WASI.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
.. versionchanged:: 3.9
|
||||
Added :data:`CLD_KILLED` and :data:`CLD_STOPPED` values.
|
||||
|
||||
|
||||
.. function:: waitstatus_to_exitcode(status)
|
||||
|
||||
Convert a wait status to an exit code.
|
||||
|
|
@ -4553,32 +4628,6 @@ written in Python, such as a mail server's external command delivery program.
|
|||
.. versionadded:: 3.9
|
||||
|
||||
|
||||
.. data:: WNOHANG
|
||||
|
||||
The option for :func:`waitpid` to return immediately if no child process status
|
||||
is available immediately. The function returns ``(0, 0)`` in this case.
|
||||
|
||||
.. availability:: Unix, not Emscripten, not WASI.
|
||||
|
||||
|
||||
.. data:: WCONTINUED
|
||||
|
||||
This option causes child processes to be reported if they have been continued
|
||||
from a job control stop since their status was last reported.
|
||||
|
||||
.. availability:: Unix, not Emscripten, not WASI.
|
||||
|
||||
Some Unix systems.
|
||||
|
||||
|
||||
.. data:: WUNTRACED
|
||||
|
||||
This option causes child processes to be reported if they have been stopped but
|
||||
their current state has not been reported since they were stopped.
|
||||
|
||||
.. availability:: Unix, not Emscripten, not WASI.
|
||||
|
||||
|
||||
The following functions take a process status code as returned by
|
||||
:func:`system`, :func:`wait`, or :func:`waitpid` as a parameter. They may be
|
||||
used to determine the disposition of a process.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,3 @@
|
|||
Restructured the documentation for the :func:`os.wait* <os.wait>` family of functions,
|
||||
and improved the docs for :func:`os.waitid` with more explanation of the
|
||||
possible argument constants.
|
||||
Loading…
Add table
Add a link
Reference in a new issue