aboutsummaryrefslogtreecommitdiff
path: root/gdb/doc
AgeCommit message (Collapse)AuthorFilesLines
8 daysgdb/alpha: Add target description supportYodel Eldar1-0/+42
This commit adds target description support for Alpha. The target description obviates the alpha_register_type and alpha_register_name functions in alpha-tdep.c. Removal of alpha_register_reggroup_p was considered but ultimately abandoned, because the "info regs" command would no longer omit the zero, fpcr, and unique registers from its output (they are neither vector nor float types). Register types in the target description annex match the types that the alpha_register_type function returned. The locally defined register_names array was moved out of alpha_register_name and renamed to alpha_register_names as a static global; calls to alpha_register_name have been replaced with direct access of the array. The patch follows the code pattern outlined in the following GDB Internals Wiki entry: https://sourceware.org/gdb/wiki/Internals%20Adding-Target-Described-Register-Support Reviewed-By: Eli Zaretskii <eliz@gnu.org> Approved-By: Simon Marchi <simon.marchi@efficios.com> Change-Id: If4b25a891228388519074a31a682e33358c71063
12 days[gdb/tdep] Add "maint set console-translation-mode <binary|text>" commandTom de Vries1-0/+17
On MSYS2, say we record a brief gdb session using TERM=dumb script: ... $ gdb -q (gdb) print 1 $1 = 1 (gdb) q ... When looking at the resulting typescript, we notice something odd: ... $ gdb -q^M (gdb) print 1^M $1 = 1^M^M (gdb) q^M ... For some reason, we have "$1 = 1\r\r\n(gdb) ". Looking at the documentation of _setmode [1], it mentions translation mode _O_TEXT as a mode in which "\n" is translated into "\r\n" on output. So, it looks like this translation happens twice. Add a command "maint set console-translation-mode <binary|text>" command that allows us to set the translation mode of stdout/stderr to binary, such that we get instead: ... $ gdb -q -ex "maint set console-translation-mode binary"^M (gdb) print 1^M $1 = 1^M (gdb) q^M ... Since we run into this in the testsuite, add "maint set console-translation-mode binary" to INTERNAL_GDBFLAGS. Based on "maint set testsuite-mode on/off" from these patches [2][3] by Pierre Muller. Compared to that proposal, I dropped the name testsuite-mode, because the behaviour is not specific to the testsuite. Also I chose values binary/text instead of on/off because eventually there may be other translation mode values that we need [4]. Co-Authored-By: Pierre Muller <muller@sourceware.org> Reviewed-By: Eli Zaretskii <eliz@gnu.org> [1] https://learn.microsoft.com/en-us/cpp/c-runtime-library/reference/setmode [2] https://sourceware.org/legacy-ml/gdb-patches/2013-09/msg00939.html [3] https://sourceware.org/legacy-ml/gdb-patches/2013-09/msg00940.html [4] https://learn.microsoft.com/en-us/cpp/c-runtime-library/translation-mode-constants
2025-06-19gdb/python: introduce gdb.warning() functionAndrew Burgess2-0/+12
This commit adds a new gdb.warning() function. This function takes a string and then calls GDB's internal warning() function. This will display the string as a warning. Using gdb.warning() means that the message will get the new emoji prefix if the user has that feature turned on. Also, the message will be sent to gdb.STDERR without the user having to remember to print to the correct stream. Reviewed-By: Eli Zaretskii <eliz@gnu.org> Approved-By: Tom Tromey <tom@tromey.com>
2025-06-17gdbserver: fix vFile:stat to actually use 'stat'Andrew Burgess1-5/+10
This commit continues the work of the previous two commits. In the following commits I added the target_fileio_stat function, and the target_ops::fileio_stat member function: * 08a115cc1c4 gdb: add target_fileio_stat, but no implementations yet * 3055e3d2f13 gdb: add GDB side target_ops::fileio_stat implementation * 6d45af96ea5 gdbserver: add gdbserver support for vFile::stat packet * 22836ca8859 gdb: check for multiple matching build-id files Unfortunately I messed up, despite being called 'stat' these function actually performed an 'lstat'. The 'lstat' is the correct (required) implementation, it's the naming that is wrong. Additionally, to support remote targets, these commit added the vFile::stat packet, which again, performed an 'lstat'. In the previous two commits I changed the GDB code to replace 'stat' with 'lstat' in the fileio function names. I then added a new vFile:lstat packet which GDB now uses instead of vFile:stat. And that just leaves the vFile:stat packet which is, right now, performing an 'lstat'. Now, clearly when I wrote this code I fully intended for this packet to perform an lstat, it's the lstat that I needed. But now, I think, we should "fix" vFile:stat to actually perform a 'stat'. This is risky. This is a change in remote protocol behaviour. Reasons why this might be OK: - vFile:stat was only added in GDB 16, so it's not been "in the wild" for too long yet. If we're quick, we might be able to "fix" this before anyone realises I messed up. - The documentation for vFile:stat is pretty vague. It certainly doesn't explicitly say "this does an lstat". Most implementers would (I think), given the name, start by assuming this should be a 'stat' (given the name). Only if they ran the full GDB testsuite, or examined GDB's implementation, would they know to use lstat. Reasons why this might not be OK: - Some other debug client could be connecting to gdbserver, sending vFile:stat and expecting to get lstat behaviour. This would break after this patch. - Some other remote server might have implemented vFile:stat support, and either figured out, or copied, the lstat behaviour from gdbserver. This remote server would technically be wrong after this commit, but as GDB no longer uses vFile:stat, then this will only become a problem if/when GDB or some other client starts to use vFile:stat in the future. Given the vague documentation for vFile:stat, and that it was only added in GDB 16, I think we should fix it now to perform a 'stat', and that is what this commit does. The change in behaviour is documented in the NEWS file. I've improved the vFile:stat documentation in the manual to better explain what is expected from this packet, and I've extended the existing test to cover vFile:stat. Reviewed-By: Eli Zaretskii <eliz@gnu.org> Approved-By: Tom Tromey <tom@tromey.com>
2025-06-17gdbserver: add vFile:lstat packet supportAndrew Burgess1-0/+15
In the following commits I added the target_fileio_stat function, and the target_ops::fileio_stat member function: * 08a115cc1c4 gdb: add target_fileio_stat, but no implementations yet * 3055e3d2f13 gdb: add GDB side target_ops::fileio_stat implementation * 6d45af96ea5 gdbserver: add gdbserver support for vFile::stat packet * 22836ca8859 gdb: check for multiple matching build-id files Unfortunately I messed up, despite being called 'stat' these function actually performed an 'lstat'. The 'lstat' is the correct (required) implementation, it's the naming that is wrong. In the previous commit I fixed the naming within GDB, renaming 'stat' to 'lstat' throughout. However, in order to support target_fileio_stat (as was) on remote targets, the above patches added the vFile:stat packet, which actually performed an 'lstat' call. This is really quite unfortunate, and I'd like to do as much as I can to try and clean up this mess. But I'm mindful that changing packets is not really the done thing. So, this commit doesn't change anything. Instead, this commit adds vFile:lstat as a new packet. Currently, this packet is handled identically as vFile:stat, the packet performs an 'lstat' call. I then update GDB to send the new vFile:lstat instead of vFile:stat for the remote_target::fileio_lstat implementation. After this commit GDB will never send the vFile:stat packet. However, I have retained the 'set remote hostio-stat-packet' control flag, just in case someone was trying to set this somewhere. Then there's one test in the testsuite which used to disable the vFile:stat packet, that test is updated to now disable vFile:lstat. There's a new test that does a more direct test of vFile:lstat. This new test can be extended to also test vFile:stat, but that is left for the next commit. And so, after this commit, GDB sends the new vFile:lstat packet in order to implement target_ops::fileio_lstat. The new packet is more clearly documented than vFile:stat is. But critically, this change doesn't risk breaking any other clients or servers that implement GDB's remote protocol. Reviewed-By: Eli Zaretskii <eliz@gnu.org> Approved-By: Tom Tromey <tom@tromey.com>
2025-06-16gdb/doc: Explain linker namespacesGuinevere Larsen1-8/+15
Recent GDB commits added more features related to linker namespaces and documented them on the manual, but did not add a convenient way for a user to understand what they are. This commit adds a quick explanation of what they are. It also fixes the inconsistency of using "linker namespaces" and "linkage namespaces", by always using the first form to avoid user confusion. Approved-By: Eli Zaretskii <eliz@gnu.org>
2025-06-16gdb/doc: remove stray comma from gdb.flush descriptionAndrew Burgess1-1/+1
Remove comma from: gdb.flush([, stream]) . I suspect this was a copy and paste from gdb.write(string [, stream]) where the comma is correct.
2025-06-14* gdb/doc/gdb.texinfo (Emacs): Refer to Emacs manualJeremy Bryant1-130/+5
The manual section on using GDB under Emacs is out-of-date and duplicates existing and comprehensive documentation in the Emacs manual. Replace the section by a short introduction and reference. Approved-By: Eli Zaretskii <eliz@gnu.org>
2025-06-11GDB: doc: Improve AArch64 subsubsection titles and index entries in gdb.texinfoThiago Jung Bauermann1-14/+15
Remove period from subsubsection titles in the AArch64 configuration-specific subsection, and expand acronyms. Regarding @cindex entries, remove periods and standardise their order and the position of "AArch64" to make it easier to find them by using the index-searching commands of Info readers that offer TAB completion. Approved-By: Eli Zaretskii <eliz@gnu.org>
2025-06-05gdb/solib: rename convenience variable to _linker_namespaceGuinevere Larsen1-2/+2
Based on feedback from IRC and PR solib/32959, this commit renames the recently introduced convenience variable $_current_linker_namespace to the shorter name $_linker_namespace. This makes it more in line with existing convenience variables such as $_thread and $_inferior, and faster to type. It should be ok to simply change the name because the variable was never released to the public, so there should be no existing scripts depending on the name. Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=32959 Reviewed-By: Eli Zaretskii <eliz@gnu.org> Approved-By: Andrew Burgess <aburgess@redhat.com> Approved-By: Tom Tromey <tom@tromey.com>
2025-06-05gdb/solib: Change type of convenience variable _current_linker_namespaceGuinevere Larsen1-3/+3
Based on IRC feedback since commit 6a0da68c036a85a46415aa0dada2421eee7c2269 gdb: add convenience variables around linker namespace debugging This commit changes the type of the _current_linker_namespace variable to be a simple integer. This makes it easier to use for expressions, like breakpoint conditions or printing from a specific namespace once that is supported, at the cost of making namespace IDs slightly less consistent. This is based on PR solib/32960, where no negative feedback was given for the suggestion. The commit also changes the usage of "linkage namespaces" to "linker namespaces" in the NEWS file, to reduce chance of confusion from an end user. Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=32960 Reviewed-By: Eli Zaretskii <eliz@gnu.org> Approved-By: Tom Tromey <tom@tromey.com>
2025-06-03gdb/python/guile: user created prefix commands get help listAndrew Burgess2-0/+22
Consider GDB's builtin prefix set/show prefix sub-commands, if they are invoked with no sub-command name then they work like this: (gdb) show print print address: Printing of addresses is on. print array: Pretty formatting of arrays is off. print array-indexes: Printing of array indexes is off. print asm-demangle: Demangling of C++/ObjC names in disassembly listings is off. ... cut lots of lines ... (gdb) set print List of set print subcommands: set print address -- Set printing of addresses. set print array -- Set pretty formatting of arrays. set print array-indexes -- Set printing of array indexes. set print asm-demangle -- Set demangling of C++/ObjC names in disassembly listings. ... cut lots of lines ... Type "help set print" followed by set print subcommand name for full documentation. Type "apropos word" to search for commands related to "word". Type "apropos -v word" for full documentation of commands related to "word". Command name abbreviations are allowed if unambiguous. (gdb) That is 'show print' lists the values of all settings under the 'print' prefix, and 'set print' lists the help text for all settings under the 'set print' prefix. Now, if we try to create something similar using the Python API: (gdb) python gdb.ParameterPrefix("my-prefix", gdb.COMMAND_NONE) (gdb) python gdb.Parameter("my-prefix foo", gdb.COMMAND_OBSCURE, gdb.PARAM_BOOLEAN) (gdb) show my-prefix (gdb) set my-prefix Neither 'show my-prefix' or 'set my-prefix' gives us the same details relating to the sub-commands that we get with the builtin prefix commands. This commit aims to address this. Currently, in cmdpy_init, when a new command is created, we always set the commands callback function to cmdpy_function. It is within cmdpy_function that we spot that the command is a prefix command, and that there is no gdb.Command.invoke method, and so return early. This commit changes things so that the rules are now: 1. For NON prefix commands, we continue to use cmdpy_function. 2. For prefix commands that do have a gdb.Command.invoke method (i.e. can handle unknown sub-commands), continue to use cmdpy_function. 3. For all other prefix commands, don't use cmdpy_function, instead use GDB's normal callback function for set/show prefixes. This requires splitting the current call to add_prefix_cmd into either a call to add_prefix_cmd, add_show_prefix_cmd, or add_basic_prefix_cmd, as appropriate. After these changes, we now see this: (gdb) python gdb.ParameterPrefix("my-prefix", gdb.COMMAND_NONE) │ (gdb) python gdb.Parameter("my-prefix foo", gdb.COMMAND_OBSCURE, gdb.PARAM_BOOLEAN) (gdb) show my-prefix │ my-prefix foo: The current value of 'my-prefix foo' is "off". (gdb) set my-prefix List of "set my-prefix" subcommands: set my-prefix foo -- Set the current value of 'my-prefix foo'. Type "help set my-prefix" followed by subcommand name for full documentation. Type "apropos word" to search for commands related to "word". Type "apropos -v word" for full documentation of commands related to "word". Command name abbreviations are allowed if unambiguous. (gdb) Which matches how a prefix defined within GDB would act. I have made the same changes to the Guile API.
2025-05-30Require Python 3.4Tom Tromey1-1/+1
I believe we previously agreed that the minimum supported Python version should be 3.4. This patch makes this change, harmonizing the documentation (which was inconsistent about the minimum version) and the code. New in v2: rebased, and removed a pre-3.4 workaround from __init__.py. Reviewed-By: Eli Zaretskii <eliz@gnu.org> Approved-by: Kevin Buettner <kevinb@redhat.com> Acked-By: Tom de Vries <tdevries@suse.de> Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=31870
2025-05-13gdb/python: new gdb.ParameterPrefix classAndrew Burgess1-0/+95
This commit adds a new gdb.ParameterPrefix class to GDB's Python API. When creating multiple gdb.Parameters, it is often desirable to group these together under a sub-command, for example, 'set print' has lots of parameters nested under it, like 'set print address', and 'set print symbol'. In the Python API the 'print' part of these commands are called prefix commands, and are created using gdb.Command objects. However, as parameters are set via the 'set ....' command list, and shown through the 'show ....' command list, creating a prefix for a parameter usually requires two prefix commands to be created, one for the 'set' command, and one for the 'show' command. This often leads to some duplication, or at the very least, each user will end up creating their own helper class to simplify creation of the two prefix commands. This commit adds a new gdb.ParameterPrefix class. Creating a single instance of this class will create both the 'set' and 'show' prefix commands, which can then be used while creating the gdb.Parameter. Here is an example of it in use: gdb.ParameterPrefix('my-prefix', gdb.COMMAND_NONE) This adds 'set my-prefix' and 'show my-prefix', both of which are prefix commands. The user can then add gdb.Parameter objects under these prefixes. The gdb.ParameterPrefix initialise method also supports documentation strings, so we can write: gdb.ParameterPrefix('my-prefix', gdb.COMMAND_NONE, "Configuration setting relating to my special extension.") which will set the documentation string for the prefix command. Also, it is possible to support prefix commands that use the `invoke` functionality to handle unknown sub-commands. This is done by sub-classing gdb.ParameterPrefix and overriding either 'invoke_set' or 'invoke_show' to handle the 'set' or 'show' prefix command respectively. Reviewed-By: Eli Zaretskii <eliz@gnu.org>
2025-05-13gdb/guile: generate general description string for parametersAndrew Burgess1-2/+4
This commit builds on the previous one, and auto-generates a general description string for parameters defined via the Guile API. This brings the Guile API closer inline with the Python API. It is worth reading the previous commit to see some motivating examples. This commit updates get_doc_string in guile/scm-param.c to allow for the generation of a general description string. Then in gdbscm_make_parameter, if '#:doc' was not given, get_doc_string is used to generate a suitable default. This does invalidate (and so the commit removes) this comment that was in gdbscm_make_parameter: /* If doc is NULL, leave it NULL. See add_setshow_cmd_full. */ First, Python already does exactly what I'm proposing here, and has done for a while, with no issues reported. And second, I've gone and read add_setshow_cmd_full, and some of the functions it calls, and can see no reasoning behind this comment... ... well, there is one reason that I can think of, but I'll discuss that more below. With this commit, if I define a parameter like this: (use-modules (gdb)) (register-parameter! (make-parameter "print test" #:command-class COMMAND_NONE #:parameter-type PARAM_BOOLEAN)) Then, in GDB, I now see this behaviour: (gdb) help show print test Show the current value of 'print test'. This command is not documented. (gdb) help set print test Set the current value of 'print test'. This command is not documented. (gdb) The two 'This command is not documented.' lines are new. This output is what we get from a similarly defined parameter using the Python API (see the previous commit for an example). I mentioned above that I can think of one reason for the (now deleted) comment in gdbscm_make_parameter about leaving the doc field as NULL, and that is this: consider the following GDB behaviour: (gdb) help show style filename foreground Show the foreground color for this property. (gdb) Notice there is only a single line of output. If I want to get the same behaviour from a parameter defined in Guile, I might try skipping the #:doc argument, but (after this commit), if I do that, GDB will auto-generate some text for me, giving two lines of output (see above). So, next, maybe I try setting #:doc to the empty string, but if I do that, then I get this: (use-modules (gdb)) (register-parameter! (make-parameter "print test" #:doc "" #:command-class COMMAND_NONE #:parameter-type PARAM_BOOLEAN)) (gdb) help show print test Show the current value of 'print test'. (gdb) Notice the blank line, that's not what I wanted. In fact, the only way to get rid of the second line is to leave the 'doc' variable as NULL in gdbscm_make_parameter, which, due to the new auto-generation, is no longer possible. This issue also existed in the Python API, and was addressed in commit: commit 4b68d4ac98aec7cb73a4b276ac7dd38d112786b4 Date: Fri Apr 11 23:45:51 2025 +0100 gdb/python: allow empty gdb.Parameter.__doc__ string After this commit, an empty __doc__ string for a gdb.Parameter is translated into a NULL pointer passed to the add_setshow_* command, which means the second line of output is completely skipped. And this commit includes the same solution for the Guile API. Now, with this commit, and the Guile parameter using an empty '#:doc' string, GDB has the following behaviour: (gdb) help show print test Show the current value of 'print test'. (gdb) This matches the output for a similarly defined parameter in Python.
2025-05-13gdb/python: allow empty gdb.Parameter.__doc__ stringAndrew Burgess1-1/+3
I was recently attempting to create some parameters via the Python API. I wanted these parameters to appear similar to how GDB handles the existing 'style' parameters. Specifically, I was interested in this behaviour: (gdb) help show style filename foreground Show the foreground color for this property. (gdb) help set style filename foreground Set the foreground color for this property. (gdb) Notice how each 'help' command only gets a single line of output. I tried to reproduce this behaviour via the Python API and was unable. The problem is that, in order to get just a single line of output like this, the style parameters are registered with a call to add_setshow_color_cmd with the 'help_doc' being passed as nullptr. On the Python side, when parameters are created, the 'help_doc' is obtained with a call to get_doc_string (python/py-param.c). This function either returns the __doc__ string, or a default string: "This command is not documented.". To avoid returning the default we could try setting __doc__ to an empty string, but setting this field to any string means that GDB prints a line for that string, like this: class test_param(gdb.Parameter): __doc__ = "" def __init__(self, name): super ().__init__(name, gdb.COMMAND_NONE, gdb.PARAM_BOOLEAN) self.value = True test_param('print test') Then in GDB: (gdb) help set print test Set the current value of 'print test'. (gdb) The blank line is the problem I'd like to solve. This commit makes a couple of changes to how parameter doc strings are handled. If the doc string is set to an empty string, then GDB now converts this to nullptr, which removes the blank line problem, the new behaviour in GDB (for the above `test_param`) is: (gdb) help set print test Set the current value of 'print test'. (gdb) Next, I noticed that if the set/show docs are set to empty strings, then the results are less than ideal: class test_param(gdb.Parameter): set_doc = "" def __init__(self, name): super ().__init__(name, gdb.COMMAND_NONE, gdb.PARAM_BOOLEAN) self.value = True test_param('print test') And in GDB: (gdb) help set print test This command is not documented. (gdb) So, if the set/show docs are the empty string, GDB now forces these to be the default string instead, the new behaviour in GDB is: (gdb) help set print test Set the current value of 'print test'. This command is not documented. (gdb) I've added some additional asserts; the set/show docs should always be non-empty strings, which I believe is the case after this commit. And the 'doc' string returned from get_doc_string should never nullptr, but could be empty. There are new tests to cover all these changes.
2025-05-12gdb: add '-stopped' and '-running' options to "info threads"Tankut Baris Aktemur1-1/+9
Add two options to "info threads": `-stopped` and `-running`. The purpose of these options is to filter the output of the command. The `-stopped` option means "print stopped threads only" and, similarly, `-running` means "print the running threads only". When both options are provided by the user, the indication is that the user wants the union. That is, the output contains both stopped and running threads. Suppose we have an application with 5 threads, 2 of which have hit a breakpoint. The "info threads" command in the non-stop mode gives: (gdb) info threads Id Target Id Frame * 1 Thread 0x7ffff7d99740 (running) 2 Thread 0x7ffff7d98700 something () at file.c:30 3 Thread 0x7ffff7597700 (running) 4 Thread 0x7ffff6d96700 something () at file.c:30 5 Thread 0x7ffff6595700 (running) (gdb) Using the "-stopped" flag, we get (gdb) info threads -stopped Id Target Id Frame 2 Thread 0x7ffff7d98700 something () at file.c:30 4 Thread 0x7ffff6d96700 something () at file.c:30 (gdb) Using the "-running" flag, we get (gdb) info threads -running Id Target Id Frame * 1 Thread 0x7ffff7d99740 (running) 3 Thread 0x7ffff7597700 (running) 5 Thread 0x7ffff6595700 (running) (gdb) Using both flags prints all: (gdb) info threads -stopped -running Id Target Id Frame * 1 Thread 0x7ffff7d99740 (running) 2 Thread 0x7ffff7d98700 something () at file.c:30 3 Thread 0x7ffff7597700 (running) 4 Thread 0x7ffff6d96700 something () at file.c:30 5 Thread 0x7ffff6595700 (running) (gdb) When combined with a thread ID, filtering applies to those threads that are matched by the ID. (gdb) info threads 3 Id Target Id Frame 3 Thread 0x7ffff7597700 (running) (gdb) info threads -stopped 3 No threads matched. (gdb) Regression-tested on X86_64 Linux. Reviewed-By: Eli Zaretskii <eliz@gnu.org> Reviewed-By: Guinevere Larsen <guinevere@redhat.com> Approved-by: Pedro Alves <pedro@palves.net
2025-05-09Move "show style sources" documentationTom Tromey1-3/+3
I noticed that I had inadvertently put the "set style warning-prefix" documentation between the paragraph for "set style sources" and the paragraph for "show style sources". This patch moves the latter up a bit to clean this up.
2025-05-06gdb/python/guile: check if styling is disabled in Color.escape_sequenceAndrew Burgess2-0/+6
I noticed that the gdb.Color.escape_sequence() method would produce an escape sequence even when styling is disabled. I think this is the wrong choice. Ideally, when styling is disabled (e.g. with 'set style enabled off'), GDB should not be producing styled output. If a GDB extension is using gdb.Color to apply styling to the output, then currently, the extension should be checking 'show style enabled' any time Color.escape_sequence() is used. This means lots of code duplication, and the possibility that some locations will be missed, which means disabling styling no longer does what it says. I propose that Color.escape_sequence() should return the empty string if styling is disabled. A Python extension can then do: python c_none = gdb.Color('none') c_red = gdb.Color('red') print(c_red.escape_sequence(True) + "Text in red." + c_none.escape_sequence(True)) end If styling is enable this will print some red text. And if styling is disabled, then it will print text in the terminal's default color. I have applied the same fix to the guile API. I have extended the tests to cover this case. Approved-By: Tom Tromey <tom@tromey.com>
2025-05-02Use emoji to indicate errors and warningsTom Tromey1-0/+24
This patch adds, at long last, some emoji output to gdb. In particular, warnings are indicated with the U+26A0 (WARNING SIGN), and errors with U+274C (CROSS MARK). There is a new setting to control whether emoji output can be used. It defaults to "auto", which means emoji will be used if the host charset is UTF-8. Note that disabling styling will also disable emoji, handy for traditionalists. I've refactored mingw console output a little, so that emoji will not be printed to the console. Note the previous code here was a bit strange in that it assumed that the first use of gdb_console_fputs would be to stdout. This version lets the user control the prefixes directly, so different emoji can be chosen if desired. Reviewed-By: Eli Zaretskii <eliz@gnu.org> Reviewed-By: Keith Seitz <keiths@redhat.com> Reviewed-By: Guinevere Larsen <guinevere@redhat.com>
2025-04-26Add "maint canonicalize" commandTom Tromey1-0/+7
This adds a new "maint canonicalize" command that can be used to see the canonical form of a C++ name. I've needed this a few times when debugging gdb. Reviewed-By: Eli Zaretskii <eliz@gnu.org> Reviewed-By: Tom de Vries <tdevries@suse.de>
2025-04-24Fix documentation for gdb.blocked_signalsTom Tromey1-5/+5
gdb exports a context manager named gdb.blocked_signals, but the documentation erroneously refers to it as gdb.block_signals. Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=32891 Approved-By: Eli Zaretskii <eliz@gnu.org> Approved-By: Tom de Vries <tdevries@suse.de>
2025-04-24Add TLS NEWS entry and document 'set force-internal-tls-address-lookup' commandKevin Buettner1-0/+50
Reviewed-By: Eli Zaretskii <eliz@gnu.org> Tested-By: Luis Machado <luis.machado@arm.com> Approved-By: Luis Machado <luis.machado@arm.com>
2025-04-24gdb/doc: tweaks to documentation for gdb.ColorAndrew Burgess1-7/+8
While reading through the documentation for the new gdb.Color class I spotted a couple of things which I thought could be improved: * I replaced @code{Color} with @code{gdb.Color}. Most of the other classes are referenced with the 'gdb.' prefix, so this makes gdb.Color consistent. Including the 'gdb.' prefix makes it far easier to search the documentation to find relevant content. And finally, my understanding is that usually in Python code, the class would be written as 'gdb.Color' unless the user specifically pulls 'Color' into the current scope using 'from gdb import Color'. * Replace 'colorspace' with 'color space'. There was already a use of the two word form in the documentation (for gdb.Color), so this just makes things consistent. * Removed use of @var on two @defun lines. No other @defun lines use @var, so the use of @var here was making the output inconsistent, e.g. in the 'info' output, @var causes the string to be capitalised. * Rename the 'color-space' argument to 'color_space' for Color.__init__. In the next commit I plan to add Python keyword argument support to this function, which means the argument name needs to be a valid keyword (i.e. must not contain the '-' character). * Added a pointer to where the @samp{COLORSPACE_} constants can be found. These constants are referenced before they are defined in the documentation, which is fine, but I think it is a good idea to let the user know where the constants can be found when we first reference them. * Remove use of 'self' for the Color.escape_sequence documentation. There are a few functions that do include 'self' as an argument (I think this is a mistake) but the vast majority don't. I think not including 'self' is the better approach; a user wouldn't be expected to explicitly pass 'self', this is done automatically by Python as a result of calling the method on an object. So I've removed the reference to 'self' from this method. Approved-By: Eli Zaretskii <eliz@gnu.org> Approved-By: Tom Tromey <tom@tromey.com>
2025-04-23gdb/python: remove Py_TPFLAGS_BASETYPE from gdb.ColorAndrew Burgess1-0/+2
Remove the Py_TPFLAGS_BASETYPE flag from the gdb.Color type. This effectively makes gdb.Color final; users can no longer create classes that inherit from gdb.Color. Right now I cannot think of any cases where inheritance would be needed over composition for a simple type like gdb.Color. If I'm wrong, then it's easy to add Py_TPFLAGS_BASETYPE back in later, this would be an extension of the API. But it's much harder to remove the flag later as that might break existing user code (note: there has been no release of GDB yet that includes the gdb.Color type). Introducing this restriction makes the next commit easier. Reviewed-By: Eli Zaretskii <eliz@gnu.org> Approved-By: Tom Tromey <tom@tromey.com>
2025-04-23GDB: Introduce "info linker-namespaces" commandGuinevere Larsen1-0/+16
Continuing to improve GDB's ability to debug linker namespaces, this commit adds the command "info linker- namespaces". The command is similar to "info sharedlibrary" but focused on improved readability when the inferior has multiple linker namespaces active. This command can be used in 2 different ways, with or without an argument. When called without argument, the command will print the number of namespaces, and for each active namespace, it's identifier, how many libraries are loaded in it, and all the libraries (in a similar table to what "info sharedlibrary" shows). As an example, this is what GDB's output could look like: (gdb) info linker-namespaces There are 2 linker namespaces loaded There are 3 libraries loaded in linker namespace [[0]] Displaying libraries for linker namespace [[0]]: From To Syms Read Shared Object Library 0x00007ffff7fc6000 0x00007ffff7fff000 Yes /lib64/ld-linux-x86-64.so.2 0x00007ffff7ebc000 0x00007ffff7fa2000 Yes (*) /lib64/libm.so.6 0x00007ffff7cc9000 0x00007ffff7ebc000 Yes (*) /lib64/libc.so.6 (*): Shared library is missing debugging information. There are 4 libraries loaded in linker namespace [[1]] Displaying libraries for linker namespace [[1]]: From To Syms Read Shared Object Library 0x00007ffff7fc6000 0x00007ffff7fff000 Yes /lib64/ld-linux-x86-64.so.2 0x00007ffff7fb9000 0x00007ffff7fbe000 Yes gdb.base/dlmopen-ns-ids/dlmopen-lib.so 0x00007ffff7bc4000 0x00007ffff7caa000 Yes (*) /lib64/libm.so.6 0x00007ffff79d1000 0x00007ffff7bc4000 Yes (*) /lib64/libc.so.6 (*): Shared library is missing debugging information. When called with an argument, the argument must be a namespace identifier (either with or without the square brackets decorators). In this situation, the command will truncate the output to only show the relevant information for the requested namespace. For example: (gdb) info linker-namespaces 0 There are 3 libraries loaded in linker namespace [[0]] Displaying libraries for linker namespace [[0]]: From To Syms Read Shared Object Library 0x00007ffff7fc6000 0x00007ffff7fff000 Yes /lib64/ld-linux-x86-64.so.2 0x00007ffff7ebc000 0x00007ffff7fa2000 Yes (*) /lib64/libm.so.6 0x00007ffff7cc9000 0x00007ffff7ebc000 Yes (*) /lib64/libc.so.6 (*): Shared library is missing debugging information. The test gdb.base/dlmopen-ns-id.exp has been extended to test this new command. Because some gcc and glibc defaults can change between systems, we are not guaranteed to always have libc and libm loaded in a namespace, so we can't guarantee the number of libraries, but the range of the result is 2, so we can still check for glaring issues. Reviewed-By: Eli Zaretskii <eliz@gnu.org> Approved-by: Kevin Buettner <kevinb@redhat.com>
2025-04-23gdb: add convenience variables around linker namespace debuggingGuinevere Larsen1-0/+12
This commit adds 2 simple built-in convenience variables to help users debug an inferior with multiple linker namespaces. The first is $_active_linker_namespaces, which just counts how many namespaces have SOs loaded onto them. The second is $_current_linker_namespace, and it tracks which namespace the current location in the inferior belongs to. This commit also introduces a test ensuring that we track namespaces correctly, and that a user can use the $_current_linker_namespace variable to set a conditional breakpoint, while linespec changes aren't finalized to make it more convenient. Reviewed-By: Eli Zaretskii <eliz@gnu.org> Approved-by: Kevin Buettner <kevinb@redhat.com>
2025-04-23This commit adds record full support for rv64gc instruction setTimur1-3/+3
It includes changes to the following files: - gdb/riscv-linux-tdep.c, gdb/riscv-linux-tdep.h: adds facilities to record syscalls. - gdb/riscv-tdep.c, gdb/riscv-tdep.h: adds facilities to record execution of rv64gc instructions. - gdb/configure.tgt: adds new files for compilation. - gdb/testsuite/lib/gdb.exp: enables testing of full record mode for RISC-V targets. - gdb/syscalls/riscv-canonicalize-syscall-gen.py: a script to generate function that canonicalizes RISC-V syscall. This script can simplify support for syscalls on rv32 and rv64 system (currently support only for rv64). To use this script you need to pass a path to a file with syscalls description from riscv-glibc (example is in the help message). The script produces a mapping from syscall names to gdb_syscall enum. - gdb/riscv-canonicalize-syscall.c: the file generated by the previous script. - gdb/doc/gdb.texinfo: notification that record mode is enabled in RISC-V. - gdb/NEWS: notification of new functionality. Approved-By: Guinevere Larsen <guinevere@redhat.com> Approved-By: Andrew Burgess <aburgess@redhat.com>
2025-04-22gdb/doc: use @samp{} in Python docsAndrew Burgess1-2/+2
In this review: https://inbox.sourceware.org/gdb-patches/86sem6ase5.fsf@gnu.org it was pointed out that I should use @samp{} around some text I was adding to the documentation. However, the offending snippet of documentation was something I copied from elsewhere in python.texi. This commit fixes the original to use @samp{}.
2025-04-08Update copyright dates to include 2025Tom Tromey13-17/+17
This updates the copyright headers to include 2025. I did this by running gdb/copyright.py and then manually modifying a few files as noted by the script. Approved-By: Eli Zaretskii <eliz@gnu.org>
2025-04-07gdb: Introduce user-friendly namespace identifier for "info shared"Guinevere Larsen1-0/+5
GDB has had basic support for linkage namespaces for some time already, but only in the sense of managing multiple copies of the same shared object being loaded, and a very fragile way to find the correct copy of a symbol (see PR shlibs/32054). This commit is the first step in improving the user experience around multiple namespace support. It introduces a user-friendly identifier for namespaces, in the format [[<number>]], that will keep consistent between dlmopen and dlclose calls. The plan is for this identifier to be usable in expressions like `print [[1]]::var` to find a specific instance of a symbol, and so the identifier must not be a valid C++ or Ada namespace identifier, otherwise disambiguation becomes a problem. Support for those expressions has not been implemented yet, it is only mentioned to explain why the identifier looks like this. This syntax was chosen based on the C attributes, since nothing in GDB uses a similar syntax that could confuse users. Other syntax options that were explored were "#<number>" and "@<number>". The former was abandoned because when printing a frame, the frame number is also printed with #<number>, so in a lot of the context in which that the identifier would show up, it appears in a confusing way. The latter clashes with the array printing syntax, and I believe that the having "@N::foo" working completely differently to "foo@2" would also lead to a bad user experience. The namespace identifiers are stored via a vector inside svr4_info object. The vector stores the address of the r_debug objects used by glibc to identify each namespace, and the user-friendly ID is the index of the r_debug in the vector. This commit also introduces a set storing the indices of active namespaces. The glibc I used to develop this patch (glibc 2.40 on Fedora 41) doesn't allow an SO to be loaded into a deactivated namespace, and requesting a new namespace when a namespace was previously closed will reuse that namespace. Because of how this is implemented, this patch lets GDB easily track the exact namespace IDs that the inferior will see. Finally, two new solib_ops function pointers were added, find_solib_ns and num_active_namespaces, to allow code outside of solib-svr4 to find and use the namespace identifiers and the number of namespaces, respectively. As a sanity check, the command `info sharedlibrary` has been changed to display the namespace identifier when the inferior has more than one active namespace. With this final change, a couple of tests had to be tweaked to handle the possible new column, and a new test has been created to make sure that the column appears and disappears as needed, and that GDB can track the value of the LMID for namespaces. Approved-by: Kevin Buettner <kevinb@redhat.com>
2025-03-19gdb/python: new styling argument to gdb.executeAndrew Burgess1-1/+9
Currently, gdb.execute emits styled output when the command is sending its output to GDB's stdout, and produces unstyled output when the output is going to a string. But it is not unreasonable that a user might wish to capture styled output from a gdb.execute call, for example, the user might want to display the styled output are part of some larger UI output block. At the same time, I don't think it makes sense to always produce styled output when capturing the output in a string; if what the user wants is to parse the output, then the style escape sequences make this far harder. I propose that gdb.execute gain a new argument 'styling'. When False we would always produce unstyled output, and when True we would produce styled output if styling is not disabled by some other means. For example, if GDB's 'set style enabled' is off, then I think gdb.execute() should respect that. My assumption here is that gdb.execute() might be executed by some extension. If the extension thinks "styled output world work here", but the user hates styled output, and has turned it off, then the extension should not be forcing styled output on the user. I chose 'styling' instead of 'styled' as the Python argument name because we already use 'styling' in gdb.Value.format_string, and we don't use 'styled' anywhere else. This is only a little bit of consistency, but I still think it's a good thing. The default for 'styling' will change depending on where the output is going. When gdb.execute is sending the output to GDB's stdout then the default for 'styling' is True. When the output is going to a string, then the default for 'styling' will be False. Not only does this match the existing behaviour, but I think this makes sense. By default we assume that output captured in a string is going to be parsed, and therefore styling markup is unhelpful, while output going to stdout should receive styling. This fixes part of the problem described in PR gdb/32676. That bug tries to capture styled source listing in a string, which wasn't previously possible. There are some additional issues with capturing source code; GDB caches the source code in the source code cache. However, GDB doesn't check if the cached content is styled or not. As a consequence, if the first time the source of a file is shown it is unstyled, then the cached will hold the unstyled source code, and future requests will return that unstyled source. I'll address this issue in a separate patch. Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=32676 Approved-By: Tom Tromey <tom@tromey.com>
2025-03-19gdb: show full shared library memory range in 'info sharedlibrary'Andrew Burgess1-0/+6
On GNU/Linux (and other targets that use solib-svr4.c) the 'info sharedlibrary' command displays the address range for the .text section of each library. This is a fallback behaviour implemented in solib_map_sections (in solib.c), for targets which are not able to provide any better information. The manual doesn't really explain what the address range given means, and the .text fallback certainly isn't described. The manual for 'info sharedlibrary' just says: 'info share REGEX' 'info sharedlibrary REGEX' Print the names of the shared libraries which are currently loaded that match REGEX. If REGEX is omitted then print all shared libraries that are loaded. In this commit I propose that we should change GDB so that the full library address range is listed for GNU/Linux (and other solib-svr4 targets). Though it is certainly useful to know where the .text for a library is, not all code is placed into the .text section, and data, or course, is stored elsewhere, so the choice of .text, though not a crazy default, is still a pretty arbitrary choice. We do also have 'maintenance info sections', which can be used to find the location of a specific section. This is of course, a maintenance command, but we could make this into a real user command if we wanted, so the information lost by this change to 'info sharedlibrary' is still available if needed. There is one small problem. After this commit, GDB is still under reporting the extents of some libraries, in some cases. What I observe is that sometimes, for reasons that I don't currently understand, the run-time linker will over allocate memory for the .bss like sections, e.g. the ELF says that 1 page is required, but 2 or 4 pages will be allocated instead. As a result, GDB will under report the extent of the library, with the end address being lower than expected. This isn't always the case though, in many cases the allocates are as I would expect, and GDB reports the correct values. However, as we have been under reporting for many years, I think this update, which gets things a lot closer to reality, is a big step in the right direction. We can always improve the results more later on if/when the logic behind the over allocations become clearer. For testing I've compared the output of 'info proc mappings' with the output of 'info sharedlibrary' (using a script), using GDB to debug itself, on Fedora Linux running on AArch64, PPC64, S390, and X86-64, and other than the over allocation problem described above, the results all look good to me. Reviewed-By: Eli Zaretskii <eliz@gnu.org> Approved-By: Simon Marchi <simon.marchi@efficios.com>
2025-03-17gdb-add-index: add --help and --version optionsAndrew Burgess1-4/+11
Update the gdb-add-index script to offer --help and --version options. The script currently accepts the argument '-dwarf-5' with a single leading '-'. As two '--' is more common for long options, the preferred argument form is now '--dwarf-5', the docs have been updated, and the new help text uses this form. For backward compatibility, the old '-dwarf-5' form is still accepted. The new arguments are '--help' or '-h', but I also accept '-help' for consistency with '-dwarf-5'. And likewise for the version argument. Handling of the gdb-add-index script is done basically the same as for gcore and gstack; we use config.status to create a .in file within the build directory, which is then processed by the Makefile to create the final script. The difference with gdb-add-index is that I left the original script as gdb/contrib/gdb-add-index.sh rather than renaming it to something like gdb/contrib/gdb-add-index-1.in, which is how gcore and gstack are handled (though they are not in the contrib directory). The reason for this is that the contrib/cc-with-tweaks.sh script looks for gdb-add-index.sh within the gdb/contrib/ source directory. As the only reason we process gdb-add-index.sh into the build directory is to support the PKGVERSION and VERSION variables, allowing cc-with-tweaks to continue using the unprocessed version seems harmless, and avoids having to change cc-with-tweaks.sh at all. I tested that I can still run tests using the cc-with-gdb-index target board, and that the installed gdb-add-index script correctly shows a version number when asked. Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=32325 Reviewed-By: Eli Zaretskii <eliz@gnu.org> Approved-By: Tom Tromey <tom@tromey.com>
2025-03-13gcore/doc: fix mistake in the gcore man pageAndrew Burgess1-1/+1
The gcore man page says that the default prefix for a generated core file will be 'gcore', i.e. we'll create files like 'gcore.pid'. In reality the default is 'core'. As far as I can tell, the default has been 'core' for years, and the docs used to say that the default was 'core', but the docs were changed by mistake in commit: commit 129eb0f1f16dc7a49799a024a7bcb109d954a1e7 Date: Fri Jul 27 00:52:23 2018 -0400 Improve gcore manpage and clarify "-o" option So, lets bring the docs back inline with the code. Approved-By: Tom Tromey <tom@tromey.com> Reviewed-By: Eli Zaretskii <eliz@gnu.org>
2025-03-13gcore: add -h|--help options, and improve help/usage message outputAndrew Burgess1-1/+5
Like the previous commit, this copies a lot from: commit fb2ded33c1e519659743047ed7817166545b6d91 Date: Fri Dec 20 12:46:11 2024 -0800 Add gstack script And adds -h | --help options to the gcore script, and smartens up the help and usage output messages. The usage text is now split over several lines (as it was getting a bit long), and an input error suggests using `--help` instead of printing the full usage string. These changes bring gcore and gstack closer in behaviour. Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=32325 Approved-By: Tom Tromey <tom@tromey.com> Reviewed-By: Eli Zaretskii <eliz@gnu.org>
2025-03-13gcore: add -v or --version option to show version numberAndrew Burgess1-1/+6
Based on the work in this commit: commit fb2ded33c1e519659743047ed7817166545b6d91 Date: Fri Dec 20 12:46:11 2024 -0800 Add gstack script This commit adds a '-v' or '--version' option to the existing gcore script. This new option causes the script to print its version number, and then exit. I needed to adjust the getopts handling a little in order to support the long form '--version' argument, but as this makes gcore more consistent with gstack, then this seems like a good thing. The usage message is now getting a little long. Don't worry, I plan to clean that up in the next commit. Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=32325 Approved-By: Tom Tromey <tom@tromey.com> Reviewed-By: Eli Zaretskii <eliz@gnu.org>
2025-03-06[gdb/doc] Fix typos in gdb.texinfoTom de Vries1-4/+4
Fix typos: ... preprend -> prepend wth -> with Connnections -> Connections ...
2025-03-06[gdb/doc] Fix typos in annotate.texinfoTom de Vries1-2/+2
Fix typos: ... Dependant ==> Dependent ...
2025-03-06[gdb/doc] Fix typos in python.texiTom de Vries1-3/+3
Fix typos: ... atribute ==> attribute ...
2025-03-03[gdb/doc] Indicate in which languages 'filename'::funcaddr worksTom de Vries1-4/+8
In the docs I read [1]: ... In this section, we discuss operators that you can use in GDB expressions regardless of your programming language. ... GDB supports these operators, in addition to those common to programming languages: ‘::’ allows you to specify a variable in terms of the file or function where it is defined. See Program Variables. ... In fact, this is not supported in Ada: ... (gdb) b *'foo.adb'::foo No file or function "foo.adb'". (gdb) ... and likewise in a few other working languages. Fix this by making this restriction explicit. Approved-By: Eli Zaretskii <eliz@gnu.org> PR gdb/32753 Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=32753 [1] https://sourceware.org/gdb/current/onlinedocs/gdb.html/Expressions.html
2025-03-03[gdb/doc] Fix address location with file prefixTom de Vries1-2/+4
In the docs I read [1]: ... Address locations indicate a specific program address. They have the generalized form *address. funcaddr An address of a function or procedure derived from its name. ... 'filename':funcaddr Like funcaddr above, but also specifies the name of the source file explicitly. This is useful if the name of the function does not specify the function unambiguously, e.g., if there are several functions with identical names in different source files. ... This is incorrect, the notation is in fact 'filename'::funcaddr. Fix this by correcting the typo, and add a reference to "variable name conflict", where the concept is explained in more detail. Approved-By: Eli Zaretskii <eliz@gnu.org> PR gdb/32748 Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=32748 [1] https://sourceware.org/gdb/current/onlinedocs/gdb.html/Address-Locations.html
2025-03-03[gdb/doc] Don't advertise *&function for pascal and modula-2Tom de Vries1-4/+3
In the docs I read [1]: ... Address locations indicate a specific program address. They have the generalized form *address. ... funcaddr An address of a function or procedure derived from its name. ... In Pascal and Modula-2, this is &function. ... I tried "break *&function" for Pascal and Modula-2, and this doesn't work, while "break *function" works fine. Fix this by updating the documentation to reflect actual behaviour. Approved-By: Eli Zaretskii <eliz@gnu.org> PR gdb/32754 Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=32754 [1] https://sourceware.org/gdb/current/onlinedocs/gdb.html/Address-Locations.html
2025-02-24[gdb/doc] Fix documentation of handle SIGKILLTom de Vries1-1/+1
Here ( https://sourceware.org/gdb/current/onlinedocs/gdb.html/Signals.html ) I read: ... GDB has the ability to detect any occurrence of a signal in your program. You can tell GDB in advance what to do for each kind of signal. ... However, here ( https://man7.org/linux/man-pages/man2/ptrace.2.html ) I read: ... While being traced, the tracee will stop each time a signal is delivered, even if the signal is being ignored. (An exception is SIGKILL, which has its usual effect.) ... So, it seems to be that for SIGKILL we can't tell GDB in advance what to do. Fix the documentation to reflect this. Approved-By: Eli Zaretskii <eliz@gnu.org> PR gdb/32714 Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=32714
2025-02-24gdb: handle empty locspec when printing breakpointsAndrew Burgess1-0/+5
For background reading, please see the previous patch, and the patch before that! After the last two patches, internal breakpoints can now be marked as shlib_disabled if the library in which they are placed is unloaded. The patch before last discusses a situation related to the gdb.base/nostdlib.exp test, when run on a GNU/Linux glibc based system where executables are compiled as PIE by default. In this case it is observed that the dynamic linker will actually report itself as unloaded (i.e. remove itself from the list of currently loaded shared libraries). This behaviour is likely a bug in the dynamic linker, but this behaviour exists in released versions of the dynamic linker, so GDB should (if the cost is not too great) be changed to handle this situation. This commit handles a problem with the 'maint info breakpoints' command. When the dynamic linker is unloaded the 'shlib event' breakpoint is marked as shlib_disabled (i.e. placed into the pending state). When displaying the breakpoint in the 'maint info breakpoints' output, GDB will try to print the locspec (location_spec *) as a string Unfortunately, the locspec will be nullptr as the internal breakpoints are not created via a location_spec, this means that GDB ends up trying to call location_sepc::to_string() on a nullptr, resulting in undefined behaviour (and a crash). For most internal breakpoint types this is not a problem. If we consider bp_longjmp_master for example, if the shared library containing a breakpoint of this type is unloaded then first GDB marks the breakpoint as shlib_disabled, then after unloading the shared library breakpoint_re_set is called, which will delete the internal breakpoint, and then try to re-create it (if needed). As a result, the user never gets a change to run 'maint info breakpoints' on a bp_longjmp_master breakpoint in the shlib_disabled state. But bp_shlib_event and bp_thread_event breakpoints are not deleted and recreated like this (see internal_breakpoint::re_set), so it is possible, in rare cases, that we could end up trying to view one of these breakpoint in a shlib_disabled state, and it would be nice if GDB didn't crash as a result. I've updated the printing code to check for and handle this case, and I've updated the docs to mention this (rare) case. For testing, I've extended gdb.base/nostdlib.exp to compile as pie and nopie, and then run 'maint info breakpoints'. If we're running on a buggy glibc then this will trigger the crash. I don't know how I can trigger this problem without a buggy glibc as this would require forcing the dynamic linker to be unloaded. Reviewed-By: Eli Zaretskii <eliz@gnu.org> Approved-By: Tom Tromey <tom@tromey.com>
2025-02-20gdb/doc: fix sentence in save gdb-index` command docSimon Marchi1-4/+3
The part "... this command by default creates it produces a single ..." sounds wrong. Replace with "... this command by default produces a single ...". Change-Id: I39cc533fa5a2bf473ca9e361ee0e6426d7d37ac6
2025-02-20gdb/doc: fix .debug_index -> .gdb_indexSimon Marchi1-1/+1
Change-Id: Ibd8d6c35c2cc02e309f83b11b5fd1172dfa05283
2025-02-19gdbserver, remote: introduce "id_str" in the "qXfer:threads:read" XMLTankut Baris Aktemur1-2/+5
GDB prints the target id of a thread in various places such as the output of the "info threads" command in the "Target Id" column or when switching to a thread. A target can define what to print for a given ptid by overriding the `pid_to_str` method. The remote target is a gateway behind which one of many various targets could be running. The remote target converts a given ptid to a string in a uniform way, without consulting the low target at the server-side. In this patch we introduce a new attribute in the XML that is sent in response to the "qXfer:threads:read" RSP packet, so that a low target at the server side, if it wishes, can specify what to print as the target id of a thread. Note that the existing "name" attribute or the "extra" text provided in the XML are not sufficient for the server-side low target to achieve the goal. Those attributes, when present, are simply appended to the target id by GDB. Reviewed-By: Eli Zaretskii <eliz@gnu.org> Reviewed-By: Thiago Jung Bauermann <thiago.bauermann@linaro.org> Approved-By: Simon Marchi <simon.marchi@efficios.com>
2025-02-10gdb/dwarf: write offset to parent entry for DW_IDX_parentSimon Marchi1-4/+37
New in v2: - add doc - fix computation of offset in entry pool Due to a mistake in the DWARF 5 spec, the way that GDB interprets DW_IDX_parent when generating and reading .debug_names is not correct. In Section 6.1.1.2, the parent index entry attribute is described as: Parent debugging information entry, a reference to the index entry for the parent. This is represented as the offset of the entry relative to the start of the entry pool. But in Table 6.1, DW_IDX_parent is described as: Index of name table entry for parent These two contradict each other. The former is the correct one and the latter is an unfortunate leftover from an earlier version of the proposal, according to [1]. It does make sense, because pointing to a name table entry is ambiguous, while poiting to an index entry directly is not. Unfortunately, GDB implemented pointing to a name table entry. Changes on the writer side: - For each written pool entry, remember the offset within the pool. - Change the DW_IDX_parent form to DW_FORM_data4. Using DW_FORM_udata isn't an option, because we don't know the actual value when doing the first pass of writing the pool (see next point), so we wouldn't know how many bytes to reserve, if we used a variable-size encoding. Using a fixed 4 bytes encoding would be an issue if the entry pool was larger than 4 GiB, but that seems unlikely. Note that clang uses DW_FORM_ref4 for this, but I'm not sure it is appropriate, since forms of the reference class are specified as referring "to one of the debugging information entries that describe the program". Since we're not referring to a DIE, I decided to stay with a form of the "constant" class. I think that readers will be able to understand either way. - Write a dummy 4 byte number when writing the pool, then patch those values later. This is needed because parents can appear before their children in the pool (there's no way to ensure that parents always appear before their children), so we might now know at first what value to put in. - Add a `write_uint` method to `class data_buf` to support that use case of patching a value in the middle of the data buffer. - Simplify the type of `m_name_to_value_set`, we no longer need to track the index at which a name will be written at. - Produce a new augmentation string, "GDB3", to be able to distinguish "old" and "new" indexes. It would be possible for a reader to distinguish the two semantics of DW_IDX_parent using the form. However, current versions of GDB don't do that, so they would be confused trying to read a new index. I think it is preferable to use a new augmentation string so that they will reject a new index instead. Changes on the reader side: - Track the GDB augmentation version, in addition to whether the augmentation string indicates the index was produced by GDB. - When reading index entries, maintain a "pool offset" -> "cooked index entry" mapping, to be able to find parents by pool offset. - When resolving parents, keep the existing behavior of finding parents by name table index if the augmentation string is "GDB2. Otherwise, look up parents by pool offset. This assumes that .debug_names from other producers (if/when we add support for reading them) use pool offsets for DW_IDX_parent. This at least what clang does. - Simplify augmentation string comparison a bit by using array views. Update the "Extensions to ‘.debug_names’" section of the documentation to reflect the new augmentation string version. Tested by: - manually producing executables with "GDB2" and "GDB3" .debug_names sections and reading them. - running the testsuite with the cc-with-debug-names board [1] https://lists.dwarfstd.org/pipermail/dwarf-discuss/2025-January/002618.html Change-Id: I265fa38070b86ef320e0a972c300d1d755735d8d Reviewed-By: Eli Zaretskii <eliz@gnu.org> Approved-By: Tom Tromey <tom@tromey.com>
2025-02-09gdb/mi: include ranges in =library-unloaded eventAndrew Burgess1-5/+15
Having looked at the dlmopen support in GDB, it occurred to me that the current MI =library-unloaded event doesn't incude enough information to be useful. Consider the gdb.mi/mi-dlmopen.exp test, this test loads libraries into multiple linker namespaces, and then unloads these libraries. We should probably figure out a way to include the linker namepsace ID in GDB's output, e.g. in the =library-loaded and =library-unloaded MI events, and in the output of 'info sharedlibrary'. But this commit is not about doing that. This commit includes the 'ranges' information in the =library-unloaded event output. This is the same ranges information as is included in the =library-loaded output. Even without the linker namespace ID, this should allow MI consumers to figure out which library instance is being unloaded. Here is the 'info sharedlibrary' output for mi-dlmopen.exp at the point where all the shared libraries are loaded: info sharedlibrary &"info sharedlibrary\n" ~"From To Syms Read Shared Object Library\n" ~"0x00007ffff7fca000 0x00007ffff7ff03f5 Yes /lib64/ld-linux-x86-64.so.2\n" ~"0x00007ffff7eda3d0 0x00007ffff7f4e898 Yes /lib64/libm.so.6\n" ~"0x00007ffff7d0e800 0x00007ffff7e6dccd Yes /lib64/libc.so.6\n" ~"0x00007ffff7fbd040 0x00007ffff7fbd116 Yes /tmp/build/gdb/testsuite/outputs/gdb.mi/mi-dlmopen/dlmopen-lib.1.so\n" ~"0x00007ffff7fb8040 0x00007ffff7fb80f9 Yes /tmp/build/gdb/testsuite/outputs/gdb.mi/mi-dlmopen/dlmopen-lib-dep.so\n" ~"0x00007ffff7bfe3d0 0x00007ffff7c72898 Yes /lib64/libm.so.6\n" ~"0x00007ffff7a32800 0x00007ffff7b91ccd Yes /lib64/libc.so.6\n" ~"0x00007ffff7fca000 0x00007ffff7ff03f5 Yes /lib64/ld-linux-x86-64.so.2\n" ~"0x00007ffff7fb3040 0x00007ffff7fb3116 Yes /tmp/build/gdb/testsuite/outputs/gdb.mi/mi-dlmopen/dlmopen-lib.1.so\n" ~"0x00007ffff7fae040 0x00007ffff7fae0f9 Yes /tmp/build/gdb/testsuite/outputs/gdb.mi/mi-dlmopen/dlmopen-lib-dep.so\n" ~"0x00007ffff7ce1040 0x00007ffff7ce1116 Yes /tmp/build/gdb/testsuite/outputs/gdb.mi/mi-dlmopen/dlmopen-lib.1.so\n" ~"0x00007ffff7cdc040 0x00007ffff7cdc0f9 Yes /tmp/build/gdb/testsuite/outputs/gdb.mi/mi-dlmopen/dlmopen-lib-dep.so\n" ~"0x00007ffff79253d0 0x00007ffff7999898 Yes /lib64/libm.so.6\n" ~"0x00007ffff7759800 0x00007ffff78b8ccd Yes /lib64/libc.so.6\n" ~"0x00007ffff7fca000 0x00007ffff7ff03f5 Yes /lib64/ld-linux-x86-64.so.2\n" ~"0x00007ffff7cd7040 0x00007ffff7cd7116 Yes /tmp/build/gdb/testsuite/outputs/gdb.mi/mi-dlmopen/dlmopen-lib.2.so\n" ^done (gdb) Notice that dlmopen-lib.1.so is loaded multiple times. Here is the =library-unloaded event when one copy of this library is unloaded before this patch: =library-unloaded,id="/tmp/build/gdb/testsuite/outputs/gdb.mi/mi-dlmopen/dlmopen-lib.1.so", target-name="/tmp/build/gdb/testsuite/outputs/gdb.mi/mi-dlmopen/dlmopen-lib.1.so", host-name="/tmp/build/gdb/testsuite/outputs/gdb.mi/mi-dlmopen/dlmopen-lib.1.so", thread-group="i1", It is not possible, given this information, to know which copy of dlmopen-lib.1.so has actually been unloaded. An MI consumer would need to query the full shared library list and update from that information. After this patch the new output is: =library-unloaded,id="/tmp/build/gdb/testsuite/outputs/gdb.mi/mi-dlmopen/dlmopen-lib.1.so", target-name="/tmp/build/gdb/testsuite/outputs/gdb.mi/mi-dlmopen/dlmopen-lib.1.so", host-name="/tmp/build/gdb/testsuite/outputs/gdb.mi/mi-dlmopen/dlmopen-lib.1.so", thread-group="i1", ranges=[{from="0x00007ffff7fbd040",to="0x00007ffff7fbd116"}], still-in-use="false" The new 'ranges' field allows an MI consumer to uniquely identify which library instance was just unmapped. A frontent could, e.g. update a library list with no need to query the full shared library list. To include the 'ranges' field I updated mi_interp::on_solib_unloaded to call a new helper function. The new helper function is split out from the existing mi_output_solib_attribs. I was tempted to just call mi_output_solib_attribs, but doing so would mean that the 'symbols-loaded' field was also added to the =library-unloaded event, however, the docs for 'symbols-unloaded' on =library-loaded says: The @var{symbols-loaded} field is emitted only for backward compatibility and should not be relied on to convey any useful information. And it seemed silly to add a fields to =library-unloaded, which I would then document as something that should be ignored. The new helper function means I can avoid emitting the 'symbols-loaded' field. I have also added a 'still-in-use' field. When true this indicates that the library was removed from the inferior's library list, but the mapping was not removed from the inferior's address space as there is another copy of the library that is still using the library. In the above list, notice that ld-linux-x86-64.so.2 appears 3 times, but each instance is mapped as 0x00007ffff7fca000. When one copy of ld-linux-x86-64.so.2 is unloaded, here's the event: =library-unloaded,id="/lib64/ld-linux-x86-64.so.2", target-name="/lib64/ld-linux-x86-64.so.2", host-name="/lib64/ld-linux-x86-64.so.2", thread-group="i1", ranges=[{from="0x00007ffff7fca000",to="0x00007ffff7ff03f5"}], still-in-use="true" The 'still-in-use' field is 'true', this indicates there are at least one instance of this library remaining mapped at 0x00007ffff7fca000. Reviewed-By: Eli Zaretskii <eliz@gnu.org>