From: Pedro Alves <pedro@palves.net>
To: gdb-patches@sourceware.org
Subject: [PATCH v2 16/16] Document pseudo-terminal and interrupting changes
Date: Mon, 14 Jun 2021 22:24:10 +0100 [thread overview]
Message-ID: <20210614212410.1612666-17-pedro@palves.net> (raw)
In-Reply-To: <20210614212410.1612666-1-pedro@palves.net>
This documents changes done in previous patches:
- the fact that on GNU/Linux, GDB creates a pseudo-terminal for the
inferior instead of juggling terminal settings.
- That when the inferior and GDB share the terminal, you can't
interrupt some programs with Ctrl-C.
- That on GNU/Linux, you may get "Program stopped." instead of
"Program received SIGINT" in response to Ctrl-C.
- That run+detach may result in the program dying with SIGHUP.
I was surprised that we do not currently have a node/section
specifically to talk about interrupting programs. Thus I've added a
new "Interrupting" section under the "Stopping and Continuing"
chapter, with some xrefs to other sections.
gdb/ChangeLog:
yyyy-mm-dd Pedro Alves <pedro@palves.net>
* NEWS: Document pseudo-terminal, "tty /dev/tty" and Ctrl-C/SIGINT
changes. Document "set/show debug managed-tty".
gdb/doc/ChangeLog:
yyyy-mm-dd Pedro Alves <pedro@palves.net>
* gdb.texinfo (Input/Output): Document that GDB may start a
program associated with a pseudo-terminal. Document "tty
/dev/tty". Document "set/show debug managed-tty".
(Attach): Document what happens on run+detach on systems where GDB
creates a pseudo-terminal for the inferior.
(Stopping and Continuing): Add new Interrupting node.
(Background Execution): Add anchor.
(Features for Debugging MS Windows PE Executables): Add anchor.
Change-Id: I267a0f9300c7ac4d2e7f14a9ba8eabc1eafcc5a7
---
gdb/doc/gdb.texinfo | 117 ++++++++++++++++++++++++++++++++++++++++++--
gdb/NEWS | 23 +++++++++
2 files changed, 135 insertions(+), 5 deletions(-)
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index d09b86cda95..a429e9299c6 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -2983,11 +2983,27 @@ current working directory of the debuggee.
@cindex redirection
@cindex i/o
@cindex terminal
-By default, the program you run under @value{GDBN} does input and output to
-the same terminal that @value{GDBN} uses. @value{GDBN} switches the terminal
-to its own terminal modes to interact with you, but it records the terminal
-modes your program was using and switches back to them when you continue
-running your program.
+By default, the program you run under @value{GDBN} does (or
+@value{GDBN} provides the illusion that it does) input and output to
+the same terminal that @value{GDBN} uses.
+
+Depending on the operating system and configuration, either:
+
+@itemize
+
+@item
+@value{GDBN} switches the terminal to its own terminal modes to
+interact with you, but it records the terminal modes your program was
+using and switches back to them when you continue running your
+program. This is the default on most systems.
+
+@item
+@value{GDBN} creates a pseudo-terminal, sets your program to use it
+for standard input and standard output, and forwards input and output
+to and from @value{GDBN}'s terminal at appropriate times. This is the
+default on GNU/Linux.
+
+@end itemize
@table @code
@kindex info terminal
@@ -3023,6 +3039,30 @@ directs that processes started with subsequent @code{run} commands
default to do input and output on the terminal @file{/dev/ttyb} and have
that as their controlling terminal.
+On some operating systems, by default, @value{GDBN} creates a
+pseudo-terminal, and sets your program to use it for standard input
+and standard output. @value{GDBN} takes care of forwarding input and
+output to and from @value{GDBN}'s terminal at appropriate times, so
+this is largely transparent.
+
+On such systems, in some cases, like for example if you need to run
+your program and then detach it, and you want the program to remain
+associated with a terminal, you may prefer that @value{GDBN} starts
+your program using the same device for standard input and output as
+@value{GDBN} is using.
+
+Specifying the special @file{/dev/tty} file as input and output device
+is interpreted as a request for doing I/O to the same terminal that
+@value{GDBN} uses directly, skipping creation of an intermediary
+pseudo-terminal on systems where @value{GDBN} creates one by default.
+
+Note that on GNU/Linux at least, a consequence of using the same
+terminal as @value{GDBN} directly is that programs that block or
+ignore the @code{SIGINT} signal (with e.g., the @code{sigprocmask}
+function), or use the @code{sigwait} function to wait for
+@code{SIGINT} signals can not be interrupted by typing the interrupt
+character (often @kbd{Ctrl-c}).
+
An explicit redirection in @code{run} overrides the @code{tty} command's
effect on the input/output device, but not its effect on the controlling
terminal.
@@ -3050,6 +3090,21 @@ restores the default behavior, which is to use the same terminal as
Show the current tty for the program being debugged.
@end table
+The management of @value{GDBN}-created terminals can be inspected
+using:
+
+@table @code
+@kindex set debug managed-tty
+@item set debug managed-tty @r{[}on|off@r{]}
+Set whether to print debug output about @value{GDBN}-managed
+terminals.
+
+@kindex show debug managed-tty
+@item show debug managed-tty
+Show whether the debug output about @value{GDBN}-managed terminals is
+printed.
+@end table
+
@node Attach
@section Debugging an Already-running Process
@kindex attach
@@ -3132,6 +3187,16 @@ things; you can control whether or not you need to confirm by using the
@code{set confirm} command (@pxref{Messages/Warnings, ,Optional Warnings and
Messages}).
+On systems where @value{GDBN} creates a pseudo-terminal for spawned
+inferiors, detaching from a process that was started by @value{GDBN}
+(for example with the @code{run} command) results in the process
+losing its terminal right after detaching, because @value{GDBN}
+destroys the pseudo-terminal device pair. If you prefer, you can use
+the @code{tty} command command to instruct @value{GDBN} to start your
+program doing I/O to the same terminal that @value{GDBN} uses or to
+some other terminal. @xref{Input/Output, ,Your Program's Input and
+Output}.
+
@node Kill Process
@section Killing the Child Process
@@ -4224,6 +4289,7 @@ running or not, what process it is, and why it stopped.
@menu
* Breakpoints:: Breakpoints, watchpoints, and catchpoints
* Continuing and Stepping:: Resuming execution
+* Interrupting:: Interrupting execution
* Skipping Over Functions and Files::
Skipping over functions and files
* Signals:: Signals
@@ -6376,6 +6442,45 @@ default is @code{on}.
@end table
+@node Interrupting
+@section Interrupting
+
+You can stop the program while it is running in the foreground by
+pressing the interrupt character (often @kbd{Ctrl-c}). If the program
+is executing in the background (@pxref{Background Execution}), you can
+use the @code{interrupt} command (@pxref{interrupt}).
+
+Depending on operating system and configuration, this results in
+interrupting the program with either a @code{SIGINT} signal:
+
+@smallexample
+Program received signal SIGINT, Interrupt.
+@end smallexample
+
+@noindent
+or plainly suspending the program:
+
+@smallexample
+Program stopped.
+@end smallexample
+
+The terminal the program was started with affects whether you get the
+former or the latter. @xref{Input/Output, ,Your Program's Input and
+Output}.
+
+On systems where interrupting the program results in a plain
+suspension instead of the program receiving a @code{SIGINT} signal,
+you can still pass a @code{SIGINT} signal to the program after it
+stops, using either the @code{signal SIGINT} or @code{queue-signal
+SIGINT} commands. @xref{Signaling,,Giving your Program a Signal}.
+
+The remote target supports a number of options to configure how the
+remote program is interrupted. @xref{Remote Configuration}.
+
+@value{GDBN} on MS-Windows supports @kbd{C-@key{BREAK}} as an
+alternative interrupt key sequence. @xref{interrupt debuggee on
+MS-Windows}.
+
@node Skipping Over Functions and Files
@section Skipping Over Functions and Files
@cindex skipping over functions and files
@@ -7090,6 +7195,7 @@ using the @code{interrupt} command.
@table @code
@kindex interrupt
+@anchor{interrupt}
@item interrupt
@itemx interrupt -a
@@ -24219,6 +24325,7 @@ DLLs with and without symbolic debugging information.
@cindex Ctrl-BREAK, MS-Windows
@cindex interrupt debuggee on MS-Windows
+@anchor{interrupt debuggee on MS-Windows}
MS-Windows programs that call @code{SetConsoleMode} to switch off the
special meaning of the @samp{Ctrl-C} keystroke cannot be interrupted
by typing @kbd{C-c}. For this reason, @value{GDBN} on MS-Windows
diff --git a/gdb/NEWS b/gdb/NEWS
index 56743fc9aea..90361d3d330 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -6,6 +6,25 @@
* The 'set disassembler-options' command now supports specifying options
for the ARC target.
+* On GNU/Linux, by default GDB now starts programs associated with a
+ pseudo-terminal slave device created and managed by GDB, instead of
+ having the inferior use the same terminal as GDB directly. GDB
+ takes care of forwarding input and output to and from GDB's terminal
+ at appropriate times, so this is largely transparent.
+
+ In addition, by default, Ctrl-C no longer stops the program with
+ SIGINT. Instead you'll see for example:
+
+ Thread 1 "main" stopped.
+
+ With these changes it is now possible to interrupt programs that
+ block or ignore the SIGINT signal (with e.g., the sigprocmask
+ function), or use the sigwait function to wait for SIGINT signal.
+
+ You can use the "tty /dev/tty" command to restore the previous
+ behavior of spawning programs associated with the same terminal as
+ GDB.
+
* GDB now supports general memory tagging functionality if the underlying
architecture supports the proper primitives and hooks. Currently this is
enabled only for AArch64 MTE.
@@ -84,6 +103,10 @@ set debug event-loop
show debug event-loop
Control the display of debug output about GDB's event loop.
+set debug managed-tty
+show debug managed-tty
+ Control the display of debug output about GDB-managed terminals.
+
set print memory-tag-violations
show print memory-tag-violations
Control whether to display additional information about memory tag violations
--
2.26.2
next prev parent reply other threads:[~2021-06-14 21:28 UTC|newest]
Thread overview: 34+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-06-14 21:23 [PATCH v2 00/16] Interrupting programs that block/ignore SIGINT Pedro Alves
2021-06-14 21:23 ` [PATCH v2 01/16] Test interrupting programs that block SIGINT [gdb/9425, gdb/14559] Pedro Alves
2021-06-14 21:23 ` [PATCH v2 02/16] prefork_hook: Remove 'args' parameter Pedro Alves
2021-06-14 21:23 ` [PATCH v2 03/16] Make gdb.base/long-inferior-output.exp fail fast Pedro Alves
2021-06-14 21:23 ` [PATCH v2 04/16] Fix gdb.multi/multi-term-settings.exp race Pedro Alves
2021-06-14 21:23 ` [PATCH v2 05/16] Don't check parent pid in gdb.threads/{ia64-sigill, siginfo-threads, watchthreads-reorder}.c Pedro Alves
2021-06-14 21:24 ` [PATCH v2 06/16] Special-case "set inferior-tty /dev/tty" Pedro Alves
2021-06-14 21:24 ` [PATCH v2 07/16] Make inferior/GDB share terminal in tests expecting output after detach Pedro Alves
2021-06-14 21:24 ` [PATCH v2 08/16] Make inferior/GDB share terminal in tests that exercise GDB/inferior reading same input Pedro Alves
2021-06-14 21:24 ` [PATCH v2 09/16] gdb.mi/mi-logging.exp, don't send input to GDB while the inferior is running Pedro Alves
2021-06-14 21:24 ` [PATCH v2 10/16] target_terminal::ours_for_output before printing signal received Pedro Alves
2021-06-14 21:24 ` [PATCH v2 11/16] Move scoped_ignore_sigttou to gdbsupport/ Pedro Alves
2021-06-17 21:49 ` Pedro Alves
2021-06-14 21:24 ` [PATCH v2 12/16] Always put inferiors in their own terminal/session [gdb/9425, gdb/14559] Pedro Alves
2021-06-14 21:24 ` [PATCH v2 13/16] exists_non_stop_target: Avoid flushing frames Pedro Alves
2021-06-14 21:24 ` [PATCH v2 14/16] convert previous_inferior_ptid to strong reference to thread_info Pedro Alves
2021-06-14 21:24 ` [PATCH v2 15/16] GNU/Linux: Interrupt/Ctrl-C with SIGSTOP instead of SIGINT [PR gdb/9425, PR gdb/14559] Pedro Alves
2021-07-08 23:05 ` Maciej W. Rozycki
2021-07-13 15:26 ` Pedro Alves
2021-06-14 21:24 ` Pedro Alves [this message]
2021-06-15 12:56 ` [PATCH v2 16/16] Document pseudo-terminal and interrupting changes Eli Zaretskii via Gdb-patches
2021-06-16 9:31 ` Pedro Alves
2021-06-16 12:29 ` Eli Zaretskii via Gdb-patches
2021-06-16 10:15 ` Pedro Alves
2021-06-16 12:15 ` Eli Zaretskii via Gdb-patches
2021-06-16 12:26 ` Pedro Alves
2021-06-16 13:05 ` Eli Zaretskii via Gdb-patches
2021-06-15 12:34 ` [PATCH v2 00/16] Interrupting programs that block/ignore SIGINT Eli Zaretskii via Gdb-patches
2021-06-16 11:27 ` Pedro Alves
2021-06-16 12:45 ` Eli Zaretskii via Gdb-patches
2021-06-18 10:12 ` Andrew Burgess
2021-06-24 18:12 ` Konstantin Kharlamov via Gdb-patches
2021-06-24 18:55 ` Pedro Alves
2021-06-29 1:15 ` Eldar Abusalimov via Gdb-patches
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20210614212410.1612666-17-pedro@palves.net \
--to=pedro@palves.net \
--cc=gdb-patches@sourceware.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox