From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-wm1-f52.google.com (mail-wm1-f52.google.com [209.85.128.52]) by sourceware.org (Postfix) with ESMTPS id A9E423858D33 for ; Tue, 31 May 2022 11:05:56 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org A9E423858D33 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-wm1-f52.google.com with SMTP id 129-20020a1c0287000000b003974edd7c56so1027169wmc.2 for ; Tue, 31 May 2022 04:05:56 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:message-id:date:mime-version:user-agent:subject :content-language:to:cc:references:from:in-reply-to :content-transfer-encoding; bh=jKYBMn24d/NeMq65VGJVG119mQ1Cs9vpxVC0P1bQSA8=; b=3gsneZVO5qyKtbo0Bqb5fj2lGepB8vg1R4pzWpWpyGCFEJnqHN2CuXlL0Vj8U9t3SZ 4VKI+t1sg29jtX4hQuBR3uIwvuVyogA9th7wd+G6LQqUzw7xgNRA0NEQ4C2QAYoQg7fR PO+S2Q+pd1KsL7ypFvTvPlmAcQHjYpD+hASqKLb+oR+oTtj0hac+Q0l1ZUiMgZMFLQCw bwEVDuw2f04wBSFHkSdMHt5aINRoa87sZD/BJpR8SNES/C4U63UxKKN7FUIdeb+v7ELA MnmSPF6OoNyICMq2w5ILlC3ufq7nBQUtf7RD0SmJMlLrfE21RaDjmINUVXuh3DUjWJP/ dbVg== X-Gm-Message-State: AOAM533MU5R6PBOPIMuyrYNJxgVAtxkO4GB3hpvOSb1uHOVT1T2WiTvP mq0B3if7rXCgrdEtaL0V+XKIw86cOsE= X-Google-Smtp-Source: ABdhPJy4OaYDAADY/o7qGeN9BsQ/aeMvV8FAKo8re5W7EySt+SQTbQEy0bUxIoZ8gPBJHxi1j//Jxw== X-Received: by 2002:a05:600c:4e4d:b0:397:5009:bcf1 with SMTP id e13-20020a05600c4e4d00b003975009bcf1mr23068712wmq.66.1653995155511; Tue, 31 May 2022 04:05:55 -0700 (PDT) Received: from ?IPV6:2001:8a0:f924:2600:209d:85e2:409e:8726? ([2001:8a0:f924:2600:209d:85e2:409e:8726]) by smtp.gmail.com with ESMTPSA id az18-20020adfe192000000b0021020517639sm8753514wrb.102.2022.05.31.04.05.53 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Tue, 31 May 2022 04:05:54 -0700 (PDT) Message-ID: Date: Tue, 31 May 2022 12:05:53 +0100 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101 Thunderbird/91.9.1 Subject: [PATCH] Improve clear command's documentation Content-Language: en-US To: Eli Zaretskii Cc: gdb-patches@sourceware.org References: <20220526194250.2310460-1-pedro@palves.net> <838rqmm7gb.fsf@gnu.org> <6914f754-4e33-5aa1-4ea6-dca9504e8bfe@palves.net> <837d63j8tx.fsf@gnu.org> From: Pedro Alves In-Reply-To: <837d63j8tx.fsf@gnu.org> Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit X-Spam-Status: No, score=-10.0 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, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) 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: Tue, 31 May 2022 11:05:59 -0000 Handling this one issue at a time. On 2022-05-30 17:15, Eli Zaretskii wrote: >> Date: Mon, 30 May 2022 15:44:59 +0100 >> Cc: gdb-patches@sourceware.org >> From: Pedro Alves >> >>>> -@item clear @var{location} >>>> -Delete any breakpoints set at the specified @var{location}. >>>> -@xref{Specify Location}, for the various forms of @var{location}; the >>>> -most useful ones are listed below: >>>> +@item clear @var{locspec} >>>> +Delete breakpoints with code locations that match @var{locspec}. >>> ^^^^^^^^^^^^^^^^^^^^^^^^ >>> "that are the result of resolving @var{locspec}" >> >> That wouldn't actually be correct for this command. For example: >> >> (top-gdb) b gdb.c:29 >> Breakpoint 4 at 0x555555641091: file /home/pedro/gdb/binutils-gdb/src/gdb/gdb.c, line 29. >> (top-gdb) b *0x555555641092 >> Breakpoint 5 at 0x555555641092: file /home/pedro/gdb/binutils-gdb/src/gdb/gdb.c, line 29. >> (top-gdb) info breakpoints >> Num Type Disp Enb Address What >> 4 breakpoint keep y 0x0000555555641091 in main(int, char**) at /home/pedro/gdb/binutils-gdb/src/gdb/gdb.c:29 >> 5 breakpoint keep y 0x0000555555641092 in main(int, char**) at /home/pedro/gdb/binutils-gdb/src/gdb/gdb.c:29 >> >> "gdb.c:29" resolves to address 0x0000555555641091, as can be seen when breakpoint 4 was >> created. However, this: >> >> (top-gdb) clear gdb.c:29 >> Deleted breakpoints 4 5 >> >> ... also deletes breakpoint 5. GDB deleted it because its code location also matches >> the user input. > > But then "matches locspec" is also inaccurate, and for the same > reason: they are two equivalent ways of describing the same process of > arriving at a code location from a location spec, or at least that's > how the text used them until now. > >> This is explained just a bit below, here: >> >> @item clear @var{linenum} >> @itemx clear @var{filename}:@var{linenum} >> Delete any breakpoints set at or within the code of the specified >> @var{linenum} of the specified @var{filename}. >> @end table >> >> Key here are "or within the code", and talking about the _specified_ >> linenum/filename, not the resolved line/filename. > > Then we need some change of text to the same effect where "clear > LOCSPEC" is described, right? How about this, basically a complete rewrite of the clear command's documentation: >From 2efda4c0040ba088da5e0e03b5afdd2b0248ec5b Mon Sep 17 00:00:00 2001 From: Pedro Alves Date: Tue, 31 May 2022 10:54:17 +0100 Subject: [PATCH] Improve clear command's documentation Change-Id: I9440052fd28f795d6f7c93a4576beadd21f28885 --- gdb/doc/gdb.texinfo | 46 +++++++++++++++++++++++++++++++++++---------- 1 file changed, 36 insertions(+), 10 deletions(-) diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 3cf4e2c73c0..b497901473d 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -5443,21 +5443,47 @@ the innermost frame is selected, this is a good way to delete a breakpoint where your program just stopped. @item clear @var{locspec} -Delete breakpoints with code locations that match @var{locspec}. -@xref{Location Specifications}, for the various forms of -@var{locspec}; the most useful ones are listed below: +Delete breakpoints with code locations that match either address, +source file and line number, or function name specified in +@var{locspec}. @xref{Location Specifications}, for the various forms +of @var{locspec}. + +The location spec to breakpoint code location matching is done in the +following ways, depending on what the location spec specifies: @table @code -@item clear @var{function} -@itemx clear @var{filename}:@var{function} -Delete any breakpoints set at entry to the named @var{function}. +@item if @var{locspec} specifies a line number +If @var{locspec} specifies a line number, such as e.g., with one of +the following forms: -@item clear @var{linenum} -@itemx clear @var{filename}:@var{linenum} -Delete any breakpoints set at or within the code of the specified -@var{linenum} of the specified @var{filename}. +@table @code +@item @code{clear @var{linenum}} +@item @code{clear @var{filename}:@var{linenum}} +@item @code{clear -line @var{linenum}} +@item @code{clear -source @var{filename} -line @var{linenum}} @end table +@noindent +then the command deletes any breakpoints with a code location set at +or within the code of the specified @var{linenum} of files that match +the specified @var{filename}, or of files that match the current +source file, if no file name was specified. + +@item if @var{locspec} specifies an address +If @var{locspec} specifies an address, with @code{clear *@var{addr}}, +then the command deletes any breakpoints with a code location set at +the given address. + +@item if @var{locspec} specifies a function +If @var{locspec} specifies a function, such as with @code{clear +@var{function}} or @code{clear -function @var{function}}, then the +command deletes any breakpoints with a code location set at entry to a +function whose name matches @var{function}. +@end table + +Ambiguity in file name and function name matching can be resolved as +described in @ref{Location Specifications}. + @cindex delete breakpoints @kindex delete @kindex d @r{(@code{delete})} base-commit: 5541bfdc97936581c0ead915e9117e22f21bdb12 -- 2.36.0