From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-wr1-f48.google.com (mail-wr1-f48.google.com [209.85.221.48]) by sourceware.org (Postfix) with ESMTPS id 37D683990019 for ; Thu, 3 Jun 2021 19:03:25 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 37D683990019 Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=palves.net Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=gmail.com Received: by mail-wr1-f48.google.com with SMTP id z8so6873502wrp.12 for ; Thu, 03 Jun 2021 12:03:25 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=AO23bojmYH3fxAqHMeXVdGptRUQ0Dz+MH9RcSFrtxxw=; b=T4RNjcSf5o5JqEssdJYsmDAxNjY9UC4KBhXl/L5+xIPURXk/auHMGoOVerqS+Fkjhy NZL6vpN2yJTnFdsR3vxLHITwrXjy9tynmjqTMp89On62JiGZUr4ItI3hbU/LnJyHIJJK k6mLOvayAjQbt0sZR/fldi03SEmv0axv1kn0MOQE+B+0xWSahVlvIMPJuwo7G59sEBxj 5AZup1grgl63NK9n6pxBD+hzmW3wl5gqjAzzF05V0HWpsOCbcSLJi5y+n7ulGBn1qR0P VYqOSXZNHQkWCmibRj/is6xLXFIT9ipL7s8+39ijj6ZrCWLdOv/FWfl7HyIhD5XHs9vn uuEw== X-Gm-Message-State: AOAM533oVtEa0zrpaKf3dv/IRiwVA+VdFuF2Hy3soIsV3AfFNScNnRtJ aL/JegyIyd6pccWd6yzpiXQd48xLS6vieg== X-Google-Smtp-Source: ABdhPJwXcXPSFPK01xx480PayQYN8/elwMGWnMLaN2XJoqLcXbACzPKFB05VpxuIhm2hX3J93kX89Q== X-Received: by 2002:adf:ce90:: with SMTP id r16mr2272wrn.146.1622747003568; Thu, 03 Jun 2021 12:03:23 -0700 (PDT) Received: from localhost ([2001:8a0:f932:6a00:6b6e:c7b6:c5a7:aac3]) by smtp.gmail.com with ESMTPSA id g26sm6238113wmh.24.2021.06.03.12.03.22 for (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Thu, 03 Jun 2021 12:03:22 -0700 (PDT) From: Pedro Alves To: gdb-patches@sourceware.org Subject: [PATCH 17/17] Document pseudo-terminal and interrupting changes Date: Thu, 3 Jun 2021 20:02:43 +0100 Message-Id: <20210603190243.2609886-18-pedro@palves.net> X-Mailer: git-send-email 2.26.2 In-Reply-To: <20210603190243.2609886-1-pedro@palves.net> References: <20210603190243.2609886-1-pedro@palves.net> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=-9.9 required=5.0 tests=BAYES_00, FREEMAIL_FORGED_FROMDOMAIN, FREEMAIL_FROM, GIT_PATCH_0, HEADER_FROM_DIFFERENT_DOMAINS, KAM_DMARC_STATUS, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H2, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.2 X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on server2.sourceware.org X-BeenThere: gdb-patches@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gdb-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 03 Jun 2021 19:03:27 -0000 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 * 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 * 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