This patch originated from this mailing list discussion:
https://inbox.sourceware.org/gdb-patches/b9b5bf03c59b58e02ca27b522338c6103d5ae49f.camel@gnu.org
The user has some core files which lack an NT_FILE note. They
wondered why GDB was still unable to find the shared libraries based
on their build-id.
The reason right now is that GDB only records the build-id information
for mappings based on the entries in the NT_FILE note. With the
entries in this note we build several lookup tables; a filename to
build-id table, a soname (extracted from the file if it is a shared
library) to build-id table, and an address range to build-id table.
When a shared library is being loaded we perform a lookup using two
pieces of information; the shared library's filename, and an address
that we know is within the shared library. If either of these give a
build-id, then we can use that build-id to ensure GDB loads the
shared library that matches the core file.
If the NT_FILE note is missing then none of the lookup tables are
created, and so the shared library build-id lookup fails, meaning that
all GDB can do is look for the shared library by name on the local
file system. This often results in the wrong library version being
loaded, or the library not being found at all.
However, Linux core files also have the segment table. This table
gives address ranges. The segment table doesn't tell us what file was
mapped in, or the offset within the file that was mapped in. But if
we go back to the three lookup tables, we can use the segment table to
build the address to build-id lookup table, and that would be enough
to allow GDB to find the build-id for a shared library in most cases.
So, here's what this patch does: linux_read_core_file_mappings (in
linux-tdep.c) is updated to first parse the NT_FILE note as it
currently does. But after this we also walk the segment table (BFD
actually converts these into sections with the LOAD flag set), and if
a segment has a build-id, and doesn't correspond to an entry found in
the NT_FILE note, we create an anonymous mapping. An anonymous
mapping is just like a mapping from the NT_FILE note, but without a
filename and file offset. This mapping is passed through the callback
just like the traditional, non-anonymous, mappings.
Then in corelow.c various functions are updated in order to handle
anonymous mappings.
Back in linux-tdep.c, function linux_core_info_proc_mappings gets a
small update to handle anonymous mappings.
The corefile-buildid.exp test is updated to remove the NT_FILE notes
and rerun the tests. This should make no difference as all this test
is checking is that GDB is able to find and load the shared libraries
and executable based on their build-ids; this is something we can do
fine now without the NT_FILE note.
I have also had to update the Python core file API documentation after
this commit. Previously we claimed that CorefileMappedFile.filename
would never be empty, but this is now possible. Luckily, this API has
not yet been in a released version of GDB, so this minor tweak isn't
going to break any existing user code. I did consider having
CorefileMappedFile.filename be a non-empty string or None, but I
couldn't see much value in this, so I just documented that the string
could be empty, and what this means.
The py-corefile.exp test needed a minor update to filter out anonymous
mappings (those without a filename), this matches the behaviour of the
builtin 'info proc mappings' command.
Reviewed-By: Keith Seitz <keiths@redhat.com>
Add a new Python event registry, events.corefile_changed. This event
is emitted each time the corefile within an inferior changes.
The event object has a single 'inferior' attribute which is the
gdb.Inferior object for which the core file changed. The user can
then inspect Inferior.corefile to see details about the new core file,
or this will be None if the core file was removed from the inferior.
I've updated the existing test to cover this new event.
The new test covers both the corefile_changed event, but also monitors
the exited event. This ties into the work done in the previous
commit where we use whether the inferior has exited or not as a guard
for whether core_target::exit_core_file_inferior should be called.
Unloading a core file should result in a single corefile_changed event
and a single exited event.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
This commit adds a new property - ranges - to gdb.Block object. It holds
a tuple of ranges for that block. Each range is a tuple of (start, end)
address. For contiguous blocks it contains only one range.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Tom Tromey <tom@tromey.com>
Extend the Architecture.disassemble API to allow the user to request
styled disassembler output via a new styling argument. A user can now
write:
insn = arch.disassemble(address, styling = True)
The instruction strings returned within INSN will contain ANSI escape
sequences so long as 'set style enabled on' is in effect. This means
that the user's personal settings (disabling styling) will override a
GDB extension that requests styled disassembler output. I think this
makes sense.
The default for the styling argument is False, this maintains the
current unstyled output as default.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Tom Tromey <tom@tromey.com>
Creating a Python gdb.FinishBreakpoint for an inline frame doesn't
work.
If we look at the 'finish' command, in the finish_command
function (infcmd.c) then we see that GDB handles inline frames very
different to non-inline frames.
For non-inline frames GDB creates a temporary breakpoint and then
resumes the inferior until the breakpoint is hit.
But for inline frames, GDB steps forward until we have left the inline
frame.
When it comes to gdb.FinishBreakpoint we only have the "create a
temporary breakpoint" mechanism; that is, after all, what the
FinishBreakpoint is, it's a temporary breakpoint placed at the
return address in the caller.
Currently, when a FinishBreakpoint is created within an inline frame,
GDB ends up creating the breakpoint at the current $pc. As a result
the breakpoint will not be hit before the current function
exits (unless there's a loop going on, but that's not the point).
We could imagine what a solution to this problem would look like, GDB
would need to figure out the set of addresses for all possible exit
points from the inline function, and place a breakpoint at each of
these locations. I don't propose doing that in this commit.
Instead, I plan to update the docs to note that creating a
FinishBreakpoint within an inline frame is not allowed, and I will
catch this case within bpfinishpy_init (python/py-finishbreakpoint.c)
and throw an error.
Though the error is new, all I'm doing is raising an error for a case
that never worked.
There's a new test to cover this case.
Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=18339
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Tom Tromey <tom@tromey.com>
This commit adds a new method gdb.Symtab.source_lines. This method
can be used to read the lines from a symtab's source file. This is
similar to GDB's internal source_cache::get_source_lines function.
Currently using the Python API, if a user wants to display source
lines then they need to use Symtab.fullname() to get the source file
name, then open this file and parse out the lines themselves.
This isn't too much effort, but the problem is that these lines will
not be styled. The user could style the source content themselves,
but will this be styled exactly as GDB would style it?
The new Symtab.source_lines() method returns source lines with styling
included (as ANSI terminal escape sequences), assuming of course, that
styling is currently enabled.
Of course, in some cases, a user of the Python API might want source
code without styling. That's supported too, the new method has an
'unstyled' argument. If this is True then the output is forced to be
unstyled. The argument is named 'unstyled' rather than 'styled'
because the API call cannot force styling on. If 'set style enabled
off' is in effect then making the API call will never return styled
source lines.
The new API call allows for a range of lines to be requested if
desired.
As part of this commit I've updated the host_string_to_python_string
utility function to take a std::string_view.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Tom Tromey <tom@tromey.com>
This commit introduces a new Python event, selected_context. This
event is attached to the user_selected_context_changed observer, which
triggers when the user changes the currently selected inferior,
thread, or frame.
Adding this event allows a Python extension to update in response to
user driven changes without having to poll the state from a
before_prompt hook, which is what I currently do to achieve the same
results.
I did consider splitting the user_selected_context_changed observer
into 3 separate Python events, inferior_changed, thread_changed, and
frame_changed, but I couldn't see any significant advantage to doing
this, so in the end I went with just a single event, and the event
object contains the inferior, thread, and frame.
Additionally, the user isn't informed about which aspect of the
context changed. That is, every event carries the inferior, thread,
and frame, so an event triggered when switching frames will looks
identical to an event triggered when switching inferiors. If the user
wants to know what changed then they will have to track the current
state themselves, and then compare the event state to the stored
current state. In many cases though I suspect that just being told
something changed, and then updating everything will be sufficient,
which is why I've not bothered trying to inform the user what changed.
Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=24482
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Tom Tromey <tom@tromey.com>
This updates the copyright headers to include 2026. I did this by
running gdb/copyright.py and then manually modifying a few files as
noted by the script.
Since commit dad36cf919 ("gdb/dwarf: use dynamic partitioning for
DWARF CU indexing"), we get the intermittent failures:
python print (gdb.lookup_static_symbol ('rr').line)
18
(gdb) FAIL: gdb.python/py-symbol.exp: print line number of rr
python print (gdb.lookup_static_symbol ('rr').value ())
99
(gdb) FAIL: gdb.python/py-symbol.exp: print value of rr
The situation is:
- The program isn't running.
- Two compilation units define a static symbol named `rr`.
- The test does:
gdb.lookup_static_symbol ('rr')
The test expects this to return one specific (out of the two) `rr`
static symbols. Since dad36cf919, the call sometimes returns the
wrong symbol.
The documentation for gdb.lookup_static_symbol says this:
There can be multiple global symbols with static linkage with the
same name. This function will only return the first matching symbol
that it finds. Which symbol is found depends on where GDB is
currently stopped, as GDB will first search for matching symbols in
the current object file, and then search all other object files. If
the application is not yet running then GDB will search all object
files in the order they appear in the debug information.
cooked_index_functions::search searches index shards linearly and
returns the first matching symbol. Before dad36cf919, the work was
split statically among threads, so symbols would end up in shards
deterministically. Since the first part of the debug info ends up in
the first shard, it happens to work as described in the doc.
Since dad36cf919, symbols end up in random shards, based on which
thread happened to pop their CU from the work queue.
I don't think that specifying which of the multiple matching static
symbols is returned is really useful, as it unnecessarily restricts the
implementation. If multiple static symbols match the criteria, I think
it makes sense that you'll get an unspecified one. Code that needs to
deal with the possibility of multiple static symbols of the same name
should use gdb.lookup_static_symbols.
I propose to remove this guarantee from gdb.lookup_static_symbol. I
understand that this is a breaking change, but I think it's easy enough
to deal with it.
Update the test to accept either symbol.
Update the doc to say that an unspecified symbol will be returned if the
program is not running and there are multiple matching symbols. The
previous text also seemed a bit wrong about its use of the term "object
file". GDB searches a static symbol for the current compilation unit
first. It then falls back to searching all symbols.
Change-Id: I22f81c186b1483a488ea7614fb81fd102db3c7f1
Approved-By: Tom Tromey <tom@tromey.com>
Reviewed-By: Tom de Vries <tdevries@suse.de>
Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=33518
Approved-By: Andrew Burgess <aburgess@redhat.com>
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
This change adapts the print syntax to Python 3.
The documentation examples will then work on current installations.
Python 2 was sunsetted in January 2020.
Approved-By: Tom Tromey <tom@tromey.com>
Add a new Corefile.mapped_files method which returns a list of
gdb.CorefileMappedFile objects.
Each gdb.CorefileMappedFile object represents a file that was mapped
into the process when the core file was created.
A gdb.CorefileMappedFile has attributes:
+ filename -- A string, the name of the mapped file.
+ build_id -- A string or None, the build-id of the mapped file if
GDB could find it (None if not).
+ is_main_executable -- A boolean, True if this mapping is the main
executable.
+ regions -- A list containing the regions of this file that were
mapped into the process.
The 'regions' list is a list of gdb.CorefileMappedFileRegion objects,
each of these objects has the following attributes:
+ start -- the start address within the inferior.
+ end -- the end address within the inferior.
+ file_offset -- the offset within the mapped file for this mapping.
There are docs and tests.
Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=32844
Approved-By: Tom Tromey <tom@tromey.com>
This commit starts adding some core file related features to the
Python API.
In this initial commit I've tried to keep the changes as small as
possible for easy review.
There's a new Python class gdb.Corefile, which represents a loaded
core file. This API doesn't allow the user to create their own
gdb.Corefile objects, a core file must be loaded using the 'core-file'
command, then a gdb.Corefile object can be obtained by querying the
inferior in which the core file was loaded.
There's a new attribute gdb.Inferior.corefile, this is None when no
core file is loaded, or contains a gdb.Corefile object if a core file
has been loaded.
Currently, the gdb.Corefile object has one attribute, and one method,
these are:
gdb.Corefile.filename -- the file name of the loaded core file.
gdb.Corefile.is_valid() -- indicates if a gdb.Corefile object is
valid or not. See notes below.
A gdb.Corefile object is only valid while the corresponding core file
is loaded into an inferior. Unloading the core file, or loading a
different one will cause a gdb.Corefile object to become invalid. For
example:
(gdb) core-file /tmp/core.54313
... snip ...
(gdb) python core=gdb.selected_inferior().corefile
(gdb) python print(core)
<gdb.Corefile inferior=1 filename='/tmp/core.54313'>
(gdb) python print(core.is_valid())
True
(gdb) core-file
No core file now.
(gdb) python print(core)
<gdb.Corefile (invalid)>
(gdb) python print(core.is_valid())
False
(gdb)
In order to track changes to the core file, there is a new observable
'core_file_changed', which accounts for the changes in corelow.c,
observable,c, and observable.h. Currently, this observable is not
visible as a Python event.
I chose to access the core file via the inferior even though the core
file BFD object is actually stored within the program_space. As such,
it might seem that the natural choice would be to add the attribute as
gdb.Progspace.corefile.
For background reading on my choice, please see:
https://inbox.sourceware.org/gdb-patches/577f2c47793acb501c2611c0e6c7ea379f774830.1668789658.git.aburgess@redhat.com
This patch was never merged, it is still on my backlog, but the
observation in that work is that some targets are not really
shareable. For example, the core_target (corelow.c) stores
information about the loaded core file within the target instance. As
such, each target instance represents a single loaded core file.
Except that the BFD part of the core file is stored in the
program_space, which is a little weird.
During review, Tom made the observation, that maybe we should
investigate moving the core file BFD into the core_target. I'm
inclined to agree with this as a direction of travel.
All this leaves us with two observations:
1. Currently, loading a core file into an inferior, then using
'add-inferior' will try to share the core_target between
inferiors. This is broken, and can trigger GDB crashes. The
obvious fix, without reworking core_target, is just to prevent
this sharing, making core_target per-inferior.
2. Having the core file information split between the core_target
instance, and the BFD stored in the program_space is a little
weird, and is really just historical. Planning for a future
where the BFD is also stored in the core_target might be wise.
So, if we imagine that the BFD is (one day) moved into the
core_target, and that the core_target really becomes non-shareable,
then it is, I think, clearer that the corefile attribute should live
on the gdb.Inferior object, not the gdb.Progspace object.
There's testing for all the functionality added in this commit.
Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=32844
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Tom Tromey <tom@tromey.com>
It is already possible to produce styled output from Python by
converting the gdb.Style to its escape code sequence, and writing that
to the output stream.
But this commit adds an alternative option to the mix by extending the
existing gdb.write() function to accept a 'style' argument. The value
of this argument can be 'None' to indicate no style change should be
performed, this is the default, and matches the existing behaviour.
Or the new 'style' argument can be a gdb.Style object, in which case
the specified style is applied only for the string passed to
gdb.write, after which the default style is re-applied.
Using gdb.write with a style object more closely matches how GDB
handles styling internally, and has the benefit that the user doesn't
need to remember to restore the default style when they are done.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Tom Tromey <tom@tromey.com>
Add a new helper class gdb.StyleParameterSet. This new class can be
used to simplify creation of new style parameter sets. A style
parameter set is the 'foreground', 'background', and (optionally), the
'intensity' settings, all grouped under a single prefix command.
And example usage is:
(gdb) python s = gdb.StyleParameterSet("my-style")
(gdb) show style my-style
style my-style background: The "my-style" style background color is: none
style my-style foreground: The "my-style" style foreground color is: none
style my-style intensity: The "my-style" style display intensity is: normal
(gdb)
Having created a gdb.StyleParameterSet, the object itself can be used
to access a named style corresponding to the setting group, like this:
(gdb) python print(s.style)
<gdb.Style name='my-style', fg=none, bg=none, intensity=normal>
(gdb)
Of course, having access to the gdb.Style makes it easy to change the
settings, or the settings can be adjusted via the normal CLI 'set'
commands.
As gdb.StyleParameterSet manages a set of parameters, and the
gdb.Parameter class uses Parameter.value as the attribute to read the
parameter's value, there is also StyleParameterSet.value, but this is
just an alias for StyleParameterSet.style, that is, it allows the
gdb.Style object to be read and written too.
It is worth noting that this class only creates a single level of
prefix command. As an example GDB has style 'disassembler mnemonic',
where the 'disassembler' part is a group of related styles. If a user
wanted to create:
style
my-style-group
style-1
style-2
style-3
Where each of 'style-1', 'style-2', and 'style-3' will have the full
set of 'foreground', 'background', and 'intensity', then the
gdb.StyleParameterSet can be used to create the 'style-N' part, but
the user will have to create the 'my-style-group' prefix themselves,
possibly using gdb.ParameterPrefix, e.g.:
gdb.ParameterPrefix("style my-style-group", gdb.COMMAND_NONE)
gdb.StyleParameterSet("my-style-group style-1")
gdb.StyleParameterSet("my-style-group style-2")
gdb.StyleParameterSet("my-style-group style-3")
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Tom Tromey <tom@tromey.com>
This commit adds a new gdb.Style class. This class represents a
complete style within GDB. A complete style is a collection of
foreground color, background color, and an intensity.
A gdb.Style comes in two flavours, named, and unnamed.
A named style is one that is based on an existing style within GDB.
For example, we have 'set style filename ...', the name of this style
is 'filename'. We also have 'set style disassembler mnemonic ...',
the name of this style is 'disassembler mnemonic'. A named style is
created by passing the name of the style, like this:
(gdb) python s1 = gdb.Style("filename")
(gdb) python s2 = gdb.Style("disassembler mnemonic")
The other type of style is an unnamed style. An unnamed style is
created using a foreground and background color, along with an
intensity. Colors are specified using gdb.Color objects. An example
of creating an unnamed style is:
(gdb) python s3 = gdb.Style(foreground=gdb.Color('red'),
background=gdb.Color('green'),
intensity=gdb.INTENSITY_BOLD)
We can see here an example of the new intensity constants that have
been added in this commit, there is gdb.INTENSITY_NORMAL,
gdb.INTENSITY_BOLD, and gdb.INTENSITY_DIM. All of the arguments are
optional, the default for the colors is gdb.Color(), which will apply
the terminal default, and the default intensity is
gdb.INTENSITY_NORMAL.
Having created a gdb.Style object there are two ways that it can be
used to style GDB's output. The Style.escape_sequence() method
returns the escape sequence needed to apply this style, this can be
used as in:
(gdb) python print(s1.escape_sequence() + "Filename Style")
The problem with this approach is that it is the users responsibility
to restore the style to the default when they are done. In the above
example, all output after the escape sequence is printed, including
the next GDB prompt, will be in the s1 (filename) style. Which is why
the Style.apply method exists. This method takes a string and returns
the same string with escape sequences added before and after. The
before sequence switches to the style, while the after escape sequence
restores the terminal default style. This can be used like:
(gdb) python print(s1.apply("Filename Style"))
Now only the 'Filename Style' text will be styled. The next GDB
prompt will be in the default terminal style. Personally, I think the
apply method is the more useful, but having 'escape_sequence' matches
what gdb.Color offers, though if/when this patch is merged, I might
propose a similar 'apply' type method for the gdb.Color class.
The gdb.Style class has 'foreground', 'background', and 'intensity'
attributes which, when read, return the obvious values. These
attributes can also be written too.
When writing to an attribute of an unnamed Style object then the Style
object itself is updated, as you might expect.
When writing to an attribute of a named Style then the style setting
itself is updated as the following example shows:
(gdb) python s1 = gdb.Style("filename")
(gdb) python print(s1.foreground)
green
(gdb) show style filename foreground
The "filename" style foreground color is: green
(gdb) python s1.foreground=gdb.Color("red")
(gdb) python print(s1.foreground)
red
(gdb) show style filename foreground
The "filename" style foreground color is: red
(gdb)
We can see that a gdb.Style object is connected to the underlying
style settings, it doesn't take a copy of the style settings at
creation time. And the relationship works both ways. Continuing the
above example:
(gdb) set style filename foreground blue
(gdb) python print(s1.foreground)
blue
(gdb)
Here we see that changing the setting value causes the gdb.Style
object to update. And this is what you would want. I imagine this
being used in a Python extension to GDB, where a user might create
global objects for some named styles, and then use these globals to
format output from some custom commands. If a user of an extension
changes a style setting then the extension wants to adapt to that
change.
Both the Style.escape_sequence and Style.apply methods take the global
style enabled setting into consideration. If styling is disabled then
Style.escape_sequence will return an empty string, and Style.apply
will return an unmodified copy of the original string object (actually
the input object with Py_INCREF applied).
There is also support for representing a gdb.Style as a string:
(gdb) python s1 = gdb.Style("filename")
(gdb) python print(s1)
<gdb.Style name='filename', fg=green, bg=none, intensity=normal>
(gdb)
Unnamed styles are similar, but don't have a 'name' field.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Tom Tromey <tom@tromey.com>
My editor "accidentally" removed all trailing whitespaces from
gdb.texinfo while doing a change. That was mostly just an annoyance
but to avoid it happening again, I suggest removing them for good.
I look at the difference in the output of "make html". The new output
has some trailing whitespaces removed, but none of them seems to cause a
semantic difference. Not sure about other formats like info or pdf
though.
Change-Id: I3f349b28c581af69703365fea07e7b93614c987c
Approved-By: Eli Zaretskii <eliz@gnu.org>
Add a new gdb.Value.is_unavailable attribute. This is similar to the
existing Value.is_optimized_out attribute, but returns True if any
part of the value is <unavailable>.
The existing Value.is_optimized_out attribute returns true if any part
of the value is optimized out, so I thought that Value.is_unavailable
should work the same way.
There's also a test.
Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=33345
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Reviewed-By: Christina Schimpe <christina.schimpe@intel.com>
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>
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.
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>
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.
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>
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>
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>
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>
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{}.
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>
This commit adds a new method to Python architecture objects that
returns a void type for that architecture.
This will be useful later to create types for function symbols created
using Python extension code.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Andrew Burgess <aburgess@redhat.com>
This commit adds new propery "subblocks" to gdb.Block objects. This
allows Python to traverse block tree starting with global block.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Andrew Burgess <aburgess@redhat.com>
When building gdb with an older makeinfo (4.13), I run into:
...
gdb/doc/gdb.texinfo:49064: warning: @sc argument all uppercase, thus no effect.
...
Using a grep, I found one more instance:
...
$ grep @sc gdb/doc/*.tex* | egrep -v '@sc{[^A-Z]*}'
gdb/doc/gdb.texinfo:\
Bit 1 (@sc{ZA}) shows whether the @code{ZA} register state is active (in use) or
gdb/doc/python.texi:\
corresponding @sc{GDB/MI} command's output. Refer to the
...
Fix this by using lowercase letters in the @sc argument, similar to how that
was done in commit c96452ad16 ("Use lower-case in @sc in the documentation").
Tested by rebuilding the documentation.
When building gdb with an older makeinfo (4.13), I run into:
...
gdb/doc/python.texi:3015: warning: `(' follows defined name \
`gdb.unwinder.Unwinder.__init__' instead of whitespace.
gdb/doc/python.texi:3041: warning: `(' follows defined name \
`gdb.unwinder.FrameId.__init__' instead of whitespace.
...
The warnings are related to these two lines:
...
@defun gdb.unwinder.Unwinder.__init__(name)
...
@defun gdb.unwinder.FrameId.__init__(sp, pc, special = @code{None})
...
Indeed, when checking the command and variable index, we can see that it
contains an incorrect entry:
...
gdb.unwinder.FrameId.__init__(sp,: Unwinding Frames in Python
...
Fix this by adding a space before the left parenthesis.
Tested by rebuilding the documentation and checking the command and variable
index.
Colors can be specified as "none" for terminal's default color, as a name of
one of the eight standard colors of ISO/IEC 6429 "black", "red", "green", etc.,
as an RGB hexadecimal tripplet #RRGGBB for 24-bit TrueColor, or as an
integer from 0 to 255. Integers 0 to 7 are the synonyms for the standard
colors. Integers 8-15 are used for the so-called bright colors from the
aixterm extended 16-color palette. Integers 16-255 are the indexes into xterm
extended 256-color palette (usually 6x6x6 cube plus gray ramp). In
general, 256-color palette is terminal dependent and sometimes can be
changed with OSC 4 sequences, e.g. "\033]4;1;rgb:00/FF/00\033\\".
It is the responsibility of the user to verify that the terminal supports
the specified colors.
PATCH v5 changes: documentation fixed.
PATCH v6 changes: documentation fixed.
PATCH v7 changes: rebase onto master and fixes after review.
PATCH v8 changes: fixes after review.
Oleg pointed out that when renaming from "status" to "enabled" in the
Python TUI events patch, I neglected to update one spot in the
documentation. This patch fixes this. I'm checking it in as obvious.
You can verify that this change is correct by examining
gdb/python/py-event-types.def.
Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=32162
While testing DAP, we found a situation where a compiler-generated
variable caused the "variables" request to fail -- the variable in
question being an apparent 67-megabyte string.
It seems to me that artificial variables like this aren't interesting
to DAP users, and the gdb CLI omits these as well.
This patch changes DAP to omit these variables, adding a new
gdb.Symbol.is_artificial attribute to make this possible.
Eli mentioned [1] that given that we use US English spelling in our
documentation, we should use "behavior" instead of "behaviour".
In wikipedia-common-misspellings.txt there's a rule:
...
behavour->behavior, behaviour
...
which leaves this as a choice.
Add an overriding rule to hardcode the choice to common-misspellings.txt:
...
behavour->behavior
...
and add a rule to rewrite behaviour into behavior:
...
behaviour->behavior
...
and re-run spellcheck.sh on gdb*.
Tested on x86_64-linux.
[1] https://sourceware.org/pipermail/gdb-patches/2024-November/213371.html
I noticed the gdb.LazyString documentation did not mention how to
create one. Then, while adding this, I found a couple other ways that
this documentation could be clarified.
Approved-By: Eli Zaretskii <eliz@gnu.org>
Implement extension_language_ops::find_objfile_from_buildid within
GDB's Python API. Doing this allows users to write Python extensions
that can help locate missing objfiles when GDB opens a core file. A
handler might perform some project- or site-specific actions to find a
missing objfile. Or might provide some project- or site-specific
advice to the user on how they can obtain the missing objfile.
The implementation is very similar to the approach taken in:
commit 8f6c452b5a
Date: Sun Oct 15 22:48:42 2023 +0100
gdb: implement missing debug handler hook for Python
The following new commands are added as commands implemented in
Python, this is similar to how the Python missing debug and unwinder
commands are implemented:
info missing-objfile-handlers
enable missing-objfile-handler LOCUS HANDLER
disable missing-objfile-handler LOCUS HANDLER
To make use of this extension hook a user will create missing objfile
handler objects, and registers these handlers with GDB. When GDB
opens a core file and encounters a missing objfile each handler is
called in turn until one is able to help. Here is a minimal handler
that does nothing useful:
import gdb
import gdb.missing_objfile
class MyFirstHandler(gdb.missing_objfile.MissingObjfileHandler):
def __init__(self):
super().__init__("my_first_handler")
def __call__(self, pspace, build_id, filename):
# This handler does nothing useful.
return None
gdb.missing_objfile.register_handler(None, MyFirstHandler())
Returning None from the __call__ method tells GDB that this handler
was unable to find the missing objfile, and GDB should ask any other
registered handlers.
Possible return values from a handler:
- None: This means the handler couldn't help. GDB will call other
registered handlers to see if they can help instead.
- False: The handler has done all it can, but the objfile couldn't
be found. GDB will not call any other handlers, and will
continue without the objfile.
- True: The handler has installed the objfile into a location where
GDB would normally expect to find it. GDB should repeat its
normal lookup process and the objfile should now be found.
- A string: The handler can return a filename, which is the missing
objfile. GDB will load this file.
Handlers can be registered globally, or per program space. GDB checks
the handlers for the current program space first, and then all of the
global handles. The first handler that returns a value that is not
None, has "handled" the missing objfile, at which point GDB continues.
The implementation of this feature is mostly straight forward. I have
reworked some of the missing debug file related code so that it can be
shared with this feature. E.g. gdb/python/lib/gdb/missing_files.py is
mostly content moved from gdb/python/lib/gdb/missing_debug.py, but
updated to be more generic. Now gdb/python/lib/gdb/missing_debug.py
and the new file gdb/python/lib/gdb/missing_objfile.py both call into
the missing_files.py file.
For gdb/python/lib/gdb/command/missing_files.py this is even more
extreme, gdb/python/lib/gdb/command/missing_debug.py is completely
gone now and gdb/python/lib/gdb/command/missing_files.py provides all
of the new commands in a generic way.
I have made one change to the existing Python API, I renamed the
attribute Progspace.missing_debug_handlers to
Progspace.missing_file_handlers. I don't see this as too
problematic. This attribute was only used to implement the missing
debug feature and was never documented beyond the fact that it
existed. There was no reason for users to be touching this attribute.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
This adds a new event source so that Python scripts can track whether
or not the TUI is presently enabled.
v2 of the patch renames "status" -> "enabled".
Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=32162
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Reviewed-by: Keith Seitz <keiths@redhat.com>
Call the ptwrite filter function whenever a ptwrite event is decoded.
The returned string is written to the aux_data string table and a
corresponding auxiliary instruction is appended to the function segment.
Approved-By: Markus Metzger <markus.t.metzger@intel.com>
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
This function allows to clear the trace data from python, forcing to
re-decode the trace for successive commands.
This will be used in future ptwrite patches, to trigger re-decoding when
the ptwrite filter changes.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Markus Metzger <markus.t.metzger@intel.com>
Auxiliary instructions are no real instructions and get their own object
class, similar to gaps. gdb.Record.instruction_history is now possibly a
list of gdb.RecordInstruction, gdb.RecordGap or gdb.RecordAuxiliary
objects.
This patch is in preparation for the new ptwrite feature, which is based on
auxiliary instructions.
Approved-By: Markus Metzger <markus.t.metzger@intel.com>
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
An Ada pretty-printer had a bug where its 'child' method returned a
gdb.Value rather than a tuple. Kévin suggested that the documentation
for this method could be improved to clarify this.
Reviewed-By: Kévin Le Gouguec <legouguec@adacore.com>
Approved-By: Eli Zaretskii <eliz@gnu.org>
This patch changes the Python "stop" event emission code to also add
the function return value, if it is known. This happens when the stop
comes from a "finish" command and when the value can be fetched.
The test is in the next patch.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
The "python" command (and the Python implementation of the gdb
"source" command) does not handle Python exceptions in the same way as
other gdb-facing Python code. In particular, exceptions are turned
into a generic error rather than being routed through
gdbpy_handle_exception, which takes care of converting to 'quit' as
appropriate.
I think this was done this way because PyRun_SimpleFile and friends do
not propagate the Python exception -- they simply indicate that one
occurred.
This patch reimplements these functions to respect the general gdb
convention here. As a bonus, some Windows-specific code can be
removed, as can the _execute_file function.
The bulk of this change is tweaking the test suite to match the new
way that exceptions are displayed. These changes are largely
uninteresting. However, it's worth pointing out the py-error.exp
change. Here, the failure changes because the test changes the host
charset to something that isn't supported by Python. This then
results in a weird error in the new setup.
Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=31354
Acked-By: Tom de Vries <tdevries@suse.de>
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
