aboutsummaryrefslogtreecommitdiff
path: root/gdb/doc/python.texi
AgeCommit message (Collapse)AuthorFilesLines
2023-09-28gdb/python: new Progspace.symbol_file attributeAndrew Burgess1-0/+17
Add a new Progspace.symbol_file attribute. This attribute holds the gdb.Objfile object that corresponds to Progspace.filename, or None if there is no main symbol file currently set. Currently, to get this gdb.Objfile, a user would need to use Progspace.objfiles, and then search for the objfile with a name that matches Progspace.filename -- which should work just fine, but having direct access seems a little nicer. Reviewed-By: Eli Zaretskii <eliz@gnu.org> Approved-By: Tom Tromey <tom@tromey.com>
2023-09-28gdb/doc: extend the description for Progspace.filenameAndrew Burgess1-1/+6
Extend the description for Progspace.filename in the documentation to mention what the returned string is actually the filename for (e.g. that it is the filename passed to the 'symbol-file' or 'file' command). Also document that this attribute will be None if no symbol file is currently loaded. Reviewed-By: Eli Zaretskii <eliz@gnu.org> Approved-By: Tom Tromey <tom@tromey.com>
2023-09-26Add two new pretty-printer methodsTom Tromey1-0/+16
This adds two new pretty-printer methods, to support random access to children. The methods are implemented for the no-op array printer, and DAP is updated to use this. Reviewed-By: Eli Zaretskii <eliz@gnu.org>
2023-09-26Introduce gdb.ValuePrinterTom Tromey1-16/+36
There was an earlier thread about adding new methods to pretty-printers: https://sourceware.org/pipermail/gdb-patches/2023-June/200503.html We've known about the need for printer extensibility for a while, but have been hampered by backward-compatibilty concerns: gdb never documented that printers might acquire new methods, and so existing printers may have attribute name clashes. To solve this problem, this patch adds a new pretty-printer tag class that signals to gdb that the printer follows new extensibility rules. Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=30816 Reviewed-By: Eli Zaretskii <eliz@gnu.org>
2023-09-20gdb/tui: add 'set tui mouse-events off' to restore mouse selectionMatthew "strager" Glazar1-0/+5
Rationale: I use the mouse with my terminal to select and copy text. In gdb, I use the mouse to select a function name to set a breakpoint, or a variable name to print, for example. When gdb is compiled with ncurses mouse support, gdb's TUI mode intercepts mouse events. Left-clicking and dragging, which would normally select text, seems to do nothing. This means I cannot select text using my mouse anymore. This makes it harder to set breakpoints, print variables, etc. Solution: I tried to fix this issue by editing the 'mousemask' call to only enable buttons 4 and 5. However, this still caused my terminal (gnome-terminal) to not allow text to be selected. The only way I could make it work is by calling 'mousemask (0, NULL);'. But doing so disables the mouse code entirely, which other people might want. I therefore decided to make a setting in gdb called 'tui mouse-events'. If enabled (the default), the behavior is as it is now: terminal mouse events are given to gdb, disabling the terminal's default behavior. If disabled (opt-in), the behavior is as it was before the year 2020: terminal mouse events are not given to gdb, therefore the mouse can be used to select and copy text. Notes: I am not attached to the setting name or its description. Feel free to suggest better wording. Testing: I tested this change in gnome-terminal by performing the following steps manually: 1. Run: gdb --args ./myprogram 2. Enable TUI: press ctrl-x ctrl-a 3. Click and drag text with the mouse. Observe no selection. 4. Input: set tui mouse-events off 5. Click and drag text with the mouse. Observe that selection works now. 6. Input: set tui mouse-events on. 7. Click and drag text with the mouse. Observe no selection.
2023-09-11Update Python signal-handling documentationTom Tromey1-2/+4
I noticed a typo in the "Basic Python" node, and when fixing it realized that the paragraph could use a link to the block_signals function. This patch is the result. Approved-By: Eli Zaretskii <eliz@gnu.org>
2023-09-05Add new Python APIs to support DAP value displayTom Tromey1-0/+24
gdb's language code may know how to display values specially. For example, the Rust code understands that &str is a string-like type, or Ada knows how to handle unconstrained arrays. This knowledge is exposed via val-print, and via varobj -- but currently not via DAP. This patch adds some support code to let DAP also handle these cases, though in a somewhat more generic way. Type.is_array_like and Value.to_array are added to make Python aware of the cases where gdb knows that a structure type is really "array-like". Type.is_string_like is added to make Python aware of cases where gdb's language code knows that a type is string-like. Unlike Value.string, these cases are handled by the type's language, rather than the current language. Reviewed-By: Eli Zaretskii <eliz@gnu.org>
2023-08-17gdb: add inferior-specific breakpointsAndrew Burgess1-4/+22
This commit extends the breakpoint mechanism to allow for inferior specific breakpoints (but not watchpoints in this commit). As GDB gains better support for multiple connections, and so for running multiple (possibly unrelated) inferiors, then it is not hard to imagine that a user might wish to create breakpoints that apply to any thread in a single inferior. To achieve this currently, the user would need to create a condition possibly making use of the $_inferior convenience variable, which, though functional, isn't the most user friendly. This commit adds a new 'inferior' keyword that allows for the creation of inferior specific breakpoints. Inferior specific breakpoints are automatically deleted when the associated inferior is removed from GDB, this is similar to how thread-specific breakpoints are deleted when the associated thread is deleted. Watchpoints are already per-program-space, which in most cases mean watchpoints are already inferior specific. There is a small window where inferior-specific watchpoints might make sense, which is after a vfork, when two processes are sharing the same address space. However, I'm leaving that as an exercise for another day. For now, attempting to use the inferior keyword with a watchpoint will give an error, like this: (gdb) watch a8 inferior 1 Cannot use 'inferior' keyword with watchpoints A final note on the implementation: currently, inferior specific breakpoints, like thread-specific breakpoints, are inserted into every inferior, GDB then checks once the inferior stops if we are in the correct thread or inferior, and resumes automatically if we stopped in the wrong thread/inferior. An obvious optimisation here is to only insert breakpoint locations into the specific program space (which mostly means inferior) that contains either the inferior or thread we are interested in. This would reduce the number times GDB has to stop and then resume again in a multi-inferior setup. I have a series on the mailing list[1] that implements this optimisation for thread-specific breakpoints. Once this series has landed I'll update that series to also handle inferior specific breakpoints in the same way. For now, inferior specific breakpoints are just slightly less optimal, but this is no different to thread-specific breakpoints in a multi-inferior debug session, so I don't see this as a huge problem. [1] https://inbox.sourceware.org/gdb-patches/cover.1685479504.git.aburgess@redhat.com/
2023-08-11Fix Python documentation for range type fieldsTom Tromey1-3/+0
GDB's Python documentation claims that range types have two fields, but this is not true, and attempts to access them hit this error: "Type is not a structure, union, enum, or function type." This patch fixes the documentation.
2023-08-04Fix incorrect class name in free_objfile documentationTom Tromey1-1/+1
The documentation for the Python free_objfile event registry uses the wrong class name. This patch fixes it. I'm checking this in as obvious.
2023-07-23Export gdb.block_signals and create gdb.ThreadTom Tromey1-38/+66
While working on an experiment, I realized that I needed the DAP block_signals function. I figured other developers may need it as well, so this patch moves it from DAP to the gdb module and exports it. I also added a new subclass of threading.Thread that ensures that signals are blocked in the new thread. Finally, this patch slightly rearranges the documentation so that gdb-side threading issues and functions are all discussed in a single node.
2023-07-21Add Progspace.objfile_for_addressTom Tromey1-0/+5
This adds a new objfile_for_address method to gdb.Progspace. This makes it easy to find the objfile for a given address. There's a related PR; and while this change would have been sufficient for my original need, it's not clear to me whether I should close the bug. Nevertheless I think it makes sense to at least mention it here. Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=19288 Reviewed-By: Eli Zaretskii <eliz@gnu.org>
2023-07-21Document array indexing for Python gdb.ValueTom Tromey1-0/+7
I noticed that the documentation for gdb.Value doesn't mention array indexing. Approved-By: Eli Zaretskii <eliz@gnu.org>
2023-07-21Remove redundant @findex from python.texiTom Tromey1-52/+0
In a review, Eli pointed out that @findex is redundant when used with @defun. This patch removes all such uses from python.texi, plus a couple uses before @defvar that are also unnecessary. Approved-By: Eli Zaretskii <eliz@gnu.org>
2023-06-28Remove Python 2 from gdb documentationTom Tromey1-15/+8
GDB can't be built using Python 2 any more, so remove the remaining vestiges of this from the documentation. Approved-By: Eli Zaretskii <eliz@gnu.org>
2023-06-19gdb/Python: Added ThreadExitedEventSimon Farre1-0/+10
v6: Fix comments. Fix copyright Remove unnecessary test suite stuff. save_var had to stay, as it mutates some test suite state that otherwise fails. v5: Did what Tom Tromey requested in v4; which can be found here: https://pi.simark.ca/gdb-patches/87pmjm0xar.fsf@tromey.com/ v4: Doc formatting fixed. v3: Eli: Updated docs & NEWS to reflect new changes. Added a reference from the .ptid attribute of the ThreadExitedEvent to the ptid attribute of InferiorThread. To do this, I've added an anchor to that attribute. Tom: Tom requested that I should probably just emit the thread object; I ran into two issues for this, which I could not resolve in this patch; 1 - The Thread Object (the python type) checks it's own validity by doing a comparison of it's `thread_info* thread` to nullptr. This means that any access of it's attributes may (probably, since we are in "async" land) throw Python exceptions because the thread has been removed from the thread object. Therefore I've decided in v3 of this patch to just emit most of the same fields that gdb.InferiorThread has, namely global_num, name, num and ptid (the 3-attribute tuple provided by gdb.InferiorThread.ptid). 2 - A python user can hold a global reference to an exiting thread. Thus in order to have a ThreadExit event that can provide attribute access reliably (both as a global reference, but also inside the thread exit handler, as we can never guarantee that it's executed _before_ the thread_info pointer is removed from the gdbpy thread object), the `thread_info *` thread pointer must not be null. However, this comes at the cost of gdb.InferiorThread believing it is "valid" - which means, that if a user holds takes a global reference to that exiting event thread object, they can some time later do `t.switch()` at which point GDB will 'explode' so to speak. v2: Fixed white space issues and NULL/nullptr stuff, as requested by Tom Tromey. v1: Currently no event is emitted for a thread exit. This adds this functionality by emitting a new gdb.ThreadExitedEvent. It currently provides four attributes: - global_num: The GDB assigned global thread number - num: the per-inferior thread number - name: name of the thread or none if not set - ptid: the PTID of the thread, a 3-attribute tuple, identical to InferiorThread.ptid attribute Added info to docs & the NEWS file as well. Added test to test suite. Fixed formatting. Feedback wanted and appreciated.
2023-06-12Add gdb.Value.assign methodTom Tromey1-0/+6
This adds an 'assign' method to gdb.Value. This allows for assignment without requiring the use of parse_and_eval. Reviewed-By: Eli Zaretskii <eliz@gnu.org>
2023-06-03[gdb] Fix typosTom de Vries1-3/+3
Fix a few typos: - implemention -> implementation - convertion(s) -> conversion(s) - backlashes -> backslashes - signoring -> ignoring - (un)ambigious -> (un)ambiguous - occured -> occurred - hidding -> hiding - temporarilly -> temporarily - immediatelly -> immediately - sillyness -> silliness - similiar -> similar - porkuser -> pokeuser - thats -> that - alway -> always - supercede -> supersede - accomodate -> accommodate - aquire -> acquire - priveleged -> privileged - priviliged -> privileged - priviledges -> privileges - privilige -> privilege - recieve -> receive - (p)refered -> (p)referred - succesfully -> successfully - successfuly -> successfully - responsability -> responsibility - wether -> whether - wich -> which - disasbleable -> disableable - descriminant -> discriminant - construcstor -> constructor - underlaying -> underlying - underyling -> underlying - structureal -> structural - appearences -> appearances - terciarily -> tertiarily - resgisters -> registers - reacheable -> reachable - likelyhood -> likelihood - intepreter -> interpreter - disassemly -> disassembly - covnersion -> conversion - conviently -> conveniently - atttribute -> attribute - struction -> struct - resonable -> reasonable - popupated -> populated - namespaxe -> namespace - intialize -> initialize - identifer(s) -> identifier(s) - expection -> exception - exectuted -> executed - dungerous -> dangerous - dissapear -> disappear - completly -> completely - (inter)changable -> (inter)changeable - beakpoint -> breakpoint - automativ -> automatic - alocating -> allocating - agressive -> aggressive - writting -> writing - reguires -> requires - registed -> registered - recuding -> reducing - opeartor -> operator - ommitted -> omitted - modifing -> modifying - intances -> instances - imbedded -> embedded - gdbaarch -> gdbarch - exection -> execution - direcive -> directive - demanged -> demangled - decidely -> decidedly - argments -> arguments - agrument -> argument - amespace -> namespace - targtet -> target - supress(ed) -> suppress(ed) - startum -> stratum - squence -> sequence - prompty -> prompt - overlow -> overflow - memember -> member - languge -> language - geneate -> generate - funcion -> function - exising -> existing - dinking -> syncing - destroh -> destroy - clenaed -> cleaned - changep -> changedp (name of variable) - arround -> around - aproach -> approach - whould -> would - symobl -> symbol - recuse -> recurse - outter -> outer - freeds -> frees - contex -> context Tested on x86_64-linux. Reviewed-By: Tom Tromey <tom@tromey.com>
2023-05-24Add attributes and methods to gdb.InferiorTom Tromey1-0/+44
This adds two new attributes and three new methods to gdb.Inferior. The attributes let Python code see the command-line arguments and the name of "main". Argument setting is also supported. The methods let Python code manipulate the inferior's environment variables. Reviewed-By: Eli Zaretskii <eliz@gnu.org>
2023-05-23Add global_context parameter to gdb.parse_and_evalTom Tromey1-1/+6
This adds a 'global_context' parse_and_eval to gdb.parse_and_eval. This lets users request a parse that is done at "global scope". I considered letting callers pass in a block instead, with None meaning "global" -- but then there didn't seem to be a clean way to express the default for this parameter. Reviewed-By: Eli Zaretskii <eliz@gnu.org>
2023-05-23Implement gdb.execute_miTom Tromey1-0/+30
This adds a new Python function, gdb.execute_mi, that can be used to invoke an MI command but get the output as a Python object, rather than a string. This is done by implementing a new ui_out subclass that builds a Python object. Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=11688 Reviewed-By: Eli Zaretskii <eliz@gnu.org>
2023-05-19Update documentation for Python Frame.older and Frame.newerTom Tromey1-2/+4
I noticed that Frame.older and Frame.newer don't document that they return None at the ends of the stack. This patch updates the documentation, and also fixes a somewhat related typo in a comment that I noticed while digging into this. Approved-By: Eli Zaretskii <eliz@gnu.org>
2023-05-18Use lower-case in @sc in the documentationTom Tromey1-17/+17
Eli pointed out that @sc only produces small caps for lower case letters in its argument, so it's weird to write it using upper-case letters. This patch fixes the instances I found. Approved-By: Eli Zaretskii <eliz@gnu.org>
2023-05-16gdb/python: extend the Python Disassembler API to allow for stylingAndrew Burgess1-4/+307
This commit extends the Python Disassembler API to allow for styling of the instructions. Before this commit the Python Disassembler API allowed the user to do two things: - They could intercept instruction disassembly requests and return a string of their choosing, this string then became the disassembled instruction, or - They could call builtin_disassemble, which would call back into libopcode to perform the disassembly. As libopcode printed the instruction GDB would collect these print requests and build a string. This string was then returned from the builtin_disassemble call, and the user could modify or extend this string as needed. Neither of these approaches allowed for, or preserved, disassembler styling, which is now available within libopcodes for many of the more popular architectures GDB supports. This commit aims to fill this gap. After this commit a user will be able to do the following things: - Implement a custom instruction disassembler entirely in Python without calling back into libopcodes, the custom disassembler will be able to return styling information such that GDB will display the instruction fully styled. All of GDB's existing style settings will affect how instructions coming from the Python disassembler are displayed in the expected manner. - Call builtin_disassemble and receive a result that represents how libopcode would like the instruction styled. The user can then adjust or extend the disassembled instruction before returning the result to GDB. Again, the instruction will be styled as expected. To achieve this I will add two new classes to GDB, DisassemblerTextPart and DisassemblerAddressPart. Within builtin_disassemble, instead of capturing the print calls from libopcodes and building a single string, we will now create either a text part or address part and store these parts in a vector. The DisassemblerTextPart will capture a small piece of text along with the associated style that should be used to display the text. This corresponds to the disassembler calling disassemble_info::fprintf_styled_func, or for disassemblers that don't support styling disassemble_info::fprintf_func. The DisassemblerAddressPart is used when libopcodes requests that an address be printed, and takes care of printing the address and associated symbol, this corresponds to the disassembler calling disassemble_info::print_address_func. These parts are then placed within the DisassemblerResult when builtin_disassemble returns. Alternatively, the user can directly create parts by calling two new methods on the DisassembleInfo class: DisassembleInfo.text_part and DisassembleInfo.address_part. Having created these parts the user can then pass these parts when initializing a new DisassemblerResult object. Finally, when we return from Python to gdbpy_print_insn, one way or another, the result being returned will have a list of parts. Back in GDB's C++ code we walk the list of parts and call back into GDB's core to display the disassembled instruction with the correct styling. The new API lives in parallel with the old API. Any existing code that creates a DisassemblerResult using a single string immediately creates a single DisassemblerTextPart containing the entire instruction and gives this part the default text style. This is also what happens if the user calls builtin_disassemble for an architecture that doesn't (yet) support libopcode styling. This matches up with what happens when the Python API is not involved, an architecture without disassembler styling support uses the old libopcodes printing API (the API that doesn't pass style info), and GDB just prints everything using the default text style. The reason that parts are created by calling methods on DisassembleInfo, rather than calling the class constructor directly, is DisassemblerAddressPart. Ideally this part would only hold the address which the part represents, but in order to support backwards compatibility we need to be able to convert the DisassemblerAddressPart into a string. To do that we need to call GDB's internal print_address function, and to do that we need an gdbarch. What this means is that the DisassemblerAddressPart needs to take a gdb.Architecture object at creation time. The only valid place a user can pull this from is from the DisassembleInfo object, so having the DisassembleInfo act as a factory ensures that the correct gdbarch is passed over each time. I implemented both solutions (the one presented here, and an alternative where parts could be constructed directly), and this felt like the cleanest solution. Reviewed-By: Eli Zaretskii <eliz@gnu.org> Reviewed-By: Tom Tromey <tom@tromey.com>
2023-05-16gdb/python: rework how the disassembler API reads the result objectAndrew Burgess1-0/+2
This commit is a refactor ahead of the next change which will make disassembler styling available through the Python API. Unfortunately, in order to make the styling support available, I think the easiest solution is to make a very small change to the existing API. The current API relies on returning a DisassemblerResult object to represent each disassembled instruction. Currently GDB allows the DisassemblerResult class to be sub-classed, which could mean that a user tries to override the various attributes that exist on the DisassemblerResult object. This commit removes this ability, effectively making the DisassemblerResult class final. Though this is a change to the existing API, I'm hoping this isn't going to cause too many issues: - The Python disassembler API was only added in the previous release of GDB, so I don't expect it to be widely used yet, and - It's not clear to me why a user would need to sub-class the DisassemblerResult type, I allowed it in the original patch because at the time I couldn't see any reason to NOT allow it. Having prevented sub-classing I can now rework the tail end of the gdbpy_print_insn function; instead of pulling the results out of the DisassemblerResult object by calling back into Python, I now cast the Python object back to its C++ type (disasm_result_object), and access the fields directly from there. In later commits I will be reworking the disasm_result_object type in order to hold information about the styled disassembler output. The tests that dealt with sub-classing DisassemblerResult have been removed, and a new test that confirms that DisassemblerResult can't be sub-classed has been added. Reviewed-By: Eli Zaretskii <eliz@gnu.org> Reviewed-By: Tom Tromey <tom@tromey.com>
2023-05-12gdb/doc: improve Python Disassembler API documentationAndrew Burgess1-5/+12
Some small improvements to the Python Disassembler API documentation: * Be consistent about using the package scope in the @deftp lines, * Rework the description of the DisassemblerResult class to include mention of builtin_disassemble.
2023-04-28Remove @var from @defun in Python documentationTom Tromey1-25/+25
Eli pointed out that @var isn't needed in @defun in Texinfo. This patch removes the cases I found in python.texi. I also renamed some variables in one spot, because "-" isn't valid in a Python variable name.
2023-04-06gdb/python: have PendingFrame methods accept keyword argumentsAndrew Burgess1-4/+4
Update the two gdb.PendingFrame methods gdb.PendingFrame.read_register and gdb.PendingFrame.create_unwind_info to accept keyword arguments. There's no huge benefit for making this change, both of these methods only take a single argument, so it is (maybe) less likely that a user will take advantage of the keyword arguments in these cases, but I think it's nice to be consistent, and I don't see any particular draw backs to making this change. For PendingFrame.read_register I've changed the argument name from 'reg' to 'register' in the documentation and used 'register' as the argument name in GDB. My preference for APIs is to use full words where possible, and given we didn't support named arguments before this change should not break any existing code. There should be no user visible changes (for existing code) after this commit. Reviewed-By: Eli Zaretskii <eliz@gnu.org> Reviewed-By: Tom Tromey <tom@tromey.com>
2023-04-06gdb/python: have UnwindInfo.add_saved_register accept named argsAndrew Burgess1-2/+2
Update gdb.UnwindInfo.add_saved_register to accept named keyword arguments. As part of this update we now use gdb_PyArg_ParseTupleAndKeywords instead of PyArg_UnpackTuple to parse the function arguments. By switching to gdb_PyArg_ParseTupleAndKeywords, we can now use 'O!' as the argument format for the function's value argument. This means that we can check the argument type (is gdb.Value) as part of the argument processing rather than manually performing the check later in the function. One result of this is that we now get a better error message (at least, I think so). Previously we would get something like: ValueError: Bad register value Now we get: TypeError: argument 2 must be gdb.Value, not XXXX It's unfortunate that the exception type changed, but I think the new exception type actually makes more sense. My preference for argument names is to use full words where that's not too excessive. As such, I've updated the name of the argument from 'reg' to 'register' in the documentation, which is the argument name I've made GDB look for here. For existing unwinder code that doesn't throw any exceptions nothing should change with this commit. It is possible that a user has some code that throws and catches the ValueError, and this code will break after this commit, but I think this is going to be sufficiently rare that we can take the risk here. Reviewed-By: Eli Zaretskii <eliz@gnu.org> Reviewed-By: Tom Tromey <tom@tromey.com>
2023-03-30gdb/python: Add new gdb.unwinder.FrameId classAndrew Burgess1-8/+41
When writing an unwinder it is necessary to create a new class to act as a frame-id. This new class is almost certainly just going to set a 'sp' and 'pc' attribute within the instance. This commit adds a little helper class gdb.unwinder.FrameId that does this job. Users can make use of this to avoid having to write out standard boilerplate code any time they write an unwinder. Of course, if the user wants their FrameId class to be more complicated in some way, then they can still write their own class, just like they could before. I've simplified the example code in the documentation to now use the new helper class, and I've also made use of this helper within the testsuite. Any existing user code will continue to work just as it did before after this change. Reviewed-By: Eli Zaretskii <eliz@gnu.org> Reviewed-By: Tom Tromey <tom@tromey.com>
2023-03-30gdb/python: Allow gdb.UnwindInfo to be created with non gdb.Value argsAndrew Burgess1-1/+2
Currently when creating a gdb.UnwindInfo object a user must call gdb.PendingFrame.create_unwind_info and pass a frame-id object. The frame-id object should have at least a 'sp' attribute, and probably a 'pc' attribute too (it can also, in some cases have a 'special' attribute). Currently all of these frame-id attributes need to be gdb.Value objects, but the only reason for that requirement is that we have some code in py-unwind.c that only handles gdb.Value objects. If instead we switch to using get_addr_from_python in py-utils.c then we will support both gdb.Value objects and also raw numbers, which might make things simpler in some cases. So, I started rewriting pyuw_object_attribute_to_pointer (in py-unwind.c) to use get_addr_from_python. However, while looking at the code I noticed a problem. The pyuw_object_attribute_to_pointer function returns a boolean flag, if everything goes OK we return true, but we return false in two cases, (1) when the attribute is not present, which might be acceptable, or might be an error, and (2) when we get an error trying to extract the attribute value, in which case a Python error will have been set. Now in pending_framepy_create_unwind_info we have this code: if (!pyuw_object_attribute_to_pointer (pyo_frame_id, "sp", &sp)) { PyErr_SetString (PyExc_ValueError, _("frame_id should have 'sp' attribute.")); return NULL; } Notice how we always set an error. This will override any error that is already set. So, if you create a frame-id object that has an 'sp' attribute, but the attribute is not a gdb.Value, then currently we fail to extract the attribute value (it's not a gdb.Value) and set this error in pyuw_object_attribute_to_pointer: rc = pyuw_value_obj_to_pointer (pyo_value.get (), addr); if (!rc) PyErr_Format ( PyExc_ValueError, _("The value of the '%s' attribute is not a pointer."), attr_name); Then we return to pending_framepy_create_unwind_info and immediately override this error with the error about 'sp' being missing. This all feels very confused. Here's my proposed solution: pyuw_object_attribute_to_pointer will now return a tri-state enum, with states OK, MISSING, or ERROR. The meanings of these states are: OK - Attribute exists and was extracted fine, MISSING - Attribute doesn't exist, no Python error was set. ERROR - Attribute does exist, but there was an error while extracting it, a Python error was set. We need to update pending_framepy_create_unwind_info, the only user of pyuw_object_attribute_to_pointer, but now I think things are much clearer. Errors from lower levels are not blindly overridden with the generic meaningless error message, but we still get the "missing 'sp' attribute" error when appropriate. This change also includes the switch to get_addr_from_python which was what started this whole journey. For well behaving user code there should be no visible changes after this commit. For user code that hits an error, hopefully the new errors should be more helpful in figuring out what's gone wrong. Additionally, users can now use integers for the 'sp' and 'pc' attributes in their frame-id objects if that is useful. Reviewed-By: Tom Tromey <tom@tromey.com>
2023-03-30gdb/python: add some additional methods to gdb.PendingFrameAndrew Burgess1-0/+40
The gdb.Frame class has far more methods than gdb.PendingFrame. Given that a PendingFrame hasn't yet been claimed by an unwinder, there is a limit to which methods we can add to it, but many of the methods that the Frame class has, the PendingFrame class could also support. In this commit I've added those methods to PendingFrame that I believe are safe. In terms of implementation: if I was starting from scratch then I would implement many of these (or most of these) as attributes rather than methods. However, given both Frame and PendingFrame are just different representation of a frame, I think there is value in keeping the interface for the two classes the same. For this reason everything here is a method -- that's what the Frame class does. The new methods I've added are: - gdb.PendingFrame.is_valid: Return True if the pending frame object is valid. - gdb.PendingFrame.name: Return the name for the frame's function, or None. - gdb.PendingFrame.pc: Return the $pc register value for this frame. - gdb.PendingFrame.language: Return a string containing the language for this frame, or None. - gdb.PendingFrame.find_sal: Return a gdb.Symtab_and_line object for the current location within the pending frame, or None. - gdb.PendingFrame.block: Return a gdb.Block for the current pending frame, or None. - gdb.PendingFrame.function: Return a gdb.Symbol for the current pending frame, or None. In every case I've just copied the implementation over from gdb.Frame and cleaned the code slightly e.g. NULL to nullptr. Additionally each function required a small update to reflect the PendingFrame type, but that's pretty minor. There are tests for all the new methods. For more extensive testing, I added the following code to the file gdb/python/lib/command/unwinders.py: from gdb.unwinder import Unwinder class TestUnwinder(Unwinder): def __init__(self): super().__init__("XXX_TestUnwinder_XXX") def __call__(self,pending_frame): lang = pending_frame.language() try: block = pending_frame.block() assert isinstance(block, gdb.Block) except RuntimeError as rte: assert str(rte) == "Cannot locate block for frame." function = pending_frame.function() arch = pending_frame.architecture() assert arch is None or isinstance(arch, gdb.Architecture) name = pending_frame.name() assert name is None or isinstance(name, str) valid = pending_frame.is_valid() pc = pending_frame.pc() sal = pending_frame.find_sal() assert sal is None or isinstance(sal, gdb.Symtab_and_line) return None gdb.unwinder.register_unwinder(None, TestUnwinder()) This registers a global unwinder that calls each of the new PendingFrame methods and checks the result is of an acceptable type. The unwinder never claims any frames though, so shouldn't change how GDB actually behaves. I then ran the testsuite. There was only a single regression, a test that uses 'disable unwinder' and expects a single unwinder to be disabled -- the extra unwinder is now disabled too, which changes the test output. So I'm reasonably confident that the new methods are not going to crash GDB. Reviewed-By: Eli Zaretskii <eliz@gnu.org> Reviewed-By: Tom Tromey <tom@tromey.com>
2023-03-30gdb/python: make the gdb.unwinder.Unwinder class more robustAndrew Burgess1-3/+58
This commit makes a few related changes to the gdb.unwinder.Unwinder class attributes: 1. The 'name' attribute is now a read-only attribute. This prevents user code from changing the name after registering the unwinder. It seems very unlikely that any user is actually trying to do this in the wild, so I'm not very worried that this will upset anyone, 2. We now validate that the name is a string in the Unwinder.__init__ method, and throw an error if this is not the case. Hopefully nobody was doing this in the wild. This should make it easier to ensure the 'info unwinder' command shows sane output (how to display a non-string name for an unwinder?), 3. The 'enabled' attribute is now implemented with a getter and setter. In the setter we ensure that the new value is a boolean, but the real important change is that we call 'gdb.invalidate_cached_frames()'. This means that the backtrace will be updated if a user manually disables an unwinder (rather than calling the 'disable unwinder' command). It is not unreasonable to think that a user might register multiple unwinders (relating to some project) and have one command that disables/enables all the related unwinders. This command might operate by poking the enabled attribute of each unwinder object directly, after this commit, this would now work correctly. There's tests for all the changes, and lots of documentation updates that both cover the new changes, but also further improve (I think) the general documentation for GDB's Unwinder API. Reviewed-By: Eli Zaretskii <eliz@gnu.org> Reviewed-By: Tom Tromey <tom@tromey.com>
2023-03-23Fix minor grammar issue in python.texiTom Tromey1-1/+1
I noticed a minor grammar problem in the 'GDB/MI Commands In Python' node of the manual. I'm checking in this patch to correct it.
2023-03-16gdb/doc: spring clean the Python unwinders documentationAndrew Burgess1-39/+43
The documentation for the Python Unwinders API could do with some improvement. The 'Unwinder Skeleton Code' has an error: it says 'unwinders' when it should say 'unwinder' in one case. Additionally, by placing the 'Unwinder Skeleton Code' before the section 'Registering an Unwinder' we have skipping including the registration line in the skeleton code. But this is confusion for users (I think) as the skeleton code is almost complete, except for one missing line which the user has to figure out for themselves. By reordering the sections, it is now obvious that the registration should be included in the skeleton code, and the example is therefore almost complete. Additionally, in the example skeleton code the way in which the frame-id was being built (using the current stack point and program counter is (a) not correct, and (b) counter to what is laid out in the 'Unwinder Input' section when describing building a frame-id. I've removed the incorrect code and replaced it with more generic comments indicating what needs to be done. As the actual actions that need to be performed are both architecture specific, and dependent on the function being unwound, it's almost impossible to include more exact code here, but I think what I'm proposing is less misleading than what we had before. I've also added more cross references. Reviewed-By: Eli Zaretskii <eliz@gnu.org>
2023-01-19GDB: Add a character string limiting optionAndrew Burgess1-0/+5
This commit splits the `set/show print elements' option into two. We retain `set/show print elements' for controlling how many elements of an array we print, but a new `set/show print characters' setting is added which is used for controlling how many characters of a string are printed. The motivation behind this change is to allow users a finer level of control over how data is printed, reflecting that, although strings can be thought of as arrays of characters, users often want to treat these two things differently. For compatibility reasons by default the `set/show print characters' option is set to `elements', which makes the limit for character strings follow the setting of the `set/show print elements' option, as it used to. Using `set print characters' with any other value makes the limit independent from the `set/show print elements' setting, however it can be restored to the default with the `set print characters elements' command at any time. A corresponding `-characters' option for the `print' command is added, with the same semantics, i.e. one can use `elements' to make a given `print' invocation follow the limit of elements, be it set with the `-elements' option also given with the same invocation or taken from the `set/show print elements' setting, for characters as well regardless of the current setting of the `set/show print characters' option. The GDB changes are all pretty straightforward, just changing references to the old 'print_max' to use a new `get_print_max_chars' helper which figures out which of the two of `print_max' and `print_max_chars' values to use. Likewise, the documentation is just updated to reference the new setting where appropriate. To make people's life easier the message shown by `show print elements' now indicates if the setting also applies to character strings: (gdb) set print characters elements (gdb) show print elements Limit on string chars or array elements to print is 200. (gdb) set print characters unlimited (gdb) show print elements Limit on array elements to print is 200. (gdb) and the help text shows the dependency as well: (gdb) help set print elements Set limit on array elements to print. "unlimited" causes there to be no limit. This setting also applies to string chars when "print characters" is set to "elements". (gdb) In the testsuite there are two minor updates, one to add `-characters' to the list of completions now shown for the `print' command, and a bare minimum pair of checks for the right handling of `set print characters' and `show print characters', copied from the corresponding checks for `set print elements' and `show print elements' respectively. Co-Authored-By: Maciej W. Rozycki <macro@embecosm.com> Approved-By: Simon Marchi <simon.marchi@efficios.com>
2023-01-19GDB: Allow arbitrary keywords in integer set commandsMaciej W. Rozycki1-11/+17
Rather than just `unlimited' allow the integer set commands (or command options) to define arbitrary keywords for the user to use, removing hardcoded arrangements for the `unlimited' keyword. Remove the confusingly named `var_zinteger', `var_zuinteger' and `var_zuinteger_unlimited' `set'/`show' command variable types redefining them in terms of `var_uinteger', `var_integer' and `var_pinteger', which have the range of [0;UINT_MAX], [INT_MIN;INT_MAX], and [0;INT_MAX] each. Following existing practice `var_pinteger' allows extra negative values to be used, however unlike `var_zuinteger_unlimited' any number of such values can be defined rather than just `-1'. The "p" in `var_pinteger' stands for "positive", for the lack of a more appropriate unambiguous letter, even though 0 obviously is not positive; "n" would be confusing as to whether it stands for "non-negative" or "negative". Add a new structure, `literal_def', the entries of which define extra keywords allowed for a command and numerical values they correspond to. Those values are not verified against the basic range supported by the underlying variable type, allowing extra values to be allowed outside that range, which may or may not be individually made visible to the user. An optional value translation is possible with the structure to follow the existing practice for some commands where user-entered 0 is internally translated to UINT_MAX or INT_MAX. Such translation can now be arbitrary. Literals defined by this structure are automatically used for completion as necessary. So for example: const literal_def integer_unlimited_literals[] = { { "unlimited", INT_MAX, 0 }, { nullptr } }; defines an extra `unlimited' keyword and a user-visible 0 value, both of which get translated to INT_MAX for the setting to be used with. Similarly: const literal_def zuinteger_unlimited_literals[] = { { "unlimited", -1, -1 }, { nullptr } }; defines the same keyword and a corresponding user-visible -1 value that is used for the requested setting. If the last member were omitted (or set to `{}') here, then only the keyword would be allowed for the user to enter and while -1 would still be used internally trying to enter it as a part of a command would result in an "integer -1 out of range" error. Use said error message in all cases (citing the invalid value requested) replacing "only -1 is allowed to set as unlimited" previously used for `var_zuinteger_unlimited' settings only rather than propagating it to `var_pinteger' type. It could only be used for the specific case where a single extra `unlimited' keyword was defined standing for -1 and the use of numeric equivalents is discouraged anyway as it is for historical reasons only that they expose GDB internals, confusingly different across variable types. Similarly update the "must be >= -1" Guile error message. Redefine Guile and Python parameter types in terms of the new variable types and interpret extra keywords as Scheme keywords and Python strings used to communicate corresponding parameter values. Do not add a new PARAM_INTEGER Guile parameter type, however do handle the `var_integer' variable type now, permitting existing parameters defined by GDB proper, such as `listsize', to be accessed from Scheme code. With these changes in place it should be trivial for a Scheme or Python programmer to expand the syntax of the `make-parameter' command and the `gdb.Parameter' class initializer to have arbitrary extra literals along with their internal representation supplied. Update the testsuite accordingly. Approved-By: Simon Marchi <simon.marchi@efficios.com>
2023-01-10gdb/doc: some whitespace fixesSimon Marchi1-2/+2
For consistency, replace tabs with spaces in all gdb.texinfo menus. Change-Id: I0801a72cf82a8afe49ec842244f42d30719634ce
2023-01-09gdb/doc: fix @code{GDBN} -> @value{GDBN}Simon Marchi1-1/+1
Change-Id: I928d6f8d6e6bc41d8c7ddbfae8f6ae0614f4993e
2023-01-01Update copyright year range in header of all files managed by GDBJoel Brobecker1-1/+1
This commit is the result of running the gdb/copyright.py script, which automated the update of the copyright year range for all source files managed by the GDB project to be updated to include year 2023.
2022-10-31Add missing TYPE_CODE_* constants to PythonTom Tromey1-0/+13
A user noticed that TYPE_CODE_FIXED_POINT was not exported by the gdb Python layer. This patch fixes the bug, and prevents future occurences of this type of bug.
2022-10-24gdb/doc: reword description of DisassembleInfo.read_memoryAndrew Burgess1-1/+1
While reading the documentation of DisassembleInfo.read_memory I spotted the word 'available' in one sentence where it didn't make sense.
2022-10-21Improve Python Unwinders documentationPedro Alves1-9/+9
- avoid "GDB proper" to refer to global locus, as object files and program spaces are also GDB proper. - gdb.register_unwinder does not accept locus=gdb. - "a unwinder" -> "an unwinder" Approved-by: Eli Zaretskii <eliz@gnu.org> Change-Id: I98c1b1000e1063815238e945ca71ec6f37b5702e
2022-09-22gdb/python: restrict the names accepted by gdb.register_window_typeAndrew Burgess1-1/+3
I noticed that, from Python, I could register a new TUI window that had whitespace in its name, like this: gdb.register_window_type('my window', MyWindowType) however, it is not possible to then use this window in a new TUI layout, e.g.: (gdb) tui new-layout foo my window 1 cmd 1 Unknown window "my" (gdb) tui new-layout foo "my window" 1 cmd 1 Unknown window ""my" (gdb) tui new-layout foo my\ window 1 cmd 1 Unknown window "my\" GDB clearly uses the whitespace to split the incoming command line. I could fix this by trying to add a mechanism by which we can use whitespace within a window name, but it seems like an easier solution if we just forbid whitespace within a window name. Not only is this easier, but I think this is probably the better solution, identifier names with spaces in would mean we'd need to audit all the places a window name could be printed and ensure that the use of a space didn't make the output ambiguous. So, having decided to disallow whitespace, I then thought about other special characters. We currently accept anything as a window name, and I wondered if this was a good idea. My concerns were about how special characters used in a window name might cause confusion, for example, we allow '$' in window names, which is maybe fine now, but what if one day we wanted to allow variable expansion when creating new layouts? Or what about starting a window name with '-'? We already support a '-horizontal' option, what if we want to add more in the future? Or use of the special character '{' which has special meaning within a new layout? In the end I figured it might make sense to place some restrictive rules in place, and then relax the rules later if/when users complain, we can consider each relaxation as its requested. So, I propose that window names should match this regular expression: [a-zA-Z][-_.a-zA-Z0-9]* There is a chance that there is user code in the wild which will break with the addition of this change, but hopefully adapting to the new restrictions shouldn't be too difficult.
2022-08-30Fix gdb.flush documentationTom Tromey1-1/+1
The gdb.flush documentation does not mention the 'stream' argument in the function signature, only in the description. This patch fixes the oversight.
2022-07-28gdb/python: Add BreakpointLocation typeSimon Farre1-0/+71
PR python/18385 v7: This version addresses the issues pointed out by Tom. Added nullchecks for Python object creations. Changed from using PyLong_FromLong to the gdb_py-versions. Re-factored some code to make it look more cohesive. Also added the more safe Python reference count decrement PY_XDECREF, even though the BreakpointLocation type is never instantiated by the user (explicitly documented in the docs) decrementing < 0 is made impossible with the safe call. Tom pointed out that using the policy class explicitly to decrement a reference counted object was not the way to go, so this has instead been wrapped in a ref_ptr that handles that for us in blocpy_dealloc. Moved macro from py-internal to py-breakpoint.c. Renamed section at the bottom of commit message "Patch Description". v6: This version addresses the points Pedro gave in review to this patch. Added the attributes `function`, `fullname` and `thread_groups` as per request by Pedro with the argument that it more resembles the output of the MI-command "-break-list". Added documentation for these attributes. Cleaned up left overs from copy+paste in test suite, removed hard coding of line numbers where possible. Refactored some code to use more c++-y style range for loops wrt to breakpoint locations. Changed terminology, naming was very inconsistent. Used a variety of "parent", "owner". Now "owner" is the only term used, and the field in the gdb_breakpoint_location_object now also called "owner". v5: Changes in response to review by Tom Tromey: - Replaced manual INCREF/DECREF calls with gdbpy_ref ptrs in places where possible. - Fixed non-gdb style conforming formatting - Get parent of bploc increases ref count of parent. - moved bploc Python definition to py-breakpoint.c The INCREF of self in bppy_get_locations is due to the individual locations holding a reference to it's owner. This is decremented at de-alloc time. The reason why this needs to be here is, if the user writes for instance; py loc = gdb.breakpoints()[X].locations[Y] The breakpoint owner object is immediately going out of scope (GC'd/dealloced), and the location object requires it to be alive for as long as it is alive. Thanks for your review, Tom! v4: Fixed remaining doc issues as per request by Eli. v3: Rewritten commit message, shortened + reworded, added tests. Patch Description Currently, the Python API lacks the ability to query breakpoints for their installed locations, and subsequently, can't query any information about them, or enable/disable individual locations. This patch solves this by adding Python type gdb.BreakpointLocation. The type is never instantiated by the user of the Python API directly, but is produced by the gdb.Breakpoint.locations attribute returning a list of gdb.BreakpointLocation. gdb.Breakpoint.locations: The attribute for retrieving the currently installed breakpoint locations for gdb.Breakpoint. Matches behavior of the "info breakpoints" command in that it only returns the last known or currently inserted breakpoint locations. BreakpointLocation contains 7 attributes 6 read-only attributes: owner: location owner's Python companion object source: file path and line number tuple: (string, long) / None address: installed address of the location function: function name where location was set fullname: fullname where location was set thread_groups: thread groups (inferiors) where location was set. 1 writeable attribute: enabled: get/set enable/disable this location (bool) Access/calls to these, can all throw Python exceptions (documented in the online documentation), and that's due to the nature of how breakpoint locations can be invalidated "behind the scenes", either by them being removed from the original breakpoint or changed, like for instance when a new symbol file is loaded, at which point all breakpoint locations are re-created by GDB. Therefore this patch has chosen to be non-intrusive: it's up to the Python user to re-request the locations if they become invalid. Also there's event handlers that handle new object files etc, if a Python user is storing breakpoint locations in some larger state they've built up, refreshing the locations is easy and it only comes with runtime overhead when the Python user wants to use them. gdb.BreakpointLocation Python type struct "gdbpy_breakpoint_location_object" is found in python-internal.h Its definition, layout, methods and functions are found in the same file as gdb.Breakpoint (py-breakpoint.c) 1 change was also made to breakpoint.h/c to make it possible to enable and disable a bp_location* specifically, without having its LOC_NUM, as this number also can change arbitrarily behind the scenes. Updated docs & news file as per request. Testsuite: tests the .source attribute and the disabling of individual locations. Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=18385 Change-Id: I302c1c50a557ad59d5d18c88ca19014731d736b0
2022-07-25set/show python dont-write-bytecode fixesKevin Buettner1-2/+7
GDB uses the environment variable PYTHONDONTWRITEBYTECODE to determine whether or not to write the result of byte-compiling python modules when the "python dont-write-bytecode" setting is "auto". Simon noticed that GDB's implementation doesn't follow the Python documentation. At present, GDB only checks for the existence of this environment variable. That is not sufficient though. Regarding PYTHONDONTWRITEBYTECODE, this document... https://docs.python.org/3/using/cmdline.html ...says: If this is set to a non-empty string, Python won't try to write .pyc files on the import of source modules. This commit fixes GDB's handling of PYTHONDONTWRITEBYTECODE by adding an empty string check. This commit also corrects the set/show command documentation for "python dont-write-bytecode". The current doc was just a copy of that for set/show python ignore-environment. During his review of an earlier version of this patch, Eli Zaretskii asked that the help text that I proposed for "set/show python dont-write-bytecode" be expanded. I've done that in addition to clarifying the documentation of this option in the GDB manual.
2022-07-18Add gdb.free_objfile event registryTom Tromey1-0/+11
Currently, Python code can use event registries to detect when gdb loads a new objfile, and when gdb clears the objfile list. However, there's no way to detect the removal of an objfile, say when the inferior calls dlclose. This patch adds a gdb.free_objfile event registry and arranges for an event to be emitted in this case.
2022-07-15Add 'summary' mode to Value.format_stringTom Tromey1-0/+6
This adds a 'summary' mode to Value.format_string and to gdb.print_options. For the former, it lets Python code format values using this mode. For the latter, it lets a printer potentially detect if it is being called in a backtrace with 'set print frame-arguments' set to 'scalars'. I considered adding a new mode here to let a pretty-printer see whether it was being called in a 'backtrace' context at all, but I'm not sure if this is really desirable.
2022-07-15Expose current 'print' settings to PythonTom Tromey1-0/+18
PR python/17291 asks for access to the current print options. While I think this need is largely satisfied by the existence of Value.format_string, it seemed to me that a bit more could be done. First, while Value.format_string uses the user's settings, it does not react to temporary settings such as "print/x". This patch changes this. Second, there is no good way to examine the current settings (in particular the temporary ones in effect for just a single "print"). This patch adds this as well. Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=17291