From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from eggs.gnu.org (eggs.gnu.org [IPv6:2001:470:142:3::10]) by sourceware.org (Postfix) with ESMTPS id 43D493858D33 for ; Mon, 13 Feb 2023 15:37:15 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 43D493858D33 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=gnu.org Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=gnu.org Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pRatG-0007Ts-Fe; Mon, 13 Feb 2023 10:37:14 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=c4TADZxf86oBUpGgeeuCM3McRv/oCmx5U/ZKil66EKI=; b=XLeNbP+YxmmX VFqFOekPtnipZZKinuEGv3SrZL/Tg6P0fCuAs+ewZTtWWiUuApaeuFTDD4oLhqff+KwYKA6e4TzIJ ekEyI2mue6RVxoqyKiroSIxge6MkoxzQNIMHY7sb4y+pH0TLjXfTVXADxKoBpzNr7HPDFQhxtFXyT 1pXTuQp+dNFe338QP3BX9vw24+S/MiFpqEJcaPT6/xEP9m0shnqLSXxxAW0stt/bstHaIfo2Poqu/ 4oymqS2CI/Wt2oMW8gdV5HkgfONGvhra8dUXPc/+3ARyL/m50q9MkoLld29+fcOWNUVrD67sg0iDr eDCYbyaBxRFtCjEaNGzGxA==; Received: from [87.69.77.57] (helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pRatF-0007dm-Sn; Mon, 13 Feb 2023 10:37:14 -0500 Date: Mon, 13 Feb 2023 17:36:50 +0200 Message-Id: <833579fugd.fsf@gnu.org> From: Eli Zaretskii To: Pedro Alves Cc: gdb-patches@sourceware.org In-Reply-To: <439ab6f5-ec2d-87ef-d84c-3ace9ead93a8@palves.net> (message from Pedro Alves on Mon, 13 Feb 2023 15:11:45 +0000) Subject: Re: [PATCH 3/6] Add new "$_shell(CMD)" internal function References: <20230210233604.2228450-1-pedro@palves.net> <20230210233604.2228450-4-pedro@palves.net> <83r0uwk4tm.fsf@gnu.org> <439ab6f5-ec2d-87ef-d84c-3ace9ead93a8@palves.net> X-Spam-Status: No, score=1.9 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_BARRACUDACENTRAL,SPF_HELO_PASS,SPF_PASS,TXREP autolearn=no autolearn_force=no version=3.4.6 X-Spam-Level: * X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org List-Id: > Cc: gdb-patches@sourceware.org > From: Pedro Alves > Date: Mon, 13 Feb 2023 15:11:45 +0000 > > I guess I should instead use that style here too? I've done that now, and here's > what we get: > > (gdb) help function _shell > $_shell - execute a shell command and return the result. > > Usage: $_shell (COMMAND) > > Arguments: > > COMMAND: The command to execute. Must be a string. > > Returns: > The command's exit code: zero on success, non-zero otherwise. > > > WDYT? OK. > >> +@anchor{$_shell convenience function} > >> +@item $_shell (@var{command-string}) > >> +@findex $_shell@r{, convenience function} > > > > @fined should be _before_ @item, so that the index records the > > position of @item, and the Info reader places you before the @item > > when you use index-search. > > But the whole "Convenience Funs" node has has item/findex sorted like that, > I just copied the preceding example. Here's what we have: > > @item $_isvoid (@var{expr}) > @findex $_isvoid@r{, convenience function} > ... > @item $_gdb_setting_str (@var{setting}) > @findex $_gdb_setting_str@r{, convenience function} > ... > @item $_gdb_setting (@var{setting}) > @findex $_gdb_setting@r{, convenience function} > ... > @item $_gdb_maint_setting_str (@var{setting}) > @findex $_gdb_maint_setting_str@r{, convenience function} > ... > @item $_gdb_maint_setting (@var{setting}) > @findex $_gdb_maint_setting@r{, convenience function} > > Are all these wrong? Sounds like they should all be fixed in one go. Yes, they are all wrong. The result is not a catastrophe, it's just sub-optimal. > I don't usually use the info reader, so I'm not really sure what to look for. In an Info reader, type "i NAME" where NAME is the name of a function, and see where it lands you. > >> +Invoke a standard shell to execute @var{command-string}. Returns the > > ^^^^^^^^^^^^^^^^ > > "the standard system shell" is better, I think. > > Note this is the same wording used when describing the "shell" command: > > @table @code > @kindex shell > @kindex ! > @cindex shell escape > @item shell @var{command-string} > @itemx !@var{command-string} > Invoke a standard shell to execute @var{command-string}. > Note that no space is needed between @code{!} and @var{command-string}. > On GNU and Unix systems, the environment variable @env{SHELL}, if it > exists, determines which shell to run. Otherwise @value{GDBN} uses > the default shell (@file{/bin/sh} on GNU and Unix systems, > @file{cmd.exe} on MS-Windows, @file{COMMAND.COM} on MS-DOS, etc.). > @end table > > > Maybe the intention was to avoid "system" as @env{SHELL} may point > to some shell the user installed, which doesn't come with or from > the "system"? So I'd prefer to use the same terminology in $_shell too. I thought 'system' is not affected by $SHELL, but if it is, then something like "Invoke a shell to execute @var{command-string}", I think. The explanation of how $SHELL affects the shell describes the details. > > Also, this text could benefit from a cross-reference to where we > > describe the commands that convert from signal numbers to their > > mnemonics, since that is system-dependent. Maybe "info signal N" is > > the right tool here? If so, a cross-reference to "Signals" is what we > > should have here. (Is there a better way of asking GDB about signal > > number N?) > > I don't think it's the right tool here, because "info signal" and > "handle", etc., are about target signals, signals that trigger in the > inferior, which GDB is able to intercept. OTOH, the $_shell function > and the "shell" command run the shell on the host, so any fatal signal code > is a host signal number, and doesn't go via any translation at all. For native debugging, they are the same, of course. So mentioning that with the caveat of native debugging will help in some cases. > I'll note that where we document $_shell_exitsignal, the convenience > variable that the "shell" command sets, we don't describe the host signals > either. Then maybe we should have some text to tell the user how to map numbers to signal mnemonics in the non-native case. > I've moved the "The shell runs on the host machine, the machine @value{GDBN} is > running on." sentence earlier, in case that helps set expectations, and > added a couple sentences about host vs target signal numbers. > > I had also forgotten to document that the argument must be a string. > > Here is the result: > > "Invoke a standard shell to execute @var{command-string}. > @var{command-string} must be a string. The shell runs on the host > machine, the machine @value{GDBN} is running on. Returns the > command's exit status. On Unix systems, a command which exits with a > zero exit status has succeeded, and non-zero exit status indicates > failure. When a command terminates on a fatal signal whose number is > @var{N}, @value{GDBN} uses the value 128+@var{N} as the exit status, > as is standard in Unix shells. Note that @var{N} is a host signal > number, not a target signal number. If you're cross debugging, the > host vs target signal numbers may be completely unrelated. The shell > to run is determined in the same way as for the @code{shell} command. > @xref{Shell Commands, ,Shell Commands}." > > WDYT? OK, with the above nits. > >> +In this scenario, you'll want to make sure that the shell command you > >> +run in the breakpoint condition takes the least amount of time > >> +possible. This is important to minimize the time it takes to evaluate > >> +the condition and re-resume the program if the condition turns out to > >> +be false. > > > > I understand what this says, but not what it means in practice. > > Perhaps one or two additional sentences to help the reader understand > > how to "make sure the shell command in a breakpoint condition takes > > the least amount of time" would be in order? > > Maybe something like this? > > "In this scenario, you'll want to make sure that the shell command you > run in the breakpoint condition takes the least amount of time > possible. For example, avoid running a command that may block > indefinitely, or that sleeps for a while before exiting. Prefer a > command or script which analyzes some state and exits immediately. > This is important because the debugged program stops for the > breakpoint every time, and then @value{GDBN} evaluates the breakpoint > condition. If the condition is false, the program is re-resumed > transparently, without informing you of the stop. A quick shell > command thus avoids significantly slowing down the debugged program > unnecessarily." Thanks, this is much more helpful.