Re: [PATCH v2 16/16] Document pseudo-terminal and interrupting changes

[Pedro Alves <pedro@palves.net>]

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.