Add documentation for remote debugging with pdb (#134260)

* Mention remote debugging via -p PID in usage text

Adds a brief note to the pdb help summary about attaching to a running
process using the -p option, making the remote debugging feature
more visible.

* Mention remote debugging in pdb.rst

diff --git a/Doc/library/pdb.rst b/Doc/library/pdb.rst
index a0304edddf6478949825bc04e873ddfa80585bd8..f4b51664545be588a3de4a5ae6a180a678c79a56 100644 (file)
--- a/Doc/library/pdb.rst
+++ b/Doc/library/pdb.rst
@@ -80,7 +80,7 @@ The debugger's prompt is ``(Pdb)``, which is the indicator that you are in debug
 You can also invoke :mod:`pdb` from the command line to debug other scripts.  For
 example::
 
-   python -m pdb [-c command] (-m module | pyfile) [args ...]
+   python -m pdb [-c command] (-m module | -p pid | pyfile) [args ...]
 
 When invoked as a module, pdb will automatically enter post-mortem debugging if
 the program being debugged exits abnormally.  After post-mortem debugging (or
@@ -104,6 +104,24 @@ useful than quitting the debugger upon program's exit.
    .. versionchanged:: 3.7
       Added the ``-m`` option.
 
+.. option:: -p, --pid <pid>
+
+   Attach to the process with the specified PID.
+
+   .. versionadded:: 3.14
+
+
+To attach to a running Python process for remote debugging, use the ``-p`` or
+``--pid`` option with the target process's PID::
+
+   python -m pdb -p 1234
+
+.. note::
+
+   Attaching to a process that is blocked in a system call or waiting for I/O
+   will only work once the next bytecode instruction is executed or when the
+   process receives a signal.
+
 Typical usage to execute a statement under control of the debugger is::
 
    >>> import pdb

diff --git a/Lib/pdb.py b/Lib/pdb.py
index 544c701bbd2c72b1d2ad96c49337b4478db3ab92..78ee35f61bbceaf72dc479023410a82be48fad57 100644 (file)
--- a/Lib/pdb.py
+++ b/Lib/pdb.py
@@ -3489,7 +3489,8 @@ def help():
 _usage = """\
 Debug the Python program given by pyfile. Alternatively,
 an executable module or package to debug can be specified using
-the -m switch.
+the -m switch. You can also attach to a running Python process
+using the -p option with its PID.
 
 Initial commands are read from .pdbrc files in your home directory
 and in the current directory, if they exist.  Commands supplied with