[v2,16/16] Document pseudo-terminal and interrupting changes

Message ID 20210614212410.1612666-17-pedro@palves.net
State New
Headers show
Series
  • Interrupting programs that block/ignore SIGINT
Related show

Commit Message

Pedro Alves June 14, 2021, 9:24 p.m.
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(-)

-- 
2.26.2

Comments

Luis Machado via Gdb-patches June 15, 2021, 12:56 p.m. | #1
> From: Pedro Alves <pedro@palves.net>

> Date: Mon, 14 Jun 2021 22:24:10 +0100

> 

> +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.


This doesn't read well.  I suggest to make "Either" and "Or" part of
the text, like this:

  Depending on the operating system and configuration:

  @itemize

  @item
  Either @value{GDBN} switches the terminal ...

  @item
  Or @value{GDB} creates a pseudo-terminal ...

> +@value{GDBN} creates a pseudo-terminal, sets your program to use it

> +for standard input and standard output

       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This begs the question about the standard error stream.

> +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.


The 2 different behaviors are described somewhat inconsistently: in
one place you say "most systems" vs "GNU/Linux", in another place
"some operating systems" instead of "GNU/Linux", and in yet another
place you say "on systems where GDB creates a pseudo-terminal".  Can
you describe the pseudo-terminal feature consistently as a GNU/Linux
feature?

Also, describing the feature in a single place, and just having a
cross-reference to there in other places will go a long way towards
making the description clear and complete.

> +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.


IMHO, this is a misfeature.  If the terminal from which GDB was run
remains on the system, it would be an unpleasant surprise for the user
that the program gets hit by SIGHUP when you detach.  I think we
should try to avoid this side effect, if that's feasible.

> +@node Interrupting

> +@section Interrupting


Once again, I'd prefer to talk about "stopping" instead.  Or maybe
even "getting control to GDB".

> +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


This seems to be inaccurate.  On MS-Windows, for example, I see
something different:

  Thread 4 received signal SIGTRAP, Trace/breakpoint trap.

So maybe you want to say that the above is only true for Posix hosts.
Or maybe just be more vague and don't try quoting the messages?

> +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}.


This begs a question I already asked elsewhere: I'd expect that
continuing the program after it was stopped like that will deliver
SIGINT to the program, without any special commands.  Isn't that so?
Your text seems to imply that it isn't, which I find surprising --
after all, the user pressed Ctrl-C, so "normally" the debuggee should
be hit with SIGINT, as if we were not debugging it.

> +@value{GDBN} on MS-Windows supports @kbd{C-@key{BREAK}} as an

> +alternative interrupt key sequence.  @xref{interrupt debuggee on

> +MS-Windows}.


I'm not sure I understand the significance of this note: after all, a
Windows program can install a Ctrl-BREAK handler exactly like it does
with Ctrl-C.  Is this only about SetConsoleMode?

Thanks.
Pedro Alves June 16, 2021, 9:31 a.m. | #2
Hi!

On 2021-06-15 1:56 p.m., Eli Zaretskii wrote:
>> +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.

> IMHO, this is a misfeature.  If the terminal from which GDB was run

> remains on the system, it would be an unpleasant surprise for the user

> that the program gets hit by SIGHUP when you detach.  I think we

> should try to avoid this side effect, if that's feasible.

> 


Hmm, I'm not sure I follow what you're saying here, maybe I'm misunderstanding.

We no longer get a SIGHUP on detach, that was fixed on v2.  What the text is saying now is
different: because when you start your program with "run", the terminal the inferior is
associated with was created by GDB, when you "detach", GDB destroys the terminal.  The
result is that the program you detached from loses its terminal.  From the detached
program's perspective, it's the same as with current GDB when you do "run", then "detach",
and then close the GDB terminal.  The difference is that with my patches the program
loses its terminal a step earlier.  In v1, the detached program would also get a SIGHUP, 
but that was fixed in v2, it no longer does.

If you really need to do "run" and then "detach" for some reason, _and_ you want
your program to have a terminal, you should start the program with a specified
terminal, like:

 - start the program outside gdb, and then use "attach".  Make sure the terminal
   you started the program at remains alive.

 - use the "tty" command to tell GDB to start the program on some specified terminal 
   (which will outlive gdb and gdb's terminal)

If you're sure gdb's terminal will stay around, and you want to tell GDB to start
the program on that terminal, you can use the "tty /dev/tty" command before starting
the program.

Is this clearer?  I can try to adjust the documentation to explain this better and be more
descriptive like above. 

Thanks,
Pedro Alves
Pedro Alves June 16, 2021, 10:15 a.m. | #3
Hi Eli,

It will take me a bit to actually go implement changes, but here are some responses.

On 2021-06-15 1:56 p.m., Eli Zaretskii wrote:
>> From: Pedro Alves <pedro@palves.net>

>> Date: Mon, 14 Jun 2021 22:24:10 +0100

>>

>> +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.

> 

> This doesn't read well.  I suggest to make "Either" and "Or" part of

> the text, like this:

> 

>   Depending on the operating system and configuration:

> 

>   @itemize

> 

>   @item

>   Either @value{GDBN} switches the terminal ...

> 

>   @item

>   Or @value{GDB} creates a pseudo-terminal ...

> 

>> +@value{GDBN} creates a pseudo-terminal, sets your program to use it

>> +for standard input and standard output

>        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

> This begs the question about the standard error stream.


Indeed.  I think I'll drop the word "standard".

> 

>> +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.

> 

> The 2 different behaviors are described somewhat inconsistently: in

> one place you say "most systems" vs "GNU/Linux", in another place

> "some operating systems" instead of "GNU/Linux", and in yet another

> place you say "on systems where GDB creates a pseudo-terminal".  Can

> you describe the pseudo-terminal feature consistently as a GNU/Linux

> feature?


Yeah, I'll take a fresh look.  I was thinking that in the future other Unix
hosts will be switched to use this feature as well, and we tend to forget updating
such references in the manual.

> 

> Also, describing the feature in a single place, and just having a

> cross-reference to there in other places will go a long way towards

> making the description clear and complete.

> 

>> +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.

> 

> IMHO, this is a misfeature.  If the terminal from which GDB was run

> remains on the system, it would be an unpleasant surprise for the user

> that the program gets hit by SIGHUP when you detach.  I think we

> should try to avoid this side effect, if that's feasible.

> 

>> +@node Interrupting

>> +@section Interrupting

> 

> Once again, I'd prefer to talk about "stopping" instead.  Or maybe

> even "getting control to GDB".

> 

>> +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

> 

> This seems to be inaccurate.  On MS-Windows, for example, I see

> something different:

> 

>   Thread 4 received signal SIGTRAP, Trace/breakpoint trap.

> 

> So maybe you want to say that the above is only true for Posix hosts.

> Or maybe just be more vague and don't try quoting the messages?

> 

>> +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}.

> 

> This begs a question I already asked elsewhere: I'd expect that

> continuing the program after it was stopped like that will deliver

> SIGINT to the program, without any special commands.  Isn't that so?

> Your text seems to imply that it isn't, which I find surprising --

> after all, the user pressed Ctrl-C, so "normally" the debuggee should

> be hit with SIGINT, as if we were not debugging it.


This was discussed in the other thread, but what you're saying really isn't
correct -- continuing the program after it was stopped doesn't normally
make the the debuggee receive the SIGINT.  Only if you explicitly pass it,
with special commands.

> 

>> +@value{GDBN} on MS-Windows supports @kbd{C-@key{BREAK}} as an

>> +alternative interrupt key sequence.  @xref{interrupt debuggee on

>> +MS-Windows}.

> 

> I'm not sure I understand the significance of this note: after all, a

> Windows program can install a Ctrl-BREAK handler exactly like it does

> with Ctrl-C.  Is this only about SetConsoleMode?


I was creating a new "Interrupting" node in the manual, so I thought it
was a good place to put cross references to other places in the manual
that talk about interruption.  That's all this is.  Just like the
reference to the remote debug section.
Luis Machado via Gdb-patches June 16, 2021, 12:15 p.m. | #4
> From: Pedro Alves <pedro@palves.net>

> Cc: gdb-patches@sourceware.org

> Date: Wed, 16 Jun 2021 11:15:38 +0100

> 

> >> +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}.

> > 

> > This begs a question I already asked elsewhere: I'd expect that

> > continuing the program after it was stopped like that will deliver

> > SIGINT to the program, without any special commands.  Isn't that so?

> > Your text seems to imply that it isn't, which I find surprising --

> > after all, the user pressed Ctrl-C, so "normally" the debuggee should

> > be hit with SIGINT, as if we were not debugging it.

> 

> This was discussed in the other thread, but what you're saying really isn't

> correct -- continuing the program after it was stopped doesn't normally

> make the the debuggee receive the SIGINT.  Only if you explicitly pass it,

> with special commands.


If you are talking about the default value of "handle SIGINT", then it
is still possible (and IMO advisable) to mention that the signal will
be passed to the debuggee, except that the default setting of SIGINT
handling purposefully prevents that.

> >> +@value{GDBN} on MS-Windows supports @kbd{C-@key{BREAK}} as an

> >> +alternative interrupt key sequence.  @xref{interrupt debuggee on

> >> +MS-Windows}.

> > 

> > I'm not sure I understand the significance of this note: after all, a

> > Windows program can install a Ctrl-BREAK handler exactly like it does

> > with Ctrl-C.  Is this only about SetConsoleMode?

> 

> I was creating a new "Interrupting" node in the manual, so I thought it

> was a good place to put cross references to other places in the manual

> that talk about interruption.  That's all this is.  Just like the

> reference to the remote debug section.


My point was more general: why are we taking such a great care
publishing the Ctrl-BREAK support?  What's the big deal?
Pedro Alves June 16, 2021, 12:26 p.m. | #5
On 2021-06-16 1:15 p.m., Eli Zaretskii wrote:
>>>> +@value{GDBN} on MS-Windows supports @kbd{C-@key{BREAK}} as an

>>>> +alternative interrupt key sequence.  @xref{interrupt debuggee on

>>>> +MS-Windows}.

>>> I'm not sure I understand the significance of this note: after all, a

>>> Windows program can install a Ctrl-BREAK handler exactly like it does

>>> with Ctrl-C.  Is this only about SetConsoleMode?

>> I was creating a new "Interrupting" node in the manual, so I thought it

>> was a good place to put cross references to other places in the manual

>> that talk about interruption.  That's all this is.  Just like the

>> reference to the remote debug section.

> My point was more general: why are we taking such a great care

> publishing the Ctrl-BREAK support?  What's the big deal?

> 


The text that I was xrefing reads:

 @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
 supports @kbd{C-@key{BREAK}} as an alternative interrupt key
 sequence, which can be used to interrupt the debuggee even if it
 ignores @kbd{C-c}.

And the sentence I wrote was just my attempt to summarize this information
so that the xref made any sense.  How would you go about this?  

- Say something different in the xref?  What?

- Remove the xref completely?  

- Move the whole text to the new Interrupt section (removing it from its original place)?

Thanks,
Pedro Alves
Luis Machado via Gdb-patches June 16, 2021, 12:29 p.m. | #6
> From: Pedro Alves <pedro@palves.net>

> Cc: gdb-patches@sourceware.org

> Date: Wed, 16 Jun 2021 10:31:27 +0100

> 

> >> +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.

> > IMHO, this is a misfeature.  If the terminal from which GDB was run

> > remains on the system, it would be an unpleasant surprise for the user

> > that the program gets hit by SIGHUP when you detach.  I think we

> > should try to avoid this side effect, if that's feasible.

> > 

> 

> Hmm, I'm not sure I follow what you're saying here, maybe I'm misunderstanding.

> 

> We no longer get a SIGHUP on detach, that was fixed on v2.  What the text is saying now is

> different: because when you start your program with "run", the terminal the inferior is

> associated with was created by GDB, when you "detach", GDB destroys the terminal.  The

> result is that the program you detached from loses its terminal.


I understood that, and this is what I was calling "a misfeature"
above.

> From the detached

> program's perspective, it's the same as with current GDB when you do "run", then "detach",

> and then close the GDB terminal.


_Technically_ it is the same.  But from the user POV, it isn't, not
unless the user closes the terminal from which he/she invoked GDB.  As
long as that terminal stays, the user might be surprised to see the
program behaving as if the terminal was closed.

> If you really need to do "run" and then "detach" for some reason, _and_ you want

> your program to have a terminal, you should start the program with a specified

> terminal, like:

> 

>  - start the program outside gdb, and then use "attach".  Make sure the terminal

>    you started the program at remains alive.

> 

>  - use the "tty" command to tell GDB to start the program on some specified terminal 

>    (which will outlive gdb and gdb's terminal)

> 

> If you're sure gdb's terminal will stay around, and you want to tell GDB to start

> the program on that terminal, you can use the "tty /dev/tty" command before starting

> the program.


I understand.  Your description is clear.  I'm saying that it would be
good to avoid this side effect, if possible.  If not, users will have
to live with it.
Luis Machado via Gdb-patches June 16, 2021, 1:05 p.m. | #7
> From: Pedro Alves <pedro@palves.net>

> Cc: gdb-patches@sourceware.org

> Date: Wed, 16 Jun 2021 13:26:33 +0100

> 

> The text that I was xrefing reads:

> 

>  @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

>  supports @kbd{C-@key{BREAK}} as an alternative interrupt key

>  sequence, which can be used to interrupt the debuggee even if it

>  ignores @kbd{C-c}.

> 

> And the sentence I wrote was just my attempt to summarize this information

> so that the xref made any sense.  How would you go about this?  

> 

> - Say something different in the xref?  What?

> 

> - Remove the xref completely?  

> 

> - Move the whole text to the new Interrupt section (removing it from its original place)?


Your text and cross-reference are okay, no need to change anything.
Sorry for the noise.

Patch

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