[PATCH 17/17] Document pseudo-terminal and interrupting changes

[Pedro Alves <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 | 110 ++++++++++++++++++++++++++++++++++++++++++--
 gdb/NEWS            |  23 +++++++++
 2 files changed, 128 insertions(+), 5 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 90d827a50e7..a7e9e9ede7d 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,29 @@ 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.
+
+In some cases, like for example if you need to run your program and
+then detach it, 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 +3089,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 +3186,17 @@ 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) can result in the process
+dying due to a @code{SIGHUP} signal right after detaching, because
+@value{GDBN} destroys the pseudo-terminal device pair.  @value{GDBN}
+detects the situation and asks you for confirmation before detaching.
+To avoid that, you can instruct @value{GDBN} to start your program
+doing I/O to the same terminal that @value{GDBN} uses with the
+@code{tty /dev/tty} command.  @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,38 @@ 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
+
+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}.
+
+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 +7188,7 @@ using the @code{interrupt} command.
 
 @table @code
 @kindex interrupt
+@anchor{interrupt}
 @item interrupt
 @itemx interrupt -a
 
@@ -24219,6 +24318,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 ab678acec8b..a3c7508e8c2 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -3,6 +3,25 @@
 
 *** Changes since GDB 10
 
+* 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.
@@ -81,6 +100,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