1 This is gdb.info, produced by makeinfo version 6.8 from gdb.texinfo.
3 Copyright (C) 1988-2023 Free Software Foundation, Inc.
5 Permission is granted to copy, distribute and/or modify this document
6 under the terms of the GNU Free Documentation License, Version 1.3 or
7 any later version published by the Free Software Foundation; with the
8 Invariant Sections being "Free Software" and "Free Software Needs Free
9 Documentation", with the Front-Cover Texts being "A GNU Manual," and
10 with the Back-Cover Texts as in (a) below.
12 (a) The FSF's Back-Cover Text is: "You are free to copy and modify
13 this GNU Manual. Buying copies from GNU Press supports the FSF in
14 developing GNU and promoting software freedom."
15 INFO-DIR-SECTION Software development
17 * Gdb: (gdb). The GNU debugger.
18 * gdbserver: (gdb) Server. The GNU debugging server.
21 This file documents the GNU debugger GDB.
23 This is the Tenth Edition, of 'Debugging with GDB: the GNU
24 Source-Level Debugger' for GDB (GDB) Version 13.2.
26 Copyright (C) 1988-2023 Free Software Foundation, Inc.
28 Permission is granted to copy, distribute and/or modify this document
29 under the terms of the GNU Free Documentation License, Version 1.3 or
30 any later version published by the Free Software Foundation; with the
31 Invariant Sections being "Free Software" and "Free Software Needs Free
32 Documentation", with the Front-Cover Texts being "A GNU Manual," and
33 with the Back-Cover Texts as in (a) below.
35 (a) The FSF's Back-Cover Text is: "You are free to copy and modify
36 this GNU Manual. Buying copies from GNU Press supports the FSF in
37 developing GNU and promoting software freedom."
40 File: gdb.info, Node: Progspaces In Python, Next: Objfiles In Python, Prev: Functions In Python, Up: Python API
42 23.3.2.24 Program Spaces In Python
43 ..................................
45 A program space, or "progspace", represents a symbolic view of an
46 address space. It consists of all of the objfiles of the program.
47 *Note Objfiles In Python::. *Note program spaces: Inferiors Connections
48 and Programs, for more details about program spaces.
50 The following progspace-related functions are available in the 'gdb'
53 -- Function: gdb.current_progspace ()
54 This function returns the program space of the currently selected
55 inferior. *Note Inferiors Connections and Programs::. This is
56 identical to 'gdb.selected_inferior().progspace' (*note Inferiors
57 In Python::) and is included for historical compatibility.
59 -- Function: gdb.progspaces ()
60 Return a sequence of all the progspaces currently known to GDB.
62 Each progspace is represented by an instance of the 'gdb.Progspace'
65 -- Variable: Progspace.filename
66 The file name of the progspace as a string.
68 -- Variable: Progspace.pretty_printers
69 The 'pretty_printers' attribute is a list of functions. It is used
70 to look up pretty-printers. A 'Value' is passed to each function
71 in order; if the function returns 'None', then the search
72 continues. Otherwise, the return value should be an object which
73 is used to format the value. *Note Pretty Printing API::, for more
76 -- Variable: Progspace.type_printers
77 The 'type_printers' attribute is a list of type printer objects.
78 *Note Type Printing API::, for more information.
80 -- Variable: Progspace.frame_filters
81 The 'frame_filters' attribute is a dictionary of frame filter
82 objects. *Note Frame Filter API::, for more information.
84 A program space has the following methods:
86 -- Function: Progspace.block_for_pc (pc)
87 Return the innermost 'gdb.Block' containing the given PC value. If
88 the block cannot be found for the PC value specified, the function
91 -- Function: Progspace.find_pc_line (pc)
92 Return the 'gdb.Symtab_and_line' object corresponding to the PC
93 value. *Note Symbol Tables In Python::. If an invalid value of PC
94 is passed as an argument, then the 'symtab' and 'line' attributes
95 of the returned 'gdb.Symtab_and_line' object will be 'None' and 0
98 -- Function: Progspace.is_valid ()
99 Returns 'True' if the 'gdb.Progspace' object is valid, 'False' if
100 not. A 'gdb.Progspace' object can become invalid if the program
101 space file it refers to is not referenced by any inferior. All
102 other 'gdb.Progspace' methods will throw an exception if it is
103 invalid at the time the method is called.
105 -- Function: Progspace.objfiles ()
106 Return a sequence of all the objfiles referenced by this program
107 space. *Note Objfiles In Python::.
109 -- Function: Progspace.solib_name (address)
110 Return the name of the shared library holding the given ADDRESS as
113 One may add arbitrary attributes to 'gdb.Progspace' objects in the
114 usual Python way. This is useful if, for example, one needs to do some
115 extra record keeping associated with the program space.
117 In this contrived example, we want to perform some processing when an
118 objfile with a certain symbol is loaded, but we only want to do this
119 once because it is expensive. To achieve this we record the results
120 with the program space because we can't predict when the desired objfile
124 def clear_objfiles_handler(event):
125 event.progspace.expensive_computation = None
126 def expensive(symbol):
127 """A mock routine to perform an "expensive" computation on symbol."""
128 print ("Computing the answer to the ultimate question ...")
130 def new_objfile_handler(event):
131 objfile = event.new_objfile
132 progspace = objfile.progspace
133 if not hasattr(progspace, 'expensive_computation') or \
134 progspace.expensive_computation is None:
135 # We use 'main' for the symbol to keep the example simple.
136 # Note: There's no current way to constrain the lookup
138 symbol = gdb.lookup_global_symbol('main')
139 if symbol is not None:
140 progspace.expensive_computation = expensive(symbol)
141 gdb.events.clear_objfiles.connect(clear_objfiles_handler)
142 gdb.events.new_objfile.connect(new_objfile_handler)
144 (gdb) file /tmp/hello
145 Reading symbols from /tmp/hello...
146 Computing the answer to the ultimate question ...
147 (gdb) python print gdb.current_progspace().expensive_computation
150 Starting program: /tmp/hello
152 [Inferior 1 (process 4242) exited normally]
155 File: gdb.info, Node: Objfiles In Python, Next: Frames In Python, Prev: Progspaces In Python, Up: Python API
157 23.3.2.25 Objfiles In Python
158 ............................
160 GDB loads symbols for an inferior from various symbol-containing files
161 (*note Files::). These include the primary executable file, any shared
162 libraries used by the inferior, and any separate debug info files (*note
163 Separate Debug Files::). GDB calls these symbol-containing files
166 The following objfile-related functions are available in the 'gdb'
169 -- Function: gdb.current_objfile ()
170 When auto-loading a Python script (*note Python Auto-loading::),
171 GDB sets the "current objfile" to the corresponding objfile. This
172 function returns the current objfile. If there is no current
173 objfile, this function returns 'None'.
175 -- Function: gdb.objfiles ()
176 Return a sequence of objfiles referenced by the current program
177 space. *Note Objfiles In Python::, and *note Progspaces In
178 Python::. This is identical to
179 'gdb.selected_inferior().progspace.objfiles()' and is included for
180 historical compatibility.
182 -- Function: gdb.lookup_objfile (name [, by_build_id])
183 Look up NAME, a file name or build ID, in the list of objfiles for
184 the current program space (*note Progspaces In Python::). If the
185 objfile is not found throw the Python 'ValueError' exception.
187 If NAME is a relative file name, then it will match any source file
188 name with the same trailing components. For example, if NAME is
189 'gcc/expr.c', then it will match source file name of
190 '/build/trunk/gcc/expr.c', but not '/build/trunk/libcpp/expr.c' or
191 '/build/trunk/gcc/x-expr.c'.
193 If BY_BUILD_ID is provided and is 'True' then NAME is the build ID
194 of the objfile. Otherwise, NAME is a file name. This is supported
195 only on some operating systems, notably those which use the ELF
196 format for binary files and the GNU Binutils. For more details
197 about this feature, see the description of the '--build-id'
198 command-line option in *note Command Line Options: (ld)Options.
200 Each objfile is represented by an instance of the 'gdb.Objfile'
203 -- Variable: Objfile.filename
204 The file name of the objfile as a string, with symbolic links
207 The value is 'None' if the objfile is no longer valid. See the
208 'gdb.Objfile.is_valid' method, described below.
210 -- Variable: Objfile.username
211 The file name of the objfile as specified by the user as a string.
213 The value is 'None' if the objfile is no longer valid. See the
214 'gdb.Objfile.is_valid' method, described below.
216 -- Variable: Objfile.is_file
217 An objfile often comes from an ordinary file, but in some cases it
218 may be constructed from the contents of memory. This attribute is
219 'True' for file-backed objfiles, and 'False' for other kinds.
221 -- Variable: Objfile.owner
222 For separate debug info objfiles this is the corresponding
223 'gdb.Objfile' object that debug info is being provided for.
224 Otherwise this is 'None'. Separate debug info objfiles are added
225 with the 'gdb.Objfile.add_separate_debug_file' method, described
228 -- Variable: Objfile.build_id
229 The build ID of the objfile as a string. If the objfile does not
230 have a build ID then the value is 'None'.
232 This is supported only on some operating systems, notably those
233 which use the ELF format for binary files and the GNU Binutils.
234 For more details about this feature, see the description of the
235 '--build-id' command-line option in *note Command Line Options:
238 -- Variable: Objfile.progspace
239 The containing program space of the objfile as a 'gdb.Progspace'
240 object. *Note Progspaces In Python::.
242 -- Variable: Objfile.pretty_printers
243 The 'pretty_printers' attribute is a list of functions. It is used
244 to look up pretty-printers. A 'Value' is passed to each function
245 in order; if the function returns 'None', then the search
246 continues. Otherwise, the return value should be an object which
247 is used to format the value. *Note Pretty Printing API::, for more
250 -- Variable: Objfile.type_printers
251 The 'type_printers' attribute is a list of type printer objects.
252 *Note Type Printing API::, for more information.
254 -- Variable: Objfile.frame_filters
255 The 'frame_filters' attribute is a dictionary of frame filter
256 objects. *Note Frame Filter API::, for more information.
258 One may add arbitrary attributes to 'gdb.Objfile' objects in the
259 usual Python way. This is useful if, for example, one needs to do some
260 extra record keeping associated with the objfile.
262 In this contrived example we record the time when GDB loaded the
267 def new_objfile_handler(event):
268 # Set the time_loaded attribute of the new objfile.
269 event.new_objfile.time_loaded = datetime.datetime.today()
270 gdb.events.new_objfile.connect(new_objfile_handler)
273 Reading symbols from ./hello...
274 (gdb) python print gdb.objfiles()[0].time_loaded
275 2014-10-09 11:41:36.770345
277 A 'gdb.Objfile' object has the following methods:
279 -- Function: Objfile.is_valid ()
280 Returns 'True' if the 'gdb.Objfile' object is valid, 'False' if
281 not. A 'gdb.Objfile' object can become invalid if the object file
282 it refers to is not loaded in GDB any longer. All other
283 'gdb.Objfile' methods will throw an exception if it is invalid at
284 the time the method is called.
286 -- Function: Objfile.add_separate_debug_file (file)
287 Add FILE to the list of files that GDB will search for debug
288 information for the objfile. This is useful when the debug info
289 has been removed from the program and stored in a separate file.
290 GDB has built-in support for finding separate debug info files
291 (*note Separate Debug Files::), but if the file doesn't live in one
292 of the standard places that GDB searches then this function can be
293 used to add a debug info file from a different place.
295 -- Function: Objfile.lookup_global_symbol (name [, domain])
296 Search for a global symbol named NAME in this objfile. Optionally,
297 the search scope can be restricted with the DOMAIN argument. The
298 DOMAIN argument must be a domain constant defined in the 'gdb'
299 module and described in *note Symbols In Python::. This function
300 is similar to 'gdb.lookup_global_symbol', except that the search is
301 limited to this objfile.
303 The result is a 'gdb.Symbol' object or 'None' if the symbol is not
306 -- Function: Objfile.lookup_static_symbol (name [, domain])
307 Like 'Objfile.lookup_global_symbol', but searches for a global
308 symbol with static linkage named NAME in this objfile.
311 File: gdb.info, Node: Frames In Python, Next: Blocks In Python, Prev: Objfiles In Python, Up: Python API
313 23.3.2.26 Accessing inferior stack frames from Python
314 .....................................................
316 When the debugged program stops, GDB is able to analyze its call stack
317 (*note Stack frames: Frames.). The 'gdb.Frame' class represents a frame
318 in the stack. A 'gdb.Frame' object is only valid while its
319 corresponding frame exists in the inferior's stack. If you try to use
320 an invalid frame object, GDB will throw a 'gdb.error' exception (*note
321 Exception Handling::).
323 Two 'gdb.Frame' objects can be compared for equality with the '=='
326 (gdb) python print gdb.newest_frame() == gdb.selected_frame ()
329 The following frame-related functions are available in the 'gdb'
332 -- Function: gdb.selected_frame ()
333 Return the selected frame object. (*note Selecting a Frame:
336 -- Function: gdb.newest_frame ()
337 Return the newest frame object for the selected thread.
339 -- Function: gdb.frame_stop_reason_string (reason)
340 Return a string explaining the reason why GDB stopped unwinding
341 frames, as expressed by the given REASON code (an integer, see the
342 'unwind_stop_reason' method further down in this section).
344 -- Function: gdb.invalidate_cached_frames
345 GDB internally keeps a cache of the frames that have been unwound.
346 This function invalidates this cache.
348 This function should not generally be called by ordinary Python
349 code. It is documented for the sake of completeness.
351 A 'gdb.Frame' object has the following methods:
353 -- Function: Frame.is_valid ()
354 Returns true if the 'gdb.Frame' object is valid, false if not. A
355 frame object can become invalid if the frame it refers to doesn't
356 exist anymore in the inferior. All 'gdb.Frame' methods will throw
357 an exception if it is invalid at the time the method is called.
359 -- Function: Frame.name ()
360 Returns the function name of the frame, or 'None' if it can't be
363 -- Function: Frame.architecture ()
364 Returns the 'gdb.Architecture' object corresponding to the frame's
365 architecture. *Note Architectures In Python::.
367 -- Function: Frame.type ()
368 Returns the type of the frame. The value can be one of:
370 An ordinary stack frame.
373 A fake stack frame that was created by GDB when performing an
374 inferior function call.
377 A frame representing an inlined function. The function was
378 inlined into a 'gdb.NORMAL_FRAME' that is older than this one.
381 A frame representing a tail call. *Note Tail Call Frames::.
384 A signal trampoline frame. This is the frame created by the
385 OS when it calls into a signal handler.
388 A fake stack frame representing a cross-architecture call.
391 This is like 'gdb.NORMAL_FRAME', but it is only used for the
394 -- Function: Frame.unwind_stop_reason ()
395 Return an integer representing the reason why it's not possible to
396 find more frames toward the outermost frame. Use
397 'gdb.frame_stop_reason_string' to convert the value returned by
398 this function to a string. The value can be one of:
400 'gdb.FRAME_UNWIND_NO_REASON'
401 No particular reason (older frames should be available).
403 'gdb.FRAME_UNWIND_NULL_ID'
404 The previous frame's analyzer returns an invalid result. This
405 is no longer used by GDB, and is kept only for backward
408 'gdb.FRAME_UNWIND_OUTERMOST'
409 This frame is the outermost.
411 'gdb.FRAME_UNWIND_UNAVAILABLE'
412 Cannot unwind further, because that would require knowing the
413 values of registers or memory that have not been collected.
415 'gdb.FRAME_UNWIND_INNER_ID'
416 This frame ID looks like it ought to belong to a NEXT frame,
417 but we got it for a PREV frame. Normally, this is a sign of
418 unwinder failure. It could also indicate stack corruption.
420 'gdb.FRAME_UNWIND_SAME_ID'
421 This frame has the same ID as the previous one. That means
422 that unwinding further would almost certainly give us another
423 frame with exactly the same ID, so break the chain. Normally,
424 this is a sign of unwinder failure. It could also indicate
427 'gdb.FRAME_UNWIND_NO_SAVED_PC'
428 The frame unwinder did not find any saved PC, but we needed
429 one to unwind further.
431 'gdb.FRAME_UNWIND_MEMORY_ERROR'
432 The frame unwinder caused an error while trying to access
435 'gdb.FRAME_UNWIND_FIRST_ERROR'
436 Any stop reason greater or equal to this value indicates some
437 kind of error. This special value facilitates writing code
438 that tests for errors in unwinding in a way that will work
439 correctly even if the list of the other values is modified in
440 future GDB versions. Using it, you could write:
441 reason = gdb.selected_frame().unwind_stop_reason ()
442 reason_str = gdb.frame_stop_reason_string (reason)
443 if reason >= gdb.FRAME_UNWIND_FIRST_ERROR:
444 print ("An error occured: %s" % reason_str)
446 -- Function: Frame.pc ()
447 Returns the frame's resume address.
449 -- Function: Frame.block ()
450 Return the frame's code block. *Note Blocks In Python::. If the
451 frame does not have a block - for example, if there is no debugging
452 information for the code in question - then this will throw an
455 -- Function: Frame.function ()
456 Return the symbol for the function corresponding to this frame.
457 *Note Symbols In Python::.
459 -- Function: Frame.older ()
460 Return the frame that called this frame.
462 -- Function: Frame.newer ()
463 Return the frame called by this frame.
465 -- Function: Frame.find_sal ()
466 Return the frame's symtab and line object. *Note Symbol Tables In
469 -- Function: Frame.read_register (register)
470 Return the value of REGISTER in this frame. Returns a 'Gdb.Value'
471 object. Throws an exception if REGISTER does not exist. The
472 REGISTER argument must be one of the following:
473 1. A string that is the name of a valid register (e.g., ''sp'' or
475 2. A 'gdb.RegisterDescriptor' object (*note Registers In
477 3. A GDB internal, platform specific number. Using these numbers
478 is supported for historic reasons, but is not recommended as
479 future changes to GDB could change the mapping between numbers
480 and the registers they represent, breaking any Python code
481 that uses the platform-specific numbers. The numbers are
482 usually found in the corresponding 'PLATFORM-tdep.h' file in
484 Using a string to access registers will be slightly slower than the
485 other two methods as GDB must look up the mapping between name and
486 internal register number. If performance is critical consider
487 looking up and caching a 'gdb.RegisterDescriptor' object.
489 -- Function: Frame.read_var (variable [, block])
490 Return the value of VARIABLE in this frame. If the optional
491 argument BLOCK is provided, search for the variable from that
492 block; otherwise start at the frame's current block (which is
493 determined by the frame's current program counter). The VARIABLE
494 argument must be a string or a 'gdb.Symbol' object; BLOCK must be a
497 -- Function: Frame.select ()
498 Set this frame to be the selected frame. *Note Examining the
501 -- Function: Frame.level ()
502 Return an integer, the stack frame level for this frame. *Note
503 Stack Frames: Frames.
505 -- Function: Frame.language ()
506 Return a string, the source language for this frame.
509 File: gdb.info, Node: Blocks In Python, Next: Symbols In Python, Prev: Frames In Python, Up: Python API
511 23.3.2.27 Accessing blocks from Python
512 ......................................
514 In GDB, symbols are stored in blocks. A block corresponds roughly to a
515 scope in the source code. Blocks are organized hierarchically, and are
516 represented individually in Python as a 'gdb.Block'. Blocks rely on
517 debugging information being available.
519 A frame has a block. Please see *note Frames In Python::, for a more
520 in-depth discussion of frames.
522 The outermost block is known as the "global block". The global block
523 typically holds public global variables and functions.
525 The block nested just inside the global block is the "static block".
526 The static block typically holds file-scoped variables and functions.
528 GDB provides a method to get a block's superblock, but there is
529 currently no way to examine the sub-blocks of a block, or to iterate
530 over all the blocks in a symbol table (*note Symbol Tables In Python::).
532 Here is a short example that should help explain blocks:
534 /* This is in the global block. */
537 /* This is in the static block. */
538 static int file_scope;
540 /* 'function' is in the global block, and 'argument' is
541 in a block nested inside of 'function'. */
542 int function (int argument)
544 /* 'local' is in a block inside 'function'. It may or may
545 not be in the same block as 'argument'. */
549 /* 'inner' is in a block whose superblock is the one holding
553 /* If this call is expanded by the compiler, you may see
554 a nested block here whose function is 'inline_function'
555 and whose superblock is the one holding 'inner'. */
560 A 'gdb.Block' is iterable. The iterator returns the symbols (*note
561 Symbols In Python::) local to the block. Python programs should not
562 assume that a specific block object will always contain a given symbol,
563 since changes in GDB features and infrastructure may cause symbols move
564 across blocks in a symbol table. You can also use Python's "dictionary
565 syntax" to access variables in this block, e.g.:
567 symbol = some_block['variable'] # symbol is of type gdb.Symbol
569 The following block-related functions are available in the 'gdb'
572 -- Function: gdb.block_for_pc (pc)
573 Return the innermost 'gdb.Block' containing the given PC value. If
574 the block cannot be found for the PC value specified, the function
575 will return 'None'. This is identical to
576 'gdb.current_progspace().block_for_pc(pc)' and is included for
577 historical compatibility.
579 A 'gdb.Block' object has the following methods:
581 -- Function: Block.is_valid ()
582 Returns 'True' if the 'gdb.Block' object is valid, 'False' if not.
583 A block object can become invalid if the block it refers to doesn't
584 exist anymore in the inferior. All other 'gdb.Block' methods will
585 throw an exception if it is invalid at the time the method is
586 called. The block's validity is also checked during iteration over
587 symbols of the block.
589 A 'gdb.Block' object has the following attributes:
591 -- Variable: Block.start
592 The start address of the block. This attribute is not writable.
594 -- Variable: Block.end
595 One past the last address that appears in the block. This
596 attribute is not writable.
598 -- Variable: Block.function
599 The name of the block represented as a 'gdb.Symbol'. If the block
600 is not named, then this attribute holds 'None'. This attribute is
603 For ordinary function blocks, the superblock is the static block.
604 However, you should note that it is possible for a function block
605 to have a superblock that is not the static block - for instance
606 this happens for an inlined function.
608 -- Variable: Block.superblock
609 The block containing this block. If this parent block does not
610 exist, this attribute holds 'None'. This attribute is not
613 -- Variable: Block.global_block
614 The global block associated with this block. This attribute is not
617 -- Variable: Block.static_block
618 The static block associated with this block. This attribute is not
621 -- Variable: Block.is_global
622 'True' if the 'gdb.Block' object is a global block, 'False' if not.
623 This attribute is not writable.
625 -- Variable: Block.is_static
626 'True' if the 'gdb.Block' object is a static block, 'False' if not.
627 This attribute is not writable.
630 File: gdb.info, Node: Symbols In Python, Next: Symbol Tables In Python, Prev: Blocks In Python, Up: Python API
632 23.3.2.28 Python representation of Symbols
633 ..........................................
635 GDB represents every variable, function and type as an entry in a symbol
636 table. *Note Examining the Symbol Table: Symbols. Similarly, Python
637 represents these symbols in GDB with the 'gdb.Symbol' object.
639 The following symbol-related functions are available in the 'gdb'
642 -- Function: gdb.lookup_symbol (name [, block [, domain]])
643 This function searches for a symbol by name. The search scope can
644 be restricted to the parameters defined in the optional domain and
647 NAME is the name of the symbol. It must be a string. The optional
648 BLOCK argument restricts the search to symbols visible in that
649 BLOCK. The BLOCK argument must be a 'gdb.Block' object. If
650 omitted, the block for the current frame is used. The optional
651 DOMAIN argument restricts the search to the domain type. The
652 DOMAIN argument must be a domain constant defined in the 'gdb'
653 module and described later in this chapter.
655 The result is a tuple of two elements. The first element is a
656 'gdb.Symbol' object or 'None' if the symbol is not found. If the
657 symbol is found, the second element is 'True' if the symbol is a
658 field of a method's object (e.g., 'this' in C++), otherwise it is
659 'False'. If the symbol is not found, the second element is
662 -- Function: gdb.lookup_global_symbol (name [, domain])
663 This function searches for a global symbol by name. The search
664 scope can be restricted to by the domain argument.
666 NAME is the name of the symbol. It must be a string. The optional
667 DOMAIN argument restricts the search to the domain type. The
668 DOMAIN argument must be a domain constant defined in the 'gdb'
669 module and described later in this chapter.
671 The result is a 'gdb.Symbol' object or 'None' if the symbol is not
674 -- Function: gdb.lookup_static_symbol (name [, domain])
675 This function searches for a global symbol with static linkage by
676 name. The search scope can be restricted to by the domain
679 NAME is the name of the symbol. It must be a string. The optional
680 DOMAIN argument restricts the search to the domain type. The
681 DOMAIN argument must be a domain constant defined in the 'gdb'
682 module and described later in this chapter.
684 The result is a 'gdb.Symbol' object or 'None' if the symbol is not
687 Note that this function will not find function-scoped static
688 variables. To look up such variables, iterate over the variables
689 of the function's 'gdb.Block' and check that 'block.addr_class' is
690 'gdb.SYMBOL_LOC_STATIC'.
692 There can be multiple global symbols with static linkage with the
693 same name. This function will only return the first matching
694 symbol that it finds. Which symbol is found depends on where GDB
695 is currently stopped, as GDB will first search for matching symbols
696 in the current object file, and then search all other object files.
697 If the application is not yet running then GDB will search all
698 object files in the order they appear in the debug information.
700 -- Function: gdb.lookup_static_symbols (name [, domain])
701 Similar to 'gdb.lookup_static_symbol', this function searches for
702 global symbols with static linkage by name, and optionally
703 restricted by the domain argument. However, this function returns
704 a list of all matching symbols found, not just the first one.
706 NAME is the name of the symbol. It must be a string. The optional
707 DOMAIN argument restricts the search to the domain type. The
708 DOMAIN argument must be a domain constant defined in the 'gdb'
709 module and described later in this chapter.
711 The result is a list of 'gdb.Symbol' objects which could be empty
712 if no matching symbols were found.
714 Note that this function will not find function-scoped static
715 variables. To look up such variables, iterate over the variables
716 of the function's 'gdb.Block' and check that 'block.addr_class' is
717 'gdb.SYMBOL_LOC_STATIC'.
719 A 'gdb.Symbol' object has the following attributes:
721 -- Variable: Symbol.type
722 The type of the symbol or 'None' if no type is recorded. This
723 attribute is represented as a 'gdb.Type' object. *Note Types In
724 Python::. This attribute is not writable.
726 -- Variable: Symbol.symtab
727 The symbol table in which the symbol appears. This attribute is
728 represented as a 'gdb.Symtab' object. *Note Symbol Tables In
729 Python::. This attribute is not writable.
731 -- Variable: Symbol.line
732 The line number in the source code at which the symbol was defined.
735 -- Variable: Symbol.name
736 The name of the symbol as a string. This attribute is not
739 -- Variable: Symbol.linkage_name
740 The name of the symbol, as used by the linker (i.e., may be
741 mangled). This attribute is not writable.
743 -- Variable: Symbol.print_name
744 The name of the symbol in a form suitable for output. This is
745 either 'name' or 'linkage_name', depending on whether the user
746 asked GDB to display demangled or mangled names.
748 -- Variable: Symbol.addr_class
749 The address class of the symbol. This classifies how to find the
750 value of a symbol. Each address class is a constant defined in the
751 'gdb' module and described later in this chapter.
753 -- Variable: Symbol.needs_frame
754 This is 'True' if evaluating this symbol's value requires a frame
755 (*note Frames In Python::) and 'False' otherwise. Typically, local
756 variables will require a frame, but other symbols will not.
758 -- Variable: Symbol.is_argument
759 'True' if the symbol is an argument of a function.
761 -- Variable: Symbol.is_constant
762 'True' if the symbol is a constant.
764 -- Variable: Symbol.is_function
765 'True' if the symbol is a function or a method.
767 -- Variable: Symbol.is_variable
768 'True' if the symbol is a variable.
770 A 'gdb.Symbol' object has the following methods:
772 -- Function: Symbol.is_valid ()
773 Returns 'True' if the 'gdb.Symbol' object is valid, 'False' if not.
774 A 'gdb.Symbol' object can become invalid if the symbol it refers to
775 does not exist in GDB any longer. All other 'gdb.Symbol' methods
776 will throw an exception if it is invalid at the time the method is
779 -- Function: Symbol.value ([frame])
780 Compute the value of the symbol, as a 'gdb.Value'. For functions,
781 this computes the address of the function, cast to the appropriate
782 type. If the symbol requires a frame in order to compute its
783 value, then FRAME must be given. If FRAME is not given, or if
784 FRAME is invalid, then this method will throw an exception.
786 The available domain categories in 'gdb.Symbol' are represented as
787 constants in the 'gdb' module:
789 'gdb.SYMBOL_UNDEF_DOMAIN'
790 This is used when a domain has not been discovered or none of the
791 following domains apply. This usually indicates an error either in
792 the symbol information or in GDB's handling of symbols.
794 'gdb.SYMBOL_VAR_DOMAIN'
795 This domain contains variables, function names, typedef names and
798 'gdb.SYMBOL_STRUCT_DOMAIN'
799 This domain holds struct, union and enum type names.
801 'gdb.SYMBOL_LABEL_DOMAIN'
802 This domain contains names of labels (for gotos).
804 'gdb.SYMBOL_MODULE_DOMAIN'
805 This domain contains names of Fortran module types.
807 'gdb.SYMBOL_COMMON_BLOCK_DOMAIN'
808 This domain contains names of Fortran common blocks.
810 The available address class categories in 'gdb.Symbol' are
811 represented as constants in the 'gdb' module:
813 'gdb.SYMBOL_LOC_UNDEF'
814 If this is returned by address class, it indicates an error either
815 in the symbol information or in GDB's handling of symbols.
817 'gdb.SYMBOL_LOC_CONST'
818 Value is constant int.
820 'gdb.SYMBOL_LOC_STATIC'
821 Value is at a fixed address.
823 'gdb.SYMBOL_LOC_REGISTER'
824 Value is in a register.
827 Value is an argument. This value is at the offset stored within
828 the symbol inside the frame's argument list.
830 'gdb.SYMBOL_LOC_REF_ARG'
831 Value address is stored in the frame's argument list. Just like
832 'LOC_ARG' except that the value's address is stored at the offset,
833 not the value itself.
835 'gdb.SYMBOL_LOC_REGPARM_ADDR'
836 Value is a specified register. Just like 'LOC_REGISTER' except the
837 register holds the address of the argument instead of the argument
840 'gdb.SYMBOL_LOC_LOCAL'
841 Value is a local variable.
843 'gdb.SYMBOL_LOC_TYPEDEF'
844 Value not used. Symbols in the domain 'SYMBOL_STRUCT_DOMAIN' all
847 'gdb.SYMBOL_LOC_LABEL'
850 'gdb.SYMBOL_LOC_BLOCK'
853 'gdb.SYMBOL_LOC_CONST_BYTES'
854 Value is a byte-sequence.
856 'gdb.SYMBOL_LOC_UNRESOLVED'
857 Value is at a fixed address, but the address of the variable has to
858 be determined from the minimal symbol table whenever the variable
861 'gdb.SYMBOL_LOC_OPTIMIZED_OUT'
862 The value does not actually exist in the program.
864 'gdb.SYMBOL_LOC_COMPUTED'
865 The value's address is a computed location.
867 'gdb.SYMBOL_LOC_COMMON_BLOCK'
868 The value's address is a symbol. This is only used for Fortran
872 File: gdb.info, Node: Symbol Tables In Python, Next: Line Tables In Python, Prev: Symbols In Python, Up: Python API
874 23.3.2.29 Symbol table representation in Python
875 ...............................................
877 Access to symbol table data maintained by GDB on the inferior is exposed
878 to Python via two objects: 'gdb.Symtab_and_line' and 'gdb.Symtab'.
879 Symbol table and line data for a frame is returned from the 'find_sal'
880 method in 'gdb.Frame' object. *Note Frames In Python::.
882 For more information on GDB's symbol table management, see *note
883 Examining the Symbol Table: Symbols, for more information.
885 A 'gdb.Symtab_and_line' object has the following attributes:
887 -- Variable: Symtab_and_line.symtab
888 The symbol table object ('gdb.Symtab') for this frame. This
889 attribute is not writable.
891 -- Variable: Symtab_and_line.pc
892 Indicates the start of the address range occupied by code for the
893 current source line. This attribute is not writable.
895 -- Variable: Symtab_and_line.last
896 Indicates the end of the address range occupied by code for the
897 current source line. This attribute is not writable.
899 -- Variable: Symtab_and_line.line
900 Indicates the current line number for this object. This attribute
903 A 'gdb.Symtab_and_line' object has the following methods:
905 -- Function: Symtab_and_line.is_valid ()
906 Returns 'True' if the 'gdb.Symtab_and_line' object is valid,
907 'False' if not. A 'gdb.Symtab_and_line' object can become invalid
908 if the Symbol table and line object it refers to does not exist in
909 GDB any longer. All other 'gdb.Symtab_and_line' methods will throw
910 an exception if it is invalid at the time the method is called.
912 A 'gdb.Symtab' object has the following attributes:
914 -- Variable: Symtab.filename
915 The symbol table's source filename. This attribute is not
918 -- Variable: Symtab.objfile
919 The symbol table's backing object file. *Note Objfiles In
920 Python::. This attribute is not writable.
922 -- Variable: Symtab.producer
923 The name and possibly version number of the program that compiled
924 the code in the symbol table. The contents of this string is up to
925 the compiler. If no producer information is available then 'None'
926 is returned. This attribute is not writable.
928 A 'gdb.Symtab' object has the following methods:
930 -- Function: Symtab.is_valid ()
931 Returns 'True' if the 'gdb.Symtab' object is valid, 'False' if not.
932 A 'gdb.Symtab' object can become invalid if the symbol table it
933 refers to does not exist in GDB any longer. All other 'gdb.Symtab'
934 methods will throw an exception if it is invalid at the time the
937 -- Function: Symtab.fullname ()
938 Return the symbol table's source absolute file name.
940 -- Function: Symtab.global_block ()
941 Return the global block of the underlying symbol table. *Note
944 -- Function: Symtab.static_block ()
945 Return the static block of the underlying symbol table. *Note
948 -- Function: Symtab.linetable ()
949 Return the line table associated with the symbol table. *Note Line
953 File: gdb.info, Node: Line Tables In Python, Next: Breakpoints In Python, Prev: Symbol Tables In Python, Up: Python API
955 23.3.2.30 Manipulating line tables using Python
956 ...............................................
958 Python code can request and inspect line table information from a symbol
959 table that is loaded in GDB. A line table is a mapping of source lines
960 to their executable locations in memory. To acquire the line table
961 information for a particular symbol table, use the 'linetable' function
962 (*note Symbol Tables In Python::).
964 A 'gdb.LineTable' is iterable. The iterator returns 'LineTableEntry'
965 objects that correspond to the source line and address for each line
966 table entry. 'LineTableEntry' objects have the following attributes:
968 -- Variable: LineTableEntry.line
969 The source line number for this line table entry. This number
970 corresponds to the actual line of source. This attribute is not
973 -- Variable: LineTableEntry.pc
974 The address that is associated with the line table entry where the
975 executable code for that source line resides in memory. This
976 attribute is not writable.
978 As there can be multiple addresses for a single source line, you may
979 receive multiple 'LineTableEntry' objects with matching 'line'
980 attributes, but with different 'pc' attributes. The iterator is sorted
981 in ascending 'pc' order. Here is a small example illustrating iterating
984 symtab = gdb.selected_frame().find_sal().symtab
985 linetable = symtab.linetable()
986 for line in linetable:
987 print ("Line: "+str(line.line)+" Address: "+hex(line.pc))
989 This will have the following output:
991 Line: 33 Address: 0x4005c8L
992 Line: 37 Address: 0x4005caL
993 Line: 39 Address: 0x4005d2L
994 Line: 40 Address: 0x4005f8L
995 Line: 42 Address: 0x4005ffL
996 Line: 44 Address: 0x400608L
997 Line: 42 Address: 0x40060cL
998 Line: 45 Address: 0x400615L
1000 In addition to being able to iterate over a 'LineTable', it also has
1001 the following direct access methods:
1003 -- Function: LineTable.line (line)
1004 Return a Python 'Tuple' of 'LineTableEntry' objects for any entries
1005 in the line table for the given LINE, which specifies the source
1006 code line. If there are no entries for that source code LINE, the
1007 Python 'None' is returned.
1009 -- Function: LineTable.has_line (line)
1010 Return a Python 'Boolean' indicating whether there is an entry in
1011 the line table for this source line. Return 'True' if an entry is
1012 found, or 'False' if not.
1014 -- Function: LineTable.source_lines ()
1015 Return a Python 'List' of the source line numbers in the symbol
1016 table. Only lines with executable code locations are returned.
1017 The contents of the 'List' will just be the source line entries
1018 represented as Python 'Long' values.
1021 File: gdb.info, Node: Breakpoints In Python, Next: Finish Breakpoints in Python, Prev: Line Tables In Python, Up: Python API
1023 23.3.2.31 Manipulating breakpoints using Python
1024 ...............................................
1026 Python code can manipulate breakpoints via the 'gdb.Breakpoint' class.
1028 A breakpoint can be created using one of the two forms of the
1029 'gdb.Breakpoint' constructor. The first one accepts a string like one
1030 would pass to the 'break' (*note Setting Breakpoints: Set Breaks.) and
1031 'watch' (*note Setting Watchpoints: Set Watchpoints.) commands, and can
1032 be used to create both breakpoints and watchpoints. The second accepts
1033 separate Python arguments similar to *note Explicit Locations::, and can
1034 only be used to create breakpoints.
1036 -- Function: Breakpoint.__init__ (spec [, type ][, wp_class ][,
1037 internal ][, temporary ][, qualified ])
1038 Create a new breakpoint according to SPEC, which is a string naming
1039 the location of a breakpoint, or an expression that defines a
1040 watchpoint. The string should describe a location in a format
1041 recognized by the 'break' command (*note Setting Breakpoints: Set
1042 Breaks.) or, in the case of a watchpoint, by the 'watch' command
1043 (*note Setting Watchpoints: Set Watchpoints.).
1045 The optional TYPE argument specifies the type of the breakpoint to
1046 create, as defined below.
1048 The optional WP_CLASS argument defines the class of watchpoint to
1049 create, if TYPE is 'gdb.BP_WATCHPOINT'. If WP_CLASS is omitted, it
1050 defaults to 'gdb.WP_WRITE'.
1052 The optional INTERNAL argument allows the breakpoint to become
1053 invisible to the user. The breakpoint will neither be reported
1054 when created, nor will it be listed in the output from 'info
1055 breakpoints' (but will be listed with the 'maint info breakpoints'
1058 The optional TEMPORARY argument makes the breakpoint a temporary
1059 breakpoint. Temporary breakpoints are deleted after they have been
1060 hit. Any further access to the Python breakpoint after it has been
1061 hit will result in a runtime error (as that breakpoint has now been
1062 automatically deleted).
1064 The optional QUALIFIED argument is a boolean that allows
1065 interpreting the function passed in 'spec' as a fully-qualified
1066 name. It is equivalent to 'break''s '-qualified' flag (*note
1067 Linespec Locations:: and *note Explicit Locations::).
1069 -- Function: Breakpoint.__init__ ([ source ][, function ][, label ][,
1070 line ], ][ internal ][, temporary ][, qualified ])
1071 This second form of creating a new breakpoint specifies the
1072 explicit location (*note Explicit Locations::) using keywords. The
1073 new breakpoint will be created in the specified source file SOURCE,
1074 at the specified FUNCTION, LABEL and LINE.
1076 INTERNAL, TEMPORARY and QUALIFIED have the same usage as explained
1079 The available types are represented by constants defined in the 'gdb'
1083 Normal code breakpoint.
1085 'gdb.BP_HARDWARE_BREAKPOINT'
1086 Hardware assisted code breakpoint.
1089 Watchpoint breakpoint.
1091 'gdb.BP_HARDWARE_WATCHPOINT'
1092 Hardware assisted watchpoint.
1094 'gdb.BP_READ_WATCHPOINT'
1095 Hardware assisted read watchpoint.
1097 'gdb.BP_ACCESS_WATCHPOINT'
1098 Hardware assisted access watchpoint.
1101 Catchpoint. Currently, this type can't be used when creating
1102 'gdb.Breakpoint' objects, but will be present in 'gdb.Breakpoint'
1103 objects reported from 'gdb.BreakpointEvent's (*note Events In
1106 The available watchpoint types are represented by constants defined
1107 in the 'gdb' module:
1110 Read only watchpoint.
1113 Write only watchpoint.
1116 Read/Write watchpoint.
1118 -- Function: Breakpoint.stop (self)
1119 The 'gdb.Breakpoint' class can be sub-classed and, in particular,
1120 you may choose to implement the 'stop' method. If this method is
1121 defined in a sub-class of 'gdb.Breakpoint', it will be called when
1122 the inferior reaches any location of a breakpoint which
1123 instantiates that sub-class. If the method returns 'True', the
1124 inferior will be stopped at the location of the breakpoint,
1125 otherwise the inferior will continue.
1127 If there are multiple breakpoints at the same location with a
1128 'stop' method, each one will be called regardless of the return
1129 status of the previous. This ensures that all 'stop' methods have
1130 a chance to execute at that location. In this scenario if one of
1131 the methods returns 'True' but the others return 'False', the
1132 inferior will still be stopped.
1134 You should not alter the execution state of the inferior (i.e.,
1135 step, next, etc.), alter the current frame context (i.e., change
1136 the current active frame), or alter, add or delete any breakpoint.
1137 As a general rule, you should not alter any data within GDB or the
1138 inferior at this time.
1140 Example 'stop' implementation:
1142 class MyBreakpoint (gdb.Breakpoint):
1144 inf_val = gdb.parse_and_eval("foo")
1149 -- Function: Breakpoint.is_valid ()
1150 Return 'True' if this 'Breakpoint' object is valid, 'False'
1151 otherwise. A 'Breakpoint' object can become invalid if the user
1152 deletes the breakpoint. In this case, the object still exists, but
1153 the underlying breakpoint does not. In the cases of watchpoint
1154 scope, the watchpoint remains valid even if execution of the
1155 inferior leaves the scope of that watchpoint.
1157 -- Function: Breakpoint.delete ()
1158 Permanently deletes the GDB breakpoint. This also invalidates the
1159 Python 'Breakpoint' object. Any further access to this object's
1160 attributes or methods will raise an error.
1162 -- Variable: Breakpoint.enabled
1163 This attribute is 'True' if the breakpoint is enabled, and 'False'
1164 otherwise. This attribute is writable. You can use it to enable
1165 or disable the breakpoint.
1167 -- Variable: Breakpoint.silent
1168 This attribute is 'True' if the breakpoint is silent, and 'False'
1169 otherwise. This attribute is writable.
1171 Note that a breakpoint can also be silent if it has commands and
1172 the first command is 'silent'. This is not reported by the
1175 -- Variable: Breakpoint.pending
1176 This attribute is 'True' if the breakpoint is pending, and 'False'
1177 otherwise. *Note Set Breaks::. This attribute is read-only.
1179 -- Variable: Breakpoint.thread
1180 If the breakpoint is thread-specific, this attribute holds the
1181 thread's global id. If the breakpoint is not thread-specific, this
1182 attribute is 'None'. This attribute is writable.
1184 -- Variable: Breakpoint.task
1185 If the breakpoint is Ada task-specific, this attribute holds the
1186 Ada task id. If the breakpoint is not task-specific (or the
1187 underlying language is not Ada), this attribute is 'None'. This
1188 attribute is writable.
1190 -- Variable: Breakpoint.ignore_count
1191 This attribute holds the ignore count for the breakpoint, an
1192 integer. This attribute is writable.
1194 -- Variable: Breakpoint.number
1195 This attribute holds the breakpoint's number -- the identifier used
1196 by the user to manipulate the breakpoint. This attribute is not
1199 -- Variable: Breakpoint.type
1200 This attribute holds the breakpoint's type -- the identifier used
1201 to determine the actual breakpoint type or use-case. This
1202 attribute is not writable.
1204 -- Variable: Breakpoint.visible
1205 This attribute tells whether the breakpoint is visible to the user
1206 when set, or when the 'info breakpoints' command is run. This
1207 attribute is not writable.
1209 -- Variable: Breakpoint.temporary
1210 This attribute indicates whether the breakpoint was created as a
1211 temporary breakpoint. Temporary breakpoints are automatically
1212 deleted after that breakpoint has been hit. Access to this
1213 attribute, and all other attributes and functions other than the
1214 'is_valid' function, will result in an error after the breakpoint
1215 has been hit (as it has been automatically deleted). This
1216 attribute is not writable.
1218 -- Variable: Breakpoint.hit_count
1219 This attribute holds the hit count for the breakpoint, an integer.
1220 This attribute is writable, but currently it can only be set to
1223 -- Variable: Breakpoint.location
1224 This attribute holds the location of the breakpoint, as specified
1225 by the user. It is a string. If the breakpoint does not have a
1226 location (that is, it is a watchpoint) the attribute's value is
1227 'None'. This attribute is not writable.
1229 -- Variable: Breakpoint.locations
1230 Get the most current list of breakpoint locations that are inserted
1231 for this breakpoint, with elements of type 'gdb.BreakpointLocation'
1232 (described below). This functionality matches that of the 'info
1233 breakpoint' command (*note Set Breaks::), in that it only retrieves
1234 the most current list of locations, thus the list itself when
1235 returned is not updated behind the scenes. This attribute is not
1238 -- Variable: Breakpoint.expression
1239 This attribute holds a breakpoint expression, as specified by the
1240 user. It is a string. If the breakpoint does not have an
1241 expression (the breakpoint is not a watchpoint) the attribute's
1242 value is 'None'. This attribute is not writable.
1244 -- Variable: Breakpoint.condition
1245 This attribute holds the condition of the breakpoint, as specified
1246 by the user. It is a string. If there is no condition, this
1247 attribute's value is 'None'. This attribute is writable.
1249 -- Variable: Breakpoint.commands
1250 This attribute holds the commands attached to the breakpoint. If
1251 there are commands, this attribute's value is a string holding all
1252 the commands, separated by newlines. If there are no commands,
1253 this attribute is 'None'. This attribute is writable.
1255 Breakpoint Locations
1256 --------------------
1258 A breakpoint location is one of the actual places where a breakpoint has
1259 been set, represented in the Python API by the 'gdb.BreakpointLocation'
1260 type. This type is never instantiated by the user directly, but is
1261 retrieved from 'Breakpoint.locations' which returns a list of breakpoint
1262 locations where it is currently set. Breakpoint locations can become
1263 invalid if new symbol files are loaded or dynamically loaded libraries
1264 are closed. Accessing the attributes of an invalidated breakpoint
1265 location will throw a 'RuntimeError' exception. Access the
1266 'Breakpoint.locations' attribute again to retrieve the new and valid
1267 breakpoints location list.
1269 -- Variable: BreakpointLocation.source
1270 This attribute returns the source file path and line number where
1271 this location was set. The type of the attribute is a tuple of
1272 STRING and LONG. If the breakpoint location doesn't have a source
1273 location, it returns None, which is the case for watchpoints and
1274 catchpoints. This will throw a 'RuntimeError' exception if the
1275 location has been invalidated. This attribute is not writable.
1277 -- Variable: BreakpointLocation.address
1278 This attribute returns the address where this location was set.
1279 This attribute is of type long. This will throw a 'RuntimeError'
1280 exception if the location has been invalidated. This attribute is
1283 -- Variable: BreakpointLocation.enabled
1284 This attribute holds the value for whether or not this location is
1285 enabled. This attribute is writable (boolean). This will throw a
1286 'RuntimeError' exception if the location has been invalidated.
1288 -- Variable: BreakpointLocation.owner
1289 This attribute holds a reference to the 'gdb.Breakpoint' owner
1290 object, from which this 'gdb.BreakpointLocation' was retrieved
1291 from. This will throw a 'RuntimeError' exception if the location
1292 has been invalidated. This attribute is not writable.
1294 -- Variable: BreakpointLocation.function
1295 This attribute gets the name of the function where this location
1296 was set. If no function could be found this attribute returns
1297 'None'. This will throw a 'RuntimeError' exception if the location
1298 has been invalidated. This attribute is not writable.
1300 -- Variable: BreakpointLocation.fullname
1301 This attribute gets the full name of where this location was set.
1302 If no full name could be found, this attribute returns 'None'.
1303 This will throw a 'RuntimeError' exception if the location has been
1304 invalidated. This attribute is not writable.
1306 -- Variable: BreakpointLocation.thread_groups
1307 This attribute gets the thread groups it was set in. It returns a
1308 'List' of the thread group ID's. This will throw a 'RuntimeError'
1309 exception if the location has been invalidated. This attribute is
1313 File: gdb.info, Node: Finish Breakpoints in Python, Next: Lazy Strings In Python, Prev: Breakpoints In Python, Up: Python API
1315 23.3.2.32 Finish Breakpoints
1316 ............................
1318 A finish breakpoint is a temporary breakpoint set at the return address
1319 of a frame, based on the 'finish' command. 'gdb.FinishBreakpoint'
1320 extends 'gdb.Breakpoint'. The underlying breakpoint will be disabled
1321 and deleted when the execution will run out of the breakpoint scope
1322 (i.e. 'Breakpoint.stop' or 'FinishBreakpoint.out_of_scope' triggered).
1323 Finish breakpoints are thread specific and must be create with the right
1326 -- Function: FinishBreakpoint.__init__ ([frame] [, internal])
1327 Create a finish breakpoint at the return address of the 'gdb.Frame'
1328 object FRAME. If FRAME is not provided, this defaults to the
1329 newest frame. The optional INTERNAL argument allows the breakpoint
1330 to become invisible to the user. *Note Breakpoints In Python::,
1331 for further details about this argument.
1333 -- Function: FinishBreakpoint.out_of_scope (self)
1334 In some circumstances (e.g. 'longjmp', C++ exceptions, GDB 'return'
1335 command, ...), a function may not properly terminate, and thus
1336 never hit the finish breakpoint. When GDB notices such a
1337 situation, the 'out_of_scope' callback will be triggered.
1339 You may want to sub-class 'gdb.FinishBreakpoint' and override this
1342 class MyFinishBreakpoint (gdb.FinishBreakpoint)
1344 print ("normal finish")
1347 def out_of_scope ():
1348 print ("abnormal finish")
1350 -- Variable: FinishBreakpoint.return_value
1351 When GDB is stopped at a finish breakpoint and the frame used to
1352 build the 'gdb.FinishBreakpoint' object had debug symbols, this
1353 attribute will contain a 'gdb.Value' object corresponding to the
1354 return value of the function. The value will be 'None' if the
1355 function return type is 'void' or if the return value was not
1356 computable. This attribute is not writable.
1359 File: gdb.info, Node: Lazy Strings In Python, Next: Architectures In Python, Prev: Finish Breakpoints in Python, Up: Python API
1361 23.3.2.33 Python representation of lazy strings
1362 ...............................................
1364 A "lazy string" is a string whose contents is not retrieved or encoded
1367 A 'gdb.LazyString' is represented in GDB as an 'address' that points
1368 to a region of memory, an 'encoding' that will be used to encode that
1369 region of memory, and a 'length' to delimit the region of memory that
1370 represents the string. The difference between a 'gdb.LazyString' and a
1371 string wrapped within a 'gdb.Value' is that a 'gdb.LazyString' will be
1372 treated differently by GDB when printing. A 'gdb.LazyString' is
1373 retrieved and encoded during printing, while a 'gdb.Value' wrapping a
1374 string is immediately retrieved and encoded on creation.
1376 A 'gdb.LazyString' object has the following functions:
1378 -- Function: LazyString.value ()
1379 Convert the 'gdb.LazyString' to a 'gdb.Value'. This value will
1380 point to the string in memory, but will lose all the delayed
1381 retrieval, encoding and handling that GDB applies to a
1384 -- Variable: LazyString.address
1385 This attribute holds the address of the string. This attribute is
1388 -- Variable: LazyString.length
1389 This attribute holds the length of the string in characters. If
1390 the length is -1, then the string will be fetched and encoded up to
1391 the first null of appropriate width. This attribute is not
1394 -- Variable: LazyString.encoding
1395 This attribute holds the encoding that will be applied to the
1396 string when the string is printed by GDB. If the encoding is not
1397 set, or contains an empty string, then GDB will select the most
1398 appropriate encoding when the string is printed. This attribute is
1401 -- Variable: LazyString.type
1402 This attribute holds the type that is represented by the lazy
1403 string's type. For a lazy string this is a pointer or array type.
1404 To resolve this to the lazy string's character type, use the type's
1405 'target' method. *Note Types In Python::. This attribute is not
1409 File: gdb.info, Node: Architectures In Python, Next: Registers In Python, Prev: Lazy Strings In Python, Up: Python API
1411 23.3.2.34 Python representation of architectures
1412 ................................................
1414 GDB uses architecture specific parameters and artifacts in a number of
1415 its various computations. An architecture is represented by an instance
1416 of the 'gdb.Architecture' class.
1418 A 'gdb.Architecture' class has the following methods:
1420 -- Function: Architecture.name ()
1421 Return the name (string value) of the architecture.
1423 -- Function: Architecture.disassemble (START_PC [, END_PC [, COUNT]])
1424 Return a list of disassembled instructions starting from the memory
1425 address START_PC. The optional arguments END_PC and COUNT
1426 determine the number of instructions in the returned list. If both
1427 the optional arguments END_PC and COUNT are specified, then a list
1428 of at most COUNT disassembled instructions whose start address
1429 falls in the closed memory address interval from START_PC to END_PC
1430 are returned. If END_PC is not specified, but COUNT is specified,
1431 then COUNT number of instructions starting from the address
1432 START_PC are returned. If COUNT is not specified but END_PC is
1433 specified, then all instructions whose start address falls in the
1434 closed memory address interval from START_PC to END_PC are
1435 returned. If neither END_PC nor COUNT are specified, then a single
1436 instruction at START_PC is returned. For all of these cases, each
1437 element of the returned list is a Python 'dict' with the following
1441 The value corresponding to this key is a Python long integer
1442 capturing the memory address of the instruction.
1445 The value corresponding to this key is a string value which
1446 represents the instruction with assembly language mnemonics.
1447 The assembly language flavor used is the same as that
1448 specified by the current CLI variable 'disassembly-flavor'.
1449 *Note Machine Code::.
1452 The value corresponding to this key is the length (integer
1453 value) of the instruction in bytes.
1455 -- Function: Architecture.integer_type (size [, signed])
1456 This function looks up an integer type by its SIZE, and optionally
1457 whether or not it is signed.
1459 SIZE is the size, in bits, of the desired integer type. Only
1460 certain sizes are currently supported: 0, 8, 16, 24, 32, 64, and
1463 If SIGNED is not specified, it defaults to 'True'. If SIGNED is
1464 'False', the returned type will be unsigned.
1466 If the indicated type cannot be found, this function will throw a
1467 'ValueError' exception.
1469 -- Function: Architecture.registers ([ REGGROUP ])
1470 Return a 'gdb.RegisterDescriptorIterator' (*note Registers In
1471 Python::) for all of the registers in REGGROUP, a string that is
1472 the name of a register group. If REGGROUP is omitted, or is the
1473 empty string, then the register group 'all' is assumed.
1475 -- Function: Architecture.register_groups ()
1476 Return a 'gdb.RegisterGroupsIterator' (*note Registers In Python::)
1477 for all of the register groups available for the
1481 File: gdb.info, Node: Registers In Python, Next: Connections In Python, Prev: Architectures In Python, Up: Python API
1483 23.3.2.35 Registers In Python
1484 .............................
1486 Python code can request from a 'gdb.Architecture' information about the
1487 set of registers available (*note 'Architecture.registers':
1488 gdbpy_architecture_registers.). The register information is returned as
1489 a 'gdb.RegisterDescriptorIterator', which is an iterator that in turn
1490 returns 'gdb.RegisterDescriptor' objects.
1492 A 'gdb.RegisterDescriptor' does not provide the value of a register
1493 (*note 'Frame.read_register': gdbpy_frame_read_register. for reading a
1494 register's value), instead the 'RegisterDescriptor' is a way to discover
1495 which registers are available for a particular architecture.
1497 A 'gdb.RegisterDescriptor' has the following read-only properties:
1499 -- Variable: RegisterDescriptor.name
1500 The name of this register.
1502 It is also possible to lookup a register descriptor based on its name
1503 using the following 'gdb.RegisterDescriptorIterator' function:
1505 -- Function: RegisterDescriptorIterator.find (NAME)
1506 Takes NAME as an argument, which must be a string, and returns a
1507 'gdb.RegisterDescriptor' for the register with that name, or 'None'
1508 if there is no register with that name.
1510 Python code can also request from a 'gdb.Architecture' information
1511 about the set of register groups available on a given architecture
1512 (*note 'Architecture.register_groups': gdbpy_architecture_reggroups.).
1514 Every register can be a member of zero or more register groups. Some
1515 register groups are used internally within GDB to control things like
1516 which registers must be saved when calling into the program being
1517 debugged (*note Calling Program Functions: Calling.). Other register
1518 groups exist to allow users to easily see related sets of registers in
1519 commands like 'info registers' (*note 'info registers REGGROUP':
1520 info_registers_reggroup.).
1522 The register groups information is returned as a
1523 'gdb.RegisterGroupsIterator', which is an iterator that in turn returns
1524 'gdb.RegisterGroup' objects.
1526 A 'gdb.RegisterGroup' object has the following read-only properties:
1528 -- Variable: RegisterGroup.name
1529 A string that is the name of this register group.
1532 File: gdb.info, Node: Connections In Python, Next: TUI Windows In Python, Prev: Registers In Python, Up: Python API
1534 23.3.2.36 Connections In Python
1535 ...............................
1537 GDB lets you run and debug multiple programs in a single session. Each
1538 program being debugged has a connection, the connection describes how
1539 GDB controls the program being debugged. Examples of different
1540 connection types are 'native' and 'remote'. *Note Inferiors Connections
1543 Connections in GDB are represented as instances of
1544 'gdb.TargetConnection', or as one of its sub-classes. To get a list of
1545 all connections use 'gdb.connections' (*note gdb.connections:
1546 gdbpy_connections.).
1548 To get the connection for a single 'gdb.Inferior' read its
1549 'gdb.Inferior.connection' attribute (*note gdb.Inferior.connection:
1550 gdbpy_inferior_connection.).
1552 Currently there is only a single sub-class of 'gdb.TargetConnection',
1553 'gdb.RemoteTargetConnection', however, additional sub-classes may be
1554 added in future releases of GDB. As a result you should avoid writing
1557 conn = gdb.selected_inferior().connection
1558 if type(conn) is gdb.RemoteTargetConnection:
1559 print("This is a remote target connection")
1561 as this may fail when more connection types are added. Instead, you
1564 conn = gdb.selected_inferior().connection
1565 if isinstance(conn, gdb.RemoteTargetConnection):
1566 print("This is a remote target connection")
1568 A 'gdb.TargetConnection' has the following method:
1570 -- Function: TargetConnection.is_valid ()
1571 Return 'True' if the 'gdb.TargetConnection' object is valid,
1572 'False' if not. A 'gdb.TargetConnection' will become invalid if
1573 the connection no longer exists within GDB, this might happen when
1574 no inferiors are using the connection, but could be delayed until
1575 the user replaces the current target.
1577 Reading any of the 'gdb.TargetConnection' properties will throw an
1578 exception if the connection is invalid.
1580 A 'gdb.TargetConnection' has the following read-only properties:
1582 -- Variable: TargetConnection.num
1583 An integer assigned by GDB to uniquely identify this connection.
1584 This is the same value as displayed in the 'Num' column of the
1585 'info connections' command output (*note info connections:
1586 Inferiors Connections and Programs.).
1588 -- Variable: TargetConnection.type
1589 A string that describes what type of connection this is. This
1590 string will be one of the valid names that can be passed to the
1591 'target' command (*note target command: Target Commands.).
1593 -- Variable: TargetConnection.description
1594 A string that gives a short description of this target type. This
1595 is the same string that is displayed in the 'Description' column of
1596 the 'info connection' command output (*note info connections:
1597 Inferiors Connections and Programs.).
1599 -- Variable: TargetConnection.details
1600 An optional string that gives additional information about this
1601 connection. This attribute can be 'None' if there are no
1602 additional details for this connection.
1604 An example of a connection type that might have additional details
1605 is the 'remote' connection, in this case the details string can
1606 contain the 'HOSTNAME:PORT' that was used to connect to the remote
1609 The 'gdb.RemoteTargetConnection' class is a sub-class of
1610 'gdb.TargetConnection', and is used to represent 'remote' and
1611 'extended-remote' connections. In addition to the attributes and
1612 methods available from the 'gdb.TargetConnection' base class, a
1613 'gdb.RemoteTargetConnection' has the following method:
1615 -- Function: RemoteTargetConnection.send_packet (PACKET)
1616 This method sends PACKET to the remote target and returns the
1617 response. The PACKET should either be a 'bytes' object, or a
1620 If PACKET is a 'Unicode' string, then the string is encoded to a
1621 'bytes' object using the ASCII codec. If the string can't be
1622 encoded then an 'UnicodeError' is raised.
1624 If PACKET is not a 'bytes' object, or a 'Unicode' string, then a
1625 'TypeError' is raised. If PACKET is empty then a 'ValueError' is
1628 The response is returned as a 'bytes' object. For Python 3 if it
1629 is known that the response can be represented as a string then this
1630 can be decoded from the buffer. For example, if it is known that
1631 the response is an ASCII string:
1633 remote_connection.send_packet("some_packet").decode("ascii")
1635 In Python 2 'bytes' and 'str' are aliases, so the result is already
1636 a string, if the response includes non-printable characters, or
1637 null characters, then these will be present in the result, care
1638 should be taken when processing the result to handle this case.
1640 The prefix, suffix, and checksum (as required by the remote serial
1641 protocol) are automatically added to the outgoing packet, and
1642 removed from the incoming packet before the contents of the reply
1645 This is equivalent to the 'maintenance packet' command (*note maint
1649 File: gdb.info, Node: TUI Windows In Python, Next: Disassembly In Python, Prev: Connections In Python, Up: Python API
1651 23.3.2.37 Implementing new TUI windows
1652 ......................................
1654 New TUI (*note TUI::) windows can be implemented in Python.
1656 -- Function: gdb.register_window_type (NAME, FACTORY)
1657 Because TUI windows are created and destroyed depending on the
1658 layout the user chooses, new window types are implemented by
1659 registering a factory function with GDB.
1661 NAME is the name of the new window. It's an error to try to
1662 replace one of the built-in windows, but other window types can be
1663 replaced. The NAME should match the regular expression
1664 '[a-zA-Z][-_.a-zA-Z0-9]*', it is an error to try and create a
1665 window with an invalid name.
1667 FUNCTION is a factory function that is called to create the TUI
1668 window. This is called with a single argument of type
1669 'gdb.TuiWindow', described below. It should return an object that
1670 implements the TUI window protocol, also described below.
1672 As mentioned above, when a factory function is called, it is passed
1673 an object of type 'gdb.TuiWindow'. This object has these methods and
1676 -- Function: TuiWindow.is_valid ()
1677 This method returns 'True' when this window is valid. When the
1678 user changes the TUI layout, windows no longer visible in the new
1679 layout will be destroyed. At this point, the 'gdb.TuiWindow' will
1680 no longer be valid, and methods (and attributes) other than
1681 'is_valid' will throw an exception.
1683 When the TUI is disabled using 'tui disable' (*note tui disable:
1684 TUI Commands.) the window is hidden rather than destroyed, but
1685 'is_valid' will still return 'False' and other methods (and
1686 attributes) will still throw an exception.
1688 -- Variable: TuiWindow.width
1689 This attribute holds the width of the window. It is not writable.
1691 -- Variable: TuiWindow.height
1692 This attribute holds the height of the window. It is not writable.
1694 -- Variable: TuiWindow.title
1695 This attribute holds the window's title, a string. This is
1696 normally displayed above the window. This attribute can be
1699 -- Function: TuiWindow.erase ()
1700 Remove all the contents of the window.
1702 -- Function: TuiWindow.write (STRING [, FULL_WINDOW])
1703 Write STRING to the window. STRING can contain ANSI terminal
1704 escape styling sequences; GDB will translate these as appropriate
1707 If the FULL_WINDOW parameter is 'True', then STRING contains the
1708 full contents of the window. This is similar to calling 'erase'
1709 before 'write', but avoids the flickering.
1711 The factory function that you supply should return an object
1712 conforming to the TUI window protocol. These are the method that can be
1713 called on this object, which is referred to below as the "window
1714 object". The methods documented below are optional; if the object does
1715 not implement one of these methods, GDB will not attempt to call it.
1716 Additional new methods may be added to the window protocol in the
1717 future. GDB guarantees that they will begin with a lower-case letter,
1718 so you can start implementation methods with upper-case letters or
1719 underscore to avoid any future conflicts.
1721 -- Function: Window.close ()
1722 When the TUI window is closed, the 'gdb.TuiWindow' object will be
1723 put into an invalid state. At this time, GDB will call 'close'
1724 method on the window object.
1726 After this method is called, GDB will discard any references it
1727 holds on this window object, and will no longer call methods on
1730 -- Function: Window.render ()
1731 In some situations, a TUI window can change size. For example,
1732 this can happen if the user resizes the terminal, or changes the
1733 layout. When this happens, GDB will call the 'render' method on
1736 If your window is intended to update in response to changes in the
1737 inferior, you will probably also want to register event listeners
1738 and send output to the 'gdb.TuiWindow'.
1740 -- Function: Window.hscroll (NUM)
1741 This is a request to scroll the window horizontally. NUM is the
1742 amount by which to scroll, with negative numbers meaning to scroll
1743 right. In the TUI model, it is the viewport that moves, not the
1744 contents. A positive argument should cause the viewport to move
1745 right, and so the content should appear to move to the left.
1747 -- Function: Window.vscroll (NUM)
1748 This is a request to scroll the window vertically. NUM is the
1749 amount by which to scroll, with negative numbers meaning to scroll
1750 backward. In the TUI model, it is the viewport that moves, not the
1751 contents. A positive argument should cause the viewport to move
1752 down, and so the content should appear to move up.
1754 -- Function: Window.click (X, Y, BUTTON)
1755 This is called on a mouse click in this window. X and Y are the
1756 mouse coordinates inside the window (0-based, from the top left
1757 corner), and BUTTON specifies which mouse button was used, whose
1758 values can be 1 (left), 2 (middle), or 3 (right).
1761 File: gdb.info, Node: Disassembly In Python, Prev: TUI Windows In Python, Up: Python API
1763 23.3.2.38 Instruction Disassembly In Python
1764 ...........................................
1766 GDB's builtin disassembler can be extended, or even replaced, using the
1767 Python API. The disassembler related features are contained within the
1768 'gdb.disassembler' module:
1770 -- class: gdb.disassembler.DisassembleInfo
1771 Disassembly is driven by instances of this class. Each time GDB
1772 needs to disassemble an instruction, an instance of this class is
1773 created and passed to a registered disassembler. The disassembler
1774 is then responsible for disassembling an instruction and returning
1777 Instances of this type are usually created within GDB, however, it
1778 is possible to create a copy of an instance of this type, see the
1779 description of '__init__' for more details.
1781 This class has the following properties and methods:
1783 -- Variable: DisassembleInfo.address
1784 A read-only integer containing the address at which GDB wishes
1785 to disassemble a single instruction.
1787 -- Variable: DisassembleInfo.architecture
1788 The 'gdb.Architecture' (*note Architectures In Python::) for
1789 which GDB is currently disassembling, this property is
1792 -- Variable: DisassembleInfo.progspace
1793 The 'gdb.Progspace' (*note Program Spaces In Python:
1794 Progspaces In Python.) for which GDB is currently
1795 disassembling, this property is read-only.
1797 -- Function: DisassembleInfo.is_valid ()
1798 Returns 'True' if the 'DisassembleInfo' object is valid,
1799 'False' if not. A 'DisassembleInfo' object will become
1800 invalid once the disassembly call for which the
1801 'DisassembleInfo' was created, has returned. Calling other
1802 'DisassembleInfo' methods, or accessing 'DisassembleInfo'
1803 properties, will raise a 'RuntimeError' exception if it is
1806 -- Function: DisassembleInfo.__init__ (info)
1807 This can be used to create a new 'DisassembleInfo' object that
1808 is a copy of INFO. The copy will have the same 'address',
1809 'architecture', and 'progspace' values as INFO, and will
1810 become invalid at the same time as INFO.
1812 This method exists so that sub-classes of 'DisassembleInfo'
1813 can be created, these sub-classes must be initialized as
1814 copies of an existing 'DisassembleInfo' object, but
1815 sub-classes might choose to override the 'read_memory' method,
1816 and so control what GDB sees when reading from memory (*note
1817 builtin_disassemble::).
1819 -- Function: DisassembleInfo.read_memory (length, offset)
1820 This method allows the disassembler to read the bytes of the
1821 instruction to be disassembled. The method reads LENGTH
1822 bytes, starting at OFFSET from 'DisassembleInfo.address'.
1824 It is important that the disassembler read the instruction
1825 bytes using this method, rather than reading inferior memory
1826 directly, as in some cases GDB disassembles from an internal
1827 buffer rather than directly from inferior memory, calling this
1828 method handles this detail.
1830 Returns a buffer object, which behaves much like an array or a
1831 string, just as 'Inferior.read_memory' does (*note
1832 Inferior.read_memory: gdbpy_inferior_read_memory.). The
1833 length of the returned buffer will always be exactly LENGTH.
1835 If GDB is unable to read the required memory then a
1836 'gdb.MemoryError' exception is raised (*note Exception
1839 This method can be overridden by a sub-class in order to
1840 control what GDB sees when reading from memory (*note
1841 builtin_disassemble::). When overriding this method it is
1842 important to understand how 'builtin_disassemble' makes use of
1845 While disassembling a single instruction there could be
1846 multiple calls to this method, and the same bytes might be
1847 read multiple times. Any single call might only read a subset
1848 of the total instruction bytes.
1850 If an implementation of 'read_memory' is unable to read the
1851 requested memory contents, for example, if there's a request
1852 to read from an invalid memory address, then a
1853 'gdb.MemoryError' should be raised.
1855 Raising a 'MemoryError' inside 'read_memory' does not
1856 automatically mean a 'MemoryError' will be raised by
1857 'builtin_disassemble'. It is possible the GDB's builtin
1858 disassembler is probing to see how many bytes are available.
1859 When 'read_memory' raises the 'MemoryError' the builtin
1860 disassembler might be able to perform a complete disassembly
1861 with the bytes it has available, in this case
1862 'builtin_disassemble' will not itself raise a 'MemoryError'.
1864 Any other exception type raised in 'read_memory' will
1865 propagate back and be re-raised by 'builtin_disassemble'.
1867 -- class: Disassembler
1868 This is a base class from which all user implemented disassemblers
1871 -- Function: Disassembler.__init__ (name)
1872 The constructor takes NAME, a string, which should be a short
1873 name for this disassembler.
1875 -- Function: Disassembler.__call__ (info)
1876 The '__call__' method must be overridden by sub-classes to
1877 perform disassembly. Calling '__call__' on this base class
1878 will raise a 'NotImplementedError' exception.
1880 The INFO argument is an instance of 'DisassembleInfo', and
1881 describes the instruction that GDB wants disassembling.
1883 If this function returns 'None', this indicates to GDB that
1884 this sub-class doesn't wish to disassemble the requested
1885 instruction. GDB will then use its builtin disassembler to
1886 perform the disassembly.
1888 Alternatively, this function can return a 'DisassemblerResult'
1889 that represents the disassembled instruction, this type is
1890 described in more detail below.
1892 The '__call__' method can raise a 'gdb.MemoryError' exception
1893 (*note Exception Handling::) to indicate to GDB that there was
1894 a problem accessing the required memory, this will then be
1895 displayed by GDB within the disassembler output.
1897 Ideally, the only three outcomes from invoking '__call__'
1898 would be a return of 'None', a successful disassembly returned
1899 in a 'DisassemblerResult', or a 'MemoryError' indicating that
1900 there was a problem reading memory.
1902 However, as an implementation of '__call__' could fail due to
1903 other reasons, e.g. some external resource required to perform
1904 disassembly is temporarily unavailable, then, if '__call__'
1905 raises a 'GdbError', the exception will be converted to a
1906 string and printed at the end of the disassembly output, the
1907 disassembly request will then stop.
1909 Any other exception type raised by the '__call__' method is
1910 considered an error in the user code, the exception will be
1911 printed to the error stream according to the 'set python
1912 print-stack' setting (*note 'set python print-stack':
1913 set_python_print_stack.).
1915 -- class: DisassemblerResult
1916 This class is used to hold the result of calling
1917 'Disassembler.__call__', and represents a single disassembled
1918 instruction. This class has the following properties and methods:
1920 -- Function: DisassemblerResult.__init__ (LENGTH, STRING)
1921 Initialize an instance of this class, LENGTH is the length of
1922 the disassembled instruction in bytes, which must be greater
1923 than zero, and STRING is a non-empty string that represents
1924 the disassembled instruction.
1926 -- Variable: DisassemblerResult.length
1927 A read-only property containing the length of the disassembled
1928 instruction in bytes, this will always be greater than zero.
1930 -- Variable: DisassemblerResult.string
1931 A read-only property containing a non-empty string
1932 representing the disassembled instruction.
1934 The following functions are also contained in the 'gdb.disassembler'
1937 -- Function: register_disassembler (disassembler, architecture)
1938 The DISASSEMBLER must be a sub-class of
1939 'gdb.disassembler.Disassembler' or 'None'.
1941 The optional ARCHITECTURE is either a string, or the value 'None'.
1942 If it is a string, then it should be the name of an architecture
1943 known to GDB, as returned either from 'gdb.Architecture.name'
1944 (*note gdb.Architecture.name: gdbpy_architecture_name.), or from
1945 'gdb.architecture_names' (*note gdb.architecture_names:
1946 gdb_architecture_names.).
1948 The DISASSEMBLER will be installed for the architecture named by
1949 ARCHITECTURE, or if ARCHITECTURE is 'None', then DISASSEMBLER will
1950 be installed as a global disassembler for use by all architectures.
1952 GDB only records a single disassembler for each architecture, and a
1953 single global disassembler. Calling 'register_disassembler' for an
1954 architecture, or for the global disassembler, will replace any
1955 existing disassembler registered for that ARCHITECTURE value. The
1956 previous disassembler is returned.
1958 If DISASSEMBLER is 'None' then any disassembler currently
1959 registered for ARCHITECTURE is deregistered and returned.
1961 When GDB is looking for a disassembler to use, GDB first looks for
1962 an architecture specific disassembler. If none has been registered
1963 then GDB looks for a global disassembler (one registered with
1964 ARCHITECTURE set to 'None'). Only one disassembler is called to
1965 perform disassembly, so, if there is both an architecture specific
1966 disassembler, and a global disassembler registered, it is the
1967 architecture specific disassembler that will be used.
1969 GDB tracks the architecture specific, and global disassemblers
1970 separately, so it doesn't matter in which order disassemblers are
1971 created or registered; an architecture specific disassembler, if
1972 present, will always be used in preference to a global
1975 You can use the 'maint info python-disassemblers' command (*note
1976 maint info python-disassemblers::) to see which disassemblers have
1979 -- Function: builtin_disassemble (info)
1980 This function calls back into GDB's builtin disassembler to
1981 disassemble the instruction identified by INFO, an instance, or
1982 sub-class, of 'DisassembleInfo'.
1984 When the builtin disassembler needs to read memory the
1985 'read_memory' method on INFO will be called. By sub-classing
1986 'DisassembleInfo' and overriding the 'read_memory' method, it is
1987 possible to intercept calls to 'read_memory' from the builtin
1988 disassembler, and to modify the values returned.
1990 It is important to understand that, even when
1991 'DisassembleInfo.read_memory' raises a 'gdb.MemoryError', it is the
1992 internal disassembler itself that reports the memory error to GDB.
1993 The reason for this is that the disassembler might probe memory to
1994 see if a byte is readable or not; if the byte can't be read then
1995 the disassembler may choose not to report an error, but instead to
1996 disassemble the bytes that it does have available.
1998 If the builtin disassembler is successful then an instance of
1999 'DisassemblerResult' is returned from 'builtin_disassemble',
2000 alternatively, if something goes wrong, an exception will be
2003 A 'MemoryError' will be raised if 'builtin_disassemble' is unable
2004 to read some memory that is required in order to perform
2005 disassembly correctly.
2007 Any exception that is not a 'MemoryError', that is raised in a call
2008 to 'read_memory', will pass through 'builtin_disassemble', and be
2009 visible to the caller.
2011 Finally, there are a few cases where GDB's builtin disassembler can
2012 fail for reasons that are not covered by 'MemoryError'. In these
2013 cases, a 'GdbError' will be raised. The contents of the exception
2014 will be a string describing the problem the disassembler
2017 Here is an example that registers a global disassembler. The new
2018 disassembler invokes the builtin disassembler, and then adds a comment,
2019 '## Comment', to each line of disassembly output:
2021 class ExampleDisassembler(gdb.disassembler.Disassembler):
2023 super().__init__("ExampleDisassembler")
2025 def __call__(self, info):
2026 result = gdb.disassembler.builtin_disassemble(info)
2027 length = result.length
2028 text = result.string + "\t## Comment"
2029 return gdb.disassembler.DisassemblerResult(length, text)
2031 gdb.disassembler.register_disassembler(ExampleDisassembler())
2033 The following example creates a sub-class of 'DisassembleInfo' in
2034 order to intercept the 'read_memory' calls, within 'read_memory' any
2035 bytes read from memory have the two 4-bit nibbles swapped around. This
2036 isn't a very useful adjustment, but serves as an example.
2038 class MyInfo(gdb.disassembler.DisassembleInfo):
2039 def __init__(self, info):
2040 super().__init__(info)
2042 def read_memory(self, length, offset):
2043 buffer = super().read_memory(length, offset)
2044 result = bytearray()
2046 v = int.from_bytes(b, 'little')
2047 v = (v << 4) & 0xf0 | (v >> 4)
2049 return memoryview(result)
2051 class NibbleSwapDisassembler(gdb.disassembler.Disassembler):
2053 super().__init__("NibbleSwapDisassembler")
2055 def __call__(self, info):
2057 return gdb.disassembler.builtin_disassemble(info)
2059 gdb.disassembler.register_disassembler(NibbleSwapDisassembler())
2062 File: gdb.info, Node: Python Auto-loading, Next: Python modules, Prev: Python API, Up: Python
2064 23.3.3 Python Auto-loading
2065 --------------------------
2067 When a new object file is read (for example, due to the 'file' command,
2068 or because the inferior has loaded a shared library), GDB will look for
2069 Python support scripts in several ways: 'OBJFILE-gdb.py' and
2070 '.debug_gdb_scripts' section. *Note Auto-loading extensions::.
2072 The auto-loading feature is useful for supplying application-specific
2073 debugging commands and scripts.
2075 Auto-loading can be enabled or disabled, and the list of auto-loaded
2076 scripts can be printed.
2078 'set auto-load python-scripts [on|off]'
2079 Enable or disable the auto-loading of Python scripts.
2081 'show auto-load python-scripts'
2082 Show whether auto-loading of Python scripts is enabled or disabled.
2084 'info auto-load python-scripts [REGEXP]'
2085 Print the list of all Python scripts that GDB auto-loaded.
2087 Also printed is the list of Python scripts that were mentioned in
2088 the '.debug_gdb_scripts' section and were either not found (*note
2089 dotdebug_gdb_scripts section::) or were not auto-loaded due to
2090 'auto-load safe-path' rejection (*note Auto-loading::). This is
2091 useful because their names are not printed when GDB tries to load
2092 them and fails. There may be many of them, and printing an error
2093 message for each one is problematic.
2095 If REGEXP is supplied only Python scripts with matching names are
2100 (gdb) info auto-load python-scripts
2102 Yes py-section-script.py
2103 full name: /tmp/py-section-script.py
2104 No my-foo-pretty-printers.py
2106 When reading an auto-loaded file or script, GDB sets the "current
2107 objfile". This is available via the 'gdb.current_objfile' function
2108 (*note Objfiles In Python::). This can be useful for registering
2109 objfile-specific pretty-printers and frame-filters.
2112 File: gdb.info, Node: Python modules, Prev: Python Auto-loading, Up: Python
2114 23.3.4 Python modules
2115 ---------------------
2117 GDB comes with several modules to assist writing Python code.
2121 * gdb.printing:: Building and registering pretty-printers.
2122 * gdb.types:: Utilities for working with types.
2123 * gdb.prompt:: Utilities for prompt value substitution.
2126 File: gdb.info, Node: gdb.printing, Next: gdb.types, Up: Python modules
2128 23.3.4.1 gdb.printing
2129 .....................
2131 This module provides a collection of utilities for working with
2134 'PrettyPrinter (NAME, SUBPRINTERS=None)'
2135 This class specifies the API that makes 'info pretty-printer',
2136 'enable pretty-printer' and 'disable pretty-printer' work.
2137 Pretty-printers should generally inherit from this class.
2139 'SubPrettyPrinter (NAME)'
2140 For printers that handle multiple types, this class specifies the
2141 corresponding API for the subprinters.
2143 'RegexpCollectionPrettyPrinter (NAME)'
2144 Utility class for handling multiple printers, all recognized via
2145 regular expressions. *Note Writing a Pretty-Printer::, for an
2148 'FlagEnumerationPrinter (NAME)'
2149 A pretty-printer which handles printing of 'enum' values. Unlike
2150 GDB's built-in 'enum' printing, this printer attempts to work
2151 properly when there is some overlap between the enumeration
2152 constants. The argument NAME is the name of the printer and also
2153 the name of the 'enum' type to look up.
2155 'register_pretty_printer (OBJ, PRINTER, REPLACE=False)'
2156 Register PRINTER with the pretty-printer list of OBJ. If REPLACE
2157 is 'True' then any existing copy of the printer is replaced.
2158 Otherwise a 'RuntimeError' exception is raised if a printer with
2159 the same name already exists.
2162 File: gdb.info, Node: gdb.types, Next: gdb.prompt, Prev: gdb.printing, Up: Python modules
2167 This module provides a collection of utilities for working with
2170 'get_basic_type (TYPE)'
2171 Return TYPE with const and volatile qualifiers stripped, and with
2172 typedefs and C++ references converted to the underlying type.
2176 typedef const int const_int;
2178 const_int& foo_ref (foo);
2179 int main () { return 0; }
2184 (gdb) python import gdb.types
2185 (gdb) python foo_ref = gdb.parse_and_eval("foo_ref")
2186 (gdb) python print gdb.types.get_basic_type(foo_ref.type)
2189 'has_field (TYPE, FIELD)'
2190 Return 'True' if TYPE, assumed to be a type with fields (e.g., a
2191 structure or union), has field FIELD.
2193 'make_enum_dict (ENUM_TYPE)'
2194 Return a Python 'dictionary' type produced from ENUM_TYPE.
2197 Returns a Python iterator similar to the standard
2198 'gdb.Type.iteritems' method, except that the iterator returned by
2199 'deep_items' will recursively traverse anonymous struct or union
2200 fields. For example:
2212 (gdb) python import gdb.types
2213 (gdb) python struct_a = gdb.lookup_type("struct A")
2214 (gdb) python print struct_a.keys ()
2216 (gdb) python print [k for k,v in gdb.types.deep_items(struct_a)]
2219 'get_type_recognizers ()'
2220 Return a list of the enabled type recognizers for the current
2221 context. This is called by GDB during the type-printing process
2222 (*note Type Printing API::).
2224 'apply_type_recognizers (recognizers, type_obj)'
2225 Apply the type recognizers, RECOGNIZERS, to the type object
2226 TYPE_OBJ. If any recognizer returns a string, return that string.
2227 Otherwise, return 'None'. This is called by GDB during the
2228 type-printing process (*note Type Printing API::).
2230 'register_type_printer (locus, printer)'
2231 This is a convenience function to register a type printer PRINTER.
2232 The printer must implement the type printer protocol. The LOCUS
2233 argument is either a 'gdb.Objfile', in which case the printer is
2234 registered with that objfile; a 'gdb.Progspace', in which case the
2235 printer is registered with that progspace; or 'None', in which case
2236 the printer is registered globally.
2239 This is a base class that implements the type printer protocol.
2240 Type printers are encouraged, but not required, to derive from this
2241 class. It defines a constructor:
2243 -- Method on TypePrinter: __init__ (self, name)
2244 Initialize the type printer with the given name. The new
2245 printer starts in the enabled state.
2248 File: gdb.info, Node: gdb.prompt, Prev: gdb.types, Up: Python modules
2253 This module provides a method for prompt value-substitution.
2255 'substitute_prompt (STRING)'
2256 Return STRING with escape sequences substituted by values. Some
2257 escape sequences take arguments. You can specify arguments inside
2258 "{}" immediately following the escape sequence.
2260 The escape sequences you can pass to this function are:
2263 Substitute a backslash.
2265 Substitute an ESC character.
2267 Substitute the selected frame; an argument names a frame
2270 Substitute a newline.
2272 Substitute a parameter's value; the argument names the
2275 Substitute a carriage return.
2277 Substitute the selected thread; an argument names a thread
2280 Substitute the version of GDB.
2282 Substitute the current working directory.
2284 Begin a sequence of non-printing characters. These sequences
2285 are typically used with the ESC character, and are not counted
2286 in the string length. Example: "\[\e[0;34m\](gdb)\[\e[0m\]"
2287 will return a blue-colored "(gdb)" prompt where the length is
2290 End a sequence of non-printing characters.
2294 substitute_prompt ("frame: \f, args: \p{print frame-arguments}")
2296 will return the string:
2298 "frame: main, args: scalars"
2301 File: gdb.info, Node: Guile, Next: Auto-loading extensions, Prev: Python, Up: Extending GDB
2303 23.4 Extending GDB using Guile
2304 ==============================
2306 You can extend GDB using the Guile implementation of the Scheme
2307 programming language (http://www.gnu.org/software/guile/). This feature
2308 is available only if GDB was configured using '--with-guile'.
2312 * Guile Introduction:: Introduction to Guile scripting in GDB
2313 * Guile Commands:: Accessing Guile from GDB
2314 * Guile API:: Accessing GDB from Guile
2315 * Guile Auto-loading:: Automatically loading Guile code
2316 * Guile Modules:: Guile modules provided by GDB
2319 File: gdb.info, Node: Guile Introduction, Next: Guile Commands, Up: Guile
2321 23.4.1 Guile Introduction
2322 -------------------------
2324 Guile is an implementation of the Scheme programming language and is the
2325 GNU project's official extension language.
2327 Guile support in GDB follows the Python support in GDB reasonably
2328 closely, so concepts there should carry over. However, some things are
2329 done differently where it makes sense.
2331 GDB requires Guile version 3.0, 2.2, or 2.0.
2333 Guile scripts used by GDB should be installed in
2334 'DATA-DIRECTORY/guile', where DATA-DIRECTORY is the data directory as
2335 determined at GDB startup (*note Data Files::). This directory, known
2336 as the "guile directory", is automatically added to the Guile Search
2337 Path in order to allow the Guile interpreter to locate all scripts
2338 installed at this location.
2341 File: gdb.info, Node: Guile Commands, Next: Guile API, Prev: Guile Introduction, Up: Guile
2343 23.4.2 Guile Commands
2344 ---------------------
2346 GDB provides two commands for accessing the Guile interpreter:
2350 The 'guile-repl' command can be used to start an interactive Guile
2351 prompt or "repl". To return to GDB, type ',q' or the 'EOF'
2352 character (e.g., 'Ctrl-D' on an empty prompt). These commands do
2353 not take any arguments.
2355 'guile [SCHEME-EXPRESSION]'
2356 'gu [SCHEME-EXPRESSION]'
2357 The 'guile' command can be used to evaluate a Scheme expression.
2359 If given an argument, GDB will pass the argument to the Guile
2360 interpreter for evaluation.
2362 (gdb) guile (display (+ 20 3)) (newline)
2365 The result of the Scheme expression is displayed using normal Guile
2368 (gdb) guile (+ 20 3)
2371 If you do not provide an argument to 'guile', it will act as a
2372 multi-line command, like 'define'. In this case, the Guile script
2373 is made up of subsequent command lines, given after the 'guile'
2374 command. This command list is terminated using a line containing
2383 It is also possible to execute a Guile script from the GDB
2386 'source script-name'
2387 The script name must end with '.scm' and GDB must be configured to
2388 recognize the script language based on filename extension using the
2389 'script-extension' setting. *Note Extending GDB: Extending GDB.
2391 'guile (load "script-name")'
2392 This method uses the 'load' Guile function. It takes a string
2393 argument that is the name of the script to load. See the Guile
2394 documentation for a description of this function. (*note
2398 File: gdb.info, Node: Guile API, Next: Guile Auto-loading, Prev: Guile Commands, Up: Guile
2403 You can get quick online help for GDB's Guile API by issuing the command
2404 'help guile', or by issuing the command ',help' from an interactive
2405 Guile session. Furthermore, most Guile procedures provided by GDB have
2406 doc strings which can be obtained with ',describe PROCEDURE-NAME' or ',d
2407 PROCEDURE-NAME' from the Guile interactive prompt.
2411 * Basic Guile:: Basic Guile Functions
2412 * Guile Configuration:: Guile configuration variables
2413 * GDB Scheme Data Types:: Scheme representations of GDB objects
2414 * Guile Exception Handling:: How Guile exceptions are translated
2415 * Values From Inferior In Guile:: Guile representation of values
2416 * Arithmetic In Guile:: Arithmetic in Guile
2417 * Types In Guile:: Guile representation of types
2418 * Guile Pretty Printing API:: Pretty-printing values with Guile
2419 * Selecting Guile Pretty-Printers:: How GDB chooses a pretty-printer
2420 * Writing a Guile Pretty-Printer:: Writing a pretty-printer
2421 * Commands In Guile:: Implementing new commands in Guile
2422 * Parameters In Guile:: Adding new GDB parameters
2423 * Progspaces In Guile:: Program spaces
2424 * Objfiles In Guile:: Object files in Guile
2425 * Frames In Guile:: Accessing inferior stack frames from Guile
2426 * Blocks In Guile:: Accessing blocks from Guile
2427 * Symbols In Guile:: Guile representation of symbols
2428 * Symbol Tables In Guile:: Guile representation of symbol tables
2429 * Breakpoints In Guile:: Manipulating breakpoints using Guile
2430 * Lazy Strings In Guile:: Guile representation of lazy strings
2431 * Architectures In Guile:: Guile representation of architectures
2432 * Disassembly In Guile:: Disassembling instructions from Guile
2433 * I/O Ports in Guile:: GDB I/O ports
2434 * Memory Ports in Guile:: Accessing memory through ports and bytevectors
2435 * Iterators In Guile:: Basic iterator support
2438 File: gdb.info, Node: Basic Guile, Next: Guile Configuration, Up: Guile API
2440 23.4.3.1 Basic Guile
2441 ....................
2443 At startup, GDB overrides Guile's 'current-output-port' and
2444 'current-error-port' to print using GDB's output-paging streams. A
2445 Guile program which outputs to one of these streams may have its output
2446 interrupted by the user (*note Screen Size::). In this situation, a
2447 Guile 'signal' exception is thrown with value 'SIGINT'.
2449 Guile's history mechanism uses the same naming as GDB's, namely the
2450 user of dollar-variables (e.g., $1, $2, etc.). The results of
2451 evaluations in Guile and in GDB are counted separately, '$1' in Guile is
2452 not the same value as '$1' in GDB.
2454 GDB is not thread-safe. If your Guile program uses multiple threads,
2455 you must be careful to only call GDB-specific functions in the GDB
2458 Some care must be taken when writing Guile code to run in GDB. Two
2459 things are worth noting in particular:
2461 * GDB installs handlers for 'SIGCHLD' and 'SIGINT'. Guile code must
2462 not override these, or even change the options using 'sigaction'.
2463 If your program changes the handling of these signals, GDB will
2464 most likely stop working correctly. Note that it is unfortunately
2465 common for GUI toolkits to install a 'SIGCHLD' handler.
2467 * GDB takes care to mark its internal file descriptors as
2468 close-on-exec. However, this cannot be done in a thread-safe way
2469 on all platforms. Your Guile programs should be aware of this and
2470 should both create new file descriptors with the close-on-exec flag
2471 set and arrange to close unneeded file descriptors before starting
2474 GDB introduces a new Guile module, named 'gdb'. All methods and
2475 classes added by GDB are placed in this module. GDB does not
2476 automatically 'import' the 'gdb' module, scripts must do this
2477 themselves. There are various options for how to import a module, so
2478 GDB leaves the choice of how the 'gdb' module is imported to the user.
2479 To simplify interactive use, it is recommended to add one of the
2480 following to your ~/.gdbinit.
2482 guile (use-modules (gdb))
2484 guile (use-modules ((gdb) #:renamer (symbol-prefix-proc 'gdb:)))
2486 Which one to choose depends on your preference. The second one adds
2487 'gdb:' as a prefix to all module functions and variables.
2489 The rest of this manual assumes the 'gdb' module has been imported
2490 without any prefix. See the Guile documentation for 'use-modules' for
2491 more information (*note (guile)Using Guile Modules::).
2495 (gdb) guile (value-type (make-value 1))
2496 ERROR: Unbound variable: value-type
2497 Error while executing Scheme code.
2498 (gdb) guile (use-modules (gdb))
2499 (gdb) guile (value-type (make-value 1))
2503 The '(gdb)' module provides these basic Guile functions.
2505 -- Scheme Procedure: execute command [#:from-tty boolean]
2506 [#:to-string boolean]
2507 Evaluate COMMAND, a string, as a GDB CLI command. If a GDB
2508 exception happens while COMMAND runs, it is translated as described
2509 in *note Guile Exception Handling: Guile Exception Handling.
2511 FROM-TTY specifies whether GDB ought to consider this command as
2512 having originated from the user invoking it interactively. It must
2513 be a boolean value. If omitted, it defaults to '#f'.
2515 By default, any output produced by COMMAND is sent to GDB's
2516 standard output (and to the log output if logging is turned on).
2517 If the TO-STRING parameter is '#t', then output will be collected
2518 by 'execute' and returned as a string. The default is '#f', in
2519 which case the return value is unspecified. If TO-STRING is '#t',
2520 the GDB virtual terminal will be temporarily set to unlimited width
2521 and height, and its pagination will be disabled; *note Screen
2524 -- Scheme Procedure: history-ref number
2525 Return a value from GDB's value history (*note Value History::).
2526 The NUMBER argument indicates which history element to return. If
2527 NUMBER is negative, then GDB will take its absolute value and count
2528 backward from the last element (i.e., the most recent element) to
2529 find the value to return. If NUMBER is zero, then GDB will return
2530 the most recent element. If the element specified by NUMBER
2531 doesn't exist in the value history, a 'gdb:error' exception will be
2534 If no exception is raised, the return value is always an instance
2535 of '<gdb:value>' (*note Values From Inferior In Guile::).
2537 _Note:_ GDB's value history is independent of Guile's. '$1' in
2538 GDB's value history contains the result of evaluating an expression
2539 from GDB's command line and '$1' from Guile's history contains the
2540 result of evaluating an expression from Guile's command line.
2542 -- Scheme Procedure: history-append! value
2543 Append VALUE, an instance of '<gdb:value>', to GDB's value history.
2544 Return its index in the history.
2546 Putting into history values returned by Guile extensions will allow
2547 the user convenient access to those values via CLI history
2550 -- Scheme Procedure: parse-and-eval expression
2551 Parse EXPRESSION as an expression in the current language, evaluate
2552 it, and return the result as a '<gdb:value>'. The EXPRESSION must
2555 This function can be useful when implementing a new command (*note
2556 Commands In Guile::), as it provides a way to parse the command's
2557 arguments as an expression. It is also is useful when computing
2558 values. For example, it is the only way to get the value of a
2559 convenience variable (*note Convenience Vars::) as a '<gdb:value>'.
2562 File: gdb.info, Node: Guile Configuration, Next: GDB Scheme Data Types, Prev: Basic Guile, Up: Guile API
2564 23.4.3.2 Guile Configuration
2565 ............................
2567 GDB provides these Scheme functions to access various configuration
2570 -- Scheme Procedure: data-directory
2571 Return a string containing GDB's data directory. This directory
2572 contains GDB's ancillary files.
2574 -- Scheme Procedure: guile-data-directory
2575 Return a string containing GDB's Guile data directory. This
2576 directory contains the Guile modules provided by GDB.
2578 -- Scheme Procedure: gdb-version
2579 Return a string containing the GDB version.
2581 -- Scheme Procedure: host-config
2582 Return a string containing the host configuration. This is the
2583 string passed to '--host' when GDB was configured.
2585 -- Scheme Procedure: target-config
2586 Return a string containing the target configuration. This is the
2587 string passed to '--target' when GDB was configured.
2590 File: gdb.info, Node: GDB Scheme Data Types, Next: Guile Exception Handling, Prev: Guile Configuration, Up: Guile API
2592 23.4.3.3 GDB Scheme Data Types
2593 ..............................
2595 The values exposed by GDB to Guile are known as "GDB objects". There
2596 are several kinds of GDB object, and each is disjoint from all other
2597 types known to Guile.
2599 -- Scheme Procedure: gdb-object-kind object
2600 Return the kind of the GDB object, e.g., '<gdb:breakpoint>', as a
2603 GDB defines the following object types:
2606 *Note Architectures In Guile::.
2609 *Note Blocks In Guile::.
2611 '<gdb:block-symbols-iterator>'
2612 *Note Blocks In Guile::.
2615 *Note Breakpoints In Guile::.
2618 *Note Commands In Guile::.
2621 *Note Guile Exception Handling::.
2624 *Note Frames In Guile::.
2627 *Note Iterators In Guile::.
2630 *Note Lazy Strings In Guile::.
2633 *Note Objfiles In Guile::.
2636 *Note Parameters In Guile::.
2638 '<gdb:pretty-printer>'
2639 *Note Guile Pretty Printing API::.
2641 '<gdb:pretty-printer-worker>'
2642 *Note Guile Pretty Printing API::.
2645 *Note Progspaces In Guile::.
2648 *Note Symbols In Guile::.
2651 *Note Symbol Tables In Guile::.
2654 *Note Symbol Tables In Guile::.
2657 *Note Types In Guile::.
2660 *Note Types In Guile::.
2663 *Note Values From Inferior In Guile::.
2665 The following GDB objects are managed internally so that the Scheme
2666 function 'eq?' may be applied to them.
2679 File: gdb.info, Node: Guile Exception Handling, Next: Values From Inferior In Guile, Prev: GDB Scheme Data Types, Up: Guile API
2681 23.4.3.4 Guile Exception Handling
2682 .................................
2684 When executing the 'guile' command, Guile exceptions uncaught within the
2685 Guile code are translated to calls to the GDB error-reporting mechanism.
2686 If the command that called 'guile' does not handle the error, GDB will
2687 terminate it and report the error according to the setting of the 'guile
2688 print-stack' parameter.
2690 The 'guile print-stack' parameter has three settings:
2696 An error message is printed containing the Guile exception name,
2697 the associated value, and the Guile call stack backtrace at the
2698 point where the exception was raised. Example:
2700 (gdb) guile (display foo)
2701 ERROR: In procedure memoize-variable-access!:
2702 ERROR: Unbound variable: foo
2703 Error while executing Scheme code.
2706 In addition to an error message a full backtrace is printed.
2708 (gdb) set guile print-stack full
2709 (gdb) guile (display foo)
2711 In ice-9/boot-9.scm:
2712 157: 10 [catch #t #<catch-closure 2c76e20> ...]
2714 ?: 9 [apply-smob/1 #<catch-closure 2c76e20>]
2715 In ice-9/boot-9.scm:
2716 157: 8 [catch #t #<catch-closure 2c76d20> ...]
2718 ?: 7 [apply-smob/1 #<catch-closure 2c76d20>]
2719 ?: 6 [call-with-input-string "(display foo)" ...]
2720 In ice-9/boot-9.scm:
2721 2320: 5 [save-module-excursion #<procedure 2c2dc30 ... ()>]
2722 In ice-9/eval-string.scm:
2723 44: 4 [read-and-eval #<input: string 27cb410> #:lang ...]
2724 37: 3 [lp (display foo)]
2727 393: 1 [eval #<memoized foo> ()]
2729 ?: 0 [memoize-variable-access! #<memoized foo> ...]
2731 ERROR: In procedure memoize-variable-access!:
2732 ERROR: Unbound variable: foo
2733 Error while executing Scheme code.
2735 GDB errors that happen in GDB commands invoked by Guile code are
2736 converted to Guile exceptions. The type of the Guile exception depends
2739 Guile procedures provided by GDB can throw the standard Guile
2740 exceptions like 'wrong-type-arg' and 'out-of-range'.
2742 User interrupt (via 'C-c' or by typing 'q' at a pagination prompt) is
2743 translated to a Guile 'signal' exception with value 'SIGINT'.
2745 GDB Guile procedures can also throw these exceptions:
2748 This exception is a catch-all for errors generated from within GDB.
2750 'gdb:invalid-object'
2751 This exception is thrown when accessing Guile objects that wrap
2752 underlying GDB objects have become invalid. For example, a
2753 '<gdb:breakpoint>' object becomes invalid if the user deletes it
2754 from the command line. The object still exists in Guile, but the
2755 object it represents is gone. Further operations on this
2756 breakpoint will throw this exception.
2759 This exception is thrown when an operation tried to access invalid
2760 memory in the inferior.
2763 This exception is thrown when a Guile pretty-printer passes a bad
2766 The following exception-related procedures are provided by the
2769 -- Scheme Procedure: make-exception key args
2770 Return a '<gdb:exception>' object given by its KEY and ARGS, which
2771 are the standard Guile parameters of an exception. See the Guile
2772 documentation for more information (*note (guile)Exceptions::).
2774 -- Scheme Procedure: exception? object
2775 Return '#t' if OBJECT is a '<gdb:exception>' object. Otherwise
2778 -- Scheme Procedure: exception-key exception
2779 Return the ARGS field of a '<gdb:exception>' object.
2781 -- Scheme Procedure: exception-args exception
2782 Return the ARGS field of a '<gdb:exception>' object.
2785 File: gdb.info, Node: Values From Inferior In Guile, Next: Arithmetic In Guile, Prev: Guile Exception Handling, Up: Guile API
2787 23.4.3.5 Values From Inferior In Guile
2788 ......................................
2790 GDB provides values it obtains from the inferior program in an object of
2791 type '<gdb:value>'. GDB uses this object for its internal bookkeeping
2792 of the inferior's values, and for fetching values when necessary.
2794 GDB does not memoize '<gdb:value>' objects. 'make-value' always
2795 returns a fresh object.
2797 (gdb) guile (eq? (make-value 1) (make-value 1))
2799 (gdb) guile (equal? (make-value 1) (make-value 1))
2802 A '<gdb:value>' that represents a function can be executed via
2803 inferior function call with 'value-call'. Any arguments provided to the
2804 call must match the function's prototype, and must be provided in the
2805 order specified by that prototype.
2807 For example, 'some-val' is a '<gdb:value>' instance representing a
2808 function that takes two integers as arguments. To execute this
2809 function, call it like so:
2811 (define result (value-call some-val 10 20))
2813 Any values returned from a function call are '<gdb:value>' objects.
2815 Note: Unlike Python scripting in GDB, inferior values that are simple
2816 scalars cannot be used directly in Scheme expressions that are valid for
2817 the value's data type. For example, '(+ (parse-and-eval "int_variable")
2818 2)' does not work. And inferior values that are structures or instances
2819 of some class cannot be accessed using any special syntax, instead
2820 'value-field' must be used.
2822 The following value-related procedures are provided by the '(gdb)'
2825 -- Scheme Procedure: value? object
2826 Return '#t' if OBJECT is a '<gdb:value>' object. Otherwise return
2829 -- Scheme Procedure: make-value value [#:type type]
2830 Many Scheme values can be converted directly to a '<gdb:value>'
2831 with this procedure. If TYPE is specified, the result is a value
2832 of this type, and if VALUE can't be represented with this type an
2833 exception is thrown. Otherwise the type of the result is
2834 determined from VALUE as described below.
2836 *Note Architectures In Guile::, for a list of the builtin types for
2839 Here's how Scheme values are converted when TYPE argument to
2840 'make-value' is not specified:
2843 A Scheme boolean is converted the boolean type for the current
2847 A Scheme integer is converted to the first of a C 'int',
2848 'unsigned int', 'long', 'unsigned long', 'long long' or
2849 'unsigned long long' type for the current architecture that
2850 can represent the value.
2852 If the Scheme integer cannot be represented as a target
2853 integer an 'out-of-range' exception is thrown.
2856 A Scheme real is converted to the C 'double' type for the
2857 current architecture.
2860 A Scheme string is converted to a string in the current target
2861 language using the current target encoding. Characters that
2862 cannot be represented in the current target encoding are
2863 replaced with the corresponding escape sequence. This is
2864 Guile's 'SCM_FAILED_CONVERSION_ESCAPE_SEQUENCE' conversion
2865 strategy (*note (guile)Strings::).
2867 Passing TYPE is not supported in this case, if it is provided
2868 a 'wrong-type-arg' exception is thrown.
2871 If VALUE is a '<gdb:lazy-string>' object (*note Lazy Strings
2872 In Guile::), then the 'lazy-string->value' procedure is
2873 called, and its result is used.
2875 Passing TYPE is not supported in this case, if it is provided
2876 a 'wrong-type-arg' exception is thrown.
2879 If VALUE is a Scheme bytevector and TYPE is provided, VALUE
2880 must be the same size, in bytes, of values of type TYPE, and
2881 the result is essentially created by using 'memcpy'.
2883 If VALUE is a Scheme bytevector and TYPE is not provided, the
2884 result is an array of type 'uint8' of the same length.
2886 -- Scheme Procedure: value-optimized-out? value
2887 Return '#t' if the compiler optimized out VALUE, thus it is not
2888 available for fetching from the inferior. Otherwise return '#f'.
2890 -- Scheme Procedure: value-address value
2891 If VALUE is addressable, returns a '<gdb:value>' object
2892 representing the address. Otherwise, '#f' is returned.
2894 -- Scheme Procedure: value-type value
2895 Return the type of VALUE as a '<gdb:type>' object (*note Types In
2898 -- Scheme Procedure: value-dynamic-type value
2899 Return the dynamic type of VALUE. This uses C++ run-time type
2900 information (RTTI) to determine the dynamic type of the value. If
2901 the value is of class type, it will return the class in which the
2902 value is embedded, if any. If the value is of pointer or reference
2903 to a class type, it will compute the dynamic type of the referenced
2904 object, and return a pointer or reference to that type,
2905 respectively. In all other cases, it will return the value's
2908 Note that this feature will only work when debugging a C++ program
2909 that includes RTTI for the object in question. Otherwise, it will
2910 just return the static type of the value as in 'ptype foo'. *Note
2913 -- Scheme Procedure: value-cast value type
2914 Return a new instance of '<gdb:value>' that is the result of
2915 casting VALUE to the type described by TYPE, which must be a
2916 '<gdb:type>' object. If the cast cannot be performed for some
2917 reason, this method throws an exception.
2919 -- Scheme Procedure: value-dynamic-cast value type
2920 Like 'value-cast', but works as if the C++ 'dynamic_cast' operator
2921 were used. Consult a C++ reference for details.
2923 -- Scheme Procedure: value-reinterpret-cast value type
2924 Like 'value-cast', but works as if the C++ 'reinterpret_cast'
2925 operator were used. Consult a C++ reference for details.
2927 -- Scheme Procedure: value-dereference value
2928 For pointer data types, this method returns a new '<gdb:value>'
2929 object whose contents is the object pointed to by VALUE. For
2930 example, if 'foo' is a C pointer to an 'int', declared in your C
2935 then you can use the corresponding '<gdb:value>' to access what
2936 'foo' points to like this:
2938 (define bar (value-dereference foo))
2940 The result 'bar' will be a '<gdb:value>' object holding the value
2941 pointed to by 'foo'.
2943 A similar function 'value-referenced-value' exists which also
2944 returns '<gdb:value>' objects corresponding to the values pointed
2945 to by pointer values (and additionally, values referenced by
2946 reference values). However, the behavior of 'value-dereference'
2947 differs from 'value-referenced-value' by the fact that the behavior
2948 of 'value-dereference' is identical to applying the C unary
2949 operator '*' on a given value. For example, consider a reference
2950 to a pointer 'ptrref', declared in your C++ program as
2952 typedef int *intptr;
2956 intptr &ptrref = ptr;
2958 Though 'ptrref' is a reference value, one can apply the method
2959 'value-dereference' to the '<gdb:value>' object corresponding to it
2960 and obtain a '<gdb:value>' which is identical to that corresponding
2961 to 'val'. However, if you apply the method
2962 'value-referenced-value', the result would be a '<gdb:value>'
2963 object identical to that corresponding to 'ptr'.
2965 (define scm-ptrref (parse-and-eval "ptrref"))
2966 (define scm-val (value-dereference scm-ptrref))
2967 (define scm-ptr (value-referenced-value scm-ptrref))
2969 The '<gdb:value>' object 'scm-val' is identical to that
2970 corresponding to 'val', and 'scm-ptr' is identical to that
2971 corresponding to 'ptr'. In general, 'value-dereference' can be
2972 applied whenever the C unary operator '*' can be applied to the
2973 corresponding C value. For those cases where applying both
2974 'value-dereference' and 'value-referenced-value' is allowed, the
2975 results obtained need not be identical (as we have seen in the
2976 above example). The results are however identical when applied on
2977 '<gdb:value>' objects corresponding to pointers ('<gdb:value>'
2978 objects with type code 'TYPE_CODE_PTR') in a C/C++ program.
2980 -- Scheme Procedure: value-referenced-value value
2981 For pointer or reference data types, this method returns a new
2982 '<gdb:value>' object corresponding to the value referenced by the
2983 pointer/reference value. For pointer data types,
2984 'value-dereference' and 'value-referenced-value' produce identical
2985 results. The difference between these methods is that
2986 'value-dereference' cannot get the values referenced by reference
2987 values. For example, consider a reference to an 'int', declared in
2993 then applying 'value-dereference' to the '<gdb:value>' object
2994 corresponding to 'ref' will result in an error, while applying
2995 'value-referenced-value' will result in a '<gdb:value>' object
2996 identical to that corresponding to 'val'.
2998 (define scm-ref (parse-and-eval "ref"))
2999 (define err-ref (value-dereference scm-ref)) ;; error
3000 (define scm-val (value-referenced-value scm-ref)) ;; ok
3002 The '<gdb:value>' object 'scm-val' is identical to that
3003 corresponding to 'val'.
3005 -- Scheme Procedure: value-reference-value value
3006 Return a new '<gdb:value>' object which is a reference to the value
3007 encapsulated by '<gdb:value>' object VALUE.
3009 -- Scheme Procedure: value-rvalue-reference-value value
3010 Return a new '<gdb:value>' object which is an rvalue reference to
3011 the value encapsulated by '<gdb:value>' object VALUE.
3013 -- Scheme Procedure: value-const-value value
3014 Return a new '<gdb:value>' object which is a 'const' version of
3015 '<gdb:value>' object VALUE.
3017 -- Scheme Procedure: value-field value field-name
3018 Return field FIELD-NAME from '<gdb:value>' object VALUE.
3020 -- Scheme Procedure: value-subscript value index
3021 Return the value of array VALUE at index INDEX. The VALUE argument
3022 must be a subscriptable '<gdb:value>' object.
3024 -- Scheme Procedure: value-call value arg-list
3025 Perform an inferior function call, taking VALUE as a pointer to the
3026 function to call. Each element of list ARG-LIST must be a
3027 <gdb:value> object or an object that can be converted to a value.
3028 The result is the value returned by the function.
3030 -- Scheme Procedure: value->bool value
3031 Return the Scheme boolean representing '<gdb:value>' VALUE. The
3032 value must be "integer like". Pointers are ok.
3034 -- Scheme Procedure: value->integer
3035 Return the Scheme integer representing '<gdb:value>' VALUE. The
3036 value must be "integer like". Pointers are ok.
3038 -- Scheme Procedure: value->real
3039 Return the Scheme real number representing '<gdb:value>' VALUE.
3040 The value must be a number.
3042 -- Scheme Procedure: value->bytevector
3043 Return a Scheme bytevector with the raw contents of '<gdb:value>'
3044 VALUE. No transformation, endian or otherwise, is performed.
3046 -- Scheme Procedure: value->string value [#:encoding encoding]
3047 [#:errors errors] [#:length length]
3048 If VALUE> represents a string, then this method converts the
3049 contents to a Guile string. Otherwise, this method will throw an
3052 Values are interpreted as strings according to the rules of the
3053 current language. If the optional length argument is given, the
3054 string will be converted to that length, and will include any
3055 embedded zeroes that the string may contain. Otherwise, for
3056 languages where the string is zero-terminated, the entire string
3059 For example, in C-like languages, a value is a string if it is a
3060 pointer to or an array of characters or ints of type 'wchar_t',
3061 'char16_t', or 'char32_t'.
3063 If the optional ENCODING argument is given, it must be a string
3064 naming the encoding of the string in the '<gdb:value>', such as
3065 '"ascii"', '"iso-8859-6"' or '"utf-8"'. It accepts the same
3066 encodings as the corresponding argument to Guile's
3067 'scm_from_stringn' function, and the Guile codec machinery will be
3068 used to convert the string. If ENCODING is not given, or if
3069 ENCODING is the empty string, then either the 'target-charset'
3070 (*note Character Sets::) will be used, or a language-specific
3071 encoding will be used, if the current language is able to supply
3074 The optional ERRORS argument is one of '#f', 'error' or
3075 'substitute'. 'error' and 'substitute' must be symbols. If ERRORS
3076 is not specified, or if its value is '#f', then the default
3077 conversion strategy is used, which is set with the Scheme function
3078 'set-port-conversion-strategy!'. If the value is ''error' then an
3079 exception is thrown if there is any conversion error. If the value
3080 is ''substitute' then any conversion error is replaced with
3081 question marks. *Note (guile)Strings::.
3083 If the optional LENGTH argument is given, the string will be
3084 fetched and converted to the given length. The length must be a
3085 Scheme integer and not a '<gdb:value>' integer.
3087 -- Scheme Procedure: value->lazy-string value [#:encoding encoding]
3089 If this '<gdb:value>' represents a string, then this method
3090 converts VALUE to a '<gdb:lazy-string' (*note Lazy Strings In
3091 Guile::). Otherwise, this method will throw an exception.
3093 If the optional ENCODING argument is given, it must be a string
3094 naming the encoding of the '<gdb:lazy-string'. Some examples are:
3095 '"ascii"', '"iso-8859-6"' or '"utf-8"'. If the ENCODING argument
3096 is an encoding that GDB does not recognize, GDB will raise an
3099 When a lazy string is printed, the GDB encoding machinery is used
3100 to convert the string during printing. If the optional ENCODING
3101 argument is not provided, or is an empty string, GDB will
3102 automatically select the encoding most suitable for the string
3103 type. For further information on encoding in GDB please see *note
3106 If the optional LENGTH argument is given, the string will be
3107 fetched and encoded to the length of characters specified. If the
3108 LENGTH argument is not provided, the string will be fetched and
3109 encoded until a null of appropriate width is found. The length
3110 must be a Scheme integer and not a '<gdb:value>' integer.
3112 -- Scheme Procedure: value-lazy? value
3113 Return '#t' if VALUE has not yet been fetched from the inferior.
3114 Otherwise return '#f'. GDB does not fetch values until necessary,
3115 for efficiency. For example:
3117 (define myval (parse-and-eval "somevar"))
3119 The value of 'somevar' is not fetched at this time. It will be
3120 fetched when the value is needed, or when the 'fetch-lazy'
3121 procedure is invoked.
3123 -- Scheme Procedure: make-lazy-value type address
3124 Return a '<gdb:value>' that will be lazily fetched from the target.
3125 The object of type '<gdb:type>' whose value to fetch is specified
3126 by its TYPE and its target memory ADDRESS, which is a Scheme
3129 -- Scheme Procedure: value-fetch-lazy! value
3130 If VALUE is a lazy value ('(value-lazy? value)' is '#t'), then the
3131 value is fetched from the inferior. Any errors that occur in the
3132 process will produce a Guile exception.
3134 If VALUE is not a lazy value, this method has no effect.
3136 The result of this function is unspecified.
3138 -- Scheme Procedure: value-print value
3139 Return the string representation (print form) of '<gdb:value>'
3143 File: gdb.info, Node: Arithmetic In Guile, Next: Types In Guile, Prev: Values From Inferior In Guile, Up: Guile API
3145 23.4.3.6 Arithmetic In Guile
3146 ............................
3148 The '(gdb)' module provides several functions for performing arithmetic
3149 on '<gdb:value>' objects. The arithmetic is performed as if it were
3150 done by the target, and therefore has target semantics which are not
3151 necessarily those of Scheme. For example operations work with a fixed
3152 precision, not the arbitrary precision of Scheme.
3154 Wherever a function takes an integer or pointer as an operand, GDB
3155 will convert appropriate Scheme values to perform the operation.
3157 -- Scheme Procedure: value-add a b
3159 -- Scheme Procedure: value-sub a b
3161 -- Scheme Procedure: value-mul a b
3163 -- Scheme Procedure: value-div a b
3165 -- Scheme Procedure: value-rem a b
3167 -- Scheme Procedure: value-mod a b
3169 -- Scheme Procedure: value-pow a b
3171 -- Scheme Procedure: value-not a
3173 -- Scheme Procedure: value-neg a
3175 -- Scheme Procedure: value-pos a
3177 -- Scheme Procedure: value-abs a
3179 -- Scheme Procedure: value-lsh a b
3181 -- Scheme Procedure: value-rsh a b
3183 -- Scheme Procedure: value-min a b
3185 -- Scheme Procedure: value-max a b
3187 -- Scheme Procedure: value-lognot a
3189 -- Scheme Procedure: value-logand a b
3191 -- Scheme Procedure: value-logior a b
3193 -- Scheme Procedure: value-logxor a b
3195 -- Scheme Procedure: value=? a b
3197 -- Scheme Procedure: value<? a b
3199 -- Scheme Procedure: value<=? a b
3201 -- Scheme Procedure: value>? a b
3203 -- Scheme Procedure: value>=? a b
3205 Scheme does not provide a 'not-equal' function, and thus Guile
3206 support in GDB does not either.
3209 File: gdb.info, Node: Types In Guile, Next: Guile Pretty Printing API, Prev: Arithmetic In Guile, Up: Guile API
3211 23.4.3.7 Types In Guile
3212 .......................
3214 GDB represents types from the inferior in objects of type '<gdb:type>'.
3216 The following type-related procedures are provided by the '(gdb)'
3219 -- Scheme Procedure: type? object
3220 Return '#t' if OBJECT is an object of type '<gdb:type>'. Otherwise
3223 -- Scheme Procedure: lookup-type name [#:block block]
3224 This function looks up a type by its NAME, which must be a string.
3226 If BLOCK is given, it is an object of type '<gdb:block>', and NAME
3227 is looked up in that scope. Otherwise, it is searched for
3230 Ordinarily, this function will return an instance of '<gdb:type>'.
3231 If the named type cannot be found, it will throw an exception.
3233 -- Scheme Procedure: type-code type
3234 Return the type code of TYPE. The type code will be one of the
3235 'TYPE_CODE_' constants defined below.
3237 -- Scheme Procedure: type-tag type
3238 Return the tag name of TYPE. The tag name is the name after
3239 'struct', 'union', or 'enum' in C and C++; not all languages have
3240 this concept. If this type has no tag name, then '#f' is returned.
3242 -- Scheme Procedure: type-name type
3243 Return the name of TYPE. If this type has no name, then '#f' is
3246 -- Scheme Procedure: type-print-name type
3247 Return the print name of TYPE. This returns something even for
3248 anonymous types. For example, for an anonymous C struct '"struct
3249 {...}"' is returned.
3251 -- Scheme Procedure: type-sizeof type
3252 Return the size of this type, in target 'char' units. Usually, a
3253 target's 'char' type will be an 8-bit byte. However, on some
3254 unusual platforms, this type may have a different size.
3256 -- Scheme Procedure: type-strip-typedefs type
3257 Return a new '<gdb:type>' that represents the real type of TYPE,
3258 after removing all layers of typedefs.
3260 -- Scheme Procedure: type-array type n1 [n2]
3261 Return a new '<gdb:type>' object which represents an array of this
3262 type. If one argument is given, it is the inclusive upper bound of
3263 the array; in this case the lower bound is zero. If two arguments
3264 are given, the first argument is the lower bound of the array, and
3265 the second argument is the upper bound of the array. An array's
3266 length must not be negative, but the bounds can be.
3268 -- Scheme Procedure: type-vector type n1 [n2]
3269 Return a new '<gdb:type>' object which represents a vector of this
3270 type. If one argument is given, it is the inclusive upper bound of
3271 the vector; in this case the lower bound is zero. If two arguments
3272 are given, the first argument is the lower bound of the vector, and
3273 the second argument is the upper bound of the vector. A vector's
3274 length must not be negative, but the bounds can be.
3276 The difference between an 'array' and a 'vector' is that arrays
3277 behave like in C: when used in expressions they decay to a pointer
3278 to the first element whereas vectors are treated as first class
3281 -- Scheme Procedure: type-pointer type
3282 Return a new '<gdb:type>' object which represents a pointer to
3285 -- Scheme Procedure: type-range type
3286 Return a list of two elements: the low bound and high bound of
3287 TYPE. If TYPE does not have a range, an exception is thrown.
3289 -- Scheme Procedure: type-reference type
3290 Return a new '<gdb:type>' object which represents a reference to
3293 -- Scheme Procedure: type-target type
3294 Return a new '<gdb:type>' object which represents the target type
3297 For a pointer type, the target type is the type of the pointed-to
3298 object. For an array type (meaning C-like arrays), the target type
3299 is the type of the elements of the array. For a function or method
3300 type, the target type is the type of the return value. For a
3301 complex type, the target type is the type of the elements. For a
3302 typedef, the target type is the aliased type.
3304 If the type does not have a target, this method will throw an
3307 -- Scheme Procedure: type-const type
3308 Return a new '<gdb:type>' object which represents a
3309 'const'-qualified variant of TYPE.
3311 -- Scheme Procedure: type-volatile type
3312 Return a new '<gdb:type>' object which represents a
3313 'volatile'-qualified variant of TYPE.
3315 -- Scheme Procedure: type-unqualified type
3316 Return a new '<gdb:type>' object which represents an unqualified
3317 variant of TYPE. That is, the result is neither 'const' nor
3320 -- Scheme Procedure: type-num-fields
3321 Return the number of fields of '<gdb:type>' TYPE.
3323 -- Scheme Procedure: type-fields type
3324 Return the fields of TYPE as a list. For structure and union
3325 types, 'fields' has the usual meaning. Range types have two
3326 fields, the minimum and maximum values. Enum types have one field
3327 per enum constant. Function and method types have one field per
3328 parameter. The base types of C++ classes are also represented as
3329 fields. If the type has no fields, or does not fit into one of
3330 these categories, an empty list will be returned. *Note Fields of
3333 -- Scheme Procedure: make-field-iterator type
3334 Return the fields of TYPE as a <gdb:iterator> object. *Note
3335 Iterators In Guile::.
3337 -- Scheme Procedure: type-field type field-name
3338 Return field named FIELD-NAME in TYPE. The result is an object of
3339 type '<gdb:field>'. *Note Fields of a type in Guile::. If the
3340 type does not have fields, or FIELD-NAME is not a field of TYPE, an
3341 exception is thrown.
3343 For example, if 'some-type' is a '<gdb:type>' instance holding a
3344 structure type, you can access its 'foo' field with:
3346 (define bar (type-field some-type "foo"))
3348 'bar' will be a '<gdb:field>' object.
3350 -- Scheme Procedure: type-has-field? type name
3351 Return '#t' if '<gdb:type>' TYPE has field named NAME. Otherwise
3354 Each type has a code, which indicates what category this type falls
3355 into. The available type categories are represented by constants
3356 defined in the '(gdb)' module:
3359 The type is a pointer.
3362 The type is an array.
3365 The type is a structure.
3368 The type is a union.
3371 The type is an enum.
3374 A bit flags type, used for things such as status registers.
3377 The type is a function.
3380 The type is an integer type.
3383 A floating point type.
3386 The special type 'void'.
3392 A range type, that is, an integer type with bounds.
3395 A string type. Note that this is only used for certain languages
3396 with language-defined string types; C strings are not represented
3399 'TYPE_CODE_BITSTRING'
3400 A string of bits. It is deprecated.
3403 An unknown or erroneous type.
3406 A method type, as found in C++.
3408 'TYPE_CODE_METHODPTR'
3409 A pointer-to-member-function.
3411 'TYPE_CODE_MEMBERPTR'
3412 A pointer-to-member.
3417 'TYPE_CODE_RVALUE_REF'
3418 A C++11 rvalue reference type.
3427 A complex float type.
3430 A typedef to some other type.
3432 'TYPE_CODE_NAMESPACE'
3435 'TYPE_CODE_DECFLOAT'
3436 A decimal floating point type.
3438 'TYPE_CODE_INTERNAL_FUNCTION'
3439 A function internal to GDB. This is the type used to represent
3440 convenience functions (*note Convenience Funs::).
3442 'gdb.TYPE_CODE_XMETHOD'
3443 A method internal to GDB. This is the type used to represent
3444 xmethods (*note Writing an Xmethod::).
3446 'gdb.TYPE_CODE_FIXED_POINT'
3447 A fixed-point number.
3449 'gdb.TYPE_CODE_NAMESPACE'
3452 Further support for types is provided in the '(gdb types)' Guile
3453 module (*note Guile Types Module::).
3455 Each field is represented as an object of type '<gdb:field>'.
3457 The following field-related procedures are provided by the '(gdb)'
3460 -- Scheme Procedure: field? object
3461 Return '#t' if OBJECT is an object of type '<gdb:field>'.
3462 Otherwise return '#f'.
3464 -- Scheme Procedure: field-name field
3465 Return the name of the field, or '#f' for anonymous fields.
3467 -- Scheme Procedure: field-type field
3468 Return the type of the field. This is usually an instance of
3469 '<gdb:type>', but it can be '#f' in some situations.
3471 -- Scheme Procedure: field-enumval field
3472 Return the enum value represented by '<gdb:field>' FIELD.
3474 -- Scheme Procedure: field-bitpos field
3475 Return the bit position of '<gdb:field>' FIELD. This attribute is
3476 not available for 'static' fields (as in C++).
3478 -- Scheme Procedure: field-bitsize field
3479 If the field is packed, or is a bitfield, return the size of
3480 '<gdb:field>' FIELD in bits. Otherwise, zero is returned; in which
3481 case the field's size is given by its type.
3483 -- Scheme Procedure: field-artificial? field
3484 Return '#t' if the field is artificial, usually meaning that it was
3485 provided by the compiler and not the user. Otherwise return '#f'.
3487 -- Scheme Procedure: field-base-class? field
3488 Return '#t' if the field represents a base class of a C++
3489 structure. Otherwise return '#f'.
3492 File: gdb.info, Node: Guile Pretty Printing API, Next: Selecting Guile Pretty-Printers, Prev: Types In Guile, Up: Guile API
3494 23.4.3.8 Guile Pretty Printing API
3495 ..................................
3497 An example output is provided (*note Pretty Printing::).
3499 A pretty-printer is represented by an object of type
3500 <gdb:pretty-printer>. Pretty-printer objects are created with
3501 'make-pretty-printer'.
3503 The following pretty-printer-related procedures are provided by the
3506 -- Scheme Procedure: make-pretty-printer name lookup-function
3507 Return a '<gdb:pretty-printer>' object named NAME.
3509 LOOKUP-FUNCTION is a function of one parameter: the value to be
3510 printed. If the value is handled by this pretty-printer, then
3511 LOOKUP-FUNCTION returns an object of type
3512 <gdb:pretty-printer-worker> to perform the actual pretty-printing.
3513 Otherwise LOOKUP-FUNCTION returns '#f'.
3515 -- Scheme Procedure: pretty-printer? object
3516 Return '#t' if OBJECT is a '<gdb:pretty-printer>' object.
3517 Otherwise return '#f'.
3519 -- Scheme Procedure: pretty-printer-enabled? pretty-printer
3520 Return '#t' if PRETTY-PRINTER is enabled. Otherwise return '#f'.
3522 -- Scheme Procedure: set-pretty-printer-enabled! pretty-printer flag
3523 Set the enabled flag of PRETTY-PRINTER to FLAG. The value returned
3526 -- Scheme Procedure: pretty-printers
3527 Return the list of global pretty-printers.
3529 -- Scheme Procedure: set-pretty-printers! pretty-printers
3530 Set the list of global pretty-printers to PRETTY-PRINTERS. The
3531 value returned is unspecified.
3533 -- Scheme Procedure: make-pretty-printer-worker display-hint to-string
3535 Return an object of type '<gdb:pretty-printer-worker>'.
3537 This function takes three parameters:
3540 DISPLAY-HINT provides a hint to GDB or GDB front end via MI to
3541 change the formatting of the value being printed. The value
3542 must be a string or '#f' (meaning there is no hint). Several
3543 values for DISPLAY-HINT are predefined by GDB:
3546 Indicate that the object being printed is "array-like".
3547 The CLI uses this to respect parameters such as 'set
3548 print elements' and 'set print array'.
3551 Indicate that the object being printed is "map-like", and
3552 that the children of this value can be assumed to
3553 alternate between keys and values.
3556 Indicate that the object being printed is "string-like".
3557 If the printer's 'to-string' function returns a Guile
3558 string of some kind, then GDB will call its internal
3559 language-specific string-printing function to format the
3560 string. For the CLI this means adding quotation marks,
3561 possibly escaping some characters, respecting 'set print
3562 elements', and the like.
3565 TO-STRING is either a function of one parameter, the
3566 '<gdb:pretty-printer-worker>' object, or '#f'.
3568 When printing from the CLI, if the 'to-string' method exists,
3569 then GDB will prepend its result to the values returned by
3570 'children'. Exactly how this formatting is done is dependent
3571 on the display hint, and may change as more hints are added.
3572 Also, depending on the print settings (*note Print
3573 Settings::), the CLI may print just the result of 'to-string'
3574 in a stack trace, omitting the result of 'children'.
3576 If this method returns a string, it is printed verbatim.
3578 Otherwise, if this method returns an instance of
3579 '<gdb:value>', then GDB prints this value. This may result in
3580 a call to another pretty-printer.
3582 If instead the method returns a Guile value which is
3583 convertible to a '<gdb:value>', then GDB performs the
3584 conversion and prints the resulting value. Again, this may
3585 result in a call to another pretty-printer. Guile scalars
3586 (integers, floats, and booleans) and strings are convertible
3587 to '<gdb:value>'; other types are not.
3589 Finally, if this method returns '#f' then no further
3590 operations are peformed in this method and nothing is printed.
3592 If the result is not one of these types, an exception is
3595 TO-STRING may also be '#f' in which case it is left to
3596 CHILDREN to print the value.
3599 CHILDREN is either a function of one parameter, the
3600 '<gdb:pretty-printer-worker>' object, or '#f'.
3602 GDB will call this function on a pretty-printer to compute the
3603 children of the pretty-printer's value.
3605 This function must return a <gdb:iterator> object. Each item
3606 returned by the iterator must be a tuple holding two elements.
3607 The first element is the "name" of the child; the second
3608 element is the child's value. The value can be any Guile
3609 object which is convertible to a GDB value.
3611 If CHILDREN is '#f', GDB will act as though the value has no
3614 Children may be hidden from display based on the value of 'set
3615 print max-depth' (*note Print Settings::).
3617 GDB provides a function which can be used to look up the default
3618 pretty-printer for a '<gdb:value>':
3620 -- Scheme Procedure: default-visualizer value
3621 This function takes a '<gdb:value>' object as an argument. If a
3622 pretty-printer for this value exists, then it is returned. If no
3623 such printer exists, then this returns '#f'.
3626 File: gdb.info, Node: Selecting Guile Pretty-Printers, Next: Writing a Guile Pretty-Printer, Prev: Guile Pretty Printing API, Up: Guile API
3628 23.4.3.9 Selecting Guile Pretty-Printers
3629 ........................................
3631 There are three sets of pretty-printers that GDB searches:
3633 * Per-objfile list of pretty-printers (*note Objfiles In Guile::).
3634 * Per-progspace list of pretty-printers (*note Progspaces In
3636 * The global list of pretty-printers (*note Guile Pretty Printing
3637 API::). These printers are available when debugging any inferior.
3639 Pretty-printer lookup is done by passing the value to be printed to
3640 the lookup function of each enabled object in turn. Lookup stops when a
3641 lookup function returns a non-'#f' value or when the list is exhausted.
3642 Lookup functions must return either a '<gdb:pretty-printer-worker>'
3643 object or '#f'. Otherwise an exception is thrown.
3645 GDB first checks the result of 'objfile-pretty-printers' of each
3646 '<gdb:objfile>' in the current program space and iteratively calls each
3647 enabled lookup function in the list for that '<gdb:objfile>' until a
3648 non-'#f' object is returned. If no pretty-printer is found in the
3649 objfile lists, GDB then searches the result of
3650 'progspace-pretty-printers' of the current program space, calling each
3651 enabled function until a non-'#f' object is returned. After these lists
3652 have been exhausted, it tries the global pretty-printers list, obtained
3653 with 'pretty-printers', again calling each enabled function until a
3654 non-'#f' object is returned.
3656 The order in which the objfiles are searched is not specified. For a
3657 given list, functions are always invoked from the head of the list, and
3658 iterated over sequentially until the end of the list, or a
3659 '<gdb:pretty-printer-worker>' object is returned.
3661 For various reasons a pretty-printer may not work. For example, the
3662 underlying data structure may have changed and the pretty-printer is out
3665 The consequences of a broken pretty-printer are severe enough that
3666 GDB provides support for enabling and disabling individual printers.
3667 For example, if 'print frame-arguments' is on, a backtrace can become
3668 highly illegible if any argument is printed with a broken printer.
3670 Pretty-printers are enabled and disabled from Scheme by calling
3671 'set-pretty-printer-enabled!'. *Note Guile Pretty Printing API::.
3674 File: gdb.info, Node: Writing a Guile Pretty-Printer, Next: Commands In Guile, Prev: Selecting Guile Pretty-Printers, Up: Guile API
3676 23.4.3.10 Writing a Guile Pretty-Printer
3677 ........................................
3679 A pretty-printer consists of two basic parts: a lookup function to
3680 determine if the type is supported, and the printer itself.
3682 Here is an example showing how a 'std::string' printer might be
3683 written. *Note Guile Pretty Printing API::, for details.
3685 (define (make-my-string-printer value)
3686 "Print a my::string string"
3687 (make-pretty-printer-worker
3690 (value-field value "_data"))
3693 And here is an example showing how a lookup function for the printer
3694 example above might be written.
3696 (define (str-lookup-function pretty-printer value)
3697 (let ((tag (type-tag (value-type value))))
3699 (string-prefix? "std::string<" tag)
3700 (make-my-string-printer value))))
3702 Then to register this printer in the global printer list:
3704 (append-pretty-printer!
3705 (make-pretty-printer "my-string" str-lookup-function))
3707 The example lookup function extracts the value's type, and attempts
3708 to match it to a type that it can pretty-print. If it is a type the
3709 printer can pretty-print, it will return a <gdb:pretty-printer-worker>
3710 object. If not, it returns '#f'.
3712 We recommend that you put your core pretty-printers into a Guile
3713 package. If your pretty-printers are for use with a library, we further
3714 recommend embedding a version number into the package name. This
3715 practice will enable GDB to load multiple versions of your
3716 pretty-printers at the same time, because they will have different
3719 You should write auto-loaded code (*note Guile Auto-loading::) such
3720 that it can be evaluated multiple times without changing its meaning.
3721 An ideal auto-load file will consist solely of 'import's of your printer
3722 modules, followed by a call to a register pretty-printers with the
3725 Taken as a whole, this approach will scale nicely to multiple
3726 inferiors, each potentially using a different library version.
3727 Embedding a version number in the Guile package name will ensure that
3728 GDB is able to load both sets of printers simultaneously. Then, because
3729 the search for pretty-printers is done by objfile, and because your
3730 auto-loaded code took care to register your library's printers with a
3731 specific objfile, GDB will find the correct printers for the specific
3732 version of the library used by each inferior.
3734 To continue the 'my::string' example, this code might appear in
3735 '(my-project my-library v1)':
3738 (define (register-printers objfile)
3739 (append-objfile-pretty-printer!
3740 (make-pretty-printer "my-string" str-lookup-function)))
3742 And then the corresponding contents of the auto-load file would be:
3744 (use-modules (gdb) (my-project my-library v1))
3745 (register-printers (current-objfile))
3747 The previous example illustrates a basic pretty-printer. There are a
3748 few things that can be improved on. The printer only handles one type,
3749 whereas a library typically has several types. One could install a
3750 lookup function for each desired type in the library, but one could also
3751 have a single lookup function recognize several types. The latter is
3752 the conventional way this is handled. If a pretty-printer can handle
3753 multiple data types, then its "subprinters" are the printers for the
3754 individual data types.
3756 The '(gdb printing)' module provides a formal way of solving this
3757 problem (*note Guile Printing Module::). Here is another example that
3758 handles multiple types.
3760 These are the types we are going to pretty-print:
3762 struct foo { int a, b; };
3763 struct bar { struct foo x, y; };
3765 Here are the printers:
3767 (define (make-foo-printer value)
3768 "Print a foo object"
3769 (make-pretty-printer-worker
3772 (format #f "a=<~a> b=<~a>"
3773 (value-field value "a") (value-field value "a")))
3776 (define (make-bar-printer value)
3777 "Print a bar object"
3778 (make-pretty-printer-worker
3781 (format #f "x=<~a> y=<~a>"
3782 (value-field value "x") (value-field value "y")))
3785 This example doesn't need a lookup function, that is handled by the
3786 '(gdb printing)' module. Instead a function is provided to build up the
3787 object that handles the lookup.
3789 (use-modules (gdb printing))
3791 (define (build-pretty-printer)
3792 (let ((pp (make-pretty-printer-collection "my-library")))
3793 (pp-collection-add-tag-printer "foo" make-foo-printer)
3794 (pp-collection-add-tag-printer "bar" make-bar-printer)
3797 And here is the autoload support:
3799 (use-modules (gdb) (my-library))
3800 (append-objfile-pretty-printer! (current-objfile) (build-pretty-printer))
3802 Finally, when this printer is loaded into GDB, here is the
3803 corresponding output of 'info pretty-printer':
3805 (gdb) info pretty-printer
3812 File: gdb.info, Node: Commands In Guile, Next: Parameters In Guile, Prev: Writing a Guile Pretty-Printer, Up: Guile API
3814 23.4.3.11 Commands In Guile
3815 ...........................
3817 You can implement new GDB CLI commands in Guile. A CLI command object
3818 is created with the 'make-command' Guile function, and added to GDB with
3819 the 'register-command!' Guile function. This two-step approach is taken
3820 to separate out the side-effect of adding the command to GDB from
3823 There is no support for multi-line commands, that is commands that
3824 consist of multiple lines and are terminated with 'end'.
3826 -- Scheme Procedure: make-command name [#:invoke invoke]
3827 [#:command-class command-class] [#:completer-class completer]
3828 [#:prefix? prefix] [#:doc doc-string]
3830 The argument NAME is the name of the command. If NAME consists of
3831 multiple words, then the initial words are looked for as prefix
3832 commands. In this case, if one of the prefix commands does not
3833 exist, an exception is raised.
3835 The result is the '<gdb:command>' object representing the command.
3836 The command is not usable until it has been registered with GDB
3837 with 'register-command!'.
3839 The rest of the arguments are optional.
3841 The argument INVOKE is a procedure of three arguments: SELF, ARGS
3842 and FROM-TTY. The argument SELF is the '<gdb:command>' object
3843 representing the command. The argument ARGS is a string
3844 representing the arguments passed to the command, after leading and
3845 trailing whitespace has been stripped. The argument FROM-TTY is a
3846 boolean flag and specifies whether the command should consider
3847 itself to have been originated from the user invoking it
3848 interactively. If this function throws an exception, it is turned
3849 into a GDB 'error' call. Otherwise, the return value is ignored.
3851 The argument COMMAND-CLASS is one of the 'COMMAND_' constants
3852 defined below. This argument tells GDB how to categorize the new
3853 command in the help system. The default is 'COMMAND_NONE'.
3855 The argument COMPLETER is either '#f', one of the 'COMPLETE_'
3856 constants defined below, or a procedure, also defined below. This
3857 argument tells GDB how to perform completion for this command. If
3858 not provided or if the value is '#f', then no completion is
3859 performed on the command.
3861 The argument PREFIX is a boolean flag indicating whether the new
3862 command is a prefix command; sub-commands of this command may be
3865 The argument DOC-STRING is help text for the new command. If no
3866 documentation string is provided, the default value "This command
3867 is not documented." is used.
3869 -- Scheme Procedure: register-command! command
3870 Add COMMAND, a '<gdb:command>' object, to GDB's list of commands.
3871 It is an error to register a command more than once. The result is
3874 -- Scheme Procedure: command? object
3875 Return '#t' if OBJECT is a '<gdb:command>' object. Otherwise
3878 -- Scheme Procedure: dont-repeat
3879 By default, a GDB command is repeated when the user enters a blank
3880 line at the command prompt. A command can suppress this behavior
3881 by invoking the 'dont-repeat' function. This is similar to the
3882 user command 'dont-repeat', see *note dont-repeat: Define.
3884 -- Scheme Procedure: string->argv string
3885 Convert a string to a list of strings split up according to GDB's
3886 argv parsing rules. It is recommended to use this for consistency.
3887 Arguments are separated by spaces and may be quoted. Example:
3889 scheme@(guile-user)> (string->argv "1 2\\ \\\"3 '4 \"5' \"6 '7\"")
3890 $1 = ("1" "2 \"3" "4 \"5" "6 '7")
3892 -- Scheme Procedure: throw-user-error message . args
3893 Throw a 'gdb:user-error' exception. The argument MESSAGE is the
3894 error message as a format string, like the FMT argument to the
3895 'format' Scheme function. *Note (guile)Formatted Output::. The
3896 argument ARGS is a list of the optional arguments of MESSAGE.
3898 This is used when the command detects a user error of some kind,
3899 say a bad command argument.
3901 (gdb) guile (use-modules (gdb))
3903 (register-command! (make-command "test-user-error"
3904 #:command-class COMMAND_OBSCURE
3905 #:invoke (lambda (self arg from-tty)
3906 (throw-user-error "Bad argument ~a" arg))))
3908 (gdb) test-user-error ugh
3909 ERROR: Bad argument ugh
3911 -- completer: self text word
3912 If the COMPLETER option to 'make-command' is a procedure, it takes
3913 three arguments: SELF which is the '<gdb:command>' object, and TEXT
3914 and WORD which are both strings. The argument TEXT holds the
3915 complete command line up to the cursor's location. The argument
3916 WORD holds the last word of the command line; this is computed
3917 using a word-breaking heuristic.
3919 All forms of completion are handled by this function, that is, the
3920 <TAB> and <M-?> key bindings (*note Completion::), and the
3921 'complete' command (*note complete: Help.).
3923 This procedure can return several kinds of values:
3925 * If the return value is a list, the contents of the list are
3926 used as the completions. It is up to COMPLETER to ensure that
3927 the contents actually do complete the word. An empty list is
3928 allowed, it means that there were no completions available.
3929 Only string elements of the list are used; other elements in
3930 the list are ignored.
3932 * If the return value is a '<gdb:iterator>' object, it is
3933 iterated over to obtain the completions. It is up to
3934 'completer-procedure' to ensure that the results actually do
3935 complete the word. Only string elements of the result are
3936 used; other elements in the sequence are ignored.
3938 * All other results are treated as though there were no
3939 available completions.
3941 When a new command is registered, it will have been declared as a
3942 member of some general class of commands. This is used to classify
3943 top-level commands in the on-line help system; note that prefix commands
3944 are not listed under their own category but rather that of their
3945 top-level command. The available classifications are represented by
3946 constants defined in the 'gdb' module:
3949 The command does not belong to any particular class. A command in
3950 this category will not be displayed in any of the help categories.
3951 This is the default.
3954 The command is related to running the inferior. For example,
3955 'start', 'step', and 'continue' are in this category. Type 'help
3956 running' at the GDB prompt to see a list of commands in this
3960 The command is related to data or variables. For example, 'call',
3961 'find', and 'print' are in this category. Type 'help data' at the
3962 GDB prompt to see a list of commands in this category.
3965 The command has to do with manipulation of the stack. For example,
3966 'backtrace', 'frame', and 'return' are in this category. Type
3967 'help stack' at the GDB prompt to see a list of commands in this
3971 This class is used for file-related commands. For example, 'file',
3972 'list' and 'section' are in this category. Type 'help files' at
3973 the GDB prompt to see a list of commands in this category.
3976 This should be used for "support facilities", generally meaning
3977 things that are useful to the user when interacting with GDB, but
3978 not related to the state of the inferior. For example, 'help',
3979 'make', and 'shell' are in this category. Type 'help support' at
3980 the GDB prompt to see a list of commands in this category.
3983 The command is an 'info'-related command, that is, related to the
3984 state of GDB itself. For example, 'info', 'macro', and 'show' are
3985 in this category. Type 'help status' at the GDB prompt to see a
3986 list of commands in this category.
3988 'COMMAND_BREAKPOINTS'
3989 The command has to do with breakpoints. For example, 'break',
3990 'clear', and 'delete' are in this category. Type 'help
3991 breakpoints' at the GDB prompt to see a list of commands in this
3994 'COMMAND_TRACEPOINTS'
3995 The command has to do with tracepoints. For example, 'trace',
3996 'actions', and 'tfind' are in this category. Type 'help
3997 tracepoints' at the GDB prompt to see a list of commands in this
4001 The command is a general purpose command for the user, and
4002 typically does not fit in one of the other categories. Type 'help
4003 user-defined' at the GDB prompt to see a list of commands in this
4004 category, as well as the list of gdb macros (*note Sequences::).
4007 The command is only used in unusual circumstances, or is not of
4008 general interest to users. For example, 'checkpoint', 'fork', and
4009 'stop' are in this category. Type 'help obscure' at the GDB prompt
4010 to see a list of commands in this category.
4012 'COMMAND_MAINTENANCE'
4013 The command is only useful to GDB maintainers. The 'maintenance'
4014 and 'flushregs' commands are in this category. Type 'help
4015 internals' at the GDB prompt to see a list of commands in this
4018 A new command can use a predefined completion function, either by
4019 specifying it via an argument at initialization, or by returning it from
4020 the 'completer' procedure. These predefined completion constants are
4021 all defined in the 'gdb' module:
4024 This constant means that no completion should be done.
4027 This constant means that filename completion should be performed.
4030 This constant means that location completion should be done. *Note
4031 Location Specifications::.
4034 This constant means that completion should examine GDB command
4038 This constant means that completion should be done using symbol
4039 names as the source.
4041 'COMPLETE_EXPRESSION'
4042 This constant means that completion should be done on expressions.
4043 Often this means completing on symbol names, but some language
4044 parsers also have support for completing on field names.
4046 The following code snippet shows how a trivial CLI command can be
4047 implemented in Guile:
4050 (register-command! (make-command "hello-world"
4051 #:command-class COMMAND_USER
4052 #:doc "Greet the whole world."
4053 #:invoke (lambda (self args from-tty) (display "Hello, World!\n"))))
4059 File: gdb.info, Node: Parameters In Guile, Next: Progspaces In Guile, Prev: Commands In Guile, Up: Guile API
4061 23.4.3.12 Parameters In Guile
4062 .............................
4064 You can implement new GDB "parameters" using Guile (1).
4066 There are many parameters that already exist and can be set in GDB.
4067 Two examples are: 'set follow-fork' and 'set charset'. Setting these
4068 parameters influences certain behavior in GDB. Similarly, you can
4069 define parameters that can be used to influence behavior in custom Guile
4070 scripts and commands.
4072 A new parameter is defined with the 'make-parameter' Guile function,
4073 and added to GDB with the 'register-parameter!' Guile function. This
4074 two-step approach is taken to separate out the side-effect of adding the
4075 parameter to GDB from 'make-parameter'.
4077 Parameters are exposed to the user via the 'set' and 'show' commands.
4080 -- Scheme Procedure: make-parameter name
4081 [#:command-class command-class]
4082 [#:parameter-type parameter-type] [#:enum-list enum-list]
4083 [#:set-func set-func] [#:show-func show-func] [#:doc doc]
4084 [#:set-doc set-doc] [#:show-doc show-doc]
4085 [#:initial-value initial-value]
4087 The argument NAME is the name of the new parameter. If NAME
4088 consists of multiple words, then the initial words are looked for
4089 as prefix parameters. An example of this can be illustrated with
4090 the 'set print' set of parameters. If NAME is 'print foo', then
4091 'print' will be searched as the prefix parameter. In this case the
4092 parameter can subsequently be accessed in GDB as 'set print foo'.
4093 If NAME consists of multiple words, and no prefix parameter group
4094 can be found, an exception is raised.
4096 The result is the '<gdb:parameter>' object representing the
4097 parameter. The parameter is not usable until it has been
4098 registered with GDB with 'register-parameter!'.
4100 The rest of the arguments are optional.
4102 The argument COMMAND-CLASS should be one of the 'COMMAND_'
4103 constants (*note Commands In Guile::). This argument tells GDB how
4104 to categorize the new parameter in the help system. The default is
4107 The argument PARAMETER-TYPE should be one of the 'PARAM_' constants
4108 defined below. This argument tells GDB the type of the new
4109 parameter; this information is used for input validation and
4110 completion. The default is 'PARAM_BOOLEAN'.
4112 If PARAMETER-TYPE is 'PARAM_ENUM', then ENUM-LIST must be a list of
4113 strings. These strings represent the possible values for the
4116 If PARAMETER-TYPE is not 'PARAM_ENUM', then the presence of
4117 ENUM-LIST will cause an exception to be thrown.
4119 The argument SET-FUNC is a function of one argument: SELF which is
4120 the '<gdb:parameter>' object representing the parameter. GDB will
4121 call this function when a PARAMETER's value has been changed via
4122 the 'set' API (for example, 'set foo off'). The value of the
4123 parameter has already been set to the new value. This function
4124 must return a string to be displayed to the user. GDB will add a
4125 trailing newline if the string is non-empty. GDB generally doesn't
4126 print anything when a parameter is set, thus typically this
4127 function should return '""'. A non-empty string result should
4128 typically be used for displaying warnings and errors.
4130 The argument SHOW-FUNC is a function of two arguments: SELF which
4131 is the '<gdb:parameter>' object representing the parameter, and
4132 SVALUE which is the string representation of the current value.
4133 GDB will call this function when a PARAMETER's 'show' API has been
4134 invoked (for example, 'show foo'). This function must return a
4135 string, and will be displayed to the user. GDB will add a trailing
4138 The argument DOC is the help text for the new parameter. If there
4139 is no documentation string, a default value is used.
4141 The argument SET-DOC is the help text for this parameter's 'set'
4144 The argument SHOW-DOC is the help text for this parameter's 'show'
4147 The argument INITIAL-VALUE specifies the initial value of the
4148 parameter. If it is a function, it takes one parameter, the
4149 '<gdb:parameter>' object and its result is used as the initial
4150 value of the parameter. The initial value must be valid for the
4151 parameter type, otherwise an exception is thrown.
4153 -- Scheme Procedure: register-parameter! parameter
4154 Add PARAMETER, a '<gdb:parameter>' object, to GDB's list of
4155 parameters. It is an error to register a parameter more than once.
4156 The result is unspecified.
4158 -- Scheme Procedure: parameter? object
4159 Return '#t' if OBJECT is a '<gdb:parameter>' object. Otherwise
4162 -- Scheme Procedure: parameter-value parameter
4163 Return the value of PARAMETER which may either be a
4164 '<gdb:parameter>' object or a string naming the parameter.
4166 -- Scheme Procedure: set-parameter-value! parameter new-value
4167 Assign PARAMETER the value of NEW-VALUE. The argument PARAMETER
4168 must be an object of type '<gdb:parameter>'. GDB does validation
4169 when assignments are made.
4171 When a new parameter is defined, its type must be specified. The
4172 available types are represented by constants defined in the 'gdb'
4176 The value is a plain boolean. The Guile boolean values, '#t' and
4177 '#f' are the only valid values.
4179 'PARAM_AUTO_BOOLEAN'
4180 The value has three possible states: true, false, and 'auto'. In
4181 Guile, true and false are represented using boolean constants, and
4182 'auto' is represented using '#:auto'.
4185 The value is an unsigned integer. The value of '#:unlimited'
4186 should be interpreted to mean "unlimited", and the value of '0' is
4187 reserved and should not be used.
4190 The value is an integer.
4193 The value is an unsigned integer.
4195 'PARAM_ZUINTEGER_UNLIMITED'
4196 The value is an integer in the range '[0, INT_MAX]'. The value of
4197 '#:unlimited' means "unlimited", the value of '-1' is reserved and
4198 should not be used, and other negative numbers are not allowed.
4201 The value is a string. When the user modifies the string, any
4202 escape sequences, such as '\t', '\f', and octal escapes, are
4203 translated into corresponding characters and encoded into the
4204 current host charset.
4206 'PARAM_STRING_NOESCAPE'
4207 The value is a string. When the user modifies the string, escapes
4208 are passed through untranslated.
4210 'PARAM_OPTIONAL_FILENAME'
4211 The value is a either a filename (a string), or '#f'.
4214 The value is a filename. This is just like
4215 'PARAM_STRING_NOESCAPE', but uses file names for completion.
4218 The value is a string, which must be one of a collection of string
4219 constants provided when the parameter is created.
4221 ---------- Footnotes ----------
4223 (1) Note that GDB parameters must not be confused with Guile’s
4224 parameter objects (*note (guile)Parameters::).
4227 File: gdb.info, Node: Progspaces In Guile, Next: Objfiles In Guile, Prev: Parameters In Guile, Up: Guile API
4229 23.4.3.13 Program Spaces In Guile
4230 .................................
4232 A program space, or "progspace", represents a symbolic view of an
4233 address space. It consists of all of the objfiles of the program.
4234 *Note Objfiles In Guile::. *Note program spaces: Inferiors Connections
4235 and Programs, for more details about program spaces.
4237 Each progspace is represented by an instance of the '<gdb:progspace>'
4238 smob. *Note GDB Scheme Data Types::.
4240 The following progspace-related functions are available in the
4243 -- Scheme Procedure: progspace? object
4244 Return '#t' if OBJECT is a '<gdb:progspace>' object. Otherwise
4247 -- Scheme Procedure: progspace-valid? progspace
4248 Return '#t' if PROGSPACE is valid, '#f' if not. A
4249 '<gdb:progspace>' object can become invalid if the program it
4250 refers to is not loaded in GDB any longer.
4252 -- Scheme Procedure: current-progspace
4253 This function returns the program space of the currently selected
4254 inferior. There is always a current progspace, this never returns
4255 '#f'. *Note Inferiors Connections and Programs::.
4257 -- Scheme Procedure: progspaces
4258 Return a list of all the progspaces currently known to GDB.
4260 -- Scheme Procedure: progspace-filename progspace
4261 Return the absolute file name of PROGSPACE as a string. This is
4262 the name of the file passed as the argument to the 'file' or
4263 'symbol-file' commands. If the program space does not have an
4264 associated file name, then '#f' is returned. This occurs, for
4265 example, when GDB is started without a program to debug.
4267 A 'gdb:invalid-object-error' exception is thrown if PROGSPACE is
4270 -- Scheme Procedure: progspace-objfiles progspace
4271 Return the list of objfiles of PROGSPACE. The order of objfiles in
4272 the result is arbitrary. Each element is an object of type
4273 '<gdb:objfile>'. *Note Objfiles In Guile::.
4275 A 'gdb:invalid-object-error' exception is thrown if PROGSPACE is
4278 -- Scheme Procedure: progspace-pretty-printers progspace
4279 Return the list of pretty-printers of PROGSPACE. Each element is
4280 an object of type '<gdb:pretty-printer>'. *Note Guile Pretty
4281 Printing API::, for more information.
4283 -- Scheme Procedure: set-progspace-pretty-printers! progspace
4285 Set the list of registered '<gdb:pretty-printer>' objects for
4286 PROGSPACE to PRINTER-LIST. *Note Guile Pretty Printing API::, for
4290 File: gdb.info, Node: Objfiles In Guile, Next: Frames In Guile, Prev: Progspaces In Guile, Up: Guile API
4292 23.4.3.14 Objfiles In Guile
4293 ...........................
4295 GDB loads symbols for an inferior from various symbol-containing files
4296 (*note Files::). These include the primary executable file, any shared
4297 libraries used by the inferior, and any separate debug info files (*note
4298 Separate Debug Files::). GDB calls these symbol-containing files
4301 Each objfile is represented as an object of type '<gdb:objfile>'.
4303 The following objfile-related procedures are provided by the '(gdb)'
4306 -- Scheme Procedure: objfile? object
4307 Return '#t' if OBJECT is a '<gdb:objfile>' object. Otherwise
4310 -- Scheme Procedure: objfile-valid? objfile
4311 Return '#t' if OBJFILE is valid, '#f' if not. A '<gdb:objfile>'
4312 object can become invalid if the object file it refers to is not
4313 loaded in GDB any longer. All other '<gdb:objfile>' procedures
4314 will throw an exception if it is invalid at the time the procedure
4317 -- Scheme Procedure: objfile-filename objfile
4318 Return the file name of OBJFILE as a string, with symbolic links
4321 -- Scheme Procedure: objfile-progspace objfile
4322 Return the '<gdb:progspace>' that this object file lives in. *Note
4323 Progspaces In Guile::, for more on progspaces.
4325 -- Scheme Procedure: objfile-pretty-printers objfile
4326 Return the list of registered '<gdb:pretty-printer>' objects for
4327 OBJFILE. *Note Guile Pretty Printing API::, for more information.
4329 -- Scheme Procedure: set-objfile-pretty-printers! objfile printer-list
4330 Set the list of registered '<gdb:pretty-printer>' objects for
4331 OBJFILE to PRINTER-LIST. The PRINTER-LIST must be a list of
4332 '<gdb:pretty-printer>' objects. *Note Guile Pretty Printing API::,
4333 for more information.
4335 -- Scheme Procedure: current-objfile
4336 When auto-loading a Guile script (*note Guile Auto-loading::), GDB
4337 sets the "current objfile" to the corresponding objfile. This
4338 function returns the current objfile. If there is no current
4339 objfile, this function returns '#f'.
4341 -- Scheme Procedure: objfiles
4342 Return a list of all the objfiles in the current program space.
4345 File: gdb.info, Node: Frames In Guile, Next: Blocks In Guile, Prev: Objfiles In Guile, Up: Guile API
4347 23.4.3.15 Accessing inferior stack frames from Guile.
4348 .....................................................
4350 When the debugged program stops, GDB is able to analyze its call stack
4351 (*note Stack frames: Frames.). The '<gdb:frame>' class represents a
4352 frame in the stack. A '<gdb:frame>' object is only valid while its
4353 corresponding frame exists in the inferior's stack. If you try to use
4354 an invalid frame object, GDB will throw a 'gdb:invalid-object' exception
4355 (*note Guile Exception Handling::).
4357 Two '<gdb:frame>' objects can be compared for equality with the
4358 'equal?' function, like:
4360 (gdb) guile (equal? (newest-frame) (selected-frame))
4363 The following frame-related procedures are provided by the '(gdb)'
4366 -- Scheme Procedure: frame? object
4367 Return '#t' if OBJECT is a '<gdb:frame>' object. Otherwise return
4370 -- Scheme Procedure: frame-valid? frame
4371 Returns '#t' if FRAME is valid, '#f' if not. A frame object can
4372 become invalid if the frame it refers to doesn't exist anymore in
4373 the inferior. All '<gdb:frame>' procedures will throw an exception
4374 if the frame is invalid at the time the procedure is called.
4376 -- Scheme Procedure: frame-name frame
4377 Return the function name of FRAME, or '#f' if it can't be obtained.
4379 -- Scheme Procedure: frame-arch frame
4380 Return the '<gdb:architecture>' object corresponding to FRAME's
4381 architecture. *Note Architectures In Guile::.
4383 -- Scheme Procedure: frame-type frame
4384 Return the type of FRAME. The value can be one of:
4387 An ordinary stack frame.
4390 A fake stack frame that was created by GDB when performing an
4391 inferior function call.
4394 A frame representing an inlined function. The function was
4395 inlined into a 'NORMAL_FRAME' that is older than this one.
4398 A frame representing a tail call. *Note Tail Call Frames::.
4401 A signal trampoline frame. This is the frame created by the
4402 OS when it calls into a signal handler.
4405 A fake stack frame representing a cross-architecture call.
4408 This is like 'NORMAL_FRAME', but it is only used for the
4411 -- Scheme Procedure: frame-unwind-stop-reason frame
4412 Return an integer representing the reason why it's not possible to
4413 find more frames toward the outermost frame. Use
4414 'unwind-stop-reason-string' to convert the value returned by this
4415 function to a string. The value can be one of:
4417 'FRAME_UNWIND_NO_REASON'
4418 No particular reason (older frames should be available).
4420 'FRAME_UNWIND_NULL_ID'
4421 The previous frame's analyzer returns an invalid result.
4423 'FRAME_UNWIND_OUTERMOST'
4424 This frame is the outermost.
4426 'FRAME_UNWIND_UNAVAILABLE'
4427 Cannot unwind further, because that would require knowing the
4428 values of registers or memory that have not been collected.
4430 'FRAME_UNWIND_INNER_ID'
4431 This frame ID looks like it ought to belong to a NEXT frame,
4432 but we got it for a PREV frame. Normally, this is a sign of
4433 unwinder failure. It could also indicate stack corruption.
4435 'FRAME_UNWIND_SAME_ID'
4436 This frame has the same ID as the previous one. That means
4437 that unwinding further would almost certainly give us another
4438 frame with exactly the same ID, so break the chain. Normally,
4439 this is a sign of unwinder failure. It could also indicate
4442 'FRAME_UNWIND_NO_SAVED_PC'
4443 The frame unwinder did not find any saved PC, but we needed
4444 one to unwind further.
4446 'FRAME_UNWIND_MEMORY_ERROR'
4447 The frame unwinder caused an error while trying to access
4450 'FRAME_UNWIND_FIRST_ERROR'
4451 Any stop reason greater or equal to this value indicates some
4452 kind of error. This special value facilitates writing code
4453 that tests for errors in unwinding in a way that will work
4454 correctly even if the list of the other values is modified in
4455 future GDB versions. Using it, you could write:
4457 (define reason (frame-unwind-stop-readon (selected-frame)))
4458 (define reason-str (unwind-stop-reason-string reason))
4459 (if (>= reason FRAME_UNWIND_FIRST_ERROR)
4460 (format #t "An error occured: ~s\n" reason-str))
4462 -- Scheme Procedure: frame-pc frame
4463 Return the frame's resume address.
4465 -- Scheme Procedure: frame-block frame
4466 Return the frame's code block as a '<gdb:block>' object. *Note
4469 -- Scheme Procedure: frame-function frame
4470 Return the symbol for the function corresponding to this frame as a
4471 '<gdb:symbol>' object, or '#f' if there isn't one. *Note Symbols
4474 -- Scheme Procedure: frame-older frame
4475 Return the frame that called FRAME.
4477 -- Scheme Procedure: frame-newer frame
4478 Return the frame called by FRAME.
4480 -- Scheme Procedure: frame-sal frame
4481 Return the frame's '<gdb:sal>' (symtab and line) object. *Note
4482 Symbol Tables In Guile::.
4484 -- Scheme Procedure: frame-read-register frame register
4485 Return the value of REGISTER in FRAME. REGISTER should be a
4488 -- Scheme Procedure: frame-read-var frame variable [#:block block]
4489 Return the value of VARIABLE in FRAME. If the optional argument
4490 BLOCK is provided, search for the variable from that block;
4491 otherwise start at the frame's current block (which is determined
4492 by the frame's current program counter). The VARIABLE must be
4493 given as a string or a '<gdb:symbol>' object, and BLOCK must be a
4494 '<gdb:block>' object.
4496 -- Scheme Procedure: frame-select frame
4497 Set FRAME to be the selected frame. *Note Examining the Stack:
4500 -- Scheme Procedure: selected-frame
4501 Return the selected frame object. *Note Selecting a Frame:
4504 -- Scheme Procedure: newest-frame
4505 Return the newest frame object for the selected thread.
4507 -- Scheme Procedure: unwind-stop-reason-string reason
4508 Return a string explaining the reason why GDB stopped unwinding
4509 frames, as expressed by the given REASON code (an integer, see the
4510 'frame-unwind-stop-reason' procedure above in this section).
4513 File: gdb.info, Node: Blocks In Guile, Next: Symbols In Guile, Prev: Frames In Guile, Up: Guile API
4515 23.4.3.16 Accessing blocks from Guile.
4516 ......................................
4518 In GDB, symbols are stored in blocks. A block corresponds roughly to a
4519 scope in the source code. Blocks are organized hierarchically, and are
4520 represented individually in Guile as an object of type '<gdb:block>'.
4521 Blocks rely on debugging information being available.
4523 A frame has a block. Please see *note Frames In Guile::, for a more
4524 in-depth discussion of frames.
4526 The outermost block is known as the "global block". The global block
4527 typically holds public global variables and functions.
4529 The block nested just inside the global block is the "static block".
4530 The static block typically holds file-scoped variables and functions.
4532 GDB provides a method to get a block's superblock, but there is
4533 currently no way to examine the sub-blocks of a block, or to iterate
4534 over all the blocks in a symbol table (*note Symbol Tables In Guile::).
4536 Here is a short example that should help explain blocks:
4538 /* This is in the global block. */
4541 /* This is in the static block. */
4542 static int file_scope;
4544 /* 'function' is in the global block, and 'argument' is
4545 in a block nested inside of 'function'. */
4546 int function (int argument)
4548 /* 'local' is in a block inside 'function'. It may or may
4549 not be in the same block as 'argument'. */
4553 /* 'inner' is in a block whose superblock is the one holding
4557 /* If this call is expanded by the compiler, you may see
4558 a nested block here whose function is 'inline_function'
4559 and whose superblock is the one holding 'inner'. */
4564 The following block-related procedures are provided by the '(gdb)'
4567 -- Scheme Procedure: block? object
4568 Return '#t' if OBJECT is a '<gdb:block>' object. Otherwise return
4571 -- Scheme Procedure: block-valid? block
4572 Returns '#t' if '<gdb:block>' BLOCK is valid, '#f' if not. A block
4573 object can become invalid if the block it refers to doesn't exist
4574 anymore in the inferior. All other '<gdb:block>' methods will
4575 throw an exception if it is invalid at the time the procedure is
4576 called. The block's validity is also checked during iteration over
4577 symbols of the block.
4579 -- Scheme Procedure: block-start block
4580 Return the start address of '<gdb:block>' BLOCK.
4582 -- Scheme Procedure: block-end block
4583 Return the end address of '<gdb:block>' BLOCK.
4585 -- Scheme Procedure: block-function block
4586 Return the name of '<gdb:block>' BLOCK represented as a
4587 '<gdb:symbol>' object. If the block is not named, then '#f' is
4590 For ordinary function blocks, the superblock is the static block.
4591 However, you should note that it is possible for a function block
4592 to have a superblock that is not the static block - for instance
4593 this happens for an inlined function.
4595 -- Scheme Procedure: block-superblock block
4596 Return the block containing '<gdb:block>' BLOCK. If the parent
4597 block does not exist, then '#f' is returned.
4599 -- Scheme Procedure: block-global-block block
4600 Return the global block associated with '<gdb:block>' BLOCK.
4602 -- Scheme Procedure: block-static-block block
4603 Return the static block associated with '<gdb:block>' BLOCK.
4605 -- Scheme Procedure: block-global? block
4606 Return '#t' if '<gdb:block>' BLOCK is a global block. Otherwise
4609 -- Scheme Procedure: block-static? block
4610 Return '#t' if '<gdb:block>' BLOCK is a static block. Otherwise
4613 -- Scheme Procedure: block-symbols
4614 Return a list of all symbols (as <gdb:symbol> objects) in
4615 '<gdb:block>' BLOCK.
4617 -- Scheme Procedure: make-block-symbols-iterator block
4618 Return an object of type '<gdb:iterator>' that will iterate over
4619 all symbols of the block. Guile programs should not assume that a
4620 specific block object will always contain a given symbol, since
4621 changes in GDB features and infrastructure may cause symbols move
4622 across blocks in a symbol table. *Note Iterators In Guile::.
4624 -- Scheme Procedure: block-symbols-progress?
4625 Return #t if the object is a <gdb:block-symbols-progress> object.
4626 This object would be obtained from the 'progress' element of the
4627 '<gdb:iterator>' object returned by 'make-block-symbols-iterator'.
4629 -- Scheme Procedure: lookup-block pc
4630 Return the innermost '<gdb:block>' containing the given PC value.
4631 If the block cannot be found for the PC value specified, the
4632 function will return '#f'.
4635 File: gdb.info, Node: Symbols In Guile, Next: Symbol Tables In Guile, Prev: Blocks In Guile, Up: Guile API
4637 23.4.3.17 Guile representation of Symbols.
4638 ..........................................
4640 GDB represents every variable, function and type as an entry in a symbol
4641 table. *Note Examining the Symbol Table: Symbols. Guile represents
4642 these symbols in GDB with the '<gdb:symbol>' object.
4644 The following symbol-related procedures are provided by the '(gdb)'
4647 -- Scheme Procedure: symbol? object
4648 Return '#t' if OBJECT is an object of type '<gdb:symbol>'.
4649 Otherwise return '#f'.
4651 -- Scheme Procedure: symbol-valid? symbol
4652 Return '#t' if the '<gdb:symbol>' object is valid, '#f' if not. A
4653 '<gdb:symbol>' object can become invalid if the symbol it refers to
4654 does not exist in GDB any longer. All other '<gdb:symbol>'
4655 procedures will throw an exception if it is invalid at the time the
4656 procedure is called.
4658 -- Scheme Procedure: symbol-type symbol
4659 Return the type of SYMBOL or '#f' if no type is recorded. The
4660 result is an object of type '<gdb:type>'. *Note Types In Guile::.
4662 -- Scheme Procedure: symbol-symtab symbol
4663 Return the symbol table in which SYMBOL appears. The result is an
4664 object of type '<gdb:symtab>'. *Note Symbol Tables In Guile::.
4666 -- Scheme Procedure: symbol-line symbol
4667 Return the line number in the source code at which SYMBOL was
4668 defined. This is an integer.
4670 -- Scheme Procedure: symbol-name symbol
4671 Return the name of SYMBOL as a string.
4673 -- Scheme Procedure: symbol-linkage-name symbol
4674 Return the name of SYMBOL, as used by the linker (i.e., may be
4677 -- Scheme Procedure: symbol-print-name symbol
4678 Return the name of SYMBOL in a form suitable for output. This is
4679 either 'name' or 'linkage_name', depending on whether the user
4680 asked GDB to display demangled or mangled names.
4682 -- Scheme Procedure: symbol-addr-class symbol
4683 Return the address class of the symbol. This classifies how to
4684 find the value of a symbol. Each address class is a constant
4685 defined in the '(gdb)' module and described later in this chapter.
4687 -- Scheme Procedure: symbol-needs-frame? symbol
4688 Return '#t' if evaluating SYMBOL's value requires a frame (*note
4689 Frames In Guile::) and '#f' otherwise. Typically, local variables
4690 will require a frame, but other symbols will not.
4692 -- Scheme Procedure: symbol-argument? symbol
4693 Return '#t' if SYMBOL is an argument of a function. Otherwise
4696 -- Scheme Procedure: symbol-constant? symbol
4697 Return '#t' if SYMBOL is a constant. Otherwise return '#f'.
4699 -- Scheme Procedure: symbol-function? symbol
4700 Return '#t' if SYMBOL is a function or a method. Otherwise return
4703 -- Scheme Procedure: symbol-variable? symbol
4704 Return '#t' if SYMBOL is a variable. Otherwise return '#f'.
4706 -- Scheme Procedure: symbol-value symbol [#:frame frame]
4707 Compute the value of SYMBOL, as a '<gdb:value>'. For functions,
4708 this computes the address of the function, cast to the appropriate
4709 type. If the symbol requires a frame in order to compute its
4710 value, then FRAME must be given. If FRAME is not given, or if
4711 FRAME is invalid, then an exception is thrown.
4713 -- Scheme Procedure: lookup-symbol name [#:block block]
4715 This function searches for a symbol by name. The search scope can
4716 be restricted to the parameters defined in the optional domain and
4719 NAME is the name of the symbol. It must be a string. The optional
4720 BLOCK argument restricts the search to symbols visible in that
4721 BLOCK. The BLOCK argument must be a '<gdb:block>' object. If
4722 omitted, the block for the current frame is used. The optional
4723 DOMAIN argument restricts the search to the domain type. The
4724 DOMAIN argument must be a domain constant defined in the '(gdb)'
4725 module and described later in this chapter.
4727 The result is a list of two elements. The first element is a
4728 '<gdb:symbol>' object or '#f' if the symbol is not found. If the
4729 symbol is found, the second element is '#t' if the symbol is a
4730 field of a method's object (e.g., 'this' in C++), otherwise it is
4731 '#f'. If the symbol is not found, the second element is '#f'.
4733 -- Scheme Procedure: lookup-global-symbol name [#:domain domain]
4734 This function searches for a global symbol by name. The search
4735 scope can be restricted by the domain argument.
4737 NAME is the name of the symbol. It must be a string. The optional
4738 DOMAIN argument restricts the search to the domain type. The
4739 DOMAIN argument must be a domain constant defined in the '(gdb)'
4740 module and described later in this chapter.
4742 The result is a '<gdb:symbol>' object or '#f' if the symbol is not
4745 The available domain categories in '<gdb:symbol>' are represented as
4746 constants in the '(gdb)' module:
4748 'SYMBOL_UNDEF_DOMAIN'
4749 This is used when a domain has not been discovered or none of the
4750 following domains apply. This usually indicates an error either in
4751 the symbol information or in GDB's handling of symbols.
4754 This domain contains variables, function names, typedef names and
4757 'SYMBOL_STRUCT_DOMAIN'
4758 This domain holds struct, union and enum type names.
4760 'SYMBOL_LABEL_DOMAIN'
4761 This domain contains names of labels (for gotos).
4763 'SYMBOL_VARIABLES_DOMAIN'
4764 This domain holds a subset of the 'SYMBOLS_VAR_DOMAIN'; it contains
4765 everything minus functions and types.
4767 'SYMBOL_FUNCTIONS_DOMAIN'
4768 This domain contains all functions.
4770 'SYMBOL_TYPES_DOMAIN'
4771 This domain contains all types.
4773 The available address class categories in '<gdb:symbol>' are
4774 represented as constants in the 'gdb' module:
4777 If this is returned by address class, it indicates an error either
4778 in the symbol information or in GDB's handling of symbols.
4781 Value is constant int.
4784 Value is at a fixed address.
4786 'SYMBOL_LOC_REGISTER'
4787 Value is in a register.
4790 Value is an argument. This value is at the offset stored within
4791 the symbol inside the frame's argument list.
4793 'SYMBOL_LOC_REF_ARG'
4794 Value address is stored in the frame's argument list. Just like
4795 'LOC_ARG' except that the value's address is stored at the offset,
4796 not the value itself.
4798 'SYMBOL_LOC_REGPARM_ADDR'
4799 Value is a specified register. Just like 'LOC_REGISTER' except the
4800 register holds the address of the argument instead of the argument
4804 Value is a local variable.
4806 'SYMBOL_LOC_TYPEDEF'
4807 Value not used. Symbols in the domain 'SYMBOL_STRUCT_DOMAIN' all
4813 'SYMBOL_LOC_CONST_BYTES'
4814 Value is a byte-sequence.
4816 'SYMBOL_LOC_UNRESOLVED'
4817 Value is at a fixed address, but the address of the variable has to
4818 be determined from the minimal symbol table whenever the variable
4821 'SYMBOL_LOC_OPTIMIZED_OUT'
4822 The value does not actually exist in the program.
4824 'SYMBOL_LOC_COMPUTED'
4825 The value's address is a computed location.
4828 File: gdb.info, Node: Symbol Tables In Guile, Next: Breakpoints In Guile, Prev: Symbols In Guile, Up: Guile API
4830 23.4.3.18 Symbol table representation in Guile.
4831 ...............................................
4833 Access to symbol table data maintained by GDB on the inferior is exposed
4834 to Guile via two objects: '<gdb:sal>' (symtab-and-line) and
4835 '<gdb:symtab>'. Symbol table and line data for a frame is returned from
4836 the 'frame-find-sal' '<gdb:frame>' procedure. *Note Frames In Guile::.
4838 For more information on GDB's symbol table management, see *note
4839 Examining the Symbol Table: Symbols.
4841 The following symtab-related procedures are provided by the '(gdb)'
4844 -- Scheme Procedure: symtab? object
4845 Return '#t' if OBJECT is an object of type '<gdb:symtab>'.
4846 Otherwise return '#f'.
4848 -- Scheme Procedure: symtab-valid? symtab
4849 Return '#t' if the '<gdb:symtab>' object is valid, '#f' if not. A
4850 '<gdb:symtab>' object becomes invalid when the symbol table it
4851 refers to no longer exists in GDB. All other '<gdb:symtab>'
4852 procedures will throw an exception if it is invalid at the time the
4853 procedure is called.
4855 -- Scheme Procedure: symtab-filename symtab
4856 Return the symbol table's source filename.
4858 -- Scheme Procedure: symtab-fullname symtab
4859 Return the symbol table's source absolute file name.
4861 -- Scheme Procedure: symtab-objfile symtab
4862 Return the symbol table's backing object file. *Note Objfiles In
4865 -- Scheme Procedure: symtab-global-block symtab
4866 Return the global block of the underlying symbol table. *Note
4869 -- Scheme Procedure: symtab-static-block symtab
4870 Return the static block of the underlying symbol table. *Note
4873 The following symtab-and-line-related procedures are provided by the
4876 -- Scheme Procedure: sal? object
4877 Return '#t' if OBJECT is an object of type '<gdb:sal>'. Otherwise
4880 -- Scheme Procedure: sal-valid? sal
4881 Return '#t' if SAL is valid, '#f' if not. A '<gdb:sal>' object
4882 becomes invalid when the Symbol table object it refers to no longer
4883 exists in GDB. All other '<gdb:sal>' procedures will throw an
4884 exception if it is invalid at the time the procedure is called.
4886 -- Scheme Procedure: sal-symtab sal
4887 Return the symbol table object ('<gdb:symtab>') for SAL.
4889 -- Scheme Procedure: sal-line sal
4890 Return the line number for SAL.
4892 -- Scheme Procedure: sal-pc sal
4893 Return the start of the address range occupied by code for SAL.
4895 -- Scheme Procedure: sal-last sal
4896 Return the end of the address range occupied by code for SAL.
4898 -- Scheme Procedure: find-pc-line pc
4899 Return the '<gdb:sal>' object corresponding to the PC value. If an
4900 invalid value of PC is passed as an argument, then the 'symtab' and
4901 'line' attributes of the returned '<gdb:sal>' object will be '#f'
4905 File: gdb.info, Node: Breakpoints In Guile, Next: Lazy Strings In Guile, Prev: Symbol Tables In Guile, Up: Guile API
4907 23.4.3.19 Manipulating breakpoints using Guile
4908 ..............................................
4910 Breakpoints in Guile are represented by objects of type
4911 '<gdb:breakpoint>'. New breakpoints can be created with the
4912 'make-breakpoint' Guile function, and then added to GDB with the
4913 'register-breakpoint!' Guile function. This two-step approach is taken
4914 to separate out the side-effect of adding the breakpoint to GDB from
4917 Support is also provided to view and manipulate breakpoints created
4920 The following breakpoint-related procedures are provided by the
4923 -- Scheme Procedure: make-breakpoint location [#:type type]
4924 [#:wp-class wp-class] [#:internal internal]
4925 [#:temporary temporary]
4926 Create a new breakpoint at LOCATION, a string naming the location
4927 of the breakpoint, or an expression that defines a watchpoint. The
4928 contents can be any location recognized by the 'break' command, or
4929 in the case of a watchpoint, by the 'watch' command.
4931 The breakpoint is initially marked as 'invalid'. The breakpoint is
4932 not usable until it has been registered with GDB with
4933 'register-breakpoint!', at which point it becomes 'valid'. The
4934 result is the '<gdb:breakpoint>' object representing the
4937 The optional TYPE denotes the breakpoint to create. This argument
4938 can be either 'BP_BREAKPOINT' or 'BP_WATCHPOINT', and defaults to
4941 The optional WP-CLASS argument defines the class of watchpoint to
4942 create, if TYPE is 'BP_WATCHPOINT'. If a watchpoint class is not
4943 provided, it is assumed to be a 'WP_WRITE' class.
4945 The optional INTERNAL argument allows the breakpoint to become
4946 invisible to the user. The breakpoint will neither be reported
4947 when registered, nor will it be listed in the output from 'info
4948 breakpoints' (but will be listed with the 'maint info breakpoints'
4949 command). If an internal flag is not provided, the breakpoint is
4950 visible (non-internal).
4952 The optional TEMPORARY argument makes the breakpoint a temporary
4953 breakpoint. Temporary breakpoints are deleted after they have been
4954 hit, after which the Guile breakpoint is no longer usable (although
4955 it may be re-registered with 'register-breakpoint!').
4957 When a watchpoint is created, GDB will try to create a hardware
4958 assisted watchpoint. If successful, the type of the watchpoint is
4959 changed from 'BP_WATCHPOINT' to 'BP_HARDWARE_WATCHPOINT' for
4960 'WP_WRITE', 'BP_READ_WATCHPOINT' for 'WP_READ', and
4961 'BP_ACCESS_WATCHPOINT' for 'WP_ACCESS'. If not successful, the
4962 type of the watchpoint is left as 'WP_WATCHPOINT'.
4964 The available types are represented by constants defined in the
4968 Normal code breakpoint.
4971 Watchpoint breakpoint.
4973 'BP_HARDWARE_WATCHPOINT'
4974 Hardware assisted watchpoint. This value cannot be specified
4975 when creating the breakpoint.
4977 'BP_READ_WATCHPOINT'
4978 Hardware assisted read watchpoint. This value cannot be
4979 specified when creating the breakpoint.
4981 'BP_ACCESS_WATCHPOINT'
4982 Hardware assisted access watchpoint. This value cannot be
4983 specified when creating the breakpoint.
4986 Catchpoint. This value cannot be specified when creating the
4989 The available watchpoint types are represented by constants defined
4990 in the '(gdb)' module:
4993 Read only watchpoint.
4996 Write only watchpoint.
4999 Read/Write watchpoint.
5001 -- Scheme Procedure: register-breakpoint! breakpoint
5002 Add BREAKPOINT, a '<gdb:breakpoint>' object, to GDB's list of
5003 breakpoints. The breakpoint must have been created with
5004 'make-breakpoint'. One cannot register breakpoints that have been
5005 created outside of Guile. Once a breakpoint is registered it
5006 becomes 'valid'. It is an error to register an already registered
5007 breakpoint. The result is unspecified.
5009 -- Scheme Procedure: delete-breakpoint! breakpoint
5010 Remove BREAKPOINT from GDB's list of breakpoints. This also
5011 invalidates the Guile BREAKPOINT object. Any further attempt to
5012 access the object will throw an exception.
5014 If BREAKPOINT was created from Guile with 'make-breakpoint' it may
5015 be re-registered with GDB, in which case the breakpoint becomes
5018 -- Scheme Procedure: breakpoints
5019 Return a list of all breakpoints. Each element of the list is a
5020 '<gdb:breakpoint>' object.
5022 -- Scheme Procedure: breakpoint? object
5023 Return '#t' if OBJECT is a '<gdb:breakpoint>' object, and '#f'
5026 -- Scheme Procedure: breakpoint-valid? breakpoint
5027 Return '#t' if BREAKPOINT is valid, '#f' otherwise. Breakpoints
5028 created with 'make-breakpoint' are marked as invalid until they are
5029 registered with GDB with 'register-breakpoint!'. A
5030 '<gdb:breakpoint>' object can become invalid if the user deletes
5031 the breakpoint. In this case, the object still exists, but the
5032 underlying breakpoint does not. In the cases of watchpoint scope,
5033 the watchpoint remains valid even if execution of the inferior
5034 leaves the scope of that watchpoint.
5036 -- Scheme Procedure: breakpoint-number breakpoint
5037 Return the breakpoint's number -- the identifier used by the user
5038 to manipulate the breakpoint.
5040 -- Scheme Procedure: breakpoint-temporary? breakpoint
5041 Return '#t' if the breakpoint was created as a temporary
5042 breakpoint. Temporary breakpoints are automatically deleted after
5043 they've been hit. Calling this procedure, and all other procedures
5044 other than 'breakpoint-valid?' and 'register-breakpoint!', will
5045 result in an error after the breakpoint has been hit (since it has
5046 been automatically deleted).
5048 -- Scheme Procedure: breakpoint-type breakpoint
5049 Return the breakpoint's type -- the identifier used to determine
5050 the actual breakpoint type or use-case.
5052 -- Scheme Procedure: breakpoint-visible? breakpoint
5053 Return '#t' if the breakpoint is visible to the user when hit, or
5054 when the 'info breakpoints' command is run. Otherwise return '#f'.
5056 -- Scheme Procedure: breakpoint-location breakpoint
5057 Return the location of the breakpoint, as specified by the user.
5058 It is a string. If the breakpoint does not have a location (that
5059 is, it is a watchpoint) return '#f'.
5061 -- Scheme Procedure: breakpoint-expression breakpoint
5062 Return the breakpoint expression, as specified by the user. It is
5063 a string. If the breakpoint does not have an expression (the
5064 breakpoint is not a watchpoint) return '#f'.
5066 -- Scheme Procedure: breakpoint-enabled? breakpoint
5067 Return '#t' if the breakpoint is enabled, and '#f' otherwise.
5069 -- Scheme Procedure: set-breakpoint-enabled! breakpoint flag
5070 Set the enabled state of BREAKPOINT to FLAG. If flag is '#f' it is
5071 disabled, otherwise it is enabled.
5073 -- Scheme Procedure: breakpoint-silent? breakpoint
5074 Return '#t' if the breakpoint is silent, and '#f' otherwise.
5076 Note that a breakpoint can also be silent if it has commands and
5077 the first command is 'silent'. This is not reported by the
5080 -- Scheme Procedure: set-breakpoint-silent! breakpoint flag
5081 Set the silent state of BREAKPOINT to FLAG. If flag is '#f' the
5082 breakpoint is made silent, otherwise it is made non-silent (or
5085 -- Scheme Procedure: breakpoint-ignore-count breakpoint
5086 Return the ignore count for BREAKPOINT.
5088 -- Scheme Procedure: set-breakpoint-ignore-count! breakpoint count
5089 Set the ignore count for BREAKPOINT to COUNT.
5091 -- Scheme Procedure: breakpoint-hit-count breakpoint
5092 Return hit count of BREAKPOINT.
5094 -- Scheme Procedure: set-breakpoint-hit-count! breakpoint count
5095 Set the hit count of BREAKPOINT to COUNT. At present, COUNT must
5098 -- Scheme Procedure: breakpoint-thread breakpoint
5099 Return the global-thread-id for thread-specific breakpoint
5100 BREAKPOINT. Return #f if BREAKPOINT is not thread-specific.
5102 -- Scheme Procedure: set-breakpoint-thread! breakpoint
5104 Set the thread-id for BREAKPOINT to GLOBAL-THREAD-ID If set to
5105 '#f', the breakpoint is no longer thread-specific.
5107 -- Scheme Procedure: breakpoint-task breakpoint
5108 If the breakpoint is Ada task-specific, return the Ada task id. If
5109 the breakpoint is not task-specific (or the underlying language is
5110 not Ada), return '#f'.
5112 -- Scheme Procedure: set-breakpoint-task! breakpoint task
5113 Set the Ada task of BREAKPOINT to TASK. If set to '#f', the
5114 breakpoint is no longer task-specific.
5116 -- Scheme Procedure: breakpoint-condition breakpoint
5117 Return the condition of BREAKPOINT, as specified by the user. It
5118 is a string. If there is no condition, return '#f'.
5120 -- Scheme Procedure: set-breakpoint-condition! breakpoint condition
5121 Set the condition of BREAKPOINT to CONDITION, which must be a
5122 string. If set to '#f' then the breakpoint becomes unconditional.
5124 -- Scheme Procedure: breakpoint-stop breakpoint
5125 Return the stop predicate of BREAKPOINT. See
5126 'set-breakpoint-stop!' below in this section.
5128 -- Scheme Procedure: set-breakpoint-stop! breakpoint procedure|#f
5129 Set the stop predicate of BREAKPOINT. The predicate PROCEDURE
5130 takes one argument: the <gdb:breakpoint> object. If this predicate
5131 is set to a procedure then it is invoked whenever the inferior
5132 reaches this breakpoint. If it returns '#t', or any non-'#f'
5133 value, then the inferior is stopped, otherwise the inferior will
5136 If there are multiple breakpoints at the same location with a
5137 'stop' predicate, each one will be called regardless of the return
5138 status of the previous. This ensures that all 'stop' predicates
5139 have a chance to execute at that location. In this scenario if one
5140 of the methods returns '#t' but the others return '#f', the
5141 inferior will still be stopped.
5143 You should not alter the execution state of the inferior (i.e.,
5144 step, next, etc.), alter the current frame context (i.e., change
5145 the current active frame), or alter, add or delete any breakpoint.
5146 As a general rule, you should not alter any data within GDB or the
5147 inferior at this time.
5149 Example 'stop' implementation:
5151 (define (my-stop? bkpt)
5152 (let ((int-val (parse-and-eval "foo")))
5153 (value=? int-val 3)))
5154 (define bkpt (make-breakpoint "main.c:42"))
5155 (register-breakpoint! bkpt)
5156 (set-breakpoint-stop! bkpt my-stop?)
5158 -- Scheme Procedure: breakpoint-commands breakpoint
5159 Return the commands attached to BREAKPOINT as a string, or '#f' if
5163 File: gdb.info, Node: Lazy Strings In Guile, Next: Architectures In Guile, Prev: Breakpoints In Guile, Up: Guile API
5165 23.4.3.20 Guile representation of lazy strings.
5166 ...............................................
5168 A "lazy string" is a string whose contents is not retrieved or encoded
5171 A '<gdb:lazy-string>' is represented in GDB as an 'address' that
5172 points to a region of memory, an 'encoding' that will be used to encode
5173 that region of memory, and a 'length' to delimit the region of memory
5174 that represents the string. The difference between a
5175 '<gdb:lazy-string>' and a string wrapped within a '<gdb:value>' is that
5176 a '<gdb:lazy-string>' will be treated differently by GDB when printing.
5177 A '<gdb:lazy-string>' is retrieved and encoded during printing, while a
5178 '<gdb:value>' wrapping a string is immediately retrieved and encoded on
5181 The following lazy-string-related procedures are provided by the
5184 -- Scheme Procedure: lazy-string? object
5185 Return '#t' if OBJECT is an object of type '<gdb:lazy-string>'.
5186 Otherwise return '#f'.
5188 -- Scheme Procedure: lazy-string-address lazy-sring
5189 Return the address of LAZY-STRING.
5191 -- Scheme Procedure: lazy-string-length lazy-string
5192 Return the length of LAZY-STRING in characters. If the length is
5193 -1, then the string will be fetched and encoded up to the first
5194 null of appropriate width.
5196 -- Scheme Procedure: lazy-string-encoding lazy-string
5197 Return the encoding that will be applied to LAZY-STRING when the
5198 string is printed by GDB. If the encoding is not set, or contains
5199 an empty string, then GDB will select the most appropriate encoding
5200 when the string is printed.
5202 -- Scheme Procedure: lazy-string-type lazy-string
5203 Return the type that is represented by LAZY-STRING's type. For a
5204 lazy string this is a pointer or array type. To resolve this to
5205 the lazy string's character type, use 'type-target-type'. *Note
5208 -- Scheme Procedure: lazy-string->value lazy-string
5209 Convert the '<gdb:lazy-string>' to a '<gdb:value>'. This value
5210 will point to the string in memory, but will lose all the delayed
5211 retrieval, encoding and handling that GDB applies to a
5212 '<gdb:lazy-string>'.
5215 File: gdb.info, Node: Architectures In Guile, Next: Disassembly In Guile, Prev: Lazy Strings In Guile, Up: Guile API
5217 23.4.3.21 Guile representation of architectures
5218 ...............................................
5220 GDB uses architecture specific parameters and artifacts in a number of
5221 its various computations. An architecture is represented by an instance
5222 of the '<gdb:arch>' class.
5224 The following architecture-related procedures are provided by the
5227 -- Scheme Procedure: arch? object
5228 Return '#t' if OBJECT is an object of type '<gdb:arch>'. Otherwise
5231 -- Scheme Procedure: current-arch
5232 Return the current architecture as a '<gdb:arch>' object.
5234 -- Scheme Procedure: arch-name arch
5235 Return the name (string value) of '<gdb:arch>' ARCH.
5237 -- Scheme Procedure: arch-charset arch
5238 Return name of target character set of '<gdb:arch>' ARCH.
5240 -- Scheme Procedure: arch-wide-charset
5241 Return name of target wide character set of '<gdb:arch>' ARCH.
5243 Each architecture provides a set of predefined types, obtained by the
5244 following functions.
5246 -- Scheme Procedure: arch-void-type arch
5247 Return the '<gdb:type>' object for a 'void' type of architecture
5250 -- Scheme Procedure: arch-char-type arch
5251 Return the '<gdb:type>' object for a 'char' type of architecture
5254 -- Scheme Procedure: arch-short-type arch
5255 Return the '<gdb:type>' object for a 'short' type of architecture
5258 -- Scheme Procedure: arch-int-type arch
5259 Return the '<gdb:type>' object for an 'int' type of architecture
5262 -- Scheme Procedure: arch-long-type arch
5263 Return the '<gdb:type>' object for a 'long' type of architecture
5266 -- Scheme Procedure: arch-schar-type arch
5267 Return the '<gdb:type>' object for a 'signed char' type of
5270 -- Scheme Procedure: arch-uchar-type arch
5271 Return the '<gdb:type>' object for an 'unsigned char' type of
5274 -- Scheme Procedure: arch-ushort-type arch
5275 Return the '<gdb:type>' object for an 'unsigned short' type of
5278 -- Scheme Procedure: arch-uint-type arch
5279 Return the '<gdb:type>' object for an 'unsigned int' type of
5282 -- Scheme Procedure: arch-ulong-type arch
5283 Return the '<gdb:type>' object for an 'unsigned long' type of
5286 -- Scheme Procedure: arch-float-type arch
5287 Return the '<gdb:type>' object for a 'float' type of architecture
5290 -- Scheme Procedure: arch-double-type arch
5291 Return the '<gdb:type>' object for a 'double' type of architecture
5294 -- Scheme Procedure: arch-longdouble-type arch
5295 Return the '<gdb:type>' object for a 'long double' type of
5298 -- Scheme Procedure: arch-bool-type arch
5299 Return the '<gdb:type>' object for a 'bool' type of architecture
5302 -- Scheme Procedure: arch-longlong-type arch
5303 Return the '<gdb:type>' object for a 'long long' type of
5306 -- Scheme Procedure: arch-ulonglong-type arch
5307 Return the '<gdb:type>' object for an 'unsigned long long' type of
5310 -- Scheme Procedure: arch-int8-type arch
5311 Return the '<gdb:type>' object for an 'int8' type of architecture
5314 -- Scheme Procedure: arch-uint8-type arch
5315 Return the '<gdb:type>' object for a 'uint8' type of architecture
5318 -- Scheme Procedure: arch-int16-type arch
5319 Return the '<gdb:type>' object for an 'int16' type of architecture
5322 -- Scheme Procedure: arch-uint16-type arch
5323 Return the '<gdb:type>' object for a 'uint16' type of architecture
5326 -- Scheme Procedure: arch-int32-type arch
5327 Return the '<gdb:type>' object for an 'int32' type of architecture
5330 -- Scheme Procedure: arch-uint32-type arch
5331 Return the '<gdb:type>' object for a 'uint32' type of architecture
5334 -- Scheme Procedure: arch-int64-type arch
5335 Return the '<gdb:type>' object for an 'int64' type of architecture
5338 -- Scheme Procedure: arch-uint64-type arch
5339 Return the '<gdb:type>' object for a 'uint64' type of architecture
5344 (gdb) guile (type-name (arch-uchar-type (current-arch)))
5348 File: gdb.info, Node: Disassembly In Guile, Next: I/O Ports in Guile, Prev: Architectures In Guile, Up: Guile API
5350 23.4.3.22 Disassembly In Guile
5351 ..............................
5353 The disassembler can be invoked from Scheme code. Furthermore, the
5354 disassembler can take a Guile port as input, allowing one to disassemble
5355 from any source, and not just target memory.
5357 -- Scheme Procedure: arch-disassemble arch start-pc [#:port port]
5358 [#:offset offset] [#:size size] [#:count count]
5359 Return a list of disassembled instructions starting from the memory
5362 The optional argument PORT specifies the input port to read bytes
5363 from. If PORT is '#f' then bytes are read from target memory.
5365 The optional argument OFFSET specifies the address offset of the
5366 first byte in PORT. This is useful, for example, when PORT
5367 specifies a 'bytevector' and you want the bytevector to be
5368 disassembled as if it came from that address. The START-PC passed
5369 to the reader for PORT is offset by the same amount.
5372 (gdb) guile (use-modules (rnrs io ports))
5373 (gdb) guile (define pc (value->integer (parse-and-eval "$pc")))
5374 (gdb) guile (define mem (open-memory #:start pc))
5375 (gdb) guile (define bv (get-bytevector-n mem 10))
5376 (gdb) guile (define bv-port (open-bytevector-input-port bv))
5377 (gdb) guile (define arch (current-arch))
5378 (gdb) guile (arch-disassemble arch pc #:port bv-port #:offset pc)
5379 (((address . 4195516) (asm . "mov $0x4005c8,%edi") (length . 5)))
5381 The optional arguments SIZE and COUNT determine the number of
5382 instructions in the returned list. If either SIZE or COUNT is
5383 specified as zero, then no instructions are disassembled and an
5384 empty list is returned. If both the optional arguments SIZE and
5385 COUNT are specified, then a list of at most COUNT disassembled
5386 instructions whose start address falls in the closed memory address
5387 interval from START-PC to (START-PC + SIZE - 1) are returned. If
5388 SIZE is not specified, but COUNT is specified, then COUNT number of
5389 instructions starting from the address START-PC are returned. If
5390 COUNT is not specified but SIZE is specified, then all instructions
5391 whose start address falls in the closed memory address interval
5392 from START-PC to (START-PC + SIZE - 1) are returned. If neither
5393 SIZE nor COUNT are specified, then a single instruction at START-PC
5396 Each element of the returned list is an alist (associative list)
5397 with the following keys:
5400 The value corresponding to this key is a Guile integer of the
5401 memory address of the instruction.
5404 The value corresponding to this key is a string value which
5405 represents the instruction with assembly language mnemonics.
5406 The assembly language flavor used is the same as that
5407 specified by the current CLI variable 'disassembly-flavor'.
5408 *Note Machine Code::.
5411 The value corresponding to this key is the length of the
5412 instruction in bytes.
5415 File: gdb.info, Node: I/O Ports in Guile, Next: Memory Ports in Guile, Prev: Disassembly In Guile, Up: Guile API
5417 23.4.3.23 I/O Ports in Guile
5418 ............................
5420 -- Scheme Procedure: input-port
5421 Return GDB's input port as a Guile port object.
5423 -- Scheme Procedure: output-port
5424 Return GDB's output port as a Guile port object.
5426 -- Scheme Procedure: error-port
5427 Return GDB's error port as a Guile port object.
5429 -- Scheme Procedure: stdio-port? object
5430 Return '#t' if OBJECT is a GDB stdio port. Otherwise return '#f'.
5433 File: gdb.info, Node: Memory Ports in Guile, Next: Iterators In Guile, Prev: I/O Ports in Guile, Up: Guile API
5435 23.4.3.24 Memory Ports in Guile
5436 ...............................
5438 GDB provides a 'port' interface to target memory. This allows Guile
5439 code to read/write target memory using Guile's port and bytevector
5440 functionality. The main routine is 'open-memory' which returns a port
5441 object. One can then read/write memory using that object.
5443 -- Scheme Procedure: open-memory [#:mode mode] [#:start address]
5445 Return a port object that can be used for reading and writing
5446 memory. The port will be open according to MODE, which is the
5447 standard mode argument to Guile port open routines, except that the
5448 '"a"' and '"l"' modes are not supported. *Note (guile)File
5449 Ports::. The '"b"' (binary) character may be present, but is
5450 ignored: memory ports are binary only. If '"0"' is appended then
5451 the port is marked as unbuffered. The default is '"r"', read-only
5454 The chunk of memory that can be accessed can be bounded. If both
5455 START and SIZE are unspecified, all of memory can be accessed. If
5456 only START is specified, all of memory from that point on can be
5457 accessed. If only SIZE if specified, all memory in the range
5458 [0,SIZE) can be accessed. If both are specified, all memory in the
5459 rane [START,START+SIZE) can be accessed.
5461 -- Scheme Procedure: memory-port?
5462 Return '#t' if OBJECT is an object of type '<gdb:memory-port>'.
5463 Otherwise return '#f'.
5465 -- Scheme Procedure: memory-port-range memory-port
5466 Return the range of '<gdb:memory-port>' MEMORY-PORT as a list of
5467 two elements: '(start end)'. The range is START to END inclusive.
5469 -- Scheme Procedure: memory-port-read-buffer-size memory-port
5470 Return the size of the read buffer of '<gdb:memory-port>'
5473 This procedure is deprecated and will be removed in GDB 11. It
5474 returns 0 when using Guile 2.2 or later.
5476 -- Scheme Procedure: set-memory-port-read-buffer-size! memory-port size
5477 Set the size of the read buffer of '<gdb:memory-port>' MEMORY-PORT
5478 to SIZE. The result is unspecified.
5480 This procedure is deprecated and will be removed in GDB 11. When
5481 GDB is built with Guile 2.2 or later, you can call 'setvbuf'
5482 instead (*note 'setvbuf': (guile)Buffering.).
5484 -- Scheme Procedure: memory-port-write-buffer-size memory-port
5485 Return the size of the write buffer of '<gdb:memory-port>'
5488 This procedure is deprecated and will be removed in GDB 11. It
5489 returns 0 when GDB is built with Guile 2.2 or later.
5491 -- Scheme Procedure: set-memory-port-write-buffer-size! memory-port
5493 Set the size of the write buffer of '<gdb:memory-port>' MEMORY-PORT
5494 to SIZE. The result is unspecified.
5496 This procedure is deprecated and will be removed in GDB 11. When
5497 GDB is built with Guile 2.2 or later, you can call 'setvbuf'
5500 A memory port is closed like any other port, with 'close-port'.
5502 Combined with Guile's 'bytevectors', memory ports provide a lot of
5503 utility. For example, to fill a buffer of 10 integers in memory, one
5504 can do something like the following.
5506 ;; In the program: int buffer[10];
5507 (use-modules (rnrs bytevectors))
5508 (use-modules (rnrs io ports))
5509 (define addr (parse-and-eval "buffer"))
5511 (define byte-size (* n 4))
5512 (define mem-port (open-memory #:mode "r+" #:start
5513 (value->integer addr) #:size byte-size))
5514 (define byte-vec (make-bytevector byte-size))
5517 (bytevector-s32-native-set! byte-vec (* i 4) (* i 42)))
5518 (put-bytevector mem-port byte-vec)
5519 (close-port mem-port)
5522 File: gdb.info, Node: Iterators In Guile, Prev: Memory Ports in Guile, Up: Guile API
5524 23.4.3.25 Iterators In Guile
5525 ............................
5527 A simple iterator facility is provided to allow, for example, iterating
5528 over the set of program symbols without having to first construct a list
5529 of all of them. A useful contribution would be to add support for SRFI
5532 -- Scheme Procedure: make-iterator object progress next!
5533 A '<gdb:iterator>' object is constructed with the 'make-iterator'
5534 procedure. It takes three arguments: the object to be iterated
5535 over, an object to record the progress of the iteration, and a
5536 procedure to return the next element in the iteration, or an
5537 implementation chosen value to denote the end of iteration.
5539 By convention, end of iteration is marked with
5540 '(end-of-iteration)', and may be tested with the
5541 'end-of-iteration?' predicate. The result of '(end-of-iteration)'
5542 is chosen so that it is not otherwise used by the '(gdb)' module.
5543 If you are using '<gdb:iterator>' in your own code it is your
5544 responsibility to maintain this invariant.
5546 A trivial example for illustration's sake:
5548 (use-modules (gdb iterator))
5549 (define my-list (list 1 2 3))
5551 (make-iterator my-list my-list
5553 (let ((l (iterator-progress iter)))
5557 (set-iterator-progress! iter (cdr l))
5560 Here is a slightly more realistic example, which computes a list of
5561 all the functions in 'my-global-block'.
5563 (use-modules (gdb iterator))
5564 (define this-sal (find-pc-line (frame-pc (selected-frame))))
5565 (define this-symtab (sal-symtab this-sal))
5566 (define this-global-block (symtab-global-block this-symtab))
5567 (define syms-iter (make-block-symbols-iterator this-global-block))
5568 (define functions (iterator-filter symbol-function? syms-iter))
5570 -- Scheme Procedure: iterator? object
5571 Return '#t' if OBJECT is a '<gdb:iterator>' object. Otherwise
5574 -- Scheme Procedure: iterator-object iterator
5575 Return the first argument that was passed to 'make-iterator'. This
5576 is the object being iterated over.
5578 -- Scheme Procedure: iterator-progress iterator
5579 Return the object tracking iteration progress.
5581 -- Scheme Procedure: set-iterator-progress! iterator new-value
5582 Set the object tracking iteration progress.
5584 -- Scheme Procedure: iterator-next! iterator
5585 Invoke the procedure that was the third argument to
5586 'make-iterator', passing it one argument, the '<gdb:iterator>'
5587 object. The result is either the next element in the iteration, or
5588 an end marker as implemented by the 'next!' procedure. By
5589 convention the end marker is the result of '(end-of-iteration)'.
5591 -- Scheme Procedure: end-of-iteration
5592 Return the Scheme object that denotes end of iteration.
5594 -- Scheme Procedure: end-of-iteration? object
5595 Return '#t' if OBJECT is the end of iteration marker. Otherwise
5598 These functions are provided by the '(gdb iterator)' module to assist
5601 -- Scheme Procedure: make-list-iterator list
5602 Return a '<gdb:iterator>' object that will iterate over LIST.
5604 -- Scheme Procedure: iterator->list iterator
5605 Return the elements pointed to by ITERATOR as a list.
5607 -- Scheme Procedure: iterator-map proc iterator
5608 Return the list of objects obtained by applying PROC to the object
5609 pointed to by ITERATOR and to each subsequent object.
5611 -- Scheme Procedure: iterator-for-each proc iterator
5612 Apply PROC to each element pointed to by ITERATOR. The result is
5615 -- Scheme Procedure: iterator-filter pred iterator
5616 Return the list of elements pointed to by ITERATOR that satisfy
5619 -- Scheme Procedure: iterator-until pred iterator
5620 Run ITERATOR until the result of '(pred element)' is true and
5621 return that as the result. Otherwise return '#f'.
5624 File: gdb.info, Node: Guile Auto-loading, Next: Guile Modules, Prev: Guile API, Up: Guile
5626 23.4.4 Guile Auto-loading
5627 -------------------------
5629 When a new object file is read (for example, due to the 'file' command,
5630 or because the inferior has loaded a shared library), GDB will look for
5631 Guile support scripts in two ways: 'OBJFILE-gdb.scm' and the
5632 '.debug_gdb_scripts' section. *Note Auto-loading extensions::.
5634 The auto-loading feature is useful for supplying application-specific
5635 debugging commands and scripts.
5637 Auto-loading can be enabled or disabled, and the list of auto-loaded
5638 scripts can be printed.
5640 'set auto-load guile-scripts [on|off]'
5641 Enable or disable the auto-loading of Guile scripts.
5643 'show auto-load guile-scripts'
5644 Show whether auto-loading of Guile scripts is enabled or disabled.
5646 'info auto-load guile-scripts [REGEXP]'
5647 Print the list of all Guile scripts that GDB auto-loaded.
5649 Also printed is the list of Guile scripts that were mentioned in
5650 the '.debug_gdb_scripts' section and were not found. This is
5651 useful because their names are not printed when GDB tries to load
5652 them and fails. There may be many of them, and printing an error
5653 message for each one is problematic.
5655 If REGEXP is supplied only Guile scripts with matching names are
5660 (gdb) info auto-load guile-scripts
5662 Yes scm-section-script.scm
5663 full name: /tmp/scm-section-script.scm
5664 No my-foo-pretty-printers.scm
5666 When reading an auto-loaded file, GDB sets the "current objfile".
5667 This is available via the 'current-objfile' procedure (*note Objfiles In
5668 Guile::). This can be useful for registering objfile-specific
5672 File: gdb.info, Node: Guile Modules, Prev: Guile Auto-loading, Up: Guile
5674 23.4.5 Guile Modules
5675 --------------------
5677 GDB comes with several modules to assist writing Guile code.
5681 * Guile Printing Module:: Building and registering pretty-printers
5682 * Guile Types Module:: Utilities for working with types
5685 File: gdb.info, Node: Guile Printing Module, Next: Guile Types Module, Up: Guile Modules
5687 23.4.5.1 Guile Printing Module
5688 ..............................
5690 This module provides a collection of utilities for working with
5695 (use-modules (gdb printing))
5697 -- Scheme Procedure: prepend-pretty-printer! object printer
5698 Add PRINTER to the front of the list of pretty-printers for OBJECT.
5699 The OBJECT must either be a '<gdb:objfile>' object, or '#f' in
5700 which case PRINTER is added to the global list of printers.
5702 -- Scheme Procecure: append-pretty-printer! object printer
5703 Add PRINTER to the end of the list of pretty-printers for OBJECT.
5704 The OBJECT must either be a '<gdb:objfile>' object, or '#f' in
5705 which case PRINTER is added to the global list of printers.
5708 File: gdb.info, Node: Guile Types Module, Prev: Guile Printing Module, Up: Guile Modules
5710 23.4.5.2 Guile Types Module
5711 ...........................
5713 This module provides a collection of utilities for working with
5714 '<gdb:type>' objects.
5718 (use-modules (gdb types))
5720 -- Scheme Procedure: get-basic-type type
5721 Return TYPE with const and volatile qualifiers stripped, and with
5722 typedefs and C++ references converted to the underlying type.
5726 typedef const int const_int;
5728 const_int& foo_ref (foo);
5729 int main () { return 0; }
5734 (gdb) guile (use-modules (gdb) (gdb types))
5735 (gdb) guile (define foo-ref (parse-and-eval "foo_ref"))
5736 (gdb) guile (get-basic-type (value-type foo-ref))
5739 -- Scheme Procedure: type-has-field-deep? type field
5740 Return '#t' if TYPE, assumed to be a type with fields (e.g., a
5741 structure or union), has field FIELD. Otherwise return '#f'. This
5742 searches baseclasses, whereas 'type-has-field?' does not.
5744 -- Scheme Procedure: make-enum-hashtable enum-type
5745 Return a Guile hash table produced from ENUM-TYPE. Elements in the
5746 hash table are referenced with 'hashq-ref'.
5749 File: gdb.info, Node: Auto-loading extensions, Next: Multiple Extension Languages, Prev: Guile, Up: Extending GDB
5751 23.5 Auto-loading extensions
5752 ============================
5754 GDB provides two mechanisms for automatically loading extensions when a
5755 new object file is read (for example, due to the 'file' command, or
5756 because the inferior has loaded a shared library): 'OBJFILE-gdb.EXT'
5757 (*note The 'OBJFILE-gdb.EXT' file: objfile-gdbdotext file.) and the
5758 '.debug_gdb_scripts' section of modern file formats like ELF (*note The
5759 '.debug_gdb_scripts' section: dotdebug_gdb_scripts section.). For a
5760 discussion of the differences between these two approaches see *note
5761 Which flavor to choose?::.
5763 The auto-loading feature is useful for supplying application-specific
5764 debugging commands and features.
5766 Auto-loading can be enabled or disabled, and the list of auto-loaded
5767 scripts can be printed. See the 'auto-loading' section of each
5768 extension language for more information. For GDB command files see
5769 *note Auto-loading sequences::. For Python files see *note Python
5772 Note that loading of this script file also requires accordingly
5773 configured 'auto-load safe-path' (*note Auto-loading safe path::).
5777 * objfile-gdbdotext file:: The 'OBJFILE-gdb.EXT' file
5778 * dotdebug_gdb_scripts section:: The '.debug_gdb_scripts' section
5779 * Which flavor to choose?:: Choosing between these approaches
5782 File: gdb.info, Node: objfile-gdbdotext file, Next: dotdebug_gdb_scripts section, Up: Auto-loading extensions
5784 23.5.1 The 'OBJFILE-gdb.EXT' file
5785 ---------------------------------
5787 When a new object file is read, GDB looks for a file named
5788 'OBJFILE-gdb.EXT' (we call it SCRIPT-NAME below), where OBJFILE is the
5789 object file's name and where EXT is the file extension for the extension
5793 GDB's own command language
5799 SCRIPT-NAME is formed by ensuring that the file name of OBJFILE is
5800 absolute, following all symlinks, and resolving '.' and '..' components,
5801 and appending the '-gdb.EXT' suffix. If this file exists and is
5802 readable, GDB will evaluate it as a script in the specified extension
5805 If this file does not exist, then GDB will look for SCRIPT-NAME file
5806 in all of the directories as specified below. (On MS-Windows/MS-DOS,
5807 the drive letter of the executable's leading directories is converted to
5808 a one-letter subdirectory, i.e. 'd:/usr/bin/' is converted to
5809 '/d/usr/bin/', because Windows filesystems disallow colons in file
5812 Note that loading of these files requires an accordingly configured
5813 'auto-load safe-path' (*note Auto-loading safe path::).
5815 For object files using '.exe' suffix GDB tries to load first the
5816 scripts normally according to its '.exe' filename. But if no scripts
5817 are found GDB also tries script filenames matching the object file
5818 without its '.exe' suffix. This '.exe' stripping is case insensitive
5819 and it is attempted on any platform. This makes the script filenames
5820 compatible between Unix and MS-Windows hosts.
5822 'set auto-load scripts-directory [DIRECTORIES]'
5823 Control GDB auto-loaded scripts location. Multiple directory
5824 entries may be delimited by the host platform path separator in use
5825 (':' on Unix, ';' on MS-Windows and MS-DOS).
5827 Each entry here needs to be covered also by the security setting
5828 'set auto-load safe-path' (*note set auto-load safe-path::).
5830 This variable defaults to '$debugdir:$datadir/auto-load'. The
5831 default 'set auto-load safe-path' value can be also overriden by
5832 GDB configuration option '--with-auto-load-dir'.
5834 Any reference to '$debugdir' will get replaced by
5835 DEBUG-FILE-DIRECTORY value (*note Separate Debug Files::) and any
5836 reference to '$datadir' will get replaced by DATA-DIRECTORY which
5837 is determined at GDB startup (*note Data Files::). '$debugdir' and
5838 '$datadir' must be placed as a directory component -- either alone
5839 or delimited by '/' or '\' directory separators, depending on the
5842 The list of directories uses path separator (':' on GNU and Unix
5843 systems, ';' on MS-Windows and MS-DOS) to separate directories,
5844 similarly to the 'PATH' environment variable.
5846 'show auto-load scripts-directory'
5847 Show GDB auto-loaded scripts location.
5849 'add-auto-load-scripts-directory [DIRECTORIES...]'
5850 Add an entry (or list of entries) to the list of auto-loaded
5851 scripts locations. Multiple entries may be delimited by the host
5852 platform path separator in use.
5854 GDB does not track which files it has already auto-loaded this way.
5855 GDB will load the associated script every time the corresponding OBJFILE
5856 is opened. So your '-gdb.EXT' file should be careful to avoid errors if
5857 it is evaluated more than once.
5860 File: gdb.info, Node: dotdebug_gdb_scripts section, Next: Which flavor to choose?, Prev: objfile-gdbdotext file, Up: Auto-loading extensions
5862 23.5.2 The '.debug_gdb_scripts' section
5863 ---------------------------------------
5865 For systems using file formats like ELF and COFF, when GDB loads a new
5866 object file it will look for a special section named
5867 '.debug_gdb_scripts'. If this section exists, its contents is a list of
5868 null-terminated entries specifying scripts to load. Each entry begins
5869 with a non-null prefix byte that specifies the kind of entry, typically
5870 the extension language and whether the script is in a file or inlined in
5871 '.debug_gdb_scripts'.
5873 The following entries are supported:
5875 'SECTION_SCRIPT_ID_PYTHON_FILE = 1'
5876 'SECTION_SCRIPT_ID_SCHEME_FILE = 3'
5877 'SECTION_SCRIPT_ID_PYTHON_TEXT = 4'
5878 'SECTION_SCRIPT_ID_SCHEME_TEXT = 6'
5880 23.5.2.1 Script File Entries
5881 ............................
5883 If the entry specifies a file, GDB will look for the file first in the
5884 current directory and then along the source search path (*note
5885 Specifying Source Directories: Source Path.), except that '$cdir' is not
5886 searched, since the compilation directory is not relevant to scripts.
5888 File entries can be placed in section '.debug_gdb_scripts' with, for
5889 example, this GCC macro for Python scripts.
5891 /* Note: The "MS" section flags are to remove duplicates. */
5892 #define DEFINE_GDB_PY_SCRIPT(script_name) \
5894 .pushsection \".debug_gdb_scripts\", \"MS\",@progbits,1\n\
5895 .byte 1 /* Python */\n\
5896 .asciz \"" script_name "\"\n\
5900 For Guile scripts, replace '.byte 1' with '.byte 3'. Then one can
5901 reference the macro in a header or source file like this:
5903 DEFINE_GDB_PY_SCRIPT ("my-app-scripts.py")
5905 The script name may include directories if desired.
5907 Note that loading of this script file also requires accordingly
5908 configured 'auto-load safe-path' (*note Auto-loading safe path::).
5910 If the macro invocation is put in a header, any application or
5911 library using this header will get a reference to the specified script,
5912 and with the use of '"MS"' attributes on the section, the linker will
5915 23.5.2.2 Script Text Entries
5916 ............................
5918 Script text entries allow to put the executable script in the entry
5919 itself instead of loading it from a file. The first line of the entry,
5920 everything after the prefix byte and up to the first newline ('0xa')
5921 character, is the script name, and must not contain any kind of space
5922 character, e.g., spaces or tabs. The rest of the entry, up to the
5923 trailing null byte, is the script to execute in the specified language.
5924 The name needs to be unique among all script names, as GDB executes each
5925 script only once based on its name.
5927 Here is an example from file 'py-section-script.c' in the GDB
5931 #include "gdb/section-scripts.h"
5933 ".pushsection \".debug_gdb_scripts\", \"MS\",@progbits,1\n"
5934 ".byte " XSTRING (SECTION_SCRIPT_ID_PYTHON_TEXT) "\n"
5935 ".ascii \"gdb.inlined-script\\n\"\n"
5936 ".ascii \"class test_cmd (gdb.Command):\\n\"\n"
5937 ".ascii \" def __init__ (self):\\n\"\n"
5938 ".ascii \" super (test_cmd, self).__init__ ("
5939 "\\\"test-cmd\\\", gdb.COMMAND_OBSCURE)\\n\"\n"
5940 ".ascii \" def invoke (self, arg, from_tty):\\n\"\n"
5941 ".ascii \" print (\\\"test-cmd output, arg = %s\\\" % arg)\\n\"\n"
5942 ".ascii \"test_cmd ()\\n\"\n"
5947 Loading of inlined scripts requires a properly configured 'auto-load
5948 safe-path' (*note Auto-loading safe path::). The path to specify in
5949 'auto-load safe-path' is the path of the file containing the
5950 '.debug_gdb_scripts' section.
5953 File: gdb.info, Node: Which flavor to choose?, Prev: dotdebug_gdb_scripts section, Up: Auto-loading extensions
5955 23.5.3 Which flavor to choose?
5956 ------------------------------
5958 Given the multiple ways of auto-loading extensions, it might not always
5959 be clear which one to choose. This section provides some guidance.
5961 Benefits of the '-gdb.EXT' way:
5963 * Can be used with file formats that don't support multiple sections.
5965 * Ease of finding scripts for public libraries.
5967 Scripts specified in the '.debug_gdb_scripts' section are searched
5968 for in the source search path. For publicly installed libraries,
5969 e.g., 'libstdc++', there typically isn't a source directory in
5970 which to find the script.
5972 * Doesn't require source code additions.
5974 Benefits of the '.debug_gdb_scripts' way:
5976 * Works with static linking.
5978 Scripts for libraries done the '-gdb.EXT' way require an objfile to
5979 trigger their loading. When an application is statically linked
5980 the only objfile available is the executable, and it is cumbersome
5981 to attach all the scripts from all the input libraries to the
5982 executable's '-gdb.EXT' script.
5984 * Works with classes that are entirely inlined.
5986 Some classes can be entirely inlined, and thus there may not be an
5987 associated shared library to attach a '-gdb.EXT' script to.
5989 * Scripts needn't be copied out of the source tree.
5991 In some circumstances, apps can be built out of large collections
5992 of internal libraries, and the build infrastructure necessary to
5993 install the '-gdb.EXT' scripts in a place where GDB can find them
5994 is cumbersome. It may be easier to specify the scripts in the
5995 '.debug_gdb_scripts' section as relative paths, and add a path to
5996 the top of the source tree to the source search path.
5999 File: gdb.info, Node: Multiple Extension Languages, Prev: Auto-loading extensions, Up: Extending GDB
6001 23.6 Multiple Extension Languages
6002 =================================
6004 The Guile and Python extension languages do not share any state, and
6005 generally do not interfere with each other. There are some things to be
6008 23.6.1 Python comes first
6009 -------------------------
6011 Python was GDB's first extension language, and to avoid breaking
6012 existing behaviour Python comes first. This is generally solved by the
6013 "first one wins" principle. GDB maintains a list of enabled extension
6014 languages, and when it makes a call to an extension language, (say to
6015 pretty-print a value), it tries each in turn until an extension language
6016 indicates it has performed the request (e.g., has returned the
6017 pretty-printed form of a value). This extends to errors while
6018 performing such requests: If an error happens while, for example, trying
6019 to pretty-print an object then the error is reported and any following
6020 extension languages are not tried.
6023 File: gdb.info, Node: Interpreters, Next: TUI, Prev: Extending GDB, Up: Top
6025 24 Command Interpreters
6026 ***********************
6028 GDB supports multiple command interpreters, and some command
6029 infrastructure to allow users or user interface writers to switch
6030 between interpreters or run commands in other interpreters.
6032 GDB currently supports two command interpreters, the console
6033 interpreter (sometimes called the command-line interpreter or CLI) and
6034 the machine interface interpreter (or GDB/MI). This manual describes
6035 both of these interfaces in great detail.
6037 By default, GDB will start with the console interpreter. However,
6038 the user may choose to start GDB with another interpreter by specifying
6039 the '-i' or '--interpreter' startup options. Defined interpreters
6043 The traditional console or command-line interpreter. This is the
6044 most often used interpreter with GDB. With no interpreter
6045 specified at runtime, GDB will use this interpreter.
6048 The newest GDB/MI interface (currently 'mi3'). Used primarily by
6049 programs wishing to use GDB as a backend for a debugger GUI or an
6050 IDE. For more information, see *note The GDB/MI Interface: GDB/MI.
6053 The GDB/MI interface introduced in GDB 9.1.
6056 The GDB/MI interface introduced in GDB 6.0.
6059 The GDB/MI interface introduced in GDB 5.1.
6061 You may execute commands in any interpreter from the current
6062 interpreter using the appropriate command. If you are running the
6063 console interpreter, simply use the 'interpreter-exec' command:
6065 interpreter-exec mi "-data-list-register-names"
6067 GDB/MI has a similar command, although it is only available in
6068 versions of GDB which support GDB/MI version 2 (or greater).
6070 Note that 'interpreter-exec' only changes the interpreter for the
6071 duration of the specified command. It does not change the interpreter
6074 Although you may only choose a single interpreter at startup, it is
6075 possible to run an independent interpreter on a specified input/output
6076 device (usually a tty).
6078 For example, consider a debugger GUI or IDE that wants to provide a
6079 GDB console view. It may do so by embedding a terminal emulator widget
6080 in its GUI, starting GDB in the traditional command-line mode with
6081 stdin/stdout/stderr redirected to that terminal, and then creating an MI
6082 interpreter running on a specified input/output device. The console
6083 interpreter created by GDB at startup handles commands the user types in
6084 the terminal widget, while the GUI controls and synchronizes state with
6085 GDB using the separate MI interpreter.
6087 To start a new secondary "user interface" running MI, use the
6090 new-ui INTERPRETER TTY
6092 The INTERPRETER parameter specifies the interpreter to run. This
6093 accepts the same values as the 'interpreter-exec' command. For example,
6094 'console', 'mi', 'mi2', etc. The TTY parameter specifies the name of
6095 the bidirectional file the interpreter uses for input/output, usually
6096 the name of a pseudoterminal slave on Unix systems. For example:
6098 (gdb) new-ui mi /dev/pts/9
6100 runs an MI interpreter on '/dev/pts/9'.
6103 File: gdb.info, Node: TUI, Next: Emacs, Prev: Interpreters, Up: Top
6105 25 GDB Text User Interface
6106 **************************
6108 The GDB Text User Interface (TUI) is a terminal interface which uses the
6109 'curses' library to show the source file, the assembly output, the
6110 program registers and GDB commands in separate text windows. The TUI
6111 mode is supported only on platforms where a suitable version of the
6112 'curses' library is available.
6114 The TUI mode is enabled by default when you invoke GDB as 'gdb -tui'.
6115 You can also switch in and out of TUI mode while GDB runs by using
6116 various TUI commands and key bindings, such as 'tui enable' or 'C-x
6117 C-a'. *Note TUI Commands: TUI Commands, and *note TUI Key Bindings: TUI
6122 * TUI Overview:: TUI overview
6123 * TUI Keys:: TUI key bindings
6124 * TUI Single Key Mode:: TUI single key mode
6125 * TUI Mouse Support:: TUI mouse support
6126 * TUI Commands:: TUI-specific commands
6127 * TUI Configuration:: TUI configuration variables
6130 File: gdb.info, Node: TUI Overview, Next: TUI Keys, Up: TUI
6135 In TUI mode, GDB can display several text windows:
6138 This window is the GDB command window with the GDB prompt and the
6139 GDB output. The GDB input is still managed using readline.
6142 The source window shows the source file of the program. The
6143 current line and active breakpoints are displayed in this window.
6146 The assembly window shows the disassembly output of the program.
6149 This window shows the processor registers. Registers are
6150 highlighted when their values change.
6152 The source and assembly windows show the current program position by
6153 highlighting the current line and marking it with a '>' marker. By
6154 default, source and assembly code styling is disabled for the
6155 highlighted text, but you can enable it with the 'set style
6156 tui-current-position on' command. *Note Output Styling::.
6158 Breakpoints are indicated with two markers. The first marker
6159 indicates the breakpoint type:
6162 Breakpoint which was hit at least once.
6165 Breakpoint which was never hit.
6168 Hardware breakpoint which was hit at least once.
6171 Hardware breakpoint which was never hit.
6173 The second marker indicates whether the breakpoint is enabled or not:
6176 Breakpoint is enabled.
6179 Breakpoint is disabled.
6181 The source, assembly and register windows are updated when the
6182 current thread changes, when the frame changes, or when the program
6185 These windows are not all visible at the same time. The command
6186 window is always visible. The others can be arranged in several
6193 * source and assembly,
6195 * source and registers, or
6197 * assembly and registers.
6199 These are the standard layouts, but other layouts can be defined.
6201 A status line above the command window shows the following
6205 Indicates the current GDB target. (*note Specifying a Debugging
6209 Gives the current process or thread number. When no process is
6210 being debugged, this field is set to 'No process'.
6213 Gives the current function name for the selected frame. The name
6214 is demangled if demangling is turned on (*note Print Settings::).
6215 When there is no symbol corresponding to the current program
6216 counter, the string '??' is displayed.
6219 Indicates the current line number for the selected frame. When the
6220 current line number is not known, the string '??' is displayed.
6223 Indicates the current program counter address.
6226 File: gdb.info, Node: TUI Keys, Next: TUI Single Key Mode, Prev: TUI Overview, Up: TUI
6228 25.2 TUI Key Bindings
6229 =====================
6231 The TUI installs several key bindings in the readline keymaps (*note
6232 Command Line Editing::). The following key bindings are installed for
6233 both TUI mode and the GDB standard mode.
6238 Enter or leave the TUI mode. When leaving the TUI mode, the curses
6239 window management stops and GDB operates using its standard mode,
6240 writing on the terminal directly. When reentering the TUI mode,
6241 control is given back to the curses windows. The screen is then
6244 This key binding uses the bindable Readline function
6248 Use a TUI layout with only one window. The layout will either be
6249 'source' or 'assembly'. When the TUI mode is not active, it will
6250 switch to the TUI mode.
6252 Think of this key binding as the Emacs 'C-x 1' binding.
6254 This key binding uses the bindable Readline function
6255 'tui-delete-other-windows'.
6258 Use a TUI layout with at least two windows. When the current
6259 layout already has two windows, the next layout with two windows is
6260 used. When a new layout is chosen, one window will always be
6261 common to the previous layout and the new one.
6263 Think of it as the Emacs 'C-x 2' binding.
6265 This key binding uses the bindable Readline function
6266 'tui-change-windows'.
6269 Change the active window. The TUI associates several key bindings
6270 (like scrolling and arrow keys) with the active window. This
6271 command gives the focus to the next TUI window.
6273 Think of it as the Emacs 'C-x o' binding.
6275 This key binding uses the bindable Readline function
6279 Switch in and out of the TUI SingleKey mode that binds single keys
6280 to GDB commands (*note TUI Single Key Mode::).
6282 This key binding uses the bindable Readline function 'next-keymap'.
6284 The following key bindings only work in the TUI mode:
6287 Scroll the active window one page up.
6290 Scroll the active window one page down.
6293 Scroll the active window one line up.
6296 Scroll the active window one line down.
6299 Scroll the active window one column left.
6302 Scroll the active window one column right.
6307 Because the arrow keys scroll the active window in the TUI mode, they
6308 are not available for their normal use by readline unless the command
6309 window has the focus. When another window is active, you must use other
6310 readline key bindings such as 'C-p', 'C-n', 'C-b' and 'C-f' to control
6314 File: gdb.info, Node: TUI Single Key Mode, Next: TUI Mouse Support, Prev: TUI Keys, Up: TUI
6316 25.3 TUI Single Key Mode
6317 ========================
6319 The TUI also provides a "SingleKey" mode, which binds several frequently
6320 used GDB commands to single keys. Type 'C-x s' to switch into this
6321 mode, where the following key bindings are used:
6336 nexti. The shortcut letter 'o' stands for "step Over".
6339 exit the SingleKey mode.
6348 stepi. The shortcut letter 'i' stands for "step Into".
6359 Other keys temporarily switch to the GDB command prompt. The key
6360 that was pressed is inserted in the editing buffer so that it is
6361 possible to type most GDB commands without interaction with the TUI
6362 SingleKey mode. Once the command is entered the TUI SingleKey mode is
6363 restored. The only way to permanently leave this mode is by typing 'q'
6366 If GDB was built with Readline 8.0 or later, the TUI SingleKey keymap
6367 will be named 'SingleKey'. This can be used in '.inputrc' to add
6368 additional bindings to this keymap.
6371 File: gdb.info, Node: TUI Mouse Support, Next: TUI Commands, Prev: TUI Single Key Mode, Up: TUI
6373 25.4 TUI Mouse Support
6374 ======================
6376 If the curses library supports the mouse, the TUI supports mouse
6379 The mouse wheel scrolls the appropriate window under the mouse
6382 The TUI itself does not directly support copying/pasting with the
6383 mouse. However, on Unix terminals, you can typically press and hold the
6384 <SHIFT> key on your keyboard to temporarily bypass GDB's TUI and access
6385 the terminal's native mouse copy/paste functionality (commonly,
6386 click-drag-release or double-click to select text, middle-click to
6387 paste). This copy/paste works with the terminal's selection buffer, as
6388 opposed to the TUI's buffer.
6391 File: gdb.info, Node: TUI Commands, Next: TUI Configuration, Prev: TUI Mouse Support, Up: TUI
6393 25.5 TUI-specific Commands
6394 ==========================
6396 The TUI has specific commands to control the text windows. These
6397 commands are always available, even when GDB is not in the TUI mode.
6398 When GDB is in the standard mode, most of these commands will
6399 automatically switch to the TUI mode.
6401 Note that if GDB's 'stdout' is not connected to a terminal, or GDB
6402 has been started with the machine interface interpreter (*note The
6403 GDB/MI Interface: GDB/MI.), most of these commands will fail with an
6404 error, because it would not be possible or desirable to enable curses
6408 Activate TUI mode. The last active TUI window layout will be used
6409 if TUI mode has previously been used in the current debugging
6410 session, otherwise a default layout is used.
6413 Disable TUI mode, returning to the console interpreter.
6416 List the names and sizes of all currently displayed windows.
6418 'tui new-layout NAME WINDOW WEIGHT [WINDOW WEIGHT...]'
6419 Create a new TUI layout. The new layout will be named NAME, and
6420 can be accessed using the 'layout' command (see below).
6422 Each WINDOW parameter is either the name of a window to display, or
6423 a window description. The windows will be displayed from top to
6424 bottom in the order listed.
6426 The names of the windows are the same as the ones given to the
6427 'focus' command (see below); additional, the 'status' window can be
6428 specified. Note that, because it is of fixed height, the weight
6429 assigned to the status window is of no importance. It is
6430 conventional to use '0' here.
6432 A window description looks a bit like an invocation of 'tui
6433 new-layout', and is of the form {['-horizontal']WINDOW WEIGHT
6434 [WINDOW WEIGHT...]}.
6436 This specifies a sub-layout. If '-horizontal' is given, the
6437 windows in this description will be arranged side-by-side, rather
6440 Each WEIGHT is an integer. It is the weight of this window
6441 relative to all the other windows in the layout. These numbers are
6442 used to calculate how much of the screen is given to each window.
6446 (gdb) tui new-layout example src 1 regs 1 status 0 cmd 1
6448 Here, the new layout is called 'example'. It shows the source and
6449 register windows, followed by the status window, and then finally
6450 the command window. The non-status windows all have the same
6451 weight, so the terminal will be split into three roughly equal
6454 Here is a more complex example, showing a horizontal layout:
6456 (gdb) tui new-layout example {-horizontal src 1 asm 1} 2 status 0 cmd 1
6458 This will result in side-by-side source and assembly windows; with
6459 the status and command window being beneath these, filling the
6460 entire width of the terminal. Because they have weight 2, the
6461 source and assembly windows will be twice the height of the command
6466 Changes which TUI windows are displayed. The NAME parameter
6467 controls which layout is shown. It can be either one of the
6468 built-in layout names, or the name of a layout defined by the user
6469 using 'tui new-layout'.
6471 The built-in layouts are as follows:
6474 Display the next layout.
6477 Display the previous layout.
6480 Display the source and command windows.
6483 Display the assembly and command windows.
6486 Display the source, assembly, and command windows.
6489 When in 'src' layout display the register, source, and command
6490 windows. When in 'asm' or 'split' layout display the
6491 register, assembler, and command windows.
6495 Changes which TUI window is currently active for scrolling. The
6496 NAME parameter can be any of the following:
6499 Make the next window active for scrolling.
6502 Make the previous window active for scrolling.
6505 Make the source window active for scrolling.
6508 Make the assembly window active for scrolling.
6511 Make the register window active for scrolling.
6514 Make the command window active for scrolling.
6518 Refresh the screen. This is similar to typing 'C-L'.
6521 Changes the register group displayed in the tui register window to
6522 GROUP. If the register window is not currently displayed this
6523 command will cause the register window to be displayed. The list
6524 of register groups, as well as their order is target specific. The
6525 following groups are available on most targets:
6527 Repeatedly selecting this group will cause the display to
6528 cycle through all of the available register groups.
6531 Repeatedly selecting this group will cause the display to
6532 cycle through all of the available register groups in the
6533 reverse order to NEXT.
6536 Display the general registers.
6538 Display the floating point registers.
6540 Display the system registers.
6542 Display the vector registers.
6544 Display all registers.
6547 Update the source window and the current execution point.
6549 'tui window height NAME +COUNT'
6550 'tui window height NAME -COUNT'
6551 'winheight NAME +COUNT'
6552 'winheight NAME -COUNT'
6553 Change the height of the window NAME by COUNT lines. Positive
6554 counts increase the height, while negative counts decrease it. The
6555 NAME parameter can be the name of any currently visible window.
6556 The names of the currently visible windows can be discovered using
6557 'info win' (*note info win: info_win_command.).
6559 The set of currently visible windows must always fill the terminal,
6560 and so, it is only possible to resize on window if there are other
6561 visible windows that can either give or receive the extra terminal
6564 'tui window width NAME +COUNT'
6565 'tui window width NAME -COUNT'
6566 'winwidth NAME +COUNT'
6567 'winwidth NAME -COUNT'
6568 Change the width of the window NAME by COUNT columns. Positive
6569 counts increase the width, while negative counts decrease it. The
6570 NAME parameter can be the name of any currently visible window.
6571 The names of the currently visible windows can be discovered using
6572 'info win' (*note info win: info_win_command.).
6574 The set of currently visible windows must always fill the terminal,
6575 and so, it is only possible to resize on window if there are other
6576 visible windows that can either give or receive the extra terminal
6580 File: gdb.info, Node: TUI Configuration, Prev: TUI Commands, Up: TUI
6582 25.6 TUI Configuration Variables
6583 ================================
6585 Several configuration variables control the appearance of TUI windows.
6587 'set tui border-kind KIND'
6588 Select the border appearance for the source, assembly and register
6589 windows. The possible values are the following:
6591 Use a space character to draw the border.
6594 Use ASCII characters '+', '-' and '|' to draw the border.
6597 Use the Alternate Character Set to draw the border. The
6598 border is drawn using character line graphics if the terminal
6601 'set tui border-mode MODE'
6602 'set tui active-border-mode MODE'
6603 Select the display attributes for the borders of the inactive
6604 windows or the active window. The MODE can be one of the
6607 Use normal attributes to display the border.
6613 Use reverse video mode.
6616 Use half bright mode.
6619 Use half bright and standout mode.
6622 Use extra bright or bold mode.
6625 Use extra bright or bold and standout mode.
6627 'set tui tab-width NCHARS'
6628 Set the width of tab stops to be NCHARS characters. This setting
6629 affects the display of TAB characters in the source and assembly
6632 'set tui compact-source [on|off]'
6633 Set whether the TUI source window is displayed in "compact" form.
6634 The default display uses more space for line numbers and starts the
6635 source text at the next tab stop; the compact display uses only as
6636 much space as is needed for the line numbers in the current file,
6637 and only a single space to separate the line numbers from the
6640 'set debug tui [on|off]'
6641 Turn on or off display of GDB internal debug messages relating to
6645 Show the current status of displaying GDB internal debug messages
6646 relating to the TUI.
6648 Note that the colors of the TUI borders can be controlled using the
6649 appropriate 'set style' commands. *Note Output Styling::.
6652 File: gdb.info, Node: Emacs, Next: GDB/MI, Prev: TUI, Up: Top
6654 26 Using GDB under GNU Emacs
6655 ****************************
6657 A special interface allows you to use GNU Emacs to view (and edit) the
6658 source files for the program you are debugging with GDB.
6660 To use this interface, use the command 'M-x gdb' in Emacs. Give the
6661 executable file you want to debug as an argument. This command starts
6662 GDB as a subprocess of Emacs, with input and output through a newly
6663 created Emacs buffer.
6665 Running GDB under Emacs can be just like running GDB normally except
6668 * All "terminal" input and output goes through an Emacs buffer,
6669 called the GUD buffer.
6671 This applies both to GDB commands and their output, and to the
6672 input and output done by the program you are debugging.
6674 This is useful because it means that you can copy the text of
6675 previous commands and input them again; you can even use parts of
6676 the output in this way.
6678 All the facilities of Emacs' Shell mode are available for
6679 interacting with your program. In particular, you can send signals
6680 the usual way--for example, 'C-c C-c' for an interrupt, 'C-c C-z'
6683 * GDB displays source code through Emacs.
6685 Each time GDB displays a stack frame, Emacs automatically finds the
6686 source file for that frame and puts an arrow ('=>') at the left
6687 margin of the current line. Emacs uses a separate buffer for
6688 source display, and splits the screen to show both your GDB session
6691 Explicit GDB 'list' or search commands still produce output as
6692 usual, but you probably have no reason to use them from Emacs.
6694 We call this "text command mode". Emacs 22.1, and later, also uses a
6695 graphical mode, enabled by default, which provides further buffers that
6696 can control the execution and describe the state of your program. *Note
6697 (Emacs)GDB Graphical Interface::.
6699 If you specify an absolute file name when prompted for the 'M-x gdb'
6700 argument, then Emacs sets your current working directory to where your
6701 program resides. If you only specify the file name, then Emacs sets
6702 your current working directory to the directory associated with the
6703 previous buffer. In this case, GDB may find your program by searching
6704 your environment's 'PATH' variable, but on some operating systems it
6705 might not find the source. So, although the GDB input and output
6706 session proceeds normally, the auxiliary buffer does not display the
6707 current source and line of execution.
6709 The initial working directory of GDB is printed on the top line of
6710 the GUD buffer and this serves as a default for the commands that
6711 specify files for GDB to operate on. *Note Commands to Specify Files:
6714 By default, 'M-x gdb' calls the program called 'gdb'. If you need to
6715 call GDB by a different name (for example, if you keep several
6716 configurations around, with different names) you can customize the Emacs
6717 variable 'gud-gdb-command-name' to run the one you want.
6719 In the GUD buffer, you can use these special Emacs commands in
6720 addition to the standard Shell mode commands:
6723 Describe the features of Emacs' GUD Mode.
6726 Execute to another source line, like the GDB 'step' command; also
6727 update the display window to show the current file and location.
6730 Execute to next source line in this function, skipping all function
6731 calls, like the GDB 'next' command. Then update the display window
6732 to show the current file and location.
6735 Execute one instruction, like the GDB 'stepi' command; update
6736 display window accordingly.
6739 Execute until exit from the selected stack frame, like the GDB
6743 Continue execution of your program, like the GDB 'continue'
6747 Go up the number of frames indicated by the numeric argument (*note
6748 Numeric Arguments: (Emacs)Arguments.), like the GDB 'up' command.
6751 Go down the number of frames indicated by the numeric argument,
6752 like the GDB 'down' command.
6754 In any source file, the Emacs command 'C-x <SPC>' ('gud-break') tells
6755 GDB to set a breakpoint on the source line point is on.
6757 In text command mode, if you type 'M-x speedbar', Emacs displays a
6758 separate frame which shows a backtrace when the GUD buffer is current.
6759 Move point to any frame in the stack and type <RET> to make it become
6760 the current frame and display the associated source in the source
6761 buffer. Alternatively, click 'Mouse-2' to make the selected frame
6762 become the current one. In graphical mode, the speedbar displays watch
6765 If you accidentally delete the source-display buffer, an easy way to
6766 get it back is to type the command 'f' in the GDB buffer, to request a
6767 frame display; when you run under Emacs, this recreates the source
6768 buffer if necessary to show you the context of the current frame.
6770 The source files displayed in Emacs are in ordinary Emacs buffers
6771 which are visiting the source files in the usual way. You can edit the
6772 files with these buffers if you wish; but keep in mind that GDB
6773 communicates with Emacs in terms of line numbers. If you add or delete
6774 lines from the text, the line numbers that GDB knows cease to correspond
6775 properly with the code.
6777 A more detailed description of Emacs' interaction with GDB is given
6778 in the Emacs manual (*note (Emacs)Debuggers::).
6781 File: gdb.info, Node: GDB/MI, Next: Annotations, Prev: Emacs, Up: Top
6783 27 The GDB/MI Interface
6784 ***********************
6788 * GDB/MI General Design::
6789 * GDB/MI Command Syntax::
6790 * GDB/MI Compatibility with CLI::
6791 * GDB/MI Development and Front Ends::
6792 * GDB/MI Output Records::
6793 * GDB/MI Simple Examples::
6794 * GDB/MI Command Description Format::
6795 * GDB/MI Breakpoint Commands::
6796 * GDB/MI Catchpoint Commands::
6797 * GDB/MI Program Context::
6798 * GDB/MI Thread Commands::
6799 * GDB/MI Ada Tasking Commands::
6800 * GDB/MI Program Execution::
6801 * GDB/MI Stack Manipulation::
6802 * GDB/MI Variable Objects::
6803 * GDB/MI Data Manipulation::
6804 * GDB/MI Tracepoint Commands::
6805 * GDB/MI Symbol Query::
6806 * GDB/MI File Commands::
6807 * GDB/MI Target Manipulation::
6808 * GDB/MI File Transfer Commands::
6809 * GDB/MI Ada Exceptions Commands::
6810 * GDB/MI Support Commands::
6811 * GDB/MI Miscellaneous Commands::
6813 Function and Purpose
6814 ====================
6816 GDB/MI is a line based machine oriented text interface to GDB and is
6817 activated by specifying using the '--interpreter' command line option
6818 (*note Mode Options::). It is specifically intended to support the
6819 development of systems which use the debugger as just one small
6820 component of a larger system.
6822 This chapter is a specification of the GDB/MI interface. It is
6823 written in the form of a reference manual.
6825 Note that GDB/MI is still under construction, so some of the features
6826 described below are incomplete and subject to change (*note GDB/MI
6827 Development and Front Ends: GDB/MI Development and Front Ends.).
6829 Notation and Terminology
6830 ========================
6832 This chapter uses the following notation:
6834 * '|' separates two alternatives.
6836 * '[ SOMETHING ]' indicates that SOMETHING is optional: it may or may
6839 * '( GROUP )*' means that GROUP inside the parentheses may repeat
6842 * '( GROUP )+' means that GROUP inside the parentheses may repeat one
6845 * '( GROUP )' means that GROUP inside the parentheses occurs exactly
6848 * '"STRING"' means a literal STRING.
6852 * GDB/MI General Design::
6853 * GDB/MI Command Syntax::
6854 * GDB/MI Compatibility with CLI::
6855 * GDB/MI Development and Front Ends::
6856 * GDB/MI Output Records::
6857 * GDB/MI Simple Examples::
6858 * GDB/MI Command Description Format::
6859 * GDB/MI Breakpoint Commands::
6860 * GDB/MI Catchpoint Commands::
6861 * GDB/MI Program Context::
6862 * GDB/MI Thread Commands::
6863 * GDB/MI Ada Tasking Commands::
6864 * GDB/MI Program Execution::
6865 * GDB/MI Stack Manipulation::
6866 * GDB/MI Variable Objects::
6867 * GDB/MI Data Manipulation::
6868 * GDB/MI Tracepoint Commands::
6869 * GDB/MI Symbol Query::
6870 * GDB/MI File Commands::
6871 * GDB/MI Target Manipulation::
6872 * GDB/MI File Transfer Commands::
6873 * GDB/MI Ada Exceptions Commands::
6874 * GDB/MI Support Commands::
6875 * GDB/MI Miscellaneous Commands::
6878 File: gdb.info, Node: GDB/MI General Design, Next: GDB/MI Command Syntax, Up: GDB/MI
6880 27.1 GDB/MI General Design
6881 ==========================
6883 Interaction of a GDB/MI frontend with GDB involves three parts--commands
6884 sent to GDB, responses to those commands and notifications. Each
6885 command results in exactly one response, indicating either successful
6886 completion of the command, or an error. For the commands that do not
6887 resume the target, the response contains the requested information. For
6888 the commands that resume the target, the response only indicates whether
6889 the target was successfully resumed. Notifications is the mechanism for
6890 reporting changes in the state of the target, or in GDB state, that
6891 cannot conveniently be associated with a command and reported as part of
6892 that command response.
6894 The important examples of notifications are:
6896 * Exec notifications. These are used to report changes in target
6897 state--when a target is resumed, or stopped. It would not be
6898 feasible to include this information in response of resuming
6899 commands, because one resume commands can result in multiple events
6900 in different threads. Also, quite some time may pass before any
6901 event happens in the target, while a frontend needs to know whether
6902 the resuming command itself was successfully executed.
6904 * Console output, and status notifications. Console output
6905 notifications are used to report output of CLI commands, as well as
6906 diagnostics for other commands. Status notifications are used to
6907 report the progress of a long-running operation. Naturally,
6908 including this information in command response would mean no output
6909 is produced until the command is finished, which is undesirable.
6911 * General notifications. Commands may have various side effects on
6912 the GDB or target state beyond their official purpose. For
6913 example, a command may change the selected thread. Although such
6914 changes can be included in command response, using notification
6915 allows for more orthogonal frontend design.
6917 There's no guarantee that whenever an MI command reports an error,
6918 GDB or the target are in any specific state, and especially, the state
6919 is not reverted to the state before the MI command was processed.
6920 Therefore, whenever an MI command results in an error, we recommend that
6921 the frontend refreshes all the information shown in the user interface.
6925 * Context management::
6926 * Asynchronous and non-stop modes::
6930 File: gdb.info, Node: Context management, Next: Asynchronous and non-stop modes, Up: GDB/MI General Design
6932 27.1.1 Context management
6933 -------------------------
6935 27.1.1.1 Threads and Frames
6936 ...........................
6938 In most cases when GDB accesses the target, this access is done in
6939 context of a specific thread and frame (*note Frames::). Often, even
6940 when accessing global data, the target requires that a thread be
6941 specified. The CLI interface maintains the selected thread and frame,
6942 and supplies them to target on each command. This is convenient,
6943 because a command line user would not want to specify that information
6944 explicitly on each command, and because user interacts with GDB via a
6945 single terminal, so no confusion is possible as to what thread and frame
6946 are the current ones.
6948 In the case of MI, the concept of selected thread and frame is less
6949 useful. First, a frontend can easily remember this information itself.
6950 Second, a graphical frontend can have more than one window, each one
6951 used for debugging a different thread, and the frontend might want to
6952 access additional threads for internal purposes. This increases the
6953 risk that by relying on implicitly selected thread, the frontend may be
6954 operating on a wrong one. Therefore, each MI command should explicitly
6955 specify which thread and frame to operate on. To make it possible, each
6956 MI command accepts the '--thread' and '--frame' options, the value to
6957 each is GDB global identifier for thread and frame to operate on.
6959 Usually, each top-level window in a frontend allows the user to
6960 select a thread and a frame, and remembers the user selection for
6961 further operations. However, in some cases GDB may suggest that the
6962 current thread or frame be changed. For example, when stopping on a
6963 breakpoint it is reasonable to switch to the thread where breakpoint is
6964 hit. For another example, if the user issues the CLI 'thread' or
6965 'frame' commands via the frontend, it is desirable to change the
6966 frontend's selection to the one specified by user. GDB communicates the
6967 suggestion to change current thread and frame using the
6968 '=thread-selected' notification.
6970 Note that historically, MI shares the selected thread with CLI, so
6971 frontends used the '-thread-select' to execute commands in the right
6972 context. However, getting this to work right is cumbersome. The
6973 simplest way is for frontend to emit '-thread-select' command before
6974 every command. This doubles the number of commands that need to be
6975 sent. The alternative approach is to suppress '-thread-select' if the
6976 selected thread in GDB is supposed to be identical to the thread the
6977 frontend wants to operate on. However, getting this optimization right
6978 can be tricky. In particular, if the frontend sends several commands to
6979 GDB, and one of the commands changes the selected thread, then the
6980 behaviour of subsequent commands will change. So, a frontend should
6981 either wait for response from such problematic commands, or explicitly
6982 add '-thread-select' for all subsequent commands. No frontend is known
6983 to do this exactly right, so it is suggested to just always pass the
6984 '--thread' and '--frame' options.
6989 The execution of several commands depends on which language is selected.
6990 By default, the current language (*note show language::) is used. But
6991 for commands known to be language-sensitive, it is recommended to use
6992 the '--language' option. This option takes one argument, which is the
6993 name of the language to use while executing the command. For instance:
6995 -data-evaluate-expression --language c "sizeof (void*)"
6999 The valid language names are the same names accepted by the 'set
7000 language' command (*note Manually::), excluding 'auto', 'local' or
7004 File: gdb.info, Node: Asynchronous and non-stop modes, Next: Thread groups, Prev: Context management, Up: GDB/MI General Design
7006 27.1.2 Asynchronous command execution and non-stop mode
7007 -------------------------------------------------------
7009 On some targets, GDB is capable of processing MI commands even while the
7010 target is running. This is called "asynchronous command execution"
7011 (*note Background Execution::). The frontend may specify a preference
7012 for asynchronous execution using the '-gdb-set mi-async 1' command,
7013 which should be emitted before either running the executable or
7014 attaching to the target. After the frontend has started the executable
7015 or attached to the target, it can find if asynchronous execution is
7016 enabled using the '-list-target-features' command.
7018 '-gdb-set mi-async [on|off]'
7019 Set whether MI is in asynchronous mode.
7021 When 'off', which is the default, MI execution commands (e.g.,
7022 '-exec-continue') are foreground commands, and GDB waits for the
7023 program to stop before processing further commands.
7025 When 'on', MI execution commands are background execution commands
7026 (e.g., '-exec-continue' becomes the equivalent of the 'c&' CLI
7027 command), and so GDB is capable of processing MI commands even
7028 while the target is running.
7030 '-gdb-show mi-async'
7031 Show whether MI asynchronous mode is enabled.
7033 Note: In GDB version 7.7 and earlier, this option was called
7034 'target-async' instead of 'mi-async', and it had the effect of both
7035 putting MI in asynchronous mode and making CLI background commands
7036 possible. CLI background commands are now always possible "out of the
7037 box" if the target supports them. The old spelling is kept as a
7038 deprecated alias for backwards compatibility.
7040 Even if GDB can accept a command while target is running, many
7041 commands that access the target do not work when the target is running.
7042 Therefore, asynchronous command execution is most useful when combined
7043 with non-stop mode (*note Non-Stop Mode::). Then, it is possible to
7044 examine the state of one thread, while other threads are running.
7046 When a given thread is running, MI commands that try to access the
7047 target in the context of that thread may not work, or may work only on
7048 some targets. In particular, commands that try to operate on thread's
7049 stack will not work, on any target. Commands that read memory, or
7050 modify breakpoints, may work or not work, depending on the target. Note
7051 that even commands that operate on global state, such as 'print', 'set',
7052 and breakpoint commands, still access the target in the context of a
7053 specific thread, so frontend should try to find a stopped thread and
7054 perform the operation on that thread (using the '--thread' option).
7056 Which commands will work in the context of a running thread is highly
7057 target dependent. However, the two commands '-exec-interrupt', to stop
7058 a thread, and '-thread-info', to find the state of a thread, will always
7062 File: gdb.info, Node: Thread groups, Prev: Asynchronous and non-stop modes, Up: GDB/MI General Design
7064 27.1.3 Thread groups
7065 --------------------
7067 GDB may be used to debug several processes at the same time. On some
7068 platforms, GDB may support debugging of several hardware systems, each
7069 one having several cores with several different processes running on
7070 each core. This section describes the MI mechanism to support such
7071 debugging scenarios.
7073 The key observation is that regardless of the structure of the
7074 target, MI can have a global list of threads, because most commands that
7075 accept the '--thread' option do not need to know what process that
7076 thread belongs to. Therefore, it is not necessary to introduce neither
7077 additional '--process' option, nor an notion of the current process in
7078 the MI interface. The only strictly new feature that is required is the
7079 ability to find how the threads are grouped into processes.
7081 To allow the user to discover such grouping, and to support arbitrary
7082 hierarchy of machines/cores/processes, MI introduces the concept of a
7083 "thread group". Thread group is a collection of threads and other
7084 thread groups. A thread group always has a string identifier, a type,
7085 and may have additional attributes specific to the type. A new command,
7086 '-list-thread-groups', returns the list of top-level thread groups,
7087 which correspond to processes that GDB is debugging at the moment. By
7088 passing an identifier of a thread group to the '-list-thread-groups'
7089 command, it is possible to obtain the members of specific thread group.
7091 To allow the user to easily discover processes, and other objects, he
7092 wishes to debug, a concept of "available thread group" is introduced.
7093 Available thread group is an thread group that GDB is not debugging, but
7094 that can be attached to, using the '-target-attach' command. The list
7095 of available top-level thread groups can be obtained using
7096 '-list-thread-groups --available'. In general, the content of a thread
7097 group may be only retrieved only after attaching to that thread group.
7099 Thread groups are related to inferiors (*note Inferiors Connections
7100 and Programs::). Each inferior corresponds to a thread group of a
7101 special type 'process', and some additional operations are permitted on
7105 File: gdb.info, Node: GDB/MI Command Syntax, Next: GDB/MI Compatibility with CLI, Prev: GDB/MI General Design, Up: GDB/MI
7107 27.2 GDB/MI Command Syntax
7108 ==========================
7112 * GDB/MI Input Syntax::
7113 * GDB/MI Output Syntax::
7116 File: gdb.info, Node: GDB/MI Input Syntax, Next: GDB/MI Output Syntax, Up: GDB/MI Command Syntax
7118 27.2.1 GDB/MI Input Syntax
7119 --------------------------
7122 'CLI-COMMAND | MI-COMMAND'
7125 '[ TOKEN ] CLI-COMMAND NL', where CLI-COMMAND is any existing GDB
7129 '[ TOKEN ] "-" OPERATION ( " " OPTION )* [ " --" ] ( " " PARAMETER
7133 "any sequence of digits"
7136 '"-" PARAMETER [ " " PARAMETER ]'
7139 'NON-BLANK-SEQUENCE | C-STRING'
7142 _any of the operations described in this chapter_
7144 'NON-BLANK-SEQUENCE ==>'
7145 _anything, provided it doesn't contain special characters such as
7146 "-", NL, """ and of course " "_
7149 '""" SEVEN-BIT-ISO-C-STRING-CONTENT """'
7156 * The CLI commands are still handled by the MI interpreter; their
7157 output is described below.
7159 * The 'TOKEN', when present, is passed back when the command
7162 * Some MI commands accept optional arguments as part of the parameter
7163 list. Each option is identified by a leading '-' (dash) and may be
7164 followed by an optional argument parameter. Options occur first in
7165 the parameter list and can be delimited from normal parameters
7166 using '--' (this is useful when some parameters begin with a dash).
7170 * We want easy access to the existing CLI syntax (for debugging).
7172 * We want it to be easy to spot a MI operation.
7175 File: gdb.info, Node: GDB/MI Output Syntax, Prev: GDB/MI Input Syntax, Up: GDB/MI Command Syntax
7177 27.2.2 GDB/MI Output Syntax
7178 ---------------------------
7180 The output from GDB/MI consists of zero or more out-of-band records
7181 followed, optionally, by a single result record. This result record is
7182 for the most recent command. The sequence of output records is
7183 terminated by '(gdb)'.
7185 If an input command was prefixed with a 'TOKEN' then the
7186 corresponding output for that command will also be prefixed by that same
7190 '( OUT-OF-BAND-RECORD )* [ RESULT-RECORD ] "(gdb)" NL'
7193 ' [ TOKEN ] "^" RESULT-CLASS ( "," RESULT )* NL'
7195 'OUT-OF-BAND-RECORD ==>'
7196 'ASYNC-RECORD | STREAM-RECORD'
7199 'EXEC-ASYNC-OUTPUT | STATUS-ASYNC-OUTPUT | NOTIFY-ASYNC-OUTPUT'
7201 'EXEC-ASYNC-OUTPUT ==>'
7202 '[ TOKEN ] "*" ASYNC-OUTPUT NL'
7204 'STATUS-ASYNC-OUTPUT ==>'
7205 '[ TOKEN ] "+" ASYNC-OUTPUT NL'
7207 'NOTIFY-ASYNC-OUTPUT ==>'
7208 '[ TOKEN ] "=" ASYNC-OUTPUT NL'
7211 'ASYNC-CLASS ( "," RESULT )*'
7214 '"done" | "running" | "connected" | "error" | "exit"'
7217 '"stopped" | OTHERS' (where OTHERS will be added depending on the
7218 needs--this is still in development).
7221 ' VARIABLE "=" VALUE'
7227 ' CONST | TUPLE | LIST '
7233 ' "{}" | "{" RESULT ( "," RESULT )* "}" '
7236 ' "[]" | "[" VALUE ( "," VALUE )* "]" | "[" RESULT ( "," RESULT )*
7240 'CONSOLE-STREAM-OUTPUT | TARGET-STREAM-OUTPUT | LOG-STREAM-OUTPUT'
7242 'CONSOLE-STREAM-OUTPUT ==>'
7245 'TARGET-STREAM-OUTPUT ==>'
7248 'LOG-STREAM-OUTPUT ==>'
7255 _any sequence of digits_.
7259 * All output sequences end in a single line containing a period.
7261 * The 'TOKEN' is from the corresponding request. Note that for all
7262 async output, while the token is allowed by the grammar and may be
7263 output by future versions of GDB for select async output messages,
7264 it is generally omitted. Frontends should treat all async output
7265 as reporting general changes in the state of the target and there
7266 should be no need to associate async output to any prior command.
7268 * STATUS-ASYNC-OUTPUT contains on-going status information about the
7269 progress of a slow operation. It can be discarded. All status
7270 output is prefixed by '+'.
7272 * EXEC-ASYNC-OUTPUT contains asynchronous state change on the target
7273 (stopped, started, disappeared). All async output is prefixed by
7276 * NOTIFY-ASYNC-OUTPUT contains supplementary information that the
7277 client should handle (e.g., a new breakpoint information). All
7278 notify output is prefixed by '='.
7280 * CONSOLE-STREAM-OUTPUT is output that should be displayed as is in
7281 the console. It is the textual response to a CLI command. All the
7282 console output is prefixed by '~'.
7284 * TARGET-STREAM-OUTPUT is the output produced by the target program.
7285 All the target output is prefixed by '@'.
7287 * LOG-STREAM-OUTPUT is output text coming from GDB's internals, for
7288 instance messages that should be displayed as part of an error log.
7289 All the log output is prefixed by '&'.
7291 * New GDB/MI commands should only output LISTS containing VALUES.
7293 *Note GDB/MI Stream Records: GDB/MI Stream Records, for more details
7294 about the various output records.
7297 File: gdb.info, Node: GDB/MI Compatibility with CLI, Next: GDB/MI Development and Front Ends, Prev: GDB/MI Command Syntax, Up: GDB/MI
7299 27.3 GDB/MI Compatibility with CLI
7300 ==================================
7302 For the developers convenience CLI commands can be entered directly, but
7303 there may be some unexpected behaviour. For example, commands that
7304 query the user will behave as if the user replied yes, breakpoint
7305 command lists are not executed and some CLI commands, such as 'if',
7306 'when' and 'define', prompt for further input with '>', which is not
7309 This feature may be removed at some stage in the future and it is
7310 recommended that front ends use the '-interpreter-exec' command (*note
7311 -interpreter-exec::).
7314 File: gdb.info, Node: GDB/MI Development and Front Ends, Next: GDB/MI Output Records, Prev: GDB/MI Compatibility with CLI, Up: GDB/MI
7316 27.4 GDB/MI Development and Front Ends
7317 ======================================
7319 The application which takes the MI output and presents the state of the
7320 program being debugged to the user is called a "front end".
7322 Since GDB/MI is used by a variety of front ends to GDB, changes to
7323 the MI interface may break existing usage. This section describes how
7324 the protocol changes and how to request previous version of the protocol
7327 Some changes in MI need not break a carefully designed front end, and
7328 for these the MI version will remain unchanged. The following is a list
7329 of changes that may occur within one level, so front ends should parse
7330 MI output in a way that can handle them:
7332 * New MI commands may be added.
7334 * New fields may be added to the output of any MI command.
7336 * The range of values for fields with specified values, e.g.,
7337 'in_scope' (*note -var-update::) may be extended.
7339 If the changes are likely to break front ends, the MI version level
7340 will be increased by one. The new versions of the MI protocol are not
7341 compatible with the old versions. Old versions of MI remain available,
7342 allowing front ends to keep using them until they are modified to use
7343 the latest MI version.
7345 Since '--interpreter=mi' always points to the latest MI version, it
7346 is recommended that front ends request a specific version of MI when
7347 launching GDB (e.g. '--interpreter=mi2') to make sure they get an
7348 interpreter with the MI version they expect.
7350 The following table gives a summary of the released versions of the
7351 MI interface: the version number, the version of GDB in which it first
7352 appeared and the breaking changes compared to the previous version.
7354 MI GDB Breaking changes
7356 ---------------------------------------------------------------------------
7360 * The '-environment-pwd', '-environment-directory'
7361 and '-environment-path' commands now returns values
7362 using the MI output syntax, rather than CLI output
7365 * '-var-list-children''s 'children' result field is
7366 now a list, rather than a tuple.
7368 * '-var-update''s 'changelist' result field is now a
7369 list, rather than a tuple.
7372 * The output of information about multi-location
7373 breakpoints has changed in the responses to the
7374 '-break-insert' and '-break-info' commands, as well
7375 as in the '=breakpoint-created' and
7376 '=breakpoint-modified' events. The multiple
7377 locations are now placed in a 'locations' field,
7378 whose value is a list.
7381 * The syntax of the "script" field in breakpoint
7382 output has changed in the responses to the
7383 '-break-insert' and '-break-info' commands, as well
7384 as the '=breakpoint-created' and
7385 '=breakpoint-modified' events. The previous output
7386 was syntactically invalid. The new output is a
7390 If your front end cannot yet migrate to a more recent version of the
7391 MI protocol, you can nevertheless selectively enable specific features
7392 available in those recent MI versions, using the following commands:
7394 '-fix-multi-location-breakpoint-output'
7395 Use the output for multi-location breakpoints which was introduced
7396 by MI 3, even when using MI versions below 3. This command has no
7397 effect when using MI version 3 or later.
7399 '-fix-breakpoint-script-output'
7400 Use the output for the breakpoint "script" field which was
7401 introduced by MI 4, even when using MI versions below 4. This
7402 command has no effect when using MI version 4 or later.
7404 The best way to avoid unexpected changes in MI that might break your
7405 front end is to make your project known to GDB developers and follow
7406 development on <gdb@sourceware.org> and <gdb-patches@sourceware.org>.
7409 File: gdb.info, Node: GDB/MI Output Records, Next: GDB/MI Simple Examples, Prev: GDB/MI Development and Front Ends, Up: GDB/MI
7411 27.5 GDB/MI Output Records
7412 ==========================
7416 * GDB/MI Result Records::
7417 * GDB/MI Stream Records::
7418 * GDB/MI Async Records::
7419 * GDB/MI Breakpoint Information::
7420 * GDB/MI Frame Information::
7421 * GDB/MI Thread Information::
7422 * GDB/MI Ada Exception Information::
7425 File: gdb.info, Node: GDB/MI Result Records, Next: GDB/MI Stream Records, Up: GDB/MI Output Records
7427 27.5.1 GDB/MI Result Records
7428 ----------------------------
7430 In addition to a number of out-of-band notifications, the response to a
7431 GDB/MI command includes one of the following result indications:
7433 '"^done" [ "," RESULTS ]'
7434 The synchronous operation was successful, 'RESULTS' are the return
7438 This result record is equivalent to '^done'. Historically, it was
7439 output instead of '^done' if the command has resumed the target.
7440 This behaviour is maintained for backward compatibility, but all
7441 frontends should treat '^done' and '^running' identically and rely
7442 on the '*running' output record to determine which threads are
7446 GDB has connected to a remote target.
7448 '"^error" "," "msg=" C-STRING [ "," "code=" C-STRING ]'
7449 The operation failed. The 'msg=C-STRING' variable contains the
7450 corresponding error message.
7452 If present, the 'code=C-STRING' variable provides an error code on
7453 which consumers can rely on to detect the corresponding error
7454 condition. At present, only one error code is defined:
7456 '"undefined-command"'
7457 Indicates that the command causing the error does not exist.
7463 File: gdb.info, Node: GDB/MI Stream Records, Next: GDB/MI Async Records, Prev: GDB/MI Result Records, Up: GDB/MI Output Records
7465 27.5.2 GDB/MI Stream Records
7466 ----------------------------
7468 GDB internally maintains a number of output streams: the console, the
7469 target, and the log. The output intended for each of these streams is
7470 funneled through the GDB/MI interface using "stream records".
7472 Each stream record begins with a unique "prefix character" which
7473 identifies its stream (*note GDB/MI Output Syntax: GDB/MI Output
7474 Syntax.). In addition to the prefix, each stream record contains a
7475 'STRING-OUTPUT'. This is either raw text (with an implicit new line) or
7476 a quoted C string (which does not contain an implicit newline).
7479 The console output stream contains text that should be displayed in
7480 the CLI console window. It contains the textual responses to CLI
7484 The target output stream contains any textual output from the
7485 running target. This is only present when GDB's event loop is
7486 truly asynchronous, which is currently only the case for remote
7490 The log stream contains debugging messages being produced by GDB's