From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from simark.ca by simark.ca with LMTP id EOTPNvvJx2DNUQAAWB0awg (envelope-from ) for ; Mon, 14 Jun 2021 17:28:27 -0400 Received: by simark.ca (Postfix, from userid 112) id DE1961F163; Mon, 14 Jun 2021 17:28:27 -0400 (EDT) X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on simark.ca X-Spam-Level: X-Spam-Status: No, score=-0.6 required=5.0 tests=MAILING_LIST_MULTI, RDNS_DYNAMIC,URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.2 Received: from sourceware.org (ip-8-43-85-97.sourceware.org [8.43.85.97]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by simark.ca (Postfix) with ESMTPS id 6E5D21E54D for ; Mon, 14 Jun 2021 17:28:26 -0400 (EDT) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 3BDE13973006 for ; Mon, 14 Jun 2021 21:28:26 +0000 (GMT) Received: from mail-wr1-f42.google.com (mail-wr1-f42.google.com [209.85.221.42]) by sourceware.org (Postfix) with ESMTPS id 4D48A3973008 for ; Mon, 14 Jun 2021 21:24:47 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 4D48A3973008 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-f42.google.com with SMTP id z8so15980614wrp.12 for ; Mon, 14 Jun 2021 14:24:47 -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=9Yk7o0OwIUMgmzXjZN9mj7cdTM3vuXw43TtoBCSN4vo=; b=X99xTD0FaC7e/aTQ8k8g4Q4TNLp6uzN40IC1mmpeWbNlHj7V8mA+xgTdEpql4EtIAM B3buS4mk7ChD91smGA+89mSvkpndECQB0DrKf3QcvrN3V8DoTCXZUCmpM5qoiRF9FwER 2coO+xJ5dSqax4G06B2B/gVAnwcozsrFSJAYQusQCnl9pkQb7WELj1TBPtgBZUg4S0+q 4OJAftY4/lh9hS2WMAQ7eS+wN5/DNb/UNVOJEP+x6F3xUwBcEVMDi5ZZ1yoVB5S8MwYd bFTcgvIt8TtICVchPeemueg+WRKBLSjKIa8NHua9nzvN7BLr0tb4Ns6/c3R54BMJ7RgM Fd2w== X-Gm-Message-State: AOAM531SG7dWLWnnCtkbkarDhF6MWX0fCjU/HhdSyLIu1GYQdJfpERzi xa9vPjI/PRMFgWGzjyJmiNJ4xwEahf/nSg== X-Google-Smtp-Source: ABdhPJxEQikf9l8bZgE9FL5YPlv2urCA8D94zllizZ43qM5UaoJCtMSLK+556IDr+5TJQJhha/0HuQ== X-Received: by 2002:a5d:6da9:: with SMTP id u9mr11641451wrs.167.1623705885772; Mon, 14 Jun 2021 14:24:45 -0700 (PDT) Received: from localhost ([2001:8a0:f932:6a00:6b6e:c7b6:c5a7:aac3]) by smtp.gmail.com with ESMTPSA id b15sm8168322wru.13.2021.06.14.14.24.44 for (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Mon, 14 Jun 2021 14:24:44 -0700 (PDT) From: Pedro Alves 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 Message-Id: <20210614212410.1612666-17-pedro@palves.net> X-Mailer: git-send-email 2.26.2 In-Reply-To: <20210614212410.1612666-1-pedro@palves.net> References: <20210614212410.1612666-1-pedro@palves.net> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit 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: , Errors-To: gdb-patches-bounces+public-inbox=simark.ca@sourceware.org Sender: "Gdb-patches" 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 | 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