gdb/python: Add architecture method to gdb.PendingFrame
[deliverable/binutils-gdb.git] / gdb / doc / python.texi
CommitLineData
b811d2c2 1@c Copyright (C) 2008--2020 Free Software Foundation, Inc.
329baa95
DE
2@c Permission is granted to copy, distribute and/or modify this document
3@c under the terms of the GNU Free Documentation License, Version 1.3 or
4@c any later version published by the Free Software Foundation; with the
5@c Invariant Sections being ``Free Software'' and ``Free Software Needs
6@c Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
7@c and with the Back-Cover Texts as in (a) below.
8@c
9@c (a) The FSF's Back-Cover Text is: ``You are free to copy and modify
10@c this GNU Manual. Buying copies from GNU Press supports the FSF in
11@c developing GNU and promoting software freedom.''
12
13@node Python
14@section Extending @value{GDBN} using Python
15@cindex python scripting
16@cindex scripting with python
17
18You can extend @value{GDBN} using the @uref{http://www.python.org/,
19Python programming language}. This feature is available only if
20@value{GDBN} was configured using @option{--with-python}.
05c6bdc1
TT
21@value{GDBN} can be built against either Python 2 or Python 3; which
22one you have depends on this configure-time option.
329baa95
DE
23
24@cindex python directory
25Python scripts used by @value{GDBN} should be installed in
26@file{@var{data-directory}/python}, where @var{data-directory} is
27the data directory as determined at @value{GDBN} startup (@pxref{Data Files}).
28This directory, known as the @dfn{python directory},
29is automatically added to the Python Search Path in order to allow
30the Python interpreter to locate all scripts installed at this location.
31
32Additionally, @value{GDBN} commands and convenience functions which
33are written in Python and are located in the
34@file{@var{data-directory}/python/gdb/command} or
35@file{@var{data-directory}/python/gdb/function} directories are
36automatically imported when @value{GDBN} starts.
37
38@menu
39* Python Commands:: Accessing Python from @value{GDBN}.
40* Python API:: Accessing @value{GDBN} from Python.
41* Python Auto-loading:: Automatically loading Python code.
42* Python modules:: Python modules provided by @value{GDBN}.
43@end menu
44
45@node Python Commands
46@subsection Python Commands
47@cindex python commands
48@cindex commands to access python
49
50@value{GDBN} provides two commands for accessing the Python interpreter,
51and one related setting:
52
53@table @code
54@kindex python-interactive
55@kindex pi
56@item python-interactive @r{[}@var{command}@r{]}
57@itemx pi @r{[}@var{command}@r{]}
58Without an argument, the @code{python-interactive} command can be used
59to start an interactive Python prompt. To return to @value{GDBN},
60type the @code{EOF} character (e.g., @kbd{Ctrl-D} on an empty prompt).
61
62Alternatively, a single-line Python command can be given as an
63argument and evaluated. If the command is an expression, the result
64will be printed; otherwise, nothing will be printed. For example:
65
66@smallexample
67(@value{GDBP}) python-interactive 2 + 3
685
69@end smallexample
70
71@kindex python
72@kindex py
73@item python @r{[}@var{command}@r{]}
74@itemx py @r{[}@var{command}@r{]}
75The @code{python} command can be used to evaluate Python code.
76
77If given an argument, the @code{python} command will evaluate the
78argument as a Python command. For example:
79
80@smallexample
81(@value{GDBP}) python print 23
8223
83@end smallexample
84
85If you do not provide an argument to @code{python}, it will act as a
86multi-line command, like @code{define}. In this case, the Python
87script is made up of subsequent command lines, given after the
88@code{python} command. This command list is terminated using a line
89containing @code{end}. For example:
90
91@smallexample
92(@value{GDBP}) python
329baa95
DE
93>print 23
94>end
9523
96@end smallexample
97
98@kindex set python print-stack
99@item set python print-stack
100By default, @value{GDBN} will print only the message component of a
101Python exception when an error occurs in a Python script. This can be
102controlled using @code{set python print-stack}: if @code{full}, then
103full Python stack printing is enabled; if @code{none}, then Python stack
104and message printing is disabled; if @code{message}, the default, only
105the message component of the error is printed.
106@end table
107
108It is also possible to execute a Python script from the @value{GDBN}
109interpreter:
110
111@table @code
112@item source @file{script-name}
113The script name must end with @samp{.py} and @value{GDBN} must be configured
114to recognize the script language based on filename extension using
115the @code{script-extension} setting. @xref{Extending GDB, ,Extending GDB}.
329baa95
DE
116@end table
117
118@node Python API
119@subsection Python API
120@cindex python api
121@cindex programming in python
122
123You can get quick online help for @value{GDBN}'s Python API by issuing
124the command @w{@kbd{python help (gdb)}}.
125
126Functions and methods which have two or more optional arguments allow
127them to be specified using keyword syntax. This allows passing some
128optional arguments while skipping others. Example:
129@w{@code{gdb.some_function ('foo', bar = 1, baz = 2)}}.
130
131@menu
132* Basic Python:: Basic Python Functions.
133* Exception Handling:: How Python exceptions are translated.
134* Values From Inferior:: Python representation of values.
135* Types In Python:: Python representation of types.
136* Pretty Printing API:: Pretty-printing values.
137* Selecting Pretty-Printers:: How GDB chooses a pretty-printer.
138* Writing a Pretty-Printer:: Writing a Pretty-Printer.
139* Type Printing API:: Pretty-printing types.
140* Frame Filter API:: Filtering Frames.
141* Frame Decorator API:: Decorating Frames.
142* Writing a Frame Filter:: Writing a Frame Filter.
d11916aa 143* Unwinding Frames in Python:: Writing frame unwinder.
0c6e92a5
SC
144* Xmethods In Python:: Adding and replacing methods of C++ classes.
145* Xmethod API:: Xmethod types.
146* Writing an Xmethod:: Writing an xmethod.
329baa95
DE
147* Inferiors In Python:: Python representation of inferiors (processes)
148* Events In Python:: Listening for events from @value{GDBN}.
149* Threads In Python:: Accessing inferior threads from Python.
0a0faf9f 150* Recordings In Python:: Accessing recordings from Python.
329baa95
DE
151* Commands In Python:: Implementing new commands in Python.
152* Parameters In Python:: Adding new @value{GDBN} parameters.
153* Functions In Python:: Writing new convenience functions.
154* Progspaces In Python:: Program spaces.
155* Objfiles In Python:: Object files.
156* Frames In Python:: Accessing inferior stack frames from Python.
157* Blocks In Python:: Accessing blocks from Python.
158* Symbols In Python:: Python representation of symbols.
159* Symbol Tables In Python:: Python representation of symbol tables.
160* Line Tables In Python:: Python representation of line tables.
161* Breakpoints In Python:: Manipulating breakpoints using Python.
162* Finish Breakpoints in Python:: Setting Breakpoints on function return
163 using Python.
164* Lazy Strings In Python:: Python representation of lazy strings.
165* Architectures In Python:: Python representation of architectures.
01b1af32 166* TUI Windows In Python:: Implementing new TUI windows.
329baa95
DE
167@end menu
168
169@node Basic Python
170@subsubsection Basic Python
171
172@cindex python stdout
173@cindex python pagination
174At startup, @value{GDBN} overrides Python's @code{sys.stdout} and
175@code{sys.stderr} to print using @value{GDBN}'s output-paging streams.
176A Python program which outputs to one of these streams may have its
177output interrupted by the user (@pxref{Screen Size}). In this
178situation, a Python @code{KeyboardInterrupt} exception is thrown.
179
180Some care must be taken when writing Python code to run in
181@value{GDBN}. Two things worth noting in particular:
182
183@itemize @bullet
184@item
185@value{GDBN} install handlers for @code{SIGCHLD} and @code{SIGINT}.
186Python code must not override these, or even change the options using
187@code{sigaction}. If your program changes the handling of these
188signals, @value{GDBN} will most likely stop working correctly. Note
189that it is unfortunately common for GUI toolkits to install a
190@code{SIGCHLD} handler.
191
192@item
193@value{GDBN} takes care to mark its internal file descriptors as
194close-on-exec. However, this cannot be done in a thread-safe way on
195all platforms. Your Python programs should be aware of this and
196should both create new file descriptors with the close-on-exec flag
197set and arrange to close unneeded file descriptors before starting a
198child process.
199@end itemize
200
201@cindex python functions
202@cindex python module
203@cindex gdb module
204@value{GDBN} introduces a new Python module, named @code{gdb}. All
205methods and classes added by @value{GDBN} are placed in this module.
206@value{GDBN} automatically @code{import}s the @code{gdb} module for
207use in all scripts evaluated by the @code{python} command.
208
1256af7d
SM
209Some types of the @code{gdb} module come with a textual representation
210(accessible through the @code{repr} or @code{str} functions). These are
211offered for debugging purposes only, expect them to change over time.
212
329baa95
DE
213@findex gdb.PYTHONDIR
214@defvar gdb.PYTHONDIR
215A string containing the python directory (@pxref{Python}).
216@end defvar
217
218@findex gdb.execute
219@defun gdb.execute (command @r{[}, from_tty @r{[}, to_string@r{]]})
220Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
221If a GDB exception happens while @var{command} runs, it is
222translated as described in @ref{Exception Handling,,Exception Handling}.
223
697aa1b7 224The @var{from_tty} flag specifies whether @value{GDBN} ought to consider this
329baa95
DE
225command as having originated from the user invoking it interactively.
226It must be a boolean value. If omitted, it defaults to @code{False}.
227
228By default, any output produced by @var{command} is sent to
b3ce5e5f
DE
229@value{GDBN}'s standard output (and to the log output if logging is
230turned on). If the @var{to_string} parameter is
329baa95
DE
231@code{True}, then output will be collected by @code{gdb.execute} and
232returned as a string. The default is @code{False}, in which case the
233return value is @code{None}. If @var{to_string} is @code{True}, the
234@value{GDBN} virtual terminal will be temporarily set to unlimited width
235and height, and its pagination will be disabled; @pxref{Screen Size}.
236@end defun
237
238@findex gdb.breakpoints
239@defun gdb.breakpoints ()
240Return a sequence holding all of @value{GDBN}'s breakpoints.
1957f6b8
TT
241@xref{Breakpoints In Python}, for more information. In @value{GDBN}
242version 7.11 and earlier, this function returned @code{None} if there
243were no breakpoints. This peculiarity was subsequently fixed, and now
244@code{gdb.breakpoints} returns an empty sequence in this case.
329baa95
DE
245@end defun
246
d8ae99a7
PM
247@defun gdb.rbreak (regex @r{[}, minsyms @r{[}, throttle, @r{[}, symtabs @r{]]]})
248Return a Python list holding a collection of newly set
249@code{gdb.Breakpoint} objects matching function names defined by the
250@var{regex} pattern. If the @var{minsyms} keyword is @code{True}, all
251system functions (those not explicitly defined in the inferior) will
252also be included in the match. The @var{throttle} keyword takes an
253integer that defines the maximum number of pattern matches for
254functions matched by the @var{regex} pattern. If the number of
255matches exceeds the integer value of @var{throttle}, a
256@code{RuntimeError} will be raised and no breakpoints will be created.
257If @var{throttle} is not defined then there is no imposed limit on the
258maximum number of matches and breakpoints to be created. The
259@var{symtabs} keyword takes a Python iterable that yields a collection
260of @code{gdb.Symtab} objects and will restrict the search to those
261functions only contained within the @code{gdb.Symtab} objects.
262@end defun
263
329baa95
DE
264@findex gdb.parameter
265@defun gdb.parameter (parameter)
697aa1b7
EZ
266Return the value of a @value{GDBN} @var{parameter} given by its name,
267a string; the parameter name string may contain spaces if the parameter has a
268multi-part name. For example, @samp{print object} is a valid
269parameter name.
329baa95
DE
270
271If the named parameter does not exist, this function throws a
272@code{gdb.error} (@pxref{Exception Handling}). Otherwise, the
273parameter's value is converted to a Python value of the appropriate
274type, and returned.
275@end defun
276
277@findex gdb.history
278@defun gdb.history (number)
279Return a value from @value{GDBN}'s value history (@pxref{Value
697aa1b7 280History}). The @var{number} argument indicates which history element to return.
329baa95
DE
281If @var{number} is negative, then @value{GDBN} will take its absolute value
282and count backward from the last element (i.e., the most recent element) to
283find the value to return. If @var{number} is zero, then @value{GDBN} will
284return the most recent element. If the element specified by @var{number}
285doesn't exist in the value history, a @code{gdb.error} exception will be
286raised.
287
288If no exception is raised, the return value is always an instance of
289@code{gdb.Value} (@pxref{Values From Inferior}).
290@end defun
291
7729052b
TT
292@findex gdb.convenience_variable
293@defun gdb.convenience_variable (name)
294Return the value of the convenience variable (@pxref{Convenience
295Vars}) named @var{name}. @var{name} must be a string. The name
296should not include the @samp{$} that is used to mark a convenience
297variable in an expression. If the convenience variable does not
298exist, then @code{None} is returned.
299@end defun
300
301@findex gdb.set_convenience_variable
302@defun gdb.set_convenience_variable (name, value)
303Set the value of the convenience variable (@pxref{Convenience Vars})
304named @var{name}. @var{name} must be a string. The name should not
305include the @samp{$} that is used to mark a convenience variable in an
306expression. If @var{value} is @code{None}, then the convenience
307variable is removed. Otherwise, if @var{value} is not a
308@code{gdb.Value} (@pxref{Values From Inferior}), it is is converted
309using the @code{gdb.Value} constructor.
310@end defun
311
329baa95
DE
312@findex gdb.parse_and_eval
313@defun gdb.parse_and_eval (expression)
697aa1b7
EZ
314Parse @var{expression}, which must be a string, as an expression in
315the current language, evaluate it, and return the result as a
316@code{gdb.Value}.
329baa95
DE
317
318This function can be useful when implementing a new command
319(@pxref{Commands In Python}), as it provides a way to parse the
320command's argument as an expression. It is also useful simply to
7729052b 321compute values.
329baa95
DE
322@end defun
323
324@findex gdb.find_pc_line
325@defun gdb.find_pc_line (pc)
326Return the @code{gdb.Symtab_and_line} object corresponding to the
327@var{pc} value. @xref{Symbol Tables In Python}. If an invalid
328value of @var{pc} is passed as an argument, then the @code{symtab} and
329@code{line} attributes of the returned @code{gdb.Symtab_and_line} object
8743a9cd
TT
330will be @code{None} and 0 respectively. This is identical to
331@code{gdb.current_progspace().find_pc_line(pc)} and is included for
332historical compatibility.
329baa95
DE
333@end defun
334
335@findex gdb.post_event
336@defun gdb.post_event (event)
337Put @var{event}, a callable object taking no arguments, into
338@value{GDBN}'s internal event queue. This callable will be invoked at
339some later point, during @value{GDBN}'s event processing. Events
340posted using @code{post_event} will be run in the order in which they
341were posted; however, there is no way to know when they will be
342processed relative to other events inside @value{GDBN}.
343
344@value{GDBN} is not thread-safe. If your Python program uses multiple
345threads, you must be careful to only call @value{GDBN}-specific
b3ce5e5f 346functions in the @value{GDBN} thread. @code{post_event} ensures
329baa95
DE
347this. For example:
348
349@smallexample
350(@value{GDBP}) python
351>import threading
352>
353>class Writer():
354> def __init__(self, message):
355> self.message = message;
356> def __call__(self):
357> gdb.write(self.message)
358>
359>class MyThread1 (threading.Thread):
360> def run (self):
361> gdb.post_event(Writer("Hello "))
362>
363>class MyThread2 (threading.Thread):
364> def run (self):
365> gdb.post_event(Writer("World\n"))
366>
367>MyThread1().start()
368>MyThread2().start()
369>end
370(@value{GDBP}) Hello World
371@end smallexample
372@end defun
373
374@findex gdb.write
375@defun gdb.write (string @r{[}, stream{]})
376Print a string to @value{GDBN}'s paginated output stream. The
377optional @var{stream} determines the stream to print to. The default
378stream is @value{GDBN}'s standard output stream. Possible stream
379values are:
380
381@table @code
382@findex STDOUT
383@findex gdb.STDOUT
384@item gdb.STDOUT
385@value{GDBN}'s standard output stream.
386
387@findex STDERR
388@findex gdb.STDERR
389@item gdb.STDERR
390@value{GDBN}'s standard error stream.
391
392@findex STDLOG
393@findex gdb.STDLOG
394@item gdb.STDLOG
395@value{GDBN}'s log stream (@pxref{Logging Output}).
396@end table
397
398Writing to @code{sys.stdout} or @code{sys.stderr} will automatically
399call this function and will automatically direct the output to the
400relevant stream.
401@end defun
402
403@findex gdb.flush
404@defun gdb.flush ()
405Flush the buffer of a @value{GDBN} paginated stream so that the
406contents are displayed immediately. @value{GDBN} will flush the
407contents of a stream automatically when it encounters a newline in the
408buffer. The optional @var{stream} determines the stream to flush. The
409default stream is @value{GDBN}'s standard output stream. Possible
410stream values are:
411
412@table @code
413@findex STDOUT
414@findex gdb.STDOUT
415@item gdb.STDOUT
416@value{GDBN}'s standard output stream.
417
418@findex STDERR
419@findex gdb.STDERR
420@item gdb.STDERR
421@value{GDBN}'s standard error stream.
422
423@findex STDLOG
424@findex gdb.STDLOG
425@item gdb.STDLOG
426@value{GDBN}'s log stream (@pxref{Logging Output}).
427
428@end table
429
430Flushing @code{sys.stdout} or @code{sys.stderr} will automatically
431call this function for the relevant stream.
432@end defun
433
434@findex gdb.target_charset
435@defun gdb.target_charset ()
436Return the name of the current target character set (@pxref{Character
437Sets}). This differs from @code{gdb.parameter('target-charset')} in
438that @samp{auto} is never returned.
439@end defun
440
441@findex gdb.target_wide_charset
442@defun gdb.target_wide_charset ()
443Return the name of the current target wide character set
444(@pxref{Character Sets}). This differs from
445@code{gdb.parameter('target-wide-charset')} in that @samp{auto} is
446never returned.
447@end defun
448
449@findex gdb.solib_name
450@defun gdb.solib_name (address)
451Return the name of the shared library holding the given @var{address}
8743a9cd
TT
452as a string, or @code{None}. This is identical to
453@code{gdb.current_progspace().solib_name(address)} and is included for
454historical compatibility.
329baa95
DE
455@end defun
456
457@findex gdb.decode_line
0d2a5839 458@defun gdb.decode_line (@r{[}expression@r{]})
329baa95
DE
459Return locations of the line specified by @var{expression}, or of the
460current line if no argument was given. This function returns a Python
461tuple containing two elements. The first element contains a string
462holding any unparsed section of @var{expression} (or @code{None} if
463the expression has been fully parsed). The second element contains
464either @code{None} or another tuple that contains all the locations
465that match the expression represented as @code{gdb.Symtab_and_line}
466objects (@pxref{Symbol Tables In Python}). If @var{expression} is
467provided, it is decoded the way that @value{GDBN}'s inbuilt
468@code{break} or @code{edit} commands do (@pxref{Specify Location}).
469@end defun
470
471@defun gdb.prompt_hook (current_prompt)
472@anchor{prompt_hook}
473
474If @var{prompt_hook} is callable, @value{GDBN} will call the method
475assigned to this operation before a prompt is displayed by
476@value{GDBN}.
477
478The parameter @code{current_prompt} contains the current @value{GDBN}
479prompt. This method must return a Python string, or @code{None}. If
480a string is returned, the @value{GDBN} prompt will be set to that
481string. If @code{None} is returned, @value{GDBN} will continue to use
482the current prompt.
483
484Some prompts cannot be substituted in @value{GDBN}. Secondary prompts
485such as those used by readline for command input, and annotation
486related prompts are prohibited from being changed.
487@end defun
488
489@node Exception Handling
490@subsubsection Exception Handling
491@cindex python exceptions
492@cindex exceptions, python
493
494When executing the @code{python} command, Python exceptions
495uncaught within the Python code are translated to calls to
496@value{GDBN} error-reporting mechanism. If the command that called
497@code{python} does not handle the error, @value{GDBN} will
498terminate it and print an error message containing the Python
499exception name, the associated value, and the Python call stack
500backtrace at the point where the exception was raised. Example:
501
502@smallexample
503(@value{GDBP}) python print foo
504Traceback (most recent call last):
505 File "<string>", line 1, in <module>
506NameError: name 'foo' is not defined
507@end smallexample
508
509@value{GDBN} errors that happen in @value{GDBN} commands invoked by
510Python code are converted to Python exceptions. The type of the
511Python exception depends on the error.
512
513@ftable @code
514@item gdb.error
515This is the base class for most exceptions generated by @value{GDBN}.
516It is derived from @code{RuntimeError}, for compatibility with earlier
517versions of @value{GDBN}.
518
519If an error occurring in @value{GDBN} does not fit into some more
520specific category, then the generated exception will have this type.
521
522@item gdb.MemoryError
523This is a subclass of @code{gdb.error} which is thrown when an
524operation tried to access invalid memory in the inferior.
525
526@item KeyboardInterrupt
527User interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination
528prompt) is translated to a Python @code{KeyboardInterrupt} exception.
529@end ftable
530
531In all cases, your exception handler will see the @value{GDBN} error
532message as its value and the Python call stack backtrace at the Python
533statement closest to where the @value{GDBN} error occured as the
534traceback.
535
4a5a194a
TT
536
537When implementing @value{GDBN} commands in Python via
538@code{gdb.Command}, or functions via @code{gdb.Function}, it is useful
539to be able to throw an exception that doesn't cause a traceback to be
540printed. For example, the user may have invoked the command
541incorrectly. @value{GDBN} provides a special exception class that can
542be used for this purpose.
543
544@ftable @code
545@item gdb.GdbError
546When thrown from a command or function, this exception will cause the
547command or function to fail, but the Python stack will not be
548displayed. @value{GDBN} does not throw this exception itself, but
549rather recognizes it when thrown from user Python code. Example:
329baa95
DE
550
551@smallexample
552(gdb) python
553>class HelloWorld (gdb.Command):
554> """Greet the whole world."""
555> def __init__ (self):
556> super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
557> def invoke (self, args, from_tty):
558> argv = gdb.string_to_argv (args)
559> if len (argv) != 0:
560> raise gdb.GdbError ("hello-world takes no arguments")
561> print "Hello, World!"
562>HelloWorld ()
563>end
564(gdb) hello-world 42
565hello-world takes no arguments
566@end smallexample
4a5a194a 567@end ftable
329baa95
DE
568
569@node Values From Inferior
570@subsubsection Values From Inferior
571@cindex values from inferior, with Python
572@cindex python, working with values from inferior
573
574@cindex @code{gdb.Value}
575@value{GDBN} provides values it obtains from the inferior program in
576an object of type @code{gdb.Value}. @value{GDBN} uses this object
577for its internal bookkeeping of the inferior's values, and for
578fetching values when necessary.
579
580Inferior values that are simple scalars can be used directly in
581Python expressions that are valid for the value's data type. Here's
582an example for an integer or floating-point value @code{some_val}:
583
584@smallexample
585bar = some_val + 2
586@end smallexample
587
588@noindent
589As result of this, @code{bar} will also be a @code{gdb.Value} object
f7bd0f78
SC
590whose values are of the same type as those of @code{some_val}. Valid
591Python operations can also be performed on @code{gdb.Value} objects
592representing a @code{struct} or @code{class} object. For such cases,
593the overloaded operator (if present), is used to perform the operation.
594For example, if @code{val1} and @code{val2} are @code{gdb.Value} objects
595representing instances of a @code{class} which overloads the @code{+}
596operator, then one can use the @code{+} operator in their Python script
597as follows:
598
599@smallexample
600val3 = val1 + val2
601@end smallexample
602
603@noindent
604The result of the operation @code{val3} is also a @code{gdb.Value}
605object corresponding to the value returned by the overloaded @code{+}
606operator. In general, overloaded operators are invoked for the
607following operations: @code{+} (binary addition), @code{-} (binary
608subtraction), @code{*} (multiplication), @code{/}, @code{%}, @code{<<},
609@code{>>}, @code{|}, @code{&}, @code{^}.
329baa95
DE
610
611Inferior values that are structures or instances of some class can
612be accessed using the Python @dfn{dictionary syntax}. For example, if
613@code{some_val} is a @code{gdb.Value} instance holding a structure, you
614can access its @code{foo} element with:
615
616@smallexample
617bar = some_val['foo']
618@end smallexample
619
620@cindex getting structure elements using gdb.Field objects as subscripts
621Again, @code{bar} will also be a @code{gdb.Value} object. Structure
622elements can also be accessed by using @code{gdb.Field} objects as
623subscripts (@pxref{Types In Python}, for more information on
624@code{gdb.Field} objects). For example, if @code{foo_field} is a
625@code{gdb.Field} object corresponding to element @code{foo} of the above
626structure, then @code{bar} can also be accessed as follows:
627
628@smallexample
629bar = some_val[foo_field]
630@end smallexample
631
632A @code{gdb.Value} that represents a function can be executed via
633inferior function call. Any arguments provided to the call must match
634the function's prototype, and must be provided in the order specified
635by that prototype.
636
637For example, @code{some_val} is a @code{gdb.Value} instance
638representing a function that takes two integers as arguments. To
639execute this function, call it like so:
640
641@smallexample
642result = some_val (10,20)
643@end smallexample
644
645Any values returned from a function call will be stored as a
646@code{gdb.Value}.
647
648The following attributes are provided:
649
650@defvar Value.address
651If this object is addressable, this read-only attribute holds a
652@code{gdb.Value} object representing the address. Otherwise,
653this attribute holds @code{None}.
654@end defvar
655
656@cindex optimized out value in Python
657@defvar Value.is_optimized_out
658This read-only boolean attribute is true if the compiler optimized out
659this value, thus it is not available for fetching from the inferior.
660@end defvar
661
662@defvar Value.type
663The type of this @code{gdb.Value}. The value of this attribute is a
664@code{gdb.Type} object (@pxref{Types In Python}).
665@end defvar
666
667@defvar Value.dynamic_type
9da10427
TT
668The dynamic type of this @code{gdb.Value}. This uses the object's
669virtual table and the C@t{++} run-time type information
670(@acronym{RTTI}) to determine the dynamic type of the value. If this
671value is of class type, it will return the class in which the value is
672embedded, if any. If this value is of pointer or reference to a class
673type, it will compute the dynamic type of the referenced object, and
674return a pointer or reference to that type, respectively. In all
675other cases, it will return the value's static type.
329baa95
DE
676
677Note that this feature will only work when debugging a C@t{++} program
678that includes @acronym{RTTI} for the object in question. Otherwise,
679it will just return the static type of the value as in @kbd{ptype foo}
680(@pxref{Symbols, ptype}).
681@end defvar
682
683@defvar Value.is_lazy
684The value of this read-only boolean attribute is @code{True} if this
685@code{gdb.Value} has not yet been fetched from the inferior.
686@value{GDBN} does not fetch values until necessary, for efficiency.
687For example:
688
689@smallexample
690myval = gdb.parse_and_eval ('somevar')
691@end smallexample
692
693The value of @code{somevar} is not fetched at this time. It will be
694fetched when the value is needed, or when the @code{fetch_lazy}
695method is invoked.
696@end defvar
697
698The following methods are provided:
699
700@defun Value.__init__ (@var{val})
701Many Python values can be converted directly to a @code{gdb.Value} via
702this object initializer. Specifically:
703
704@table @asis
705@item Python boolean
706A Python boolean is converted to the boolean type from the current
707language.
708
709@item Python integer
710A Python integer is converted to the C @code{long} type for the
711current architecture.
712
713@item Python long
714A Python long is converted to the C @code{long long} type for the
715current architecture.
716
717@item Python float
718A Python float is converted to the C @code{double} type for the
719current architecture.
720
721@item Python string
b3ce5e5f
DE
722A Python string is converted to a target string in the current target
723language using the current target encoding.
724If a character cannot be represented in the current target encoding,
725then an exception is thrown.
329baa95
DE
726
727@item @code{gdb.Value}
728If @code{val} is a @code{gdb.Value}, then a copy of the value is made.
729
730@item @code{gdb.LazyString}
731If @code{val} is a @code{gdb.LazyString} (@pxref{Lazy Strings In
732Python}), then the lazy string's @code{value} method is called, and
733its result is used.
734@end table
735@end defun
736
ff6c8b35 737@defun Value.__init__ (@var{val}, @var{type})
af54ade9
KB
738This second form of the @code{gdb.Value} constructor returns a
739@code{gdb.Value} of type @var{type} where the value contents are taken
740from the Python buffer object specified by @var{val}. The number of
741bytes in the Python buffer object must be greater than or equal to the
742size of @var{type}.
743@end defun
744
329baa95
DE
745@defun Value.cast (type)
746Return a new instance of @code{gdb.Value} that is the result of
747casting this instance to the type described by @var{type}, which must
748be a @code{gdb.Type} object. If the cast cannot be performed for some
749reason, this method throws an exception.
750@end defun
751
752@defun Value.dereference ()
753For pointer data types, this method returns a new @code{gdb.Value} object
754whose contents is the object pointed to by the pointer. For example, if
755@code{foo} is a C pointer to an @code{int}, declared in your C program as
756
757@smallexample
758int *foo;
759@end smallexample
760
761@noindent
762then you can use the corresponding @code{gdb.Value} to access what
763@code{foo} points to like this:
764
765@smallexample
766bar = foo.dereference ()
767@end smallexample
768
769The result @code{bar} will be a @code{gdb.Value} object holding the
770value pointed to by @code{foo}.
771
772A similar function @code{Value.referenced_value} exists which also
760f7560 773returns @code{gdb.Value} objects corresponding to the values pointed to
329baa95
DE
774by pointer values (and additionally, values referenced by reference
775values). However, the behavior of @code{Value.dereference}
776differs from @code{Value.referenced_value} by the fact that the
777behavior of @code{Value.dereference} is identical to applying the C
778unary operator @code{*} on a given value. For example, consider a
779reference to a pointer @code{ptrref}, declared in your C@t{++} program
780as
781
782@smallexample
783typedef int *intptr;
784...
785int val = 10;
786intptr ptr = &val;
787intptr &ptrref = ptr;
788@end smallexample
789
790Though @code{ptrref} is a reference value, one can apply the method
791@code{Value.dereference} to the @code{gdb.Value} object corresponding
792to it and obtain a @code{gdb.Value} which is identical to that
793corresponding to @code{val}. However, if you apply the method
794@code{Value.referenced_value}, the result would be a @code{gdb.Value}
795object identical to that corresponding to @code{ptr}.
796
797@smallexample
798py_ptrref = gdb.parse_and_eval ("ptrref")
799py_val = py_ptrref.dereference ()
800py_ptr = py_ptrref.referenced_value ()
801@end smallexample
802
803The @code{gdb.Value} object @code{py_val} is identical to that
804corresponding to @code{val}, and @code{py_ptr} is identical to that
805corresponding to @code{ptr}. In general, @code{Value.dereference} can
806be applied whenever the C unary operator @code{*} can be applied
807to the corresponding C value. For those cases where applying both
808@code{Value.dereference} and @code{Value.referenced_value} is allowed,
809the results obtained need not be identical (as we have seen in the above
810example). The results are however identical when applied on
811@code{gdb.Value} objects corresponding to pointers (@code{gdb.Value}
812objects with type code @code{TYPE_CODE_PTR}) in a C/C@t{++} program.
813@end defun
814
815@defun Value.referenced_value ()
816For pointer or reference data types, this method returns a new
817@code{gdb.Value} object corresponding to the value referenced by the
818pointer/reference value. For pointer data types,
819@code{Value.dereference} and @code{Value.referenced_value} produce
820identical results. The difference between these methods is that
821@code{Value.dereference} cannot get the values referenced by reference
822values. For example, consider a reference to an @code{int}, declared
823in your C@t{++} program as
824
825@smallexample
826int val = 10;
827int &ref = val;
828@end smallexample
829
830@noindent
831then applying @code{Value.dereference} to the @code{gdb.Value} object
832corresponding to @code{ref} will result in an error, while applying
833@code{Value.referenced_value} will result in a @code{gdb.Value} object
834identical to that corresponding to @code{val}.
835
836@smallexample
837py_ref = gdb.parse_and_eval ("ref")
838er_ref = py_ref.dereference () # Results in error
839py_val = py_ref.referenced_value () # Returns the referenced value
840@end smallexample
841
842The @code{gdb.Value} object @code{py_val} is identical to that
843corresponding to @code{val}.
844@end defun
845
4c082a81
SC
846@defun Value.reference_value ()
847Return a @code{gdb.Value} object which is a reference to the value
848encapsulated by this instance.
849@end defun
850
851@defun Value.const_value ()
852Return a @code{gdb.Value} object which is a @code{const} version of the
853value encapsulated by this instance.
854@end defun
855
329baa95
DE
856@defun Value.dynamic_cast (type)
857Like @code{Value.cast}, but works as if the C@t{++} @code{dynamic_cast}
858operator were used. Consult a C@t{++} reference for details.
859@end defun
860
861@defun Value.reinterpret_cast (type)
862Like @code{Value.cast}, but works as if the C@t{++} @code{reinterpret_cast}
863operator were used. Consult a C@t{++} reference for details.
864@end defun
865
52093e1b
MB
866@defun Value.format_string (...)
867Convert a @code{gdb.Value} to a string, similarly to what the @code{print}
868command does. Invoked with no arguments, this is equivalent to calling
869the @code{str} function on the @code{gdb.Value}. The representation of
870the same value may change across different versions of @value{GDBN}, so
871you shouldn't, for instance, parse the strings returned by this method.
872
873All the arguments are keyword only. If an argument is not specified, the
874current global default setting is used.
875
876@table @code
877@item raw
878@code{True} if pretty-printers (@pxref{Pretty Printing}) should not be
879used to format the value. @code{False} if enabled pretty-printers
880matching the type represented by the @code{gdb.Value} should be used to
881format it.
882
883@item pretty_arrays
884@code{True} if arrays should be pretty printed to be more convenient to
885read, @code{False} if they shouldn't (see @code{set print array} in
886@ref{Print Settings}).
887
888@item pretty_structs
889@code{True} if structs should be pretty printed to be more convenient to
890read, @code{False} if they shouldn't (see @code{set print pretty} in
891@ref{Print Settings}).
892
893@item array_indexes
894@code{True} if array indexes should be included in the string
895representation of arrays, @code{False} if they shouldn't (see @code{set
896print array-indexes} in @ref{Print Settings}).
897
898@item symbols
899@code{True} if the string representation of a pointer should include the
900corresponding symbol name (if one exists), @code{False} if it shouldn't
901(see @code{set print symbol} in @ref{Print Settings}).
902
903@item unions
904@code{True} if unions which are contained in other structures or unions
905should be expanded, @code{False} if they shouldn't (see @code{set print
906union} in @ref{Print Settings}).
907
908@item deref_refs
909@code{True} if C@t{++} references should be resolved to the value they
910refer to, @code{False} (the default) if they shouldn't. Note that, unlike
911for the @code{print} command, references are not automatically expanded
912when using the @code{format_string} method or the @code{str}
913function. There is no global @code{print} setting to change the default
914behaviour.
915
916@item actual_objects
917@code{True} if the representation of a pointer to an object should
918identify the @emph{actual} (derived) type of the object rather than the
919@emph{declared} type, using the virtual function table. @code{False} if
920the @emph{declared} type should be used. (See @code{set print object} in
921@ref{Print Settings}).
922
923@item static_fields
924@code{True} if static members should be included in the string
925representation of a C@t{++} object, @code{False} if they shouldn't (see
926@code{set print static-members} in @ref{Print Settings}).
927
928@item max_elements
929Number of array elements to print, or @code{0} to print an unlimited
930number of elements (see @code{set print elements} in @ref{Print
931Settings}).
932
2e62ab40
AB
933@item max_depth
934The maximum depth to print for nested structs and unions, or @code{-1}
935to print an unlimited number of elements (see @code{set print
936max-depth} in @ref{Print Settings}).
937
52093e1b
MB
938@item repeat_threshold
939Set the threshold for suppressing display of repeated array elements, or
940@code{0} to represent all elements, even if repeated. (See @code{set
941print repeats} in @ref{Print Settings}).
942
943@item format
944A string containing a single character representing the format to use for
945the returned string. For instance, @code{'x'} is equivalent to using the
946@value{GDBN} command @code{print} with the @code{/x} option and formats
947the value as a hexadecimal number.
948@end table
949@end defun
950
329baa95
DE
951@defun Value.string (@r{[}encoding@r{[}, errors@r{[}, length@r{]]]})
952If this @code{gdb.Value} represents a string, then this method
953converts the contents to a Python string. Otherwise, this method will
954throw an exception.
955
b3ce5e5f
DE
956Values are interpreted as strings according to the rules of the
957current language. If the optional length argument is given, the
958string will be converted to that length, and will include any embedded
959zeroes that the string may contain. Otherwise, for languages
960where the string is zero-terminated, the entire string will be
961converted.
329baa95 962
b3ce5e5f
DE
963For example, in C-like languages, a value is a string if it is a pointer
964to or an array of characters or ints of type @code{wchar_t}, @code{char16_t},
965or @code{char32_t}.
329baa95
DE
966
967If the optional @var{encoding} argument is given, it must be a string
968naming the encoding of the string in the @code{gdb.Value}, such as
969@code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. It accepts
970the same encodings as the corresponding argument to Python's
971@code{string.decode} method, and the Python codec machinery will be used
972to convert the string. If @var{encoding} is not given, or if
973@var{encoding} is the empty string, then either the @code{target-charset}
974(@pxref{Character Sets}) will be used, or a language-specific encoding
975will be used, if the current language is able to supply one.
976
977The optional @var{errors} argument is the same as the corresponding
978argument to Python's @code{string.decode} method.
979
980If the optional @var{length} argument is given, the string will be
981fetched and converted to the given length.
982@end defun
983
984@defun Value.lazy_string (@r{[}encoding @r{[}, length@r{]]})
985If this @code{gdb.Value} represents a string, then this method
986converts the contents to a @code{gdb.LazyString} (@pxref{Lazy Strings
987In Python}). Otherwise, this method will throw an exception.
988
989If the optional @var{encoding} argument is given, it must be a string
990naming the encoding of the @code{gdb.LazyString}. Some examples are:
991@samp{ascii}, @samp{iso-8859-6} or @samp{utf-8}. If the
992@var{encoding} argument is an encoding that @value{GDBN} does
993recognize, @value{GDBN} will raise an error.
994
995When a lazy string is printed, the @value{GDBN} encoding machinery is
996used to convert the string during printing. If the optional
997@var{encoding} argument is not provided, or is an empty string,
998@value{GDBN} will automatically select the encoding most suitable for
999the string type. For further information on encoding in @value{GDBN}
1000please see @ref{Character Sets}.
1001
1002If the optional @var{length} argument is given, the string will be
1003fetched and encoded to the length of characters specified. If
1004the @var{length} argument is not provided, the string will be fetched
1005and encoded until a null of appropriate width is found.
1006@end defun
1007
1008@defun Value.fetch_lazy ()
1009If the @code{gdb.Value} object is currently a lazy value
1010(@code{gdb.Value.is_lazy} is @code{True}), then the value is
1011fetched from the inferior. Any errors that occur in the process
1012will produce a Python exception.
1013
1014If the @code{gdb.Value} object is not a lazy value, this method
1015has no effect.
1016
1017This method does not return a value.
1018@end defun
1019
1020
1021@node Types In Python
1022@subsubsection Types In Python
1023@cindex types in Python
1024@cindex Python, working with types
1025
1026@tindex gdb.Type
1027@value{GDBN} represents types from the inferior using the class
1028@code{gdb.Type}.
1029
1030The following type-related functions are available in the @code{gdb}
1031module:
1032
1033@findex gdb.lookup_type
1034@defun gdb.lookup_type (name @r{[}, block@r{]})
697aa1b7 1035This function looks up a type by its @var{name}, which must be a string.
329baa95
DE
1036
1037If @var{block} is given, then @var{name} is looked up in that scope.
1038Otherwise, it is searched for globally.
1039
1040Ordinarily, this function will return an instance of @code{gdb.Type}.
1041If the named type cannot be found, it will throw an exception.
1042@end defun
1043
1044If the type is a structure or class type, or an enum type, the fields
1045of that type can be accessed using the Python @dfn{dictionary syntax}.
1046For example, if @code{some_type} is a @code{gdb.Type} instance holding
1047a structure type, you can access its @code{foo} field with:
1048
1049@smallexample
1050bar = some_type['foo']
1051@end smallexample
1052
1053@code{bar} will be a @code{gdb.Field} object; see below under the
1054description of the @code{Type.fields} method for a description of the
1055@code{gdb.Field} class.
1056
1057An instance of @code{Type} has the following attributes:
1058
6d7bb824
TT
1059@defvar Type.alignof
1060The alignment of this type, in bytes. Type alignment comes from the
1061debugging information; if it was not specified, then @value{GDBN} will
1062use the relevant ABI to try to determine the alignment. In some
1063cases, even this is not possible, and zero will be returned.
1064@end defvar
1065
329baa95
DE
1066@defvar Type.code
1067The type code for this type. The type code will be one of the
1068@code{TYPE_CODE_} constants defined below.
1069@end defvar
1070
1acda803
TT
1071@defvar Type.dynamic
1072A boolean indicating whether this type is dynamic. In some
1073situations, such as Rust @code{enum} types or Ada variant records, the
45fc7c99
TT
1074concrete type of a value may vary depending on its contents. That is,
1075the declared type of a variable, or the type returned by
1076@code{gdb.lookup_type} may be dynamic; while the type of the
1077variable's value will be a concrete instance of that dynamic type.
1078
1079For example, consider this code:
1080@smallexample
1081int n;
1082int array[n];
1083@end smallexample
1084
1085Here, at least conceptually (whether your compiler actually does this
1086is a separate issue), examining @w{@code{gdb.lookup_symbol("array", ...).type}}
1087could yield a @code{gdb.Type} which reports a size of @code{None}.
1088This is the dynamic type.
1089
1090However, examining @code{gdb.parse_and_eval("array").type} would yield
1091a concrete type, whose length would be known.
1acda803
TT
1092@end defvar
1093
329baa95
DE
1094@defvar Type.name
1095The name of this type. If this type has no name, then @code{None}
1096is returned.
1097@end defvar
1098
1099@defvar Type.sizeof
1100The size of this type, in target @code{char} units. Usually, a
1101target's @code{char} type will be an 8-bit byte. However, on some
1acda803
TT
1102unusual platforms, this type may have a different size. A dynamic
1103type may not have a fixed size; in this case, this attribute's value
1104will be @code{None}.
329baa95
DE
1105@end defvar
1106
1107@defvar Type.tag
1108The tag name for this type. The tag name is the name after
1109@code{struct}, @code{union}, or @code{enum} in C and C@t{++}; not all
1110languages have this concept. If this type has no tag name, then
1111@code{None} is returned.
1112@end defvar
1113
e1f2e1a2
CB
1114@defvar Type.objfile
1115The @code{gdb.Objfile} that this type was defined in, or @code{None} if
1116there is no associated objfile.
1117@end defvar
1118
329baa95
DE
1119The following methods are provided:
1120
1121@defun Type.fields ()
1122For structure and union types, this method returns the fields. Range
1123types have two fields, the minimum and maximum values. Enum types
1124have one field per enum constant. Function and method types have one
1125field per parameter. The base types of C@t{++} classes are also
1126represented as fields. If the type has no fields, or does not fit
1127into one of these categories, an empty sequence will be returned.
1128
1129Each field is a @code{gdb.Field} object, with some pre-defined attributes:
1130@table @code
1131@item bitpos
1132This attribute is not available for @code{enum} or @code{static}
9c37b5ae 1133(as in C@t{++}) fields. The value is the position, counting
1acda803
TT
1134in bits, from the start of the containing type. Note that, in a
1135dynamic type, the position of a field may not be constant. In this
45fc7c99
TT
1136case, the value will be @code{None}. Also, a dynamic type may have
1137fields that do not appear in a corresponding concrete type.
329baa95
DE
1138
1139@item enumval
1140This attribute is only available for @code{enum} fields, and its value
1141is the enumeration member's integer representation.
1142
1143@item name
1144The name of the field, or @code{None} for anonymous fields.
1145
1146@item artificial
1147This is @code{True} if the field is artificial, usually meaning that
1148it was provided by the compiler and not the user. This attribute is
1149always provided, and is @code{False} if the field is not artificial.
1150
1151@item is_base_class
1152This is @code{True} if the field represents a base class of a C@t{++}
1153structure. This attribute is always provided, and is @code{False}
1154if the field is not a base class of the type that is the argument of
1155@code{fields}, or if that type was not a C@t{++} class.
1156
1157@item bitsize
1158If the field is packed, or is a bitfield, then this will have a
1159non-zero value, which is the size of the field in bits. Otherwise,
1160this will be zero; in this case the field's size is given by its type.
1161
1162@item type
1163The type of the field. This is usually an instance of @code{Type},
1164but it can be @code{None} in some situations.
1165
1166@item parent_type
1167The type which contains this field. This is an instance of
1168@code{gdb.Type}.
1169@end table
1170@end defun
1171
1172@defun Type.array (@var{n1} @r{[}, @var{n2}@r{]})
1173Return a new @code{gdb.Type} object which represents an array of this
1174type. If one argument is given, it is the inclusive upper bound of
1175the array; in this case the lower bound is zero. If two arguments are
1176given, the first argument is the lower bound of the array, and the
1177second argument is the upper bound of the array. An array's length
1178must not be negative, but the bounds can be.
1179@end defun
1180
1181@defun Type.vector (@var{n1} @r{[}, @var{n2}@r{]})
1182Return a new @code{gdb.Type} object which represents a vector of this
1183type. If one argument is given, it is the inclusive upper bound of
1184the vector; in this case the lower bound is zero. If two arguments are
1185given, the first argument is the lower bound of the vector, and the
1186second argument is the upper bound of the vector. A vector's length
1187must not be negative, but the bounds can be.
1188
1189The difference between an @code{array} and a @code{vector} is that
1190arrays behave like in C: when used in expressions they decay to a pointer
1191to the first element whereas vectors are treated as first class values.
1192@end defun
1193
1194@defun Type.const ()
1195Return a new @code{gdb.Type} object which represents a
1196@code{const}-qualified variant of this type.
1197@end defun
1198
1199@defun Type.volatile ()
1200Return a new @code{gdb.Type} object which represents a
1201@code{volatile}-qualified variant of this type.
1202@end defun
1203
1204@defun Type.unqualified ()
1205Return a new @code{gdb.Type} object which represents an unqualified
1206variant of this type. That is, the result is neither @code{const} nor
1207@code{volatile}.
1208@end defun
1209
1210@defun Type.range ()
1211Return a Python @code{Tuple} object that contains two elements: the
1212low bound of the argument type and the high bound of that type. If
1213the type does not have a range, @value{GDBN} will raise a
1214@code{gdb.error} exception (@pxref{Exception Handling}).
1215@end defun
1216
1217@defun Type.reference ()
1218Return a new @code{gdb.Type} object which represents a reference to this
1219type.
1220@end defun
1221
1222@defun Type.pointer ()
1223Return a new @code{gdb.Type} object which represents a pointer to this
1224type.
1225@end defun
1226
1227@defun Type.strip_typedefs ()
1228Return a new @code{gdb.Type} that represents the real type,
1229after removing all layers of typedefs.
1230@end defun
1231
1232@defun Type.target ()
1233Return a new @code{gdb.Type} object which represents the target type
1234of this type.
1235
1236For a pointer type, the target type is the type of the pointed-to
1237object. For an array type (meaning C-like arrays), the target type is
1238the type of the elements of the array. For a function or method type,
1239the target type is the type of the return value. For a complex type,
1240the target type is the type of the elements. For a typedef, the
1241target type is the aliased type.
1242
1243If the type does not have a target, this method will throw an
1244exception.
1245@end defun
1246
1247@defun Type.template_argument (n @r{[}, block@r{]})
1248If this @code{gdb.Type} is an instantiation of a template, this will
1a6a384b
JL
1249return a new @code{gdb.Value} or @code{gdb.Type} which represents the
1250value of the @var{n}th template argument (indexed starting at 0).
329baa95 1251
1a6a384b
JL
1252If this @code{gdb.Type} is not a template type, or if the type has fewer
1253than @var{n} template arguments, this will throw an exception.
1254Ordinarily, only C@t{++} code will have template types.
329baa95
DE
1255
1256If @var{block} is given, then @var{name} is looked up in that scope.
1257Otherwise, it is searched for globally.
1258@end defun
1259
59fb7612
SS
1260@defun Type.optimized_out ()
1261Return @code{gdb.Value} instance of this type whose value is optimized
1262out. This allows a frame decorator to indicate that the value of an
1263argument or a local variable is not known.
1264@end defun
329baa95
DE
1265
1266Each type has a code, which indicates what category this type falls
1267into. The available type categories are represented by constants
1268defined in the @code{gdb} module:
1269
b3ce5e5f
DE
1270@vtable @code
1271@vindex TYPE_CODE_PTR
329baa95
DE
1272@item gdb.TYPE_CODE_PTR
1273The type is a pointer.
1274
b3ce5e5f 1275@vindex TYPE_CODE_ARRAY
329baa95
DE
1276@item gdb.TYPE_CODE_ARRAY
1277The type is an array.
1278
b3ce5e5f 1279@vindex TYPE_CODE_STRUCT
329baa95
DE
1280@item gdb.TYPE_CODE_STRUCT
1281The type is a structure.
1282
b3ce5e5f 1283@vindex TYPE_CODE_UNION
329baa95
DE
1284@item gdb.TYPE_CODE_UNION
1285The type is a union.
1286
b3ce5e5f 1287@vindex TYPE_CODE_ENUM
329baa95
DE
1288@item gdb.TYPE_CODE_ENUM
1289The type is an enum.
1290
b3ce5e5f 1291@vindex TYPE_CODE_FLAGS
329baa95
DE
1292@item gdb.TYPE_CODE_FLAGS
1293A bit flags type, used for things such as status registers.
1294
b3ce5e5f 1295@vindex TYPE_CODE_FUNC
329baa95
DE
1296@item gdb.TYPE_CODE_FUNC
1297The type is a function.
1298
b3ce5e5f 1299@vindex TYPE_CODE_INT
329baa95
DE
1300@item gdb.TYPE_CODE_INT
1301The type is an integer type.
1302
b3ce5e5f 1303@vindex TYPE_CODE_FLT
329baa95
DE
1304@item gdb.TYPE_CODE_FLT
1305A floating point type.
1306
b3ce5e5f 1307@vindex TYPE_CODE_VOID
329baa95
DE
1308@item gdb.TYPE_CODE_VOID
1309The special type @code{void}.
1310
b3ce5e5f 1311@vindex TYPE_CODE_SET
329baa95
DE
1312@item gdb.TYPE_CODE_SET
1313A Pascal set type.
1314
b3ce5e5f 1315@vindex TYPE_CODE_RANGE
329baa95
DE
1316@item gdb.TYPE_CODE_RANGE
1317A range type, that is, an integer type with bounds.
1318
b3ce5e5f 1319@vindex TYPE_CODE_STRING
329baa95
DE
1320@item gdb.TYPE_CODE_STRING
1321A string type. Note that this is only used for certain languages with
1322language-defined string types; C strings are not represented this way.
1323
b3ce5e5f 1324@vindex TYPE_CODE_BITSTRING
329baa95
DE
1325@item gdb.TYPE_CODE_BITSTRING
1326A string of bits. It is deprecated.
1327
b3ce5e5f 1328@vindex TYPE_CODE_ERROR
329baa95
DE
1329@item gdb.TYPE_CODE_ERROR
1330An unknown or erroneous type.
1331
b3ce5e5f 1332@vindex TYPE_CODE_METHOD
329baa95 1333@item gdb.TYPE_CODE_METHOD
9c37b5ae 1334A method type, as found in C@t{++}.
329baa95 1335
b3ce5e5f 1336@vindex TYPE_CODE_METHODPTR
329baa95
DE
1337@item gdb.TYPE_CODE_METHODPTR
1338A pointer-to-member-function.
1339
b3ce5e5f 1340@vindex TYPE_CODE_MEMBERPTR
329baa95
DE
1341@item gdb.TYPE_CODE_MEMBERPTR
1342A pointer-to-member.
1343
b3ce5e5f 1344@vindex TYPE_CODE_REF
329baa95
DE
1345@item gdb.TYPE_CODE_REF
1346A reference type.
1347
3fcf899d
AV
1348@vindex TYPE_CODE_RVALUE_REF
1349@item gdb.TYPE_CODE_RVALUE_REF
1350A C@t{++}11 rvalue reference type.
1351
b3ce5e5f 1352@vindex TYPE_CODE_CHAR
329baa95
DE
1353@item gdb.TYPE_CODE_CHAR
1354A character type.
1355
b3ce5e5f 1356@vindex TYPE_CODE_BOOL
329baa95
DE
1357@item gdb.TYPE_CODE_BOOL
1358A boolean type.
1359
b3ce5e5f 1360@vindex TYPE_CODE_COMPLEX
329baa95
DE
1361@item gdb.TYPE_CODE_COMPLEX
1362A complex float type.
1363
b3ce5e5f 1364@vindex TYPE_CODE_TYPEDEF
329baa95
DE
1365@item gdb.TYPE_CODE_TYPEDEF
1366A typedef to some other type.
1367
b3ce5e5f 1368@vindex TYPE_CODE_NAMESPACE
329baa95
DE
1369@item gdb.TYPE_CODE_NAMESPACE
1370A C@t{++} namespace.
1371
b3ce5e5f 1372@vindex TYPE_CODE_DECFLOAT
329baa95
DE
1373@item gdb.TYPE_CODE_DECFLOAT
1374A decimal floating point type.
1375
b3ce5e5f 1376@vindex TYPE_CODE_INTERNAL_FUNCTION
329baa95
DE
1377@item gdb.TYPE_CODE_INTERNAL_FUNCTION
1378A function internal to @value{GDBN}. This is the type used to represent
1379convenience functions.
b3ce5e5f 1380@end vtable
329baa95
DE
1381
1382Further support for types is provided in the @code{gdb.types}
1383Python module (@pxref{gdb.types}).
1384
1385@node Pretty Printing API
1386@subsubsection Pretty Printing API
b3ce5e5f 1387@cindex python pretty printing api
329baa95 1388
329baa95 1389A pretty-printer is just an object that holds a value and implements a
27a9fec6
TT
1390specific interface, defined here. An example output is provided
1391(@pxref{Pretty Printing}).
329baa95
DE
1392
1393@defun pretty_printer.children (self)
1394@value{GDBN} will call this method on a pretty-printer to compute the
1395children of the pretty-printer's value.
1396
1397This method must return an object conforming to the Python iterator
1398protocol. Each item returned by the iterator must be a tuple holding
1399two elements. The first element is the ``name'' of the child; the
1400second element is the child's value. The value can be any Python
1401object which is convertible to a @value{GDBN} value.
1402
1403This method is optional. If it does not exist, @value{GDBN} will act
1404as though the value has no children.
2e62ab40 1405
a97c8e56
TT
1406For efficiency, the @code{children} method should lazily compute its
1407results. This will let @value{GDBN} read as few elements as
1408necessary, for example when various print settings (@pxref{Print
1409Settings}) or @code{-var-list-children} (@pxref{GDB/MI Variable
1410Objects}) limit the number of elements to be displayed.
1411
2e62ab40
AB
1412Children may be hidden from display based on the value of @samp{set
1413print max-depth} (@pxref{Print Settings}).
329baa95
DE
1414@end defun
1415
1416@defun pretty_printer.display_hint (self)
1417The CLI may call this method and use its result to change the
1418formatting of a value. The result will also be supplied to an MI
1419consumer as a @samp{displayhint} attribute of the variable being
1420printed.
1421
1422This method is optional. If it does exist, this method must return a
9f9aa852 1423string or the special value @code{None}.
329baa95
DE
1424
1425Some display hints are predefined by @value{GDBN}:
1426
1427@table @samp
1428@item array
1429Indicate that the object being printed is ``array-like''. The CLI
1430uses this to respect parameters such as @code{set print elements} and
1431@code{set print array}.
1432
1433@item map
1434Indicate that the object being printed is ``map-like'', and that the
1435children of this value can be assumed to alternate between keys and
1436values.
1437
1438@item string
1439Indicate that the object being printed is ``string-like''. If the
1440printer's @code{to_string} method returns a Python string of some
1441kind, then @value{GDBN} will call its internal language-specific
1442string-printing function to format the string. For the CLI this means
1443adding quotation marks, possibly escaping some characters, respecting
1444@code{set print elements}, and the like.
1445@end table
9f9aa852
AB
1446
1447The special value @code{None} causes @value{GDBN} to apply the default
1448display rules.
329baa95
DE
1449@end defun
1450
1451@defun pretty_printer.to_string (self)
1452@value{GDBN} will call this method to display the string
1453representation of the value passed to the object's constructor.
1454
1455When printing from the CLI, if the @code{to_string} method exists,
1456then @value{GDBN} will prepend its result to the values returned by
1457@code{children}. Exactly how this formatting is done is dependent on
1458the display hint, and may change as more hints are added. Also,
1459depending on the print settings (@pxref{Print Settings}), the CLI may
1460print just the result of @code{to_string} in a stack trace, omitting
1461the result of @code{children}.
1462
1463If this method returns a string, it is printed verbatim.
1464
1465Otherwise, if this method returns an instance of @code{gdb.Value},
1466then @value{GDBN} prints this value. This may result in a call to
1467another pretty-printer.
1468
1469If instead the method returns a Python value which is convertible to a
1470@code{gdb.Value}, then @value{GDBN} performs the conversion and prints
1471the resulting value. Again, this may result in a call to another
1472pretty-printer. Python scalars (integers, floats, and booleans) and
1473strings are convertible to @code{gdb.Value}; other types are not.
1474
1475Finally, if this method returns @code{None} then no further operations
1476are peformed in this method and nothing is printed.
1477
1478If the result is not one of these types, an exception is raised.
1479@end defun
1480
1481@value{GDBN} provides a function which can be used to look up the
1482default pretty-printer for a @code{gdb.Value}:
1483
1484@findex gdb.default_visualizer
1485@defun gdb.default_visualizer (value)
1486This function takes a @code{gdb.Value} object as an argument. If a
1487pretty-printer for this value exists, then it is returned. If no such
1488printer exists, then this returns @code{None}.
1489@end defun
1490
1491@node Selecting Pretty-Printers
1492@subsubsection Selecting Pretty-Printers
b3ce5e5f 1493@cindex selecting python pretty-printers
329baa95 1494
48869a5f
TT
1495@value{GDBN} provides several ways to register a pretty-printer:
1496globally, per program space, and per objfile. When choosing how to
1497register your pretty-printer, a good rule is to register it with the
1498smallest scope possible: that is prefer a specific objfile first, then
1499a program space, and only register a printer globally as a last
1500resort.
1501
1502@findex gdb.pretty_printers
1503@defvar gdb.pretty_printers
329baa95
DE
1504The Python list @code{gdb.pretty_printers} contains an array of
1505functions or callable objects that have been registered via addition
1506as a pretty-printer. Printers in this list are called @code{global}
1507printers, they're available when debugging all inferiors.
48869a5f
TT
1508@end defvar
1509
329baa95
DE
1510Each @code{gdb.Progspace} contains a @code{pretty_printers} attribute.
1511Each @code{gdb.Objfile} also contains a @code{pretty_printers}
1512attribute.
1513
1514Each function on these lists is passed a single @code{gdb.Value}
1515argument and should return a pretty-printer object conforming to the
1516interface definition above (@pxref{Pretty Printing API}). If a function
1517cannot create a pretty-printer for the value, it should return
1518@code{None}.
1519
1520@value{GDBN} first checks the @code{pretty_printers} attribute of each
1521@code{gdb.Objfile} in the current program space and iteratively calls
1522each enabled lookup routine in the list for that @code{gdb.Objfile}
1523until it receives a pretty-printer object.
1524If no pretty-printer is found in the objfile lists, @value{GDBN} then
1525searches the pretty-printer list of the current program space,
1526calling each enabled function until an object is returned.
1527After these lists have been exhausted, it tries the global
1528@code{gdb.pretty_printers} list, again calling each enabled function until an
1529object is returned.
1530
1531The order in which the objfiles are searched is not specified. For a
1532given list, functions are always invoked from the head of the list,
1533and iterated over sequentially until the end of the list, or a printer
1534object is returned.
1535
1536For various reasons a pretty-printer may not work.
1537For example, the underlying data structure may have changed and
1538the pretty-printer is out of date.
1539
1540The consequences of a broken pretty-printer are severe enough that
1541@value{GDBN} provides support for enabling and disabling individual
1542printers. For example, if @code{print frame-arguments} is on,
1543a backtrace can become highly illegible if any argument is printed
1544with a broken printer.
1545
1546Pretty-printers are enabled and disabled by attaching an @code{enabled}
1547attribute to the registered function or callable object. If this attribute
1548is present and its value is @code{False}, the printer is disabled, otherwise
1549the printer is enabled.
1550
1551@node Writing a Pretty-Printer
1552@subsubsection Writing a Pretty-Printer
1553@cindex writing a pretty-printer
1554
1555A pretty-printer consists of two parts: a lookup function to detect
1556if the type is supported, and the printer itself.
1557
1558Here is an example showing how a @code{std::string} printer might be
1559written. @xref{Pretty Printing API}, for details on the API this class
1560must provide.
1561
1562@smallexample
1563class StdStringPrinter(object):
1564 "Print a std::string"
1565
1566 def __init__(self, val):
1567 self.val = val
1568
1569 def to_string(self):
1570 return self.val['_M_dataplus']['_M_p']
1571
1572 def display_hint(self):
1573 return 'string'
1574@end smallexample
1575
1576And here is an example showing how a lookup function for the printer
1577example above might be written.
1578
1579@smallexample
1580def str_lookup_function(val):
1581 lookup_tag = val.type.tag
1582 if lookup_tag == None:
1583 return None
1584 regex = re.compile("^std::basic_string<char,.*>$")
1585 if regex.match(lookup_tag):
1586 return StdStringPrinter(val)
1587 return None
1588@end smallexample
1589
1590The example lookup function extracts the value's type, and attempts to
1591match it to a type that it can pretty-print. If it is a type the
1592printer can pretty-print, it will return a printer object. If not, it
1593returns @code{None}.
1594
1595We recommend that you put your core pretty-printers into a Python
1596package. If your pretty-printers are for use with a library, we
1597further recommend embedding a version number into the package name.
1598This practice will enable @value{GDBN} to load multiple versions of
1599your pretty-printers at the same time, because they will have
1600different names.
1601
1602You should write auto-loaded code (@pxref{Python Auto-loading}) such that it
1603can be evaluated multiple times without changing its meaning. An
1604ideal auto-load file will consist solely of @code{import}s of your
1605printer modules, followed by a call to a register pretty-printers with
1606the current objfile.
1607
1608Taken as a whole, this approach will scale nicely to multiple
1609inferiors, each potentially using a different library version.
1610Embedding a version number in the Python package name will ensure that
1611@value{GDBN} is able to load both sets of printers simultaneously.
1612Then, because the search for pretty-printers is done by objfile, and
1613because your auto-loaded code took care to register your library's
1614printers with a specific objfile, @value{GDBN} will find the correct
1615printers for the specific version of the library used by each
1616inferior.
1617
1618To continue the @code{std::string} example (@pxref{Pretty Printing API}),
1619this code might appear in @code{gdb.libstdcxx.v6}:
1620
1621@smallexample
1622def register_printers(objfile):
1623 objfile.pretty_printers.append(str_lookup_function)
1624@end smallexample
1625
1626@noindent
1627And then the corresponding contents of the auto-load file would be:
1628
1629@smallexample
1630import gdb.libstdcxx.v6
1631gdb.libstdcxx.v6.register_printers(gdb.current_objfile())
1632@end smallexample
1633
1634The previous example illustrates a basic pretty-printer.
1635There are a few things that can be improved on.
1636The printer doesn't have a name, making it hard to identify in a
1637list of installed printers. The lookup function has a name, but
1638lookup functions can have arbitrary, even identical, names.
1639
1640Second, the printer only handles one type, whereas a library typically has
1641several types. One could install a lookup function for each desired type
1642in the library, but one could also have a single lookup function recognize
1643several types. The latter is the conventional way this is handled.
1644If a pretty-printer can handle multiple data types, then its
1645@dfn{subprinters} are the printers for the individual data types.
1646
1647The @code{gdb.printing} module provides a formal way of solving these
1648problems (@pxref{gdb.printing}).
1649Here is another example that handles multiple types.
1650
1651These are the types we are going to pretty-print:
1652
1653@smallexample
1654struct foo @{ int a, b; @};
1655struct bar @{ struct foo x, y; @};
1656@end smallexample
1657
1658Here are the printers:
1659
1660@smallexample
1661class fooPrinter:
1662 """Print a foo object."""
1663
1664 def __init__(self, val):
1665 self.val = val
1666
1667 def to_string(self):
1668 return ("a=<" + str(self.val["a"]) +
1669 "> b=<" + str(self.val["b"]) + ">")
1670
1671class barPrinter:
1672 """Print a bar object."""
1673
1674 def __init__(self, val):
1675 self.val = val
1676
1677 def to_string(self):
1678 return ("x=<" + str(self.val["x"]) +
1679 "> y=<" + str(self.val["y"]) + ">")
1680@end smallexample
1681
1682This example doesn't need a lookup function, that is handled by the
1683@code{gdb.printing} module. Instead a function is provided to build up
1684the object that handles the lookup.
1685
1686@smallexample
1687import gdb.printing
1688
1689def build_pretty_printer():
1690 pp = gdb.printing.RegexpCollectionPrettyPrinter(
1691 "my_library")
1692 pp.add_printer('foo', '^foo$', fooPrinter)
1693 pp.add_printer('bar', '^bar$', barPrinter)
1694 return pp
1695@end smallexample
1696
1697And here is the autoload support:
1698
1699@smallexample
1700import gdb.printing
1701import my_library
1702gdb.printing.register_pretty_printer(
1703 gdb.current_objfile(),
1704 my_library.build_pretty_printer())
1705@end smallexample
1706
1707Finally, when this printer is loaded into @value{GDBN}, here is the
1708corresponding output of @samp{info pretty-printer}:
1709
1710@smallexample
1711(gdb) info pretty-printer
1712my_library.so:
1713 my_library
1714 foo
1715 bar
1716@end smallexample
1717
1718@node Type Printing API
1719@subsubsection Type Printing API
1720@cindex type printing API for Python
1721
1722@value{GDBN} provides a way for Python code to customize type display.
1723This is mainly useful for substituting canonical typedef names for
1724types.
1725
1726@cindex type printer
1727A @dfn{type printer} is just a Python object conforming to a certain
1728protocol. A simple base class implementing the protocol is provided;
1729see @ref{gdb.types}. A type printer must supply at least:
1730
1731@defivar type_printer enabled
1732A boolean which is True if the printer is enabled, and False
1733otherwise. This is manipulated by the @code{enable type-printer}
1734and @code{disable type-printer} commands.
1735@end defivar
1736
1737@defivar type_printer name
1738The name of the type printer. This must be a string. This is used by
1739the @code{enable type-printer} and @code{disable type-printer}
1740commands.
1741@end defivar
1742
1743@defmethod type_printer instantiate (self)
1744This is called by @value{GDBN} at the start of type-printing. It is
1745only called if the type printer is enabled. This method must return a
1746new object that supplies a @code{recognize} method, as described below.
1747@end defmethod
1748
1749
1750When displaying a type, say via the @code{ptype} command, @value{GDBN}
1751will compute a list of type recognizers. This is done by iterating
1752first over the per-objfile type printers (@pxref{Objfiles In Python}),
1753followed by the per-progspace type printers (@pxref{Progspaces In
1754Python}), and finally the global type printers.
1755
1756@value{GDBN} will call the @code{instantiate} method of each enabled
1757type printer. If this method returns @code{None}, then the result is
1758ignored; otherwise, it is appended to the list of recognizers.
1759
1760Then, when @value{GDBN} is going to display a type name, it iterates
1761over the list of recognizers. For each one, it calls the recognition
1762function, stopping if the function returns a non-@code{None} value.
1763The recognition function is defined as:
1764
1765@defmethod type_recognizer recognize (self, type)
1766If @var{type} is not recognized, return @code{None}. Otherwise,
1767return a string which is to be printed as the name of @var{type}.
697aa1b7
EZ
1768The @var{type} argument will be an instance of @code{gdb.Type}
1769(@pxref{Types In Python}).
329baa95
DE
1770@end defmethod
1771
1772@value{GDBN} uses this two-pass approach so that type printers can
1773efficiently cache information without holding on to it too long. For
1774example, it can be convenient to look up type information in a type
1775printer and hold it for a recognizer's lifetime; if a single pass were
1776done then type printers would have to make use of the event system in
1777order to avoid holding information that could become stale as the
1778inferior changed.
1779
1780@node Frame Filter API
521b499b 1781@subsubsection Filtering Frames
329baa95
DE
1782@cindex frame filters api
1783
1784Frame filters are Python objects that manipulate the visibility of a
1785frame or frames when a backtrace (@pxref{Backtrace}) is printed by
1786@value{GDBN}.
1787
1788Only commands that print a backtrace, or, in the case of @sc{gdb/mi}
1789commands (@pxref{GDB/MI}), those that return a collection of frames
1790are affected. The commands that work with frame filters are:
1791
1792@code{backtrace} (@pxref{backtrace-command,, The backtrace command}),
1793@code{-stack-list-frames}
1794(@pxref{-stack-list-frames,, The -stack-list-frames command}),
1795@code{-stack-list-variables} (@pxref{-stack-list-variables,, The
1796-stack-list-variables command}), @code{-stack-list-arguments}
1797@pxref{-stack-list-arguments,, The -stack-list-arguments command}) and
1798@code{-stack-list-locals} (@pxref{-stack-list-locals,, The
1799-stack-list-locals command}).
1800
1801A frame filter works by taking an iterator as an argument, applying
1802actions to the contents of that iterator, and returning another
1803iterator (or, possibly, the same iterator it was provided in the case
1804where the filter does not perform any operations). Typically, frame
1805filters utilize tools such as the Python's @code{itertools} module to
1806work with and create new iterators from the source iterator.
1807Regardless of how a filter chooses to apply actions, it must not alter
1808the underlying @value{GDBN} frame or frames, or attempt to alter the
1809call-stack within @value{GDBN}. This preserves data integrity within
1810@value{GDBN}. Frame filters are executed on a priority basis and care
1811should be taken that some frame filters may have been executed before,
1812and that some frame filters will be executed after.
1813
1814An important consideration when designing frame filters, and well
1815worth reflecting upon, is that frame filters should avoid unwinding
1816the call stack if possible. Some stacks can run very deep, into the
1817tens of thousands in some cases. To search every frame when a frame
1818filter executes may be too expensive at that step. The frame filter
1819cannot know how many frames it has to iterate over, and it may have to
1820iterate through them all. This ends up duplicating effort as
1821@value{GDBN} performs this iteration when it prints the frames. If
1822the filter can defer unwinding frames until frame decorators are
1823executed, after the last filter has executed, it should. @xref{Frame
1824Decorator API}, for more information on decorators. Also, there are
1825examples for both frame decorators and filters in later chapters.
1826@xref{Writing a Frame Filter}, for more information.
1827
1828The Python dictionary @code{gdb.frame_filters} contains key/object
1829pairings that comprise a frame filter. Frame filters in this
1830dictionary are called @code{global} frame filters, and they are
1831available when debugging all inferiors. These frame filters must
1832register with the dictionary directly. In addition to the
1833@code{global} dictionary, there are other dictionaries that are loaded
1834with different inferiors via auto-loading (@pxref{Python
1835Auto-loading}). The two other areas where frame filter dictionaries
1836can be found are: @code{gdb.Progspace} which contains a
1837@code{frame_filters} dictionary attribute, and each @code{gdb.Objfile}
1838object which also contains a @code{frame_filters} dictionary
1839attribute.
1840
1841When a command is executed from @value{GDBN} that is compatible with
1842frame filters, @value{GDBN} combines the @code{global},
1843@code{gdb.Progspace} and all @code{gdb.Objfile} dictionaries currently
1844loaded. All of the @code{gdb.Objfile} dictionaries are combined, as
1845several frames, and thus several object files, might be in use.
1846@value{GDBN} then prunes any frame filter whose @code{enabled}
1847attribute is @code{False}. This pruned list is then sorted according
1848to the @code{priority} attribute in each filter.
1849
1850Once the dictionaries are combined, pruned and sorted, @value{GDBN}
1851creates an iterator which wraps each frame in the call stack in a
1852@code{FrameDecorator} object, and calls each filter in order. The
1853output from the previous filter will always be the input to the next
1854filter, and so on.
1855
1856Frame filters have a mandatory interface which each frame filter must
1857implement, defined here:
1858
1859@defun FrameFilter.filter (iterator)
1860@value{GDBN} will call this method on a frame filter when it has
1861reached the order in the priority list for that filter.
1862
1863For example, if there are four frame filters:
1864
1865@smallexample
1866Name Priority
1867
1868Filter1 5
1869Filter2 10
1870Filter3 100
1871Filter4 1
1872@end smallexample
1873
1874The order that the frame filters will be called is:
1875
1876@smallexample
1877Filter3 -> Filter2 -> Filter1 -> Filter4
1878@end smallexample
1879
1880Note that the output from @code{Filter3} is passed to the input of
1881@code{Filter2}, and so on.
1882
1883This @code{filter} method is passed a Python iterator. This iterator
1884contains a sequence of frame decorators that wrap each
1885@code{gdb.Frame}, or a frame decorator that wraps another frame
1886decorator. The first filter that is executed in the sequence of frame
1887filters will receive an iterator entirely comprised of default
1888@code{FrameDecorator} objects. However, after each frame filter is
1889executed, the previous frame filter may have wrapped some or all of
1890the frame decorators with their own frame decorator. As frame
1891decorators must also conform to a mandatory interface, these
1892decorators can be assumed to act in a uniform manner (@pxref{Frame
1893Decorator API}).
1894
1895This method must return an object conforming to the Python iterator
1896protocol. Each item in the iterator must be an object conforming to
1897the frame decorator interface. If a frame filter does not wish to
1898perform any operations on this iterator, it should return that
1899iterator untouched.
1900
1901This method is not optional. If it does not exist, @value{GDBN} will
1902raise and print an error.
1903@end defun
1904
1905@defvar FrameFilter.name
1906The @code{name} attribute must be Python string which contains the
1907name of the filter displayed by @value{GDBN} (@pxref{Frame Filter
1908Management}). This attribute may contain any combination of letters
1909or numbers. Care should be taken to ensure that it is unique. This
1910attribute is mandatory.
1911@end defvar
1912
1913@defvar FrameFilter.enabled
1914The @code{enabled} attribute must be Python boolean. This attribute
1915indicates to @value{GDBN} whether the frame filter is enabled, and
1916should be considered when frame filters are executed. If
1917@code{enabled} is @code{True}, then the frame filter will be executed
1918when any of the backtrace commands detailed earlier in this chapter
1919are executed. If @code{enabled} is @code{False}, then the frame
1920filter will not be executed. This attribute is mandatory.
1921@end defvar
1922
1923@defvar FrameFilter.priority
1924The @code{priority} attribute must be Python integer. This attribute
1925controls the order of execution in relation to other frame filters.
1926There are no imposed limits on the range of @code{priority} other than
1927it must be a valid integer. The higher the @code{priority} attribute,
1928the sooner the frame filter will be executed in relation to other
1929frame filters. Although @code{priority} can be negative, it is
1930recommended practice to assume zero is the lowest priority that a
1931frame filter can be assigned. Frame filters that have the same
1932priority are executed in unsorted order in that priority slot. This
521b499b 1933attribute is mandatory. 100 is a good default priority.
329baa95
DE
1934@end defvar
1935
1936@node Frame Decorator API
521b499b 1937@subsubsection Decorating Frames
329baa95
DE
1938@cindex frame decorator api
1939
1940Frame decorators are sister objects to frame filters (@pxref{Frame
1941Filter API}). Frame decorators are applied by a frame filter and can
1942only be used in conjunction with frame filters.
1943
1944The purpose of a frame decorator is to customize the printed content
1945of each @code{gdb.Frame} in commands where frame filters are executed.
1946This concept is called decorating a frame. Frame decorators decorate
1947a @code{gdb.Frame} with Python code contained within each API call.
1948This separates the actual data contained in a @code{gdb.Frame} from
1949the decorated data produced by a frame decorator. This abstraction is
1950necessary to maintain integrity of the data contained in each
1951@code{gdb.Frame}.
1952
1953Frame decorators have a mandatory interface, defined below.
1954
1955@value{GDBN} already contains a frame decorator called
1956@code{FrameDecorator}. This contains substantial amounts of
1957boilerplate code to decorate the content of a @code{gdb.Frame}. It is
1958recommended that other frame decorators inherit and extend this
1959object, and only to override the methods needed.
1960
521b499b
TT
1961@tindex gdb.FrameDecorator
1962@code{FrameDecorator} is defined in the Python module
1963@code{gdb.FrameDecorator}, so your code can import it like:
1964@smallexample
1965from gdb.FrameDecorator import FrameDecorator
1966@end smallexample
1967
329baa95
DE
1968@defun FrameDecorator.elided (self)
1969
1970The @code{elided} method groups frames together in a hierarchical
1971system. An example would be an interpreter, where multiple low-level
1972frames make up a single call in the interpreted language. In this
1973example, the frame filter would elide the low-level frames and present
1974a single high-level frame, representing the call in the interpreted
1975language, to the user.
1976
1977The @code{elided} function must return an iterable and this iterable
1978must contain the frames that are being elided wrapped in a suitable
1979frame decorator. If no frames are being elided this function may
1980return an empty iterable, or @code{None}. Elided frames are indented
1981from normal frames in a @code{CLI} backtrace, or in the case of
1982@code{GDB/MI}, are placed in the @code{children} field of the eliding
1983frame.
1984
1985It is the frame filter's task to also filter out the elided frames from
1986the source iterator. This will avoid printing the frame twice.
1987@end defun
1988
1989@defun FrameDecorator.function (self)
1990
1991This method returns the name of the function in the frame that is to
1992be printed.
1993
1994This method must return a Python string describing the function, or
1995@code{None}.
1996
1997If this function returns @code{None}, @value{GDBN} will not print any
1998data for this field.
1999@end defun
2000
2001@defun FrameDecorator.address (self)
2002
2003This method returns the address of the frame that is to be printed.
2004
2005This method must return a Python numeric integer type of sufficient
2006size to describe the address of the frame, or @code{None}.
2007
2008If this function returns a @code{None}, @value{GDBN} will not print
2009any data for this field.
2010@end defun
2011
2012@defun FrameDecorator.filename (self)
2013
2014This method returns the filename and path associated with this frame.
2015
2016This method must return a Python string containing the filename and
2017the path to the object file backing the frame, or @code{None}.
2018
2019If this function returns a @code{None}, @value{GDBN} will not print
2020any data for this field.
2021@end defun
2022
2023@defun FrameDecorator.line (self):
2024
2025This method returns the line number associated with the current
2026position within the function addressed by this frame.
2027
2028This method must return a Python integer type, or @code{None}.
2029
2030If this function returns a @code{None}, @value{GDBN} will not print
2031any data for this field.
2032@end defun
2033
2034@defun FrameDecorator.frame_args (self)
2035@anchor{frame_args}
2036
2037This method must return an iterable, or @code{None}. Returning an
2038empty iterable, or @code{None} means frame arguments will not be
2039printed for this frame. This iterable must contain objects that
2040implement two methods, described here.
2041
2042This object must implement a @code{argument} method which takes a
2043single @code{self} parameter and must return a @code{gdb.Symbol}
2044(@pxref{Symbols In Python}), or a Python string. The object must also
2045implement a @code{value} method which takes a single @code{self}
2046parameter and must return a @code{gdb.Value} (@pxref{Values From
2047Inferior}), a Python value, or @code{None}. If the @code{value}
2048method returns @code{None}, and the @code{argument} method returns a
2049@code{gdb.Symbol}, @value{GDBN} will look-up and print the value of
2050the @code{gdb.Symbol} automatically.
2051
2052A brief example:
2053
2054@smallexample
2055class SymValueWrapper():
2056
2057 def __init__(self, symbol, value):
2058 self.sym = symbol
2059 self.val = value
2060
2061 def value(self):
2062 return self.val
2063
2064 def symbol(self):
2065 return self.sym
2066
2067class SomeFrameDecorator()
2068...
2069...
2070 def frame_args(self):
2071 args = []
2072 try:
2073 block = self.inferior_frame.block()
2074 except:
2075 return None
2076
2077 # Iterate over all symbols in a block. Only add
2078 # symbols that are arguments.
2079 for sym in block:
2080 if not sym.is_argument:
2081 continue
2082 args.append(SymValueWrapper(sym,None))
2083
2084 # Add example synthetic argument.
2085 args.append(SymValueWrapper(``foo'', 42))
2086
2087 return args
2088@end smallexample
2089@end defun
2090
2091@defun FrameDecorator.frame_locals (self)
2092
2093This method must return an iterable or @code{None}. Returning an
2094empty iterable, or @code{None} means frame local arguments will not be
2095printed for this frame.
2096
2097The object interface, the description of the various strategies for
2098reading frame locals, and the example are largely similar to those
2099described in the @code{frame_args} function, (@pxref{frame_args,,The
2100frame filter frame_args function}). Below is a modified example:
2101
2102@smallexample
2103class SomeFrameDecorator()
2104...
2105...
2106 def frame_locals(self):
2107 vars = []
2108 try:
2109 block = self.inferior_frame.block()
2110 except:
2111 return None
2112
2113 # Iterate over all symbols in a block. Add all
2114 # symbols, except arguments.
2115 for sym in block:
2116 if sym.is_argument:
2117 continue
2118 vars.append(SymValueWrapper(sym,None))
2119
2120 # Add an example of a synthetic local variable.
2121 vars.append(SymValueWrapper(``bar'', 99))
2122
2123 return vars
2124@end smallexample
2125@end defun
2126
2127@defun FrameDecorator.inferior_frame (self):
2128
2129This method must return the underlying @code{gdb.Frame} that this
2130frame decorator is decorating. @value{GDBN} requires the underlying
2131frame for internal frame information to determine how to print certain
2132values when printing a frame.
2133@end defun
2134
2135@node Writing a Frame Filter
2136@subsubsection Writing a Frame Filter
2137@cindex writing a frame filter
2138
2139There are three basic elements that a frame filter must implement: it
2140must correctly implement the documented interface (@pxref{Frame Filter
2141API}), it must register itself with @value{GDBN}, and finally, it must
2142decide if it is to work on the data provided by @value{GDBN}. In all
2143cases, whether it works on the iterator or not, each frame filter must
2144return an iterator. A bare-bones frame filter follows the pattern in
2145the following example.
2146
2147@smallexample
2148import gdb
2149
2150class FrameFilter():
2151
2152 def __init__(self):
2153 # Frame filter attribute creation.
2154 #
2155 # 'name' is the name of the filter that GDB will display.
2156 #
2157 # 'priority' is the priority of the filter relative to other
2158 # filters.
2159 #
2160 # 'enabled' is a boolean that indicates whether this filter is
2161 # enabled and should be executed.
2162
2163 self.name = "Foo"
2164 self.priority = 100
2165 self.enabled = True
2166
2167 # Register this frame filter with the global frame_filters
2168 # dictionary.
2169 gdb.frame_filters[self.name] = self
2170
2171 def filter(self, frame_iter):
2172 # Just return the iterator.
2173 return frame_iter
2174@end smallexample
2175
2176The frame filter in the example above implements the three
2177requirements for all frame filters. It implements the API, self
2178registers, and makes a decision on the iterator (in this case, it just
2179returns the iterator untouched).
2180
2181The first step is attribute creation and assignment, and as shown in
2182the comments the filter assigns the following attributes: @code{name},
2183@code{priority} and whether the filter should be enabled with the
2184@code{enabled} attribute.
2185
2186The second step is registering the frame filter with the dictionary or
2187dictionaries that the frame filter has interest in. As shown in the
2188comments, this filter just registers itself with the global dictionary
2189@code{gdb.frame_filters}. As noted earlier, @code{gdb.frame_filters}
2190is a dictionary that is initialized in the @code{gdb} module when
2191@value{GDBN} starts. What dictionary a filter registers with is an
2192important consideration. Generally, if a filter is specific to a set
2193of code, it should be registered either in the @code{objfile} or
2194@code{progspace} dictionaries as they are specific to the program
2195currently loaded in @value{GDBN}. The global dictionary is always
2196present in @value{GDBN} and is never unloaded. Any filters registered
2197with the global dictionary will exist until @value{GDBN} exits. To
2198avoid filters that may conflict, it is generally better to register
2199frame filters against the dictionaries that more closely align with
2200the usage of the filter currently in question. @xref{Python
2201Auto-loading}, for further information on auto-loading Python scripts.
2202
2203@value{GDBN} takes a hands-off approach to frame filter registration,
2204therefore it is the frame filter's responsibility to ensure
2205registration has occurred, and that any exceptions are handled
2206appropriately. In particular, you may wish to handle exceptions
2207relating to Python dictionary key uniqueness. It is mandatory that
2208the dictionary key is the same as frame filter's @code{name}
2209attribute. When a user manages frame filters (@pxref{Frame Filter
2210Management}), the names @value{GDBN} will display are those contained
2211in the @code{name} attribute.
2212
2213The final step of this example is the implementation of the
2214@code{filter} method. As shown in the example comments, we define the
2215@code{filter} method and note that the method must take an iterator,
2216and also must return an iterator. In this bare-bones example, the
2217frame filter is not very useful as it just returns the iterator
2218untouched. However this is a valid operation for frame filters that
2219have the @code{enabled} attribute set, but decide not to operate on
2220any frames.
2221
2222In the next example, the frame filter operates on all frames and
2223utilizes a frame decorator to perform some work on the frames.
2224@xref{Frame Decorator API}, for further information on the frame
2225decorator interface.
2226
2227This example works on inlined frames. It highlights frames which are
2228inlined by tagging them with an ``[inlined]'' tag. By applying a
2229frame decorator to all frames with the Python @code{itertools imap}
2230method, the example defers actions to the frame decorator. Frame
2231decorators are only processed when @value{GDBN} prints the backtrace.
2232
2233This introduces a new decision making topic: whether to perform
2234decision making operations at the filtering step, or at the printing
2235step. In this example's approach, it does not perform any filtering
2236decisions at the filtering step beyond mapping a frame decorator to
2237each frame. This allows the actual decision making to be performed
2238when each frame is printed. This is an important consideration, and
2239well worth reflecting upon when designing a frame filter. An issue
2240that frame filters should avoid is unwinding the stack if possible.
2241Some stacks can run very deep, into the tens of thousands in some
2242cases. To search every frame to determine if it is inlined ahead of
2243time may be too expensive at the filtering step. The frame filter
2244cannot know how many frames it has to iterate over, and it would have
2245to iterate through them all. This ends up duplicating effort as
2246@value{GDBN} performs this iteration when it prints the frames.
2247
2248In this example decision making can be deferred to the printing step.
2249As each frame is printed, the frame decorator can examine each frame
2250in turn when @value{GDBN} iterates. From a performance viewpoint,
2251this is the most appropriate decision to make as it avoids duplicating
2252the effort that the printing step would undertake anyway. Also, if
2253there are many frame filters unwinding the stack during filtering, it
2254can substantially delay the printing of the backtrace which will
2255result in large memory usage, and a poor user experience.
2256
2257@smallexample
2258class InlineFilter():
2259
2260 def __init__(self):
2261 self.name = "InlinedFrameFilter"
2262 self.priority = 100
2263 self.enabled = True
2264 gdb.frame_filters[self.name] = self
2265
2266 def filter(self, frame_iter):
2267 frame_iter = itertools.imap(InlinedFrameDecorator,
2268 frame_iter)
2269 return frame_iter
2270@end smallexample
2271
2272This frame filter is somewhat similar to the earlier example, except
2273that the @code{filter} method applies a frame decorator object called
2274@code{InlinedFrameDecorator} to each element in the iterator. The
2275@code{imap} Python method is light-weight. It does not proactively
2276iterate over the iterator, but rather creates a new iterator which
2277wraps the existing one.
2278
2279Below is the frame decorator for this example.
2280
2281@smallexample
2282class InlinedFrameDecorator(FrameDecorator):
2283
2284 def __init__(self, fobj):
2285 super(InlinedFrameDecorator, self).__init__(fobj)
2286
2287 def function(self):
2288 frame = fobj.inferior_frame()
2289 name = str(frame.name())
2290
2291 if frame.type() == gdb.INLINE_FRAME:
2292 name = name + " [inlined]"
2293
2294 return name
2295@end smallexample
2296
2297This frame decorator only defines and overrides the @code{function}
2298method. It lets the supplied @code{FrameDecorator}, which is shipped
2299with @value{GDBN}, perform the other work associated with printing
2300this frame.
2301
2302The combination of these two objects create this output from a
2303backtrace:
2304
2305@smallexample
2306#0 0x004004e0 in bar () at inline.c:11
2307#1 0x00400566 in max [inlined] (b=6, a=12) at inline.c:21
2308#2 0x00400566 in main () at inline.c:31
2309@end smallexample
2310
2311So in the case of this example, a frame decorator is applied to all
2312frames, regardless of whether they may be inlined or not. As
2313@value{GDBN} iterates over the iterator produced by the frame filters,
2314@value{GDBN} executes each frame decorator which then makes a decision
2315on what to print in the @code{function} callback. Using a strategy
2316like this is a way to defer decisions on the frame content to printing
2317time.
2318
2319@subheading Eliding Frames
2320
2321It might be that the above example is not desirable for representing
2322inlined frames, and a hierarchical approach may be preferred. If we
2323want to hierarchically represent frames, the @code{elided} frame
2324decorator interface might be preferable.
2325
2326This example approaches the issue with the @code{elided} method. This
2327example is quite long, but very simplistic. It is out-of-scope for
2328this section to write a complete example that comprehensively covers
2329all approaches of finding and printing inlined frames. However, this
2330example illustrates the approach an author might use.
2331
2332This example comprises of three sections.
2333
2334@smallexample
2335class InlineFrameFilter():
2336
2337 def __init__(self):
2338 self.name = "InlinedFrameFilter"
2339 self.priority = 100
2340 self.enabled = True
2341 gdb.frame_filters[self.name] = self
2342
2343 def filter(self, frame_iter):
2344 return ElidingInlineIterator(frame_iter)
2345@end smallexample
2346
2347This frame filter is very similar to the other examples. The only
2348difference is this frame filter is wrapping the iterator provided to
2349it (@code{frame_iter}) with a custom iterator called
2350@code{ElidingInlineIterator}. This again defers actions to when
2351@value{GDBN} prints the backtrace, as the iterator is not traversed
2352until printing.
2353
2354The iterator for this example is as follows. It is in this section of
2355the example where decisions are made on the content of the backtrace.
2356
2357@smallexample
2358class ElidingInlineIterator:
2359 def __init__(self, ii):
2360 self.input_iterator = ii
2361
2362 def __iter__(self):
2363 return self
2364
2365 def next(self):
2366 frame = next(self.input_iterator)
2367
2368 if frame.inferior_frame().type() != gdb.INLINE_FRAME:
2369 return frame
2370
2371 try:
2372 eliding_frame = next(self.input_iterator)
2373 except StopIteration:
2374 return frame
2375 return ElidingFrameDecorator(eliding_frame, [frame])
2376@end smallexample
2377
2378This iterator implements the Python iterator protocol. When the
2379@code{next} function is called (when @value{GDBN} prints each frame),
2380the iterator checks if this frame decorator, @code{frame}, is wrapping
2381an inlined frame. If it is not, it returns the existing frame decorator
2382untouched. If it is wrapping an inlined frame, it assumes that the
2383inlined frame was contained within the next oldest frame,
2384@code{eliding_frame}, which it fetches. It then creates and returns a
2385frame decorator, @code{ElidingFrameDecorator}, which contains both the
2386elided frame, and the eliding frame.
2387
2388@smallexample
2389class ElidingInlineDecorator(FrameDecorator):
2390
2391 def __init__(self, frame, elided_frames):
2392 super(ElidingInlineDecorator, self).__init__(frame)
2393 self.frame = frame
2394 self.elided_frames = elided_frames
2395
2396 def elided(self):
2397 return iter(self.elided_frames)
2398@end smallexample
2399
2400This frame decorator overrides one function and returns the inlined
2401frame in the @code{elided} method. As before it lets
2402@code{FrameDecorator} do the rest of the work involved in printing
2403this frame. This produces the following output.
2404
2405@smallexample
2406#0 0x004004e0 in bar () at inline.c:11
2407#2 0x00400529 in main () at inline.c:25
2408 #1 0x00400529 in max (b=6, a=12) at inline.c:15
2409@end smallexample
2410
2411In that output, @code{max} which has been inlined into @code{main} is
2412printed hierarchically. Another approach would be to combine the
2413@code{function} method, and the @code{elided} method to both print a
2414marker in the inlined frame, and also show the hierarchical
2415relationship.
2416
d11916aa
SS
2417@node Unwinding Frames in Python
2418@subsubsection Unwinding Frames in Python
2419@cindex unwinding frames in Python
2420
2421In @value{GDBN} terminology ``unwinding'' is the process of finding
2422the previous frame (that is, caller's) from the current one. An
2423unwinder has three methods. The first one checks if it can handle
2424given frame (``sniff'' it). For the frames it can sniff an unwinder
2425provides two additional methods: it can return frame's ID, and it can
2426fetch registers from the previous frame. A running @value{GDBN}
2427mantains a list of the unwinders and calls each unwinder's sniffer in
2428turn until it finds the one that recognizes the current frame. There
2429is an API to register an unwinder.
2430
2431The unwinders that come with @value{GDBN} handle standard frames.
2432However, mixed language applications (for example, an application
2433running Java Virtual Machine) sometimes use frame layouts that cannot
2434be handled by the @value{GDBN} unwinders. You can write Python code
2435that can handle such custom frames.
2436
2437You implement a frame unwinder in Python as a class with which has two
2438attributes, @code{name} and @code{enabled}, with obvious meanings, and
2439a single method @code{__call__}, which examines a given frame and
2440returns an object (an instance of @code{gdb.UnwindInfo class)}
2441describing it. If an unwinder does not recognize a frame, it should
2442return @code{None}. The code in @value{GDBN} that enables writing
2443unwinders in Python uses this object to return frame's ID and previous
2444frame registers when @value{GDBN} core asks for them.
2445
e7b5068c
TT
2446An unwinder should do as little work as possible. Some otherwise
2447innocuous operations can cause problems (even crashes, as this code is
2448not not well-hardened yet). For example, making an inferior call from
2449an unwinder is unadvisable, as an inferior call will reset
2450@value{GDBN}'s stack unwinding process, potentially causing re-entrant
2451unwinding.
2452
d11916aa
SS
2453@subheading Unwinder Input
2454
2455An object passed to an unwinder (a @code{gdb.PendingFrame} instance)
2456provides a method to read frame's registers:
2457
2458@defun PendingFrame.read_register (reg)
e7b5068c 2459This method returns the contents of the register @var{reg} in the
d11916aa
SS
2460frame as a @code{gdb.Value} object. @var{reg} can be either a
2461register number or a register name; the values are platform-specific.
2462They are usually found in the corresponding
e7b5068c
TT
2463@file{@var{platform}-tdep.h} file in the @value{GDBN} source tree. If
2464@var{reg} does not name a register for the current architecture, this
2465method will throw an exception.
2466
2467Note that this method will always return a @code{gdb.Value} for a
2468valid register name. This does not mean that the value will be valid.
2469For example, you may request a register that an earlier unwinder could
2470not unwind---the value will be unavailable. Instead, the
2471@code{gdb.Value} returned from this method will be lazy; that is, its
2472underlying bits will not be fetched until it is first used. So,
2473attempting to use such a value will cause an exception at the point of
2474use.
2475
2476The type of the returned @code{gdb.Value} depends on the register and
2477the architecture. It is common for registers to have a scalar type,
2478like @code{long long}; but many other types are possible, such as
2479pointer, pointer-to-function, floating point or vector types.
d11916aa
SS
2480@end defun
2481
2482It also provides a factory method to create a @code{gdb.UnwindInfo}
2483instance to be returned to @value{GDBN}:
2484
2485@defun PendingFrame.create_unwind_info (frame_id)
2486Returns a new @code{gdb.UnwindInfo} instance identified by given
2487@var{frame_id}. The argument is used to build @value{GDBN}'s frame ID
2488using one of functions provided by @value{GDBN}. @var{frame_id}'s attributes
2489determine which function will be used, as follows:
2490
2491@table @code
d11916aa 2492@item sp, pc
e7b5068c
TT
2493The frame is identified by the given stack address and PC. The stack
2494address must be chosen so that it is constant throughout the lifetime
2495of the frame, so a typical choice is the value of the stack pointer at
2496the start of the function---in the DWARF standard, this would be the
2497``Call Frame Address''.
d11916aa 2498
e7b5068c
TT
2499This is the most common case by far. The other cases are documented
2500for completeness but are only useful in specialized situations.
2501
2502@item sp, pc, special
2503The frame is identified by the stack address, the PC, and a
2504``special'' address. The special address is used on architectures
2505that can have frames that do not change the stack, but which are still
2506distinct, for example the IA-64, which has a second stack for
2507registers. Both @var{sp} and @var{special} must be constant
2508throughout the lifetime of the frame.
d11916aa
SS
2509
2510@item sp
e7b5068c
TT
2511The frame is identified by the stack address only. Any other stack
2512frame with a matching @var{sp} will be considered to match this frame.
2513Inside gdb, this is called a ``wild frame''. You will never need
2514this.
d11916aa 2515@end table
e7b5068c
TT
2516
2517Each attribute value should be an instance of @code{gdb.Value}.
d11916aa
SS
2518
2519@end defun
2520
87dbc774
AB
2521@defun PendingFrame.architecture ()
2522Return the @code{gdb.Architecture} (@pxref{Architectures In Python})
2523for this @code{gdb.PendingFrame}. This represents the architecture of
2524the particular frame being unwound.
2525@end defun
2526
d11916aa
SS
2527@subheading Unwinder Output: UnwindInfo
2528
2529Use @code{PendingFrame.create_unwind_info} method described above to
2530create a @code{gdb.UnwindInfo} instance. Use the following method to
2531specify caller registers that have been saved in this frame:
2532
2533@defun gdb.UnwindInfo.add_saved_register (reg, value)
2534@var{reg} identifies the register. It can be a number or a name, just
2535as for the @code{PendingFrame.read_register} method above.
2536@var{value} is a register value (a @code{gdb.Value} object).
2537@end defun
2538
2539@subheading Unwinder Skeleton Code
2540
2541@value{GDBN} comes with the module containing the base @code{Unwinder}
2542class. Derive your unwinder class from it and structure the code as
2543follows:
2544
2545@smallexample
2546from gdb.unwinders import Unwinder
2547
2548class FrameId(object):
2549 def __init__(self, sp, pc):
2550 self.sp = sp
2551 self.pc = pc
2552
2553
2554class MyUnwinder(Unwinder):
2555 def __init__(....):
6b92c0d3 2556 super(MyUnwinder, self).__init___(<expects unwinder name argument>)
d11916aa
SS
2557
2558 def __call__(pending_frame):
2559 if not <we recognize frame>:
2560 return None
2561 # Create UnwindInfo. Usually the frame is identified by the stack
2562 # pointer and the program counter.
2563 sp = pending_frame.read_register(<SP number>)
2564 pc = pending_frame.read_register(<PC number>)
2565 unwind_info = pending_frame.create_unwind_info(FrameId(sp, pc))
2566
2567 # Find the values of the registers in the caller's frame and
2568 # save them in the result:
2569 unwind_info.add_saved_register(<register>, <value>)
2570 ....
2571
2572 # Return the result:
2573 return unwind_info
2574
2575@end smallexample
2576
2577@subheading Registering a Unwinder
2578
2579An object file, a program space, and the @value{GDBN} proper can have
2580unwinders registered with it.
2581
2582The @code{gdb.unwinders} module provides the function to register a
2583unwinder:
2584
2585@defun gdb.unwinder.register_unwinder (locus, unwinder, replace=False)
2586@var{locus} is specifies an object file or a program space to which
2587@var{unwinder} is added. Passing @code{None} or @code{gdb} adds
2588@var{unwinder} to the @value{GDBN}'s global unwinder list. The newly
2589added @var{unwinder} will be called before any other unwinder from the
2590same locus. Two unwinders in the same locus cannot have the same
2591name. An attempt to add a unwinder with already existing name raises
2592an exception unless @var{replace} is @code{True}, in which case the
2593old unwinder is deleted.
2594@end defun
2595
2596@subheading Unwinder Precedence
2597
2598@value{GDBN} first calls the unwinders from all the object files in no
2599particular order, then the unwinders from the current program space,
2600and finally the unwinders from @value{GDBN}.
2601
0c6e92a5
SC
2602@node Xmethods In Python
2603@subsubsection Xmethods In Python
2604@cindex xmethods in Python
2605
2606@dfn{Xmethods} are additional methods or replacements for existing
2607methods of a C@t{++} class. This feature is useful for those cases
2608where a method defined in C@t{++} source code could be inlined or
2609optimized out by the compiler, making it unavailable to @value{GDBN}.
2610For such cases, one can define an xmethod to serve as a replacement
2611for the method defined in the C@t{++} source code. @value{GDBN} will
2612then invoke the xmethod, instead of the C@t{++} method, to
2613evaluate expressions. One can also use xmethods when debugging
2614with core files. Moreover, when debugging live programs, invoking an
2615xmethod need not involve running the inferior (which can potentially
2616perturb its state). Hence, even if the C@t{++} method is available, it
2617is better to use its replacement xmethod if one is defined.
2618
2619The xmethods feature in Python is available via the concepts of an
2620@dfn{xmethod matcher} and an @dfn{xmethod worker}. To
2621implement an xmethod, one has to implement a matcher and a
2622corresponding worker for it (more than one worker can be
2623implemented, each catering to a different overloaded instance of the
2624method). Internally, @value{GDBN} invokes the @code{match} method of a
2625matcher to match the class type and method name. On a match, the
2626@code{match} method returns a list of matching @emph{worker} objects.
2627Each worker object typically corresponds to an overloaded instance of
2628the xmethod. They implement a @code{get_arg_types} method which
2629returns a sequence of types corresponding to the arguments the xmethod
2630requires. @value{GDBN} uses this sequence of types to perform
2631overload resolution and picks a winning xmethod worker. A winner
2632is also selected from among the methods @value{GDBN} finds in the
2633C@t{++} source code. Next, the winning xmethod worker and the
2634winning C@t{++} method are compared to select an overall winner. In
2635case of a tie between a xmethod worker and a C@t{++} method, the
2636xmethod worker is selected as the winner. That is, if a winning
2637xmethod worker is found to be equivalent to the winning C@t{++}
2638method, then the xmethod worker is treated as a replacement for
2639the C@t{++} method. @value{GDBN} uses the overall winner to invoke the
2640method. If the winning xmethod worker is the overall winner, then
897c3d32 2641the corresponding xmethod is invoked via the @code{__call__} method
0c6e92a5
SC
2642of the worker object.
2643
2644If one wants to implement an xmethod as a replacement for an
2645existing C@t{++} method, then they have to implement an equivalent
2646xmethod which has exactly the same name and takes arguments of
2647exactly the same type as the C@t{++} method. If the user wants to
2648invoke the C@t{++} method even though a replacement xmethod is
2649available for that method, then they can disable the xmethod.
2650
2651@xref{Xmethod API}, for API to implement xmethods in Python.
2652@xref{Writing an Xmethod}, for implementing xmethods in Python.
2653
2654@node Xmethod API
2655@subsubsection Xmethod API
2656@cindex xmethod API
2657
2658The @value{GDBN} Python API provides classes, interfaces and functions
2659to implement, register and manipulate xmethods.
2660@xref{Xmethods In Python}.
2661
2662An xmethod matcher should be an instance of a class derived from
2663@code{XMethodMatcher} defined in the module @code{gdb.xmethod}, or an
2664object with similar interface and attributes. An instance of
2665@code{XMethodMatcher} has the following attributes:
2666
2667@defvar name
2668The name of the matcher.
2669@end defvar
2670
2671@defvar enabled
2672A boolean value indicating whether the matcher is enabled or disabled.
2673@end defvar
2674
2675@defvar methods
2676A list of named methods managed by the matcher. Each object in the list
2677is an instance of the class @code{XMethod} defined in the module
2678@code{gdb.xmethod}, or any object with the following attributes:
2679
2680@table @code
2681
2682@item name
2683Name of the xmethod which should be unique for each xmethod
2684managed by the matcher.
2685
2686@item enabled
2687A boolean value indicating whether the xmethod is enabled or
2688disabled.
2689
2690@end table
2691
2692The class @code{XMethod} is a convenience class with same
2693attributes as above along with the following constructor:
2694
dd5d5494 2695@defun XMethod.__init__ (self, name)
0c6e92a5
SC
2696Constructs an enabled xmethod with name @var{name}.
2697@end defun
2698@end defvar
2699
2700@noindent
2701The @code{XMethodMatcher} class has the following methods:
2702
dd5d5494 2703@defun XMethodMatcher.__init__ (self, name)
0c6e92a5
SC
2704Constructs an enabled xmethod matcher with name @var{name}. The
2705@code{methods} attribute is initialized to @code{None}.
2706@end defun
2707
dd5d5494 2708@defun XMethodMatcher.match (self, class_type, method_name)
0c6e92a5
SC
2709Derived classes should override this method. It should return a
2710xmethod worker object (or a sequence of xmethod worker
2711objects) matching the @var{class_type} and @var{method_name}.
2712@var{class_type} is a @code{gdb.Type} object, and @var{method_name}
2713is a string value. If the matcher manages named methods as listed in
2714its @code{methods} attribute, then only those worker objects whose
2715corresponding entries in the @code{methods} list are enabled should be
2716returned.
2717@end defun
2718
2719An xmethod worker should be an instance of a class derived from
2720@code{XMethodWorker} defined in the module @code{gdb.xmethod},
2721or support the following interface:
2722
dd5d5494 2723@defun XMethodWorker.get_arg_types (self)
0c6e92a5
SC
2724This method returns a sequence of @code{gdb.Type} objects corresponding
2725to the arguments that the xmethod takes. It can return an empty
2726sequence or @code{None} if the xmethod does not take any arguments.
2727If the xmethod takes a single argument, then a single
2728@code{gdb.Type} object corresponding to it can be returned.
2729@end defun
2730
2ce1cdbf
DE
2731@defun XMethodWorker.get_result_type (self, *args)
2732This method returns a @code{gdb.Type} object representing the type
2733of the result of invoking this xmethod.
2734The @var{args} argument is the same tuple of arguments that would be
2735passed to the @code{__call__} method of this worker.
2736@end defun
2737
dd5d5494 2738@defun XMethodWorker.__call__ (self, *args)
0c6e92a5
SC
2739This is the method which does the @emph{work} of the xmethod. The
2740@var{args} arguments is the tuple of arguments to the xmethod. Each
2741element in this tuple is a gdb.Value object. The first element is
2742always the @code{this} pointer value.
2743@end defun
2744
2745For @value{GDBN} to lookup xmethods, the xmethod matchers
2746should be registered using the following function defined in the module
2747@code{gdb.xmethod}:
2748
dd5d5494 2749@defun register_xmethod_matcher (locus, matcher, replace=False)
0c6e92a5
SC
2750The @code{matcher} is registered with @code{locus}, replacing an
2751existing matcher with the same name as @code{matcher} if
2752@code{replace} is @code{True}. @code{locus} can be a
2753@code{gdb.Objfile} object (@pxref{Objfiles In Python}), or a
1e47491b 2754@code{gdb.Progspace} object (@pxref{Progspaces In Python}), or
0c6e92a5
SC
2755@code{None}. If it is @code{None}, then @code{matcher} is registered
2756globally.
2757@end defun
2758
2759@node Writing an Xmethod
2760@subsubsection Writing an Xmethod
2761@cindex writing xmethods in Python
2762
2763Implementing xmethods in Python will require implementing xmethod
2764matchers and xmethod workers (@pxref{Xmethods In Python}). Consider
2765the following C@t{++} class:
2766
2767@smallexample
2768class MyClass
2769@{
2770public:
2771 MyClass (int a) : a_(a) @{ @}
2772
2773 int geta (void) @{ return a_; @}
2774 int operator+ (int b);
2775
2776private:
2777 int a_;
2778@};
2779
2780int
2781MyClass::operator+ (int b)
2782@{
2783 return a_ + b;
2784@}
2785@end smallexample
2786
2787@noindent
2788Let us define two xmethods for the class @code{MyClass}, one
2789replacing the method @code{geta}, and another adding an overloaded
2790flavor of @code{operator+} which takes a @code{MyClass} argument (the
2791C@t{++} code above already has an overloaded @code{operator+}
2792which takes an @code{int} argument). The xmethod matcher can be
2793defined as follows:
2794
2795@smallexample
2796class MyClass_geta(gdb.xmethod.XMethod):
2797 def __init__(self):
2798 gdb.xmethod.XMethod.__init__(self, 'geta')
2799
2800 def get_worker(self, method_name):
2801 if method_name == 'geta':
2802 return MyClassWorker_geta()
2803
2804
2805class MyClass_sum(gdb.xmethod.XMethod):
2806 def __init__(self):
2807 gdb.xmethod.XMethod.__init__(self, 'sum')
2808
2809 def get_worker(self, method_name):
2810 if method_name == 'operator+':
2811 return MyClassWorker_plus()
2812
2813
2814class MyClassMatcher(gdb.xmethod.XMethodMatcher):
2815 def __init__(self):
2816 gdb.xmethod.XMethodMatcher.__init__(self, 'MyClassMatcher')
2817 # List of methods 'managed' by this matcher
2818 self.methods = [MyClass_geta(), MyClass_sum()]
2819
2820 def match(self, class_type, method_name):
2821 if class_type.tag != 'MyClass':
2822 return None
2823 workers = []
2824 for method in self.methods:
2825 if method.enabled:
2826 worker = method.get_worker(method_name)
2827 if worker:
2828 workers.append(worker)
2829
2830 return workers
2831@end smallexample
2832
2833@noindent
2834Notice that the @code{match} method of @code{MyClassMatcher} returns
2835a worker object of type @code{MyClassWorker_geta} for the @code{geta}
2836method, and a worker object of type @code{MyClassWorker_plus} for the
2837@code{operator+} method. This is done indirectly via helper classes
2838derived from @code{gdb.xmethod.XMethod}. One does not need to use the
2839@code{methods} attribute in a matcher as it is optional. However, if a
2840matcher manages more than one xmethod, it is a good practice to list the
2841xmethods in the @code{methods} attribute of the matcher. This will then
2842facilitate enabling and disabling individual xmethods via the
2843@code{enable/disable} commands. Notice also that a worker object is
2844returned only if the corresponding entry in the @code{methods} attribute
2845of the matcher is enabled.
2846
2847The implementation of the worker classes returned by the matcher setup
2848above is as follows:
2849
2850@smallexample
2851class MyClassWorker_geta(gdb.xmethod.XMethodWorker):
2852 def get_arg_types(self):
2853 return None
2ce1cdbf
DE
2854
2855 def get_result_type(self, obj):
2856 return gdb.lookup_type('int')
0c6e92a5
SC
2857
2858 def __call__(self, obj):
2859 return obj['a_']
2860
2861
2862class MyClassWorker_plus(gdb.xmethod.XMethodWorker):
2863 def get_arg_types(self):
2864 return gdb.lookup_type('MyClass')
2ce1cdbf
DE
2865
2866 def get_result_type(self, obj):
2867 return gdb.lookup_type('int')
0c6e92a5
SC
2868
2869 def __call__(self, obj, other):
2870 return obj['a_'] + other['a_']
2871@end smallexample
2872
2873For @value{GDBN} to actually lookup a xmethod, it has to be
2874registered with it. The matcher defined above is registered with
2875@value{GDBN} globally as follows:
2876
2877@smallexample
2878gdb.xmethod.register_xmethod_matcher(None, MyClassMatcher())
2879@end smallexample
2880
2881If an object @code{obj} of type @code{MyClass} is initialized in C@t{++}
2882code as follows:
2883
2884@smallexample
2885MyClass obj(5);
2886@end smallexample
2887
2888@noindent
2889then, after loading the Python script defining the xmethod matchers
2890and workers into @code{GDBN}, invoking the method @code{geta} or using
2891the operator @code{+} on @code{obj} will invoke the xmethods
2892defined above:
2893
2894@smallexample
2895(gdb) p obj.geta()
2896$1 = 5
2897
2898(gdb) p obj + obj
2899$2 = 10
2900@end smallexample
2901
2902Consider another example with a C++ template class:
2903
2904@smallexample
2905template <class T>
2906class MyTemplate
2907@{
2908public:
2909 MyTemplate () : dsize_(10), data_ (new T [10]) @{ @}
2910 ~MyTemplate () @{ delete [] data_; @}
2911
2912 int footprint (void)
2913 @{
2914 return sizeof (T) * dsize_ + sizeof (MyTemplate<T>);
2915 @}
2916
2917private:
2918 int dsize_;
2919 T *data_;
2920@};
2921@end smallexample
2922
2923Let us implement an xmethod for the above class which serves as a
2924replacement for the @code{footprint} method. The full code listing
2925of the xmethod workers and xmethod matchers is as follows:
2926
2927@smallexample
2928class MyTemplateWorker_footprint(gdb.xmethod.XMethodWorker):
2929 def __init__(self, class_type):
2930 self.class_type = class_type
2ce1cdbf 2931
0c6e92a5
SC
2932 def get_arg_types(self):
2933 return None
2ce1cdbf
DE
2934
2935 def get_result_type(self):
2936 return gdb.lookup_type('int')
2937
0c6e92a5
SC
2938 def __call__(self, obj):
2939 return (self.class_type.sizeof +
2940 obj['dsize_'] *
2941 self.class_type.template_argument(0).sizeof)
2942
2943
2944class MyTemplateMatcher_footprint(gdb.xmethod.XMethodMatcher):
2945 def __init__(self):
2946 gdb.xmethod.XMethodMatcher.__init__(self, 'MyTemplateMatcher')
2947
2948 def match(self, class_type, method_name):
2949 if (re.match('MyTemplate<[ \t\n]*[_a-zA-Z][ _a-zA-Z0-9]*>',
2950 class_type.tag) and
2951 method_name == 'footprint'):
2952 return MyTemplateWorker_footprint(class_type)
2953@end smallexample
2954
2955Notice that, in this example, we have not used the @code{methods}
2956attribute of the matcher as the matcher manages only one xmethod. The
2957user can enable/disable this xmethod by enabling/disabling the matcher
2958itself.
2959
329baa95
DE
2960@node Inferiors In Python
2961@subsubsection Inferiors In Python
2962@cindex inferiors in Python
2963
2964@findex gdb.Inferior
2965Programs which are being run under @value{GDBN} are called inferiors
65c574f6 2966(@pxref{Inferiors Connections and Programs}). Python scripts can access
329baa95
DE
2967information about and manipulate inferiors controlled by @value{GDBN}
2968via objects of the @code{gdb.Inferior} class.
2969
2970The following inferior-related functions are available in the @code{gdb}
2971module:
2972
2973@defun gdb.inferiors ()
2974Return a tuple containing all inferior objects.
2975@end defun
2976
2977@defun gdb.selected_inferior ()
2978Return an object representing the current inferior.
2979@end defun
2980
2981A @code{gdb.Inferior} object has the following attributes:
2982
2983@defvar Inferior.num
2984ID of inferior, as assigned by GDB.
2985@end defvar
2986
2987@defvar Inferior.pid
2988Process ID of the inferior, as assigned by the underlying operating
2989system.
2990@end defvar
2991
2992@defvar Inferior.was_attached
2993Boolean signaling whether the inferior was created using `attach', or
2994started by @value{GDBN} itself.
2995@end defvar
2996
a40bf0c2
SM
2997@defvar Inferior.progspace
2998The inferior's program space. @xref{Progspaces In Python}.
2999@end defvar
3000
329baa95
DE
3001A @code{gdb.Inferior} object has the following methods:
3002
3003@defun Inferior.is_valid ()
3004Returns @code{True} if the @code{gdb.Inferior} object is valid,
3005@code{False} if not. A @code{gdb.Inferior} object will become invalid
3006if the inferior no longer exists within @value{GDBN}. All other
3007@code{gdb.Inferior} methods will throw an exception if it is invalid
3008at the time the method is called.
3009@end defun
3010
3011@defun Inferior.threads ()
3012This method returns a tuple holding all the threads which are valid
3013when it is called. If there are no valid threads, the method will
3014return an empty tuple.
3015@end defun
3016
add5ded5
TT
3017@defun Inferior.architecture ()
3018Return the @code{gdb.Architecture} (@pxref{Architectures In Python})
3019for this inferior. This represents the architecture of the inferior
3020as a whole. Some platforms can have multiple architectures in a
3021single address space, so this may not match the architecture of a
163cffef 3022particular frame (@pxref{Frames In Python}).
9e1698c6 3023@end defun
add5ded5 3024
329baa95
DE
3025@findex Inferior.read_memory
3026@defun Inferior.read_memory (address, length)
a86c90e6 3027Read @var{length} addressable memory units from the inferior, starting at
329baa95
DE
3028@var{address}. Returns a buffer object, which behaves much like an array
3029or a string. It can be modified and given to the
79778b30 3030@code{Inferior.write_memory} function. In Python 3, the return
329baa95
DE
3031value is a @code{memoryview} object.
3032@end defun
3033
3034@findex Inferior.write_memory
3035@defun Inferior.write_memory (address, buffer @r{[}, length@r{]})
3036Write the contents of @var{buffer} to the inferior, starting at
3037@var{address}. The @var{buffer} parameter must be a Python object
3038which supports the buffer protocol, i.e., a string, an array or the
3039object returned from @code{Inferior.read_memory}. If given, @var{length}
a86c90e6
SM
3040determines the number of addressable memory units from @var{buffer} to be
3041written.
329baa95
DE
3042@end defun
3043
3044@findex gdb.search_memory
3045@defun Inferior.search_memory (address, length, pattern)
3046Search a region of the inferior memory starting at @var{address} with
3047the given @var{length} using the search pattern supplied in
3048@var{pattern}. The @var{pattern} parameter must be a Python object
3049which supports the buffer protocol, i.e., a string, an array or the
3050object returned from @code{gdb.read_memory}. Returns a Python @code{Long}
3051containing the address where the pattern was found, or @code{None} if
3052the pattern could not be found.
3053@end defun
3054
2b0c8b01 3055@findex Inferior.thread_from_handle
da2c323b 3056@findex Inferior.thread_from_thread_handle
2b0c8b01
KB
3057@defun Inferior.thread_from_handle (handle)
3058Return the thread object corresponding to @var{handle}, a thread
da2c323b
KB
3059library specific data structure such as @code{pthread_t} for pthreads
3060library implementations.
2b0c8b01
KB
3061
3062The function @code{Inferior.thread_from_thread_handle} provides
3063the same functionality, but use of @code{Inferior.thread_from_thread_handle}
3064is deprecated.
da2c323b
KB
3065@end defun
3066
329baa95
DE
3067@node Events In Python
3068@subsubsection Events In Python
3069@cindex inferior events in Python
3070
3071@value{GDBN} provides a general event facility so that Python code can be
3072notified of various state changes, particularly changes that occur in
3073the inferior.
3074
3075An @dfn{event} is just an object that describes some state change. The
3076type of the object and its attributes will vary depending on the details
3077of the change. All the existing events are described below.
3078
3079In order to be notified of an event, you must register an event handler
3080with an @dfn{event registry}. An event registry is an object in the
3081@code{gdb.events} module which dispatches particular events. A registry
3082provides methods to register and unregister event handlers:
3083
3084@defun EventRegistry.connect (object)
3085Add the given callable @var{object} to the registry. This object will be
3086called when an event corresponding to this registry occurs.
3087@end defun
3088
3089@defun EventRegistry.disconnect (object)
3090Remove the given @var{object} from the registry. Once removed, the object
3091will no longer receive notifications of events.
3092@end defun
3093
3094Here is an example:
3095
3096@smallexample
3097def exit_handler (event):
3098 print "event type: exit"
3099 print "exit code: %d" % (event.exit_code)
3100
3101gdb.events.exited.connect (exit_handler)
3102@end smallexample
3103
3104In the above example we connect our handler @code{exit_handler} to the
3105registry @code{events.exited}. Once connected, @code{exit_handler} gets
3106called when the inferior exits. The argument @dfn{event} in this example is
3107of type @code{gdb.ExitedEvent}. As you can see in the example the
3108@code{ExitedEvent} object has an attribute which indicates the exit code of
3109the inferior.
3110
3111The following is a listing of the event registries that are available and
3112details of the events they emit:
3113
3114@table @code
3115
3116@item events.cont
3117Emits @code{gdb.ThreadEvent}.
3118
3119Some events can be thread specific when @value{GDBN} is running in non-stop
3120mode. When represented in Python, these events all extend
3121@code{gdb.ThreadEvent}. Note, this event is not emitted directly; instead,
3122events which are emitted by this or other modules might extend this event.
3123Examples of these events are @code{gdb.BreakpointEvent} and
3124@code{gdb.ContinueEvent}.
3125
3126@defvar ThreadEvent.inferior_thread
3127In non-stop mode this attribute will be set to the specific thread which was
3128involved in the emitted event. Otherwise, it will be set to @code{None}.
3129@end defvar
3130
3131Emits @code{gdb.ContinueEvent} which extends @code{gdb.ThreadEvent}.
3132
3133This event indicates that the inferior has been continued after a stop. For
3134inherited attribute refer to @code{gdb.ThreadEvent} above.
3135
3136@item events.exited
3137Emits @code{events.ExitedEvent} which indicates that the inferior has exited.
3138@code{events.ExitedEvent} has two attributes:
3139@defvar ExitedEvent.exit_code
3140An integer representing the exit code, if available, which the inferior
3141has returned. (The exit code could be unavailable if, for example,
3142@value{GDBN} detaches from the inferior.) If the exit code is unavailable,
3143the attribute does not exist.
3144@end defvar
373832b6 3145@defvar ExitedEvent.inferior
329baa95
DE
3146A reference to the inferior which triggered the @code{exited} event.
3147@end defvar
3148
3149@item events.stop
3150Emits @code{gdb.StopEvent} which extends @code{gdb.ThreadEvent}.
3151
3152Indicates that the inferior has stopped. All events emitted by this registry
3153extend StopEvent. As a child of @code{gdb.ThreadEvent}, @code{gdb.StopEvent}
3154will indicate the stopped thread when @value{GDBN} is running in non-stop
3155mode. Refer to @code{gdb.ThreadEvent} above for more details.
3156
3157Emits @code{gdb.SignalEvent} which extends @code{gdb.StopEvent}.
3158
3159This event indicates that the inferior or one of its threads has received as
3160signal. @code{gdb.SignalEvent} has the following attributes:
3161
3162@defvar SignalEvent.stop_signal
3163A string representing the signal received by the inferior. A list of possible
3164signal values can be obtained by running the command @code{info signals} in
3165the @value{GDBN} command prompt.
3166@end defvar
3167
3168Also emits @code{gdb.BreakpointEvent} which extends @code{gdb.StopEvent}.
3169
3170@code{gdb.BreakpointEvent} event indicates that one or more breakpoints have
3171been hit, and has the following attributes:
3172
3173@defvar BreakpointEvent.breakpoints
3174A sequence containing references to all the breakpoints (type
3175@code{gdb.Breakpoint}) that were hit.
3176@xref{Breakpoints In Python}, for details of the @code{gdb.Breakpoint} object.
3177@end defvar
3178@defvar BreakpointEvent.breakpoint
3179A reference to the first breakpoint that was hit.
3180This function is maintained for backward compatibility and is now deprecated
3181in favor of the @code{gdb.BreakpointEvent.breakpoints} attribute.
3182@end defvar
3183
3184@item events.new_objfile
3185Emits @code{gdb.NewObjFileEvent} which indicates that a new object file has
3186been loaded by @value{GDBN}. @code{gdb.NewObjFileEvent} has one attribute:
3187
3188@defvar NewObjFileEvent.new_objfile
3189A reference to the object file (@code{gdb.Objfile}) which has been loaded.
3190@xref{Objfiles In Python}, for details of the @code{gdb.Objfile} object.
3191@end defvar
3192
4ffbba72
DE
3193@item events.clear_objfiles
3194Emits @code{gdb.ClearObjFilesEvent} which indicates that the list of object
3195files for a program space has been reset.
3196@code{gdb.ClearObjFilesEvent} has one attribute:
3197
3198@defvar ClearObjFilesEvent.progspace
3199A reference to the program space (@code{gdb.Progspace}) whose objfile list has
3200been cleared. @xref{Progspaces In Python}.
3201@end defvar
3202
fb5af5e3
TT
3203@item events.inferior_call
3204Emits events just before and after a function in the inferior is
3205called by @value{GDBN}. Before an inferior call, this emits an event
3206of type @code{gdb.InferiorCallPreEvent}, and after an inferior call,
3207this emits an event of type @code{gdb.InferiorCallPostEvent}.
3208
3209@table @code
3210@tindex gdb.InferiorCallPreEvent
3211@item @code{gdb.InferiorCallPreEvent}
3212Indicates that a function in the inferior is about to be called.
162078c8
NB
3213
3214@defvar InferiorCallPreEvent.ptid
3215The thread in which the call will be run.
3216@end defvar
3217
3218@defvar InferiorCallPreEvent.address
3219The location of the function to be called.
3220@end defvar
3221
fb5af5e3
TT
3222@tindex gdb.InferiorCallPostEvent
3223@item @code{gdb.InferiorCallPostEvent}
3224Indicates that a function in the inferior has just been called.
162078c8
NB
3225
3226@defvar InferiorCallPostEvent.ptid
3227The thread in which the call was run.
3228@end defvar
3229
3230@defvar InferiorCallPostEvent.address
3231The location of the function that was called.
3232@end defvar
fb5af5e3 3233@end table
162078c8
NB
3234
3235@item events.memory_changed
3236Emits @code{gdb.MemoryChangedEvent} which indicates that the memory of the
3237inferior has been modified by the @value{GDBN} user, for instance via a
3238command like @w{@code{set *addr = value}}. The event has the following
3239attributes:
3240
3241@defvar MemoryChangedEvent.address
3242The start address of the changed region.
3243@end defvar
3244
3245@defvar MemoryChangedEvent.length
3246Length in bytes of the changed region.
3247@end defvar
3248
3249@item events.register_changed
3250Emits @code{gdb.RegisterChangedEvent} which indicates that a register in the
3251inferior has been modified by the @value{GDBN} user.
3252
3253@defvar RegisterChangedEvent.frame
3254A gdb.Frame object representing the frame in which the register was modified.
3255@end defvar
3256@defvar RegisterChangedEvent.regnum
3257Denotes which register was modified.
3258@end defvar
3259
dac790e1
TT
3260@item events.breakpoint_created
3261This is emitted when a new breakpoint has been created. The argument
3262that is passed is the new @code{gdb.Breakpoint} object.
3263
3264@item events.breakpoint_modified
3265This is emitted when a breakpoint has been modified in some way. The
3266argument that is passed is the new @code{gdb.Breakpoint} object.
3267
3268@item events.breakpoint_deleted
3269This is emitted when a breakpoint has been deleted. The argument that
3270is passed is the @code{gdb.Breakpoint} object. When this event is
3271emitted, the @code{gdb.Breakpoint} object will already be in its
3272invalid state; that is, the @code{is_valid} method will return
3273@code{False}.
3274
3f77c769
TT
3275@item events.before_prompt
3276This event carries no payload. It is emitted each time @value{GDBN}
3277presents a prompt to the user.
3278
7c96f8c1
TT
3279@item events.new_inferior
3280This is emitted when a new inferior is created. Note that the
3281inferior is not necessarily running; in fact, it may not even have an
3282associated executable.
3283
3284The event is of type @code{gdb.NewInferiorEvent}. This has a single
3285attribute:
3286
3287@defvar NewInferiorEvent.inferior
3288The new inferior, a @code{gdb.Inferior} object.
3289@end defvar
3290
3291@item events.inferior_deleted
3292This is emitted when an inferior has been deleted. Note that this is
3293not the same as process exit; it is notified when the inferior itself
3294is removed, say via @code{remove-inferiors}.
3295
3296The event is of type @code{gdb.InferiorDeletedEvent}. This has a single
3297attribute:
3298
3299@defvar NewInferiorEvent.inferior
3300The inferior that is being removed, a @code{gdb.Inferior} object.
3301@end defvar
3302
3303@item events.new_thread
3304This is emitted when @value{GDBN} notices a new thread. The event is of
3305type @code{gdb.NewThreadEvent}, which extends @code{gdb.ThreadEvent}.
3306This has a single attribute:
3307
3308@defvar NewThreadEvent.inferior_thread
3309The new thread.
3310@end defvar
3311
329baa95
DE
3312@end table
3313
3314@node Threads In Python
3315@subsubsection Threads In Python
3316@cindex threads in python
3317
3318@findex gdb.InferiorThread
3319Python scripts can access information about, and manipulate inferior threads
3320controlled by @value{GDBN}, via objects of the @code{gdb.InferiorThread} class.
3321
3322The following thread-related functions are available in the @code{gdb}
3323module:
3324
3325@findex gdb.selected_thread
3326@defun gdb.selected_thread ()
3327This function returns the thread object for the selected thread. If there
3328is no selected thread, this will return @code{None}.
3329@end defun
3330
14796d29 3331To get the list of threads for an inferior, use the @code{Inferior.threads()}
0ca4866a 3332method. @xref{Inferiors In Python}.
14796d29 3333
329baa95
DE
3334A @code{gdb.InferiorThread} object has the following attributes:
3335
3336@defvar InferiorThread.name
3337The name of the thread. If the user specified a name using
3338@code{thread name}, then this returns that name. Otherwise, if an
3339OS-supplied name is available, then it is returned. Otherwise, this
3340returns @code{None}.
3341
3342This attribute can be assigned to. The new value must be a string
3343object, which sets the new name, or @code{None}, which removes any
3344user-specified thread name.
3345@end defvar
3346
3347@defvar InferiorThread.num
5d5658a1 3348The per-inferior number of the thread, as assigned by GDB.
329baa95
DE
3349@end defvar
3350
22a02324
PA
3351@defvar InferiorThread.global_num
3352The global ID of the thread, as assigned by GDB. You can use this to
3353make Python breakpoints thread-specific, for example
3354(@pxref{python_breakpoint_thread,,The Breakpoint.thread attribute}).
3355@end defvar
3356
329baa95
DE
3357@defvar InferiorThread.ptid
3358ID of the thread, as assigned by the operating system. This attribute is a
3359tuple containing three integers. The first is the Process ID (PID); the second
3360is the Lightweight Process ID (LWPID), and the third is the Thread ID (TID).
3361Either the LWPID or TID may be 0, which indicates that the operating system
3362does not use that identifier.
3363@end defvar
3364
84654457
PA
3365@defvar InferiorThread.inferior
3366The inferior this thread belongs to. This attribute is represented as
3367a @code{gdb.Inferior} object. This attribute is not writable.
3368@end defvar
3369
329baa95
DE
3370A @code{gdb.InferiorThread} object has the following methods:
3371
3372@defun InferiorThread.is_valid ()
3373Returns @code{True} if the @code{gdb.InferiorThread} object is valid,
3374@code{False} if not. A @code{gdb.InferiorThread} object will become
3375invalid if the thread exits, or the inferior that the thread belongs
3376is deleted. All other @code{gdb.InferiorThread} methods will throw an
3377exception if it is invalid at the time the method is called.
3378@end defun
3379
3380@defun InferiorThread.switch ()
3381This changes @value{GDBN}'s currently selected thread to the one represented
3382by this object.
3383@end defun
3384
3385@defun InferiorThread.is_stopped ()
3386Return a Boolean indicating whether the thread is stopped.
3387@end defun
3388
3389@defun InferiorThread.is_running ()
3390Return a Boolean indicating whether the thread is running.
3391@end defun
3392
3393@defun InferiorThread.is_exited ()
3394Return a Boolean indicating whether the thread is exited.
3395@end defun
3396
c369f8f0
KB
3397@defun InferiorThread.handle ()
3398Return the thread object's handle, represented as a Python @code{bytes}
3399object. A @code{gdb.Value} representation of the handle may be
3400constructed via @code{gdb.Value(bufobj, type)} where @var{bufobj} is
3401the Python @code{bytes} representation of the handle and @var{type} is
3402a @code{gdb.Type} for the handle type.
3403@end defun
3404
0a0faf9f
TW
3405@node Recordings In Python
3406@subsubsection Recordings In Python
3407@cindex recordings in python
3408
3409The following recordings-related functions
3410(@pxref{Process Record and Replay}) are available in the @code{gdb}
3411module:
3412
3413@defun gdb.start_recording (@r{[}method@r{]}, @r{[}format@r{]})
3414Start a recording using the given @var{method} and @var{format}. If
3415no @var{format} is given, the default format for the recording method
3416is used. If no @var{method} is given, the default method will be used.
3417Returns a @code{gdb.Record} object on success. Throw an exception on
3418failure.
3419
3420The following strings can be passed as @var{method}:
3421
3422@itemize @bullet
3423@item
3424@code{"full"}
3425@item
3426@code{"btrace"}: Possible values for @var{format}: @code{"pt"},
3427@code{"bts"} or leave out for default format.
3428@end itemize
3429@end defun
3430
3431@defun gdb.current_recording ()
3432Access a currently running recording. Return a @code{gdb.Record}
3433object on success. Return @code{None} if no recording is currently
3434active.
3435@end defun
3436
3437@defun gdb.stop_recording ()
3438Stop the current recording. Throw an exception if no recording is
3439currently active. All record objects become invalid after this call.
3440@end defun
3441
3442A @code{gdb.Record} object has the following attributes:
3443
0a0faf9f
TW
3444@defvar Record.method
3445A string with the current recording method, e.g.@: @code{full} or
3446@code{btrace}.
3447@end defvar
3448
3449@defvar Record.format
3450A string with the current recording format, e.g.@: @code{bt}, @code{pts} or
3451@code{None}.
3452@end defvar
3453
3454@defvar Record.begin
3455A method specific instruction object representing the first instruction
3456in this recording.
3457@end defvar
3458
3459@defvar Record.end
3460A method specific instruction object representing the current
3461instruction, that is not actually part of the recording.
3462@end defvar
3463
3464@defvar Record.replay_position
3465The instruction representing the current replay position. If there is
3466no replay active, this will be @code{None}.
3467@end defvar
3468
3469@defvar Record.instruction_history
3470A list with all recorded instructions.
3471@end defvar
3472
3473@defvar Record.function_call_history
3474A list with all recorded function call segments.
3475@end defvar
3476
3477A @code{gdb.Record} object has the following methods:
3478
3479@defun Record.goto (instruction)
3480Move the replay position to the given @var{instruction}.
3481@end defun
3482
d050f7d7
TW
3483The common @code{gdb.Instruction} class that recording method specific
3484instruction objects inherit from, has the following attributes:
0a0faf9f 3485
d050f7d7 3486@defvar Instruction.pc
913aeadd 3487An integer representing this instruction's address.
0a0faf9f
TW
3488@end defvar
3489
d050f7d7 3490@defvar Instruction.data
913aeadd
TW
3491A buffer with the raw instruction data. In Python 3, the return value is a
3492@code{memoryview} object.
0a0faf9f
TW
3493@end defvar
3494
d050f7d7 3495@defvar Instruction.decoded
913aeadd 3496A human readable string with the disassembled instruction.
0a0faf9f
TW
3497@end defvar
3498
d050f7d7 3499@defvar Instruction.size
913aeadd 3500The size of the instruction in bytes.
0a0faf9f
TW
3501@end defvar
3502
d050f7d7
TW
3503Additionally @code{gdb.RecordInstruction} has the following attributes:
3504
3505@defvar RecordInstruction.number
3506An integer identifying this instruction. @code{number} corresponds to
3507the numbers seen in @code{record instruction-history}
3508(@pxref{Process Record and Replay}).
3509@end defvar
3510
3511@defvar RecordInstruction.sal
3512A @code{gdb.Symtab_and_line} object representing the associated symtab
3513and line of this instruction. May be @code{None} if no debug information is
3514available.
3515@end defvar
3516
0ed5da75 3517@defvar RecordInstruction.is_speculative
d050f7d7 3518A boolean indicating whether the instruction was executed speculatively.
913aeadd
TW
3519@end defvar
3520
3521If an error occured during recording or decoding a recording, this error is
3522represented by a @code{gdb.RecordGap} object in the instruction list. It has
3523the following attributes:
3524
3525@defvar RecordGap.number
3526An integer identifying this gap. @code{number} corresponds to the numbers seen
3527in @code{record instruction-history} (@pxref{Process Record and Replay}).
3528@end defvar
3529
3530@defvar RecordGap.error_code
3531A numerical representation of the reason for the gap. The value is specific to
3532the current recording method.
3533@end defvar
3534
3535@defvar RecordGap.error_string
3536A human readable string with the reason for the gap.
0a0faf9f
TW
3537@end defvar
3538
14f819c8 3539A @code{gdb.RecordFunctionSegment} object has the following attributes:
0a0faf9f 3540
14f819c8
TW
3541@defvar RecordFunctionSegment.number
3542An integer identifying this function segment. @code{number} corresponds to
0a0faf9f
TW
3543the numbers seen in @code{record function-call-history}
3544(@pxref{Process Record and Replay}).
3545@end defvar
3546
14f819c8 3547@defvar RecordFunctionSegment.symbol
0a0faf9f 3548A @code{gdb.Symbol} object representing the associated symbol. May be
14f819c8 3549@code{None} if no debug information is available.
0a0faf9f
TW
3550@end defvar
3551
14f819c8 3552@defvar RecordFunctionSegment.level
0a0faf9f
TW
3553An integer representing the function call's stack level. May be
3554@code{None} if the function call is a gap.
3555@end defvar
3556
14f819c8 3557@defvar RecordFunctionSegment.instructions
0ed5da75 3558A list of @code{gdb.RecordInstruction} or @code{gdb.RecordGap} objects
913aeadd 3559associated with this function call.
0a0faf9f
TW
3560@end defvar
3561
14f819c8
TW
3562@defvar RecordFunctionSegment.up
3563A @code{gdb.RecordFunctionSegment} object representing the caller's
0a0faf9f
TW
3564function segment. If the call has not been recorded, this will be the
3565function segment to which control returns. If neither the call nor the
3566return have been recorded, this will be @code{None}.
3567@end defvar
3568
14f819c8
TW
3569@defvar RecordFunctionSegment.prev
3570A @code{gdb.RecordFunctionSegment} object representing the previous
0a0faf9f
TW
3571segment of this function call. May be @code{None}.
3572@end defvar
3573
14f819c8
TW
3574@defvar RecordFunctionSegment.next
3575A @code{gdb.RecordFunctionSegment} object representing the next segment of
0a0faf9f
TW
3576this function call. May be @code{None}.
3577@end defvar
3578
3579The following example demonstrates the usage of these objects and
3580functions to create a function that will rewind a record to the last
3581time a function in a different file was executed. This would typically
3582be used to track the execution of user provided callback functions in a
3583library which typically are not visible in a back trace.
3584
3585@smallexample
3586def bringback ():
3587 rec = gdb.current_recording ()
3588 if not rec:
3589 return
3590
3591 insn = rec.instruction_history
3592 if len (insn) == 0:
3593 return
3594
3595 try:
3596 position = insn.index (rec.replay_position)
3597 except:
3598 position = -1
3599 try:
3600 filename = insn[position].sal.symtab.fullname ()
3601 except:
3602 filename = None
3603
3604 for i in reversed (insn[:position]):
3605 try:
3606 current = i.sal.symtab.fullname ()
3607 except:
3608 current = None
3609
3610 if filename == current:
3611 continue
3612
3613 rec.goto (i)
3614 return
3615@end smallexample
3616
3617Another possible application is to write a function that counts the
3618number of code executions in a given line range. This line range can
3619contain parts of functions or span across several functions and is not
3620limited to be contiguous.
3621
3622@smallexample
3623def countrange (filename, linerange):
3624 count = 0
3625
3626 def filter_only (file_name):
3627 for call in gdb.current_recording ().function_call_history:
3628 try:
3629 if file_name in call.symbol.symtab.fullname ():
3630 yield call
3631 except:
3632 pass
3633
3634 for c in filter_only (filename):
3635 for i in c.instructions:
3636 try:
3637 if i.sal.line in linerange:
3638 count += 1
3639 break;
3640 except:
3641 pass
3642
3643 return count
3644@end smallexample
3645
329baa95
DE
3646@node Commands In Python
3647@subsubsection Commands In Python
3648
3649@cindex commands in python
3650@cindex python commands
3651You can implement new @value{GDBN} CLI commands in Python. A CLI
3652command is implemented using an instance of the @code{gdb.Command}
3653class, most commonly using a subclass.
3654
3655@defun Command.__init__ (name, @var{command_class} @r{[}, @var{completer_class} @r{[}, @var{prefix}@r{]]})
3656The object initializer for @code{Command} registers the new command
3657with @value{GDBN}. This initializer is normally invoked from the
3658subclass' own @code{__init__} method.
3659
3660@var{name} is the name of the command. If @var{name} consists of
3661multiple words, then the initial words are looked for as prefix
3662commands. In this case, if one of the prefix commands does not exist,
3663an exception is raised.
3664
3665There is no support for multi-line commands.
3666
3667@var{command_class} should be one of the @samp{COMMAND_} constants
3668defined below. This argument tells @value{GDBN} how to categorize the
3669new command in the help system.
3670
3671@var{completer_class} is an optional argument. If given, it should be
3672one of the @samp{COMPLETE_} constants defined below. This argument
3673tells @value{GDBN} how to perform completion for this command. If not
3674given, @value{GDBN} will attempt to complete using the object's
3675@code{complete} method (see below); if no such method is found, an
3676error will occur when completion is attempted.
3677
3678@var{prefix} is an optional argument. If @code{True}, then the new
3679command is a prefix command; sub-commands of this command may be
3680registered.
3681
3682The help text for the new command is taken from the Python
3683documentation string for the command's class, if there is one. If no
3684documentation string is provided, the default value ``This command is
3685not documented.'' is used.
3686@end defun
3687
3688@cindex don't repeat Python command
3689@defun Command.dont_repeat ()
3690By default, a @value{GDBN} command is repeated when the user enters a
3691blank line at the command prompt. A command can suppress this
3692behavior by invoking the @code{dont_repeat} method. This is similar
3693to the user command @code{dont-repeat}, see @ref{Define, dont-repeat}.
3694@end defun
3695
3696@defun Command.invoke (argument, from_tty)
3697This method is called by @value{GDBN} when this command is invoked.
3698
3699@var{argument} is a string. It is the argument to the command, after
3700leading and trailing whitespace has been stripped.
3701
3702@var{from_tty} is a boolean argument. When true, this means that the
3703command was entered by the user at the terminal; when false it means
3704that the command came from elsewhere.
3705
3706If this method throws an exception, it is turned into a @value{GDBN}
3707@code{error} call. Otherwise, the return value is ignored.
3708
3709@findex gdb.string_to_argv
3710To break @var{argument} up into an argv-like string use
3711@code{gdb.string_to_argv}. This function behaves identically to
3712@value{GDBN}'s internal argument lexer @code{buildargv}.
3713It is recommended to use this for consistency.
3714Arguments are separated by spaces and may be quoted.
3715Example:
3716
3717@smallexample
3718print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"")
3719['1', '2 "3', '4 "5', "6 '7"]
3720@end smallexample
3721
3722@end defun
3723
3724@cindex completion of Python commands
3725@defun Command.complete (text, word)
3726This method is called by @value{GDBN} when the user attempts
3727completion on this command. All forms of completion are handled by
3728this method, that is, the @key{TAB} and @key{M-?} key bindings
3729(@pxref{Completion}), and the @code{complete} command (@pxref{Help,
3730complete}).
3731
697aa1b7
EZ
3732The arguments @var{text} and @var{word} are both strings; @var{text}
3733holds the complete command line up to the cursor's location, while
329baa95
DE
3734@var{word} holds the last word of the command line; this is computed
3735using a word-breaking heuristic.
3736
3737The @code{complete} method can return several values:
3738@itemize @bullet
3739@item
3740If the return value is a sequence, the contents of the sequence are
3741used as the completions. It is up to @code{complete} to ensure that the
3742contents actually do complete the word. A zero-length sequence is
3743allowed, it means that there were no completions available. Only
3744string elements of the sequence are used; other elements in the
3745sequence are ignored.
3746
3747@item
3748If the return value is one of the @samp{COMPLETE_} constants defined
3749below, then the corresponding @value{GDBN}-internal completion
3750function is invoked, and its result is used.
3751
3752@item
3753All other results are treated as though there were no available
3754completions.
3755@end itemize
3756@end defun
3757
3758When a new command is registered, it must be declared as a member of
3759some general class of commands. This is used to classify top-level
3760commands in the on-line help system; note that prefix commands are not
3761listed under their own category but rather that of their top-level
3762command. The available classifications are represented by constants
3763defined in the @code{gdb} module:
3764
3765@table @code
3766@findex COMMAND_NONE
3767@findex gdb.COMMAND_NONE
3768@item gdb.COMMAND_NONE
3769The command does not belong to any particular class. A command in
3770this category will not be displayed in any of the help categories.
3771
3772@findex COMMAND_RUNNING
3773@findex gdb.COMMAND_RUNNING
3774@item gdb.COMMAND_RUNNING
3775The command is related to running the inferior. For example,
3776@code{start}, @code{step}, and @code{continue} are in this category.
3777Type @kbd{help running} at the @value{GDBN} prompt to see a list of
3778commands in this category.
3779
3780@findex COMMAND_DATA
3781@findex gdb.COMMAND_DATA
3782@item gdb.COMMAND_DATA
3783The command is related to data or variables. For example,
3784@code{call}, @code{find}, and @code{print} are in this category. Type
3785@kbd{help data} at the @value{GDBN} prompt to see a list of commands
3786in this category.
3787
3788@findex COMMAND_STACK
3789@findex gdb.COMMAND_STACK
3790@item gdb.COMMAND_STACK
3791The command has to do with manipulation of the stack. For example,
3792@code{backtrace}, @code{frame}, and @code{return} are in this
3793category. Type @kbd{help stack} at the @value{GDBN} prompt to see a
3794list of commands in this category.
3795
3796@findex COMMAND_FILES
3797@findex gdb.COMMAND_FILES
3798@item gdb.COMMAND_FILES
3799This class is used for file-related commands. For example,
3800@code{file}, @code{list} and @code{section} are in this category.
3801Type @kbd{help files} at the @value{GDBN} prompt to see a list of
3802commands in this category.
3803
3804@findex COMMAND_SUPPORT
3805@findex gdb.COMMAND_SUPPORT
3806@item gdb.COMMAND_SUPPORT
3807This should be used for ``support facilities'', generally meaning
3808things that are useful to the user when interacting with @value{GDBN},
3809but not related to the state of the inferior. For example,
3810@code{help}, @code{make}, and @code{shell} are in this category. Type
3811@kbd{help support} at the @value{GDBN} prompt to see a list of
3812commands in this category.
3813
3814@findex COMMAND_STATUS
3815@findex gdb.COMMAND_STATUS
3816@item gdb.COMMAND_STATUS
3817The command is an @samp{info}-related command, that is, related to the
3818state of @value{GDBN} itself. For example, @code{info}, @code{macro},
3819and @code{show} are in this category. Type @kbd{help status} at the
3820@value{GDBN} prompt to see a list of commands in this category.
3821
3822@findex COMMAND_BREAKPOINTS
3823@findex gdb.COMMAND_BREAKPOINTS
3824@item gdb.COMMAND_BREAKPOINTS
3825The command has to do with breakpoints. For example, @code{break},
3826@code{clear}, and @code{delete} are in this category. Type @kbd{help
3827breakpoints} at the @value{GDBN} prompt to see a list of commands in
3828this category.
3829
3830@findex COMMAND_TRACEPOINTS
3831@findex gdb.COMMAND_TRACEPOINTS
3832@item gdb.COMMAND_TRACEPOINTS
3833The command has to do with tracepoints. For example, @code{trace},
3834@code{actions}, and @code{tfind} are in this category. Type
3835@kbd{help tracepoints} at the @value{GDBN} prompt to see a list of
3836commands in this category.
3837
2b2fbab8
TT
3838@findex COMMAND_TUI
3839@findex gdb.COMMAND_TUI
3840@item gdb.COMMAND_TUI
3841The command has to do with the text user interface (@pxref{TUI}).
3842Type @kbd{help tui} at the @value{GDBN} prompt to see a list of
3843commands in this category.
3844
329baa95
DE
3845@findex COMMAND_USER
3846@findex gdb.COMMAND_USER
3847@item gdb.COMMAND_USER
3848The command is a general purpose command for the user, and typically
3849does not fit in one of the other categories.
3850Type @kbd{help user-defined} at the @value{GDBN} prompt to see
3851a list of commands in this category, as well as the list of gdb macros
3852(@pxref{Sequences}).
3853
3854@findex COMMAND_OBSCURE
3855@findex gdb.COMMAND_OBSCURE
3856@item gdb.COMMAND_OBSCURE
3857The command is only used in unusual circumstances, or is not of
3858general interest to users. For example, @code{checkpoint},
3859@code{fork}, and @code{stop} are in this category. Type @kbd{help
3860obscure} at the @value{GDBN} prompt to see a list of commands in this
3861category.
3862
3863@findex COMMAND_MAINTENANCE
3864@findex gdb.COMMAND_MAINTENANCE
3865@item gdb.COMMAND_MAINTENANCE
3866The command is only useful to @value{GDBN} maintainers. The
3867@code{maintenance} and @code{flushregs} commands are in this category.
3868Type @kbd{help internals} at the @value{GDBN} prompt to see a list of
3869commands in this category.
3870@end table
3871
3872A new command can use a predefined completion function, either by
3873specifying it via an argument at initialization, or by returning it
3874from the @code{complete} method. These predefined completion
3875constants are all defined in the @code{gdb} module:
3876
b3ce5e5f
DE
3877@vtable @code
3878@vindex COMPLETE_NONE
329baa95
DE
3879@item gdb.COMPLETE_NONE
3880This constant means that no completion should be done.
3881
b3ce5e5f 3882@vindex COMPLETE_FILENAME
329baa95
DE
3883@item gdb.COMPLETE_FILENAME
3884This constant means that filename completion should be performed.
3885
b3ce5e5f 3886@vindex COMPLETE_LOCATION
329baa95
DE
3887@item gdb.COMPLETE_LOCATION
3888This constant means that location completion should be done.
3889@xref{Specify Location}.
3890
b3ce5e5f 3891@vindex COMPLETE_COMMAND
329baa95
DE
3892@item gdb.COMPLETE_COMMAND
3893This constant means that completion should examine @value{GDBN}
3894command names.
3895
b3ce5e5f 3896@vindex COMPLETE_SYMBOL
329baa95
DE
3897@item gdb.COMPLETE_SYMBOL
3898This constant means that completion should be done using symbol names
3899as the source.
3900
b3ce5e5f 3901@vindex COMPLETE_EXPRESSION
329baa95
DE
3902@item gdb.COMPLETE_EXPRESSION
3903This constant means that completion should be done on expressions.
3904Often this means completing on symbol names, but some language
3905parsers also have support for completing on field names.
b3ce5e5f 3906@end vtable
329baa95
DE
3907
3908The following code snippet shows how a trivial CLI command can be
3909implemented in Python:
3910
3911@smallexample
3912class HelloWorld (gdb.Command):
3913 """Greet the whole world."""
3914
3915 def __init__ (self):
3916 super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
3917
3918 def invoke (self, arg, from_tty):
3919 print "Hello, World!"
3920
3921HelloWorld ()
3922@end smallexample
3923
3924The last line instantiates the class, and is necessary to trigger the
3925registration of the command with @value{GDBN}. Depending on how the
3926Python code is read into @value{GDBN}, you may need to import the
3927@code{gdb} module explicitly.
3928
3929@node Parameters In Python
3930@subsubsection Parameters In Python
3931
3932@cindex parameters in python
3933@cindex python parameters
3934@tindex gdb.Parameter
3935@tindex Parameter
3936You can implement new @value{GDBN} parameters using Python. A new
3937parameter is implemented as an instance of the @code{gdb.Parameter}
3938class.
3939
3940Parameters are exposed to the user via the @code{set} and
3941@code{show} commands. @xref{Help}.
3942
3943There are many parameters that already exist and can be set in
3944@value{GDBN}. Two examples are: @code{set follow fork} and
3945@code{set charset}. Setting these parameters influences certain
3946behavior in @value{GDBN}. Similarly, you can define parameters that
3947can be used to influence behavior in custom Python scripts and commands.
3948
3949@defun Parameter.__init__ (name, @var{command-class}, @var{parameter-class} @r{[}, @var{enum-sequence}@r{]})
3950The object initializer for @code{Parameter} registers the new
3951parameter with @value{GDBN}. This initializer is normally invoked
3952from the subclass' own @code{__init__} method.
3953
3954@var{name} is the name of the new parameter. If @var{name} consists
3955of multiple words, then the initial words are looked for as prefix
3956parameters. An example of this can be illustrated with the
3957@code{set print} set of parameters. If @var{name} is
3958@code{print foo}, then @code{print} will be searched as the prefix
3959parameter. In this case the parameter can subsequently be accessed in
3960@value{GDBN} as @code{set print foo}.
3961
3962If @var{name} consists of multiple words, and no prefix parameter group
3963can be found, an exception is raised.
3964
3965@var{command-class} should be one of the @samp{COMMAND_} constants
3966(@pxref{Commands In Python}). This argument tells @value{GDBN} how to
3967categorize the new parameter in the help system.
3968
3969@var{parameter-class} should be one of the @samp{PARAM_} constants
3970defined below. This argument tells @value{GDBN} the type of the new
3971parameter; this information is used for input validation and
3972completion.
3973
3974If @var{parameter-class} is @code{PARAM_ENUM}, then
3975@var{enum-sequence} must be a sequence of strings. These strings
3976represent the possible values for the parameter.
3977
3978If @var{parameter-class} is not @code{PARAM_ENUM}, then the presence
3979of a fourth argument will cause an exception to be thrown.
3980
3981The help text for the new parameter is taken from the Python
3982documentation string for the parameter's class, if there is one. If
3983there is no documentation string, a default value is used.
3984@end defun
3985
3986@defvar Parameter.set_doc
3987If this attribute exists, and is a string, then its value is used as
3988the help text for this parameter's @code{set} command. The value is
3989examined when @code{Parameter.__init__} is invoked; subsequent changes
3990have no effect.
3991@end defvar
3992
3993@defvar Parameter.show_doc
3994If this attribute exists, and is a string, then its value is used as
3995the help text for this parameter's @code{show} command. The value is
3996examined when @code{Parameter.__init__} is invoked; subsequent changes
3997have no effect.
3998@end defvar
3999
4000@defvar Parameter.value
4001The @code{value} attribute holds the underlying value of the
4002parameter. It can be read and assigned to just as any other
4003attribute. @value{GDBN} does validation when assignments are made.
4004@end defvar
4005
984ee559
TT
4006There are two methods that may be implemented in any @code{Parameter}
4007class. These are:
329baa95
DE
4008
4009@defun Parameter.get_set_string (self)
984ee559
TT
4010If this method exists, @value{GDBN} will call it when a
4011@var{parameter}'s value has been changed via the @code{set} API (for
4012example, @kbd{set foo off}). The @code{value} attribute has already
4013been populated with the new value and may be used in output. This
4014method must return a string. If the returned string is not empty,
4015@value{GDBN} will present it to the user.
ae778caf
TT
4016
4017If this method raises the @code{gdb.GdbError} exception
4018(@pxref{Exception Handling}), then @value{GDBN} will print the
4019exception's string and the @code{set} command will fail. Note,
4020however, that the @code{value} attribute will not be reset in this
4021case. So, if your parameter must validate values, it should store the
4022old value internally and reset the exposed value, like so:
4023
4024@smallexample
4025class ExampleParam (gdb.Parameter):
4026 def __init__ (self, name):
4027 super (ExampleParam, self).__init__ (name,
4028 gdb.COMMAND_DATA,
4029 gdb.PARAM_BOOLEAN)
4030 self.value = True
4031 self.saved_value = True
4032 def validate(self):
4033 return False
4034 def get_set_string (self):
4035 if not self.validate():
4036 self.value = self.saved_value
4037 raise gdb.GdbError('Failed to validate')
4038 self.saved_value = self.value
4039@end smallexample
329baa95
DE
4040@end defun
4041
4042@defun Parameter.get_show_string (self, svalue)
4043@value{GDBN} will call this method when a @var{parameter}'s
4044@code{show} API has been invoked (for example, @kbd{show foo}). The
4045argument @code{svalue} receives the string representation of the
4046current value. This method must return a string.
4047@end defun
4048
4049When a new parameter is defined, its type must be specified. The
4050available types are represented by constants defined in the @code{gdb}
4051module:
4052
4053@table @code
4054@findex PARAM_BOOLEAN
4055@findex gdb.PARAM_BOOLEAN
4056@item gdb.PARAM_BOOLEAN
4057The value is a plain boolean. The Python boolean values, @code{True}
4058and @code{False} are the only valid values.
4059
4060@findex PARAM_AUTO_BOOLEAN
4061@findex gdb.PARAM_AUTO_BOOLEAN
4062@item gdb.PARAM_AUTO_BOOLEAN
4063The value has three possible states: true, false, and @samp{auto}. In
4064Python, true and false are represented using boolean constants, and
4065@samp{auto} is represented using @code{None}.
4066
4067@findex PARAM_UINTEGER
4068@findex gdb.PARAM_UINTEGER
4069@item gdb.PARAM_UINTEGER
4070The value is an unsigned integer. The value of 0 should be
4071interpreted to mean ``unlimited''.
4072
4073@findex PARAM_INTEGER
4074@findex gdb.PARAM_INTEGER
4075@item gdb.PARAM_INTEGER
4076The value is a signed integer. The value of 0 should be interpreted
4077to mean ``unlimited''.
4078
4079@findex PARAM_STRING
4080@findex gdb.PARAM_STRING
4081@item gdb.PARAM_STRING
4082The value is a string. When the user modifies the string, any escape
4083sequences, such as @samp{\t}, @samp{\f}, and octal escapes, are
4084translated into corresponding characters and encoded into the current
4085host charset.
4086
4087@findex PARAM_STRING_NOESCAPE
4088@findex gdb.PARAM_STRING_NOESCAPE
4089@item gdb.PARAM_STRING_NOESCAPE
4090The value is a string. When the user modifies the string, escapes are
4091passed through untranslated.
4092
4093@findex PARAM_OPTIONAL_FILENAME
4094@findex gdb.PARAM_OPTIONAL_FILENAME
4095@item gdb.PARAM_OPTIONAL_FILENAME
4096The value is a either a filename (a string), or @code{None}.
4097
4098@findex PARAM_FILENAME
4099@findex gdb.PARAM_FILENAME
4100@item gdb.PARAM_FILENAME
4101The value is a filename. This is just like
4102@code{PARAM_STRING_NOESCAPE}, but uses file names for completion.
4103
4104@findex PARAM_ZINTEGER
4105@findex gdb.PARAM_ZINTEGER
4106@item gdb.PARAM_ZINTEGER
4107The value is an integer. This is like @code{PARAM_INTEGER}, except 0
4108is interpreted as itself.
4109
0489430a
TT
4110@findex PARAM_ZUINTEGER
4111@findex gdb.PARAM_ZUINTEGER
4112@item gdb.PARAM_ZUINTEGER
4113The value is an unsigned integer. This is like @code{PARAM_INTEGER},
4114except 0 is interpreted as itself, and the value cannot be negative.
4115
4116@findex PARAM_ZUINTEGER_UNLIMITED
4117@findex gdb.PARAM_ZUINTEGER_UNLIMITED
4118@item gdb.PARAM_ZUINTEGER_UNLIMITED
4119The value is a signed integer. This is like @code{PARAM_ZUINTEGER},
4120except the special value -1 should be interpreted to mean
4121``unlimited''. Other negative values are not allowed.
4122
329baa95
DE
4123@findex PARAM_ENUM
4124@findex gdb.PARAM_ENUM
4125@item gdb.PARAM_ENUM
4126The value is a string, which must be one of a collection string
4127constants provided when the parameter is created.
4128@end table
4129
4130@node Functions In Python
4131@subsubsection Writing new convenience functions
4132
4133@cindex writing convenience functions
4134@cindex convenience functions in python
4135@cindex python convenience functions
4136@tindex gdb.Function
4137@tindex Function
4138You can implement new convenience functions (@pxref{Convenience Vars})
4139in Python. A convenience function is an instance of a subclass of the
4140class @code{gdb.Function}.
4141
4142@defun Function.__init__ (name)
4143The initializer for @code{Function} registers the new function with
4144@value{GDBN}. The argument @var{name} is the name of the function,
4145a string. The function will be visible to the user as a convenience
4146variable of type @code{internal function}, whose name is the same as
4147the given @var{name}.
4148
4149The documentation for the new function is taken from the documentation
4150string for the new class.
4151@end defun
4152
4153@defun Function.invoke (@var{*args})
4154When a convenience function is evaluated, its arguments are converted
4155to instances of @code{gdb.Value}, and then the function's
4156@code{invoke} method is called. Note that @value{GDBN} does not
4157predetermine the arity of convenience functions. Instead, all
4158available arguments are passed to @code{invoke}, following the
4159standard Python calling convention. In particular, a convenience
4160function can have default values for parameters without ill effect.
4161
4162The return value of this method is used as its value in the enclosing
4163expression. If an ordinary Python value is returned, it is converted
4164to a @code{gdb.Value} following the usual rules.
4165@end defun
4166
4167The following code snippet shows how a trivial convenience function can
4168be implemented in Python:
4169
4170@smallexample
4171class Greet (gdb.Function):
4172 """Return string to greet someone.
4173Takes a name as argument."""
4174
4175 def __init__ (self):
4176 super (Greet, self).__init__ ("greet")
4177
4178 def invoke (self, name):
4179 return "Hello, %s!" % name.string ()
4180
4181Greet ()
4182@end smallexample
4183
4184The last line instantiates the class, and is necessary to trigger the
4185registration of the function with @value{GDBN}. Depending on how the
4186Python code is read into @value{GDBN}, you may need to import the
4187@code{gdb} module explicitly.
4188
4189Now you can use the function in an expression:
4190
4191@smallexample
4192(gdb) print $greet("Bob")
4193$1 = "Hello, Bob!"
4194@end smallexample
4195
4196@node Progspaces In Python
4197@subsubsection Program Spaces In Python
4198
4199@cindex progspaces in python
4200@tindex gdb.Progspace
4201@tindex Progspace
4202A program space, or @dfn{progspace}, represents a symbolic view
4203of an address space.
4204It consists of all of the objfiles of the program.
4205@xref{Objfiles In Python}.
65c574f6 4206@xref{Inferiors Connections and Programs, program spaces}, for more details
329baa95
DE
4207about program spaces.
4208
4209The following progspace-related functions are available in the
4210@code{gdb} module:
4211
4212@findex gdb.current_progspace
4213@defun gdb.current_progspace ()
4214This function returns the program space of the currently selected inferior.
65c574f6 4215@xref{Inferiors Connections and Programs}. This is identical to
a40bf0c2
SM
4216@code{gdb.selected_inferior().progspace} (@pxref{Inferiors In Python}) and is
4217included for historical compatibility.
329baa95
DE
4218@end defun
4219
4220@findex gdb.progspaces
4221@defun gdb.progspaces ()
4222Return a sequence of all the progspaces currently known to @value{GDBN}.
4223@end defun
4224
4225Each progspace is represented by an instance of the @code{gdb.Progspace}
4226class.
4227
4228@defvar Progspace.filename
4229The file name of the progspace as a string.
4230@end defvar
4231
4232@defvar Progspace.pretty_printers
4233The @code{pretty_printers} attribute is a list of functions. It is
4234used to look up pretty-printers. A @code{Value} is passed to each
4235function in order; if the function returns @code{None}, then the
4236search continues. Otherwise, the return value should be an object
4237which is used to format the value. @xref{Pretty Printing API}, for more
4238information.
4239@end defvar
4240
4241@defvar Progspace.type_printers
4242The @code{type_printers} attribute is a list of type printer objects.
4243@xref{Type Printing API}, for more information.
4244@end defvar
4245
4246@defvar Progspace.frame_filters
4247The @code{frame_filters} attribute is a dictionary of frame filter
4248objects. @xref{Frame Filter API}, for more information.
4249@end defvar
4250
8743a9cd
TT
4251A program space has the following methods:
4252
4253@findex Progspace.block_for_pc
4254@defun Progspace.block_for_pc (pc)
4255Return the innermost @code{gdb.Block} containing the given @var{pc}
4256value. If the block cannot be found for the @var{pc} value specified,
4257the function will return @code{None}.
4258@end defun
4259
4260@findex Progspace.find_pc_line
4261@defun Progspace.find_pc_line (pc)
4262Return the @code{gdb.Symtab_and_line} object corresponding to the
4263@var{pc} value. @xref{Symbol Tables In Python}. If an invalid value
4264of @var{pc} is passed as an argument, then the @code{symtab} and
4265@code{line} attributes of the returned @code{gdb.Symtab_and_line}
4266object will be @code{None} and 0 respectively.
4267@end defun
4268
4269@findex Progspace.is_valid
4270@defun Progspace.is_valid ()
4271Returns @code{True} if the @code{gdb.Progspace} object is valid,
4272@code{False} if not. A @code{gdb.Progspace} object can become invalid
4273if the program space file it refers to is not referenced by any
4274inferior. All other @code{gdb.Progspace} methods will throw an
4275exception if it is invalid at the time the method is called.
4276@end defun
4277
4278@findex Progspace.objfiles
4279@defun Progspace.objfiles ()
4280Return a sequence of all the objfiles referenced by this program
4281space. @xref{Objfiles In Python}.
4282@end defun
4283
4284@findex Progspace.solib_name
4285@defun Progspace.solib_name (address)
4286Return the name of the shared library holding the given @var{address}
4287as a string, or @code{None}.
4288@end defun
4289
02be9a71
DE
4290One may add arbitrary attributes to @code{gdb.Progspace} objects
4291in the usual Python way.
4292This is useful if, for example, one needs to do some extra record keeping
4293associated with the program space.
4294
4295In this contrived example, we want to perform some processing when
4296an objfile with a certain symbol is loaded, but we only want to do
4297this once because it is expensive. To achieve this we record the results
4298with the program space because we can't predict when the desired objfile
4299will be loaded.
4300
4301@smallexample
4302(gdb) python
4303def clear_objfiles_handler(event):
4304 event.progspace.expensive_computation = None
4305def expensive(symbol):
4306 """A mock routine to perform an "expensive" computation on symbol."""
4307 print "Computing the answer to the ultimate question ..."
4308 return 42
4309def new_objfile_handler(event):
4310 objfile = event.new_objfile
4311 progspace = objfile.progspace
4312 if not hasattr(progspace, 'expensive_computation') or \
4313 progspace.expensive_computation is None:
4314 # We use 'main' for the symbol to keep the example simple.
4315 # Note: There's no current way to constrain the lookup
4316 # to one objfile.
4317 symbol = gdb.lookup_global_symbol('main')
4318 if symbol is not None:
4319 progspace.expensive_computation = expensive(symbol)
4320gdb.events.clear_objfiles.connect(clear_objfiles_handler)
4321gdb.events.new_objfile.connect(new_objfile_handler)
4322end
4323(gdb) file /tmp/hello
0bab6cf1 4324Reading symbols from /tmp/hello...
02be9a71
DE
4325Computing the answer to the ultimate question ...
4326(gdb) python print gdb.current_progspace().expensive_computation
432742
4328(gdb) run
4329Starting program: /tmp/hello
4330Hello.
4331[Inferior 1 (process 4242) exited normally]
4332@end smallexample
4333
329baa95
DE
4334@node Objfiles In Python
4335@subsubsection Objfiles In Python
4336
4337@cindex objfiles in python
4338@tindex gdb.Objfile
4339@tindex Objfile
4340@value{GDBN} loads symbols for an inferior from various
4341symbol-containing files (@pxref{Files}). These include the primary
4342executable file, any shared libraries used by the inferior, and any
4343separate debug info files (@pxref{Separate Debug Files}).
4344@value{GDBN} calls these symbol-containing files @dfn{objfiles}.
4345
4346The following objfile-related functions are available in the
4347@code{gdb} module:
4348
4349@findex gdb.current_objfile
4350@defun gdb.current_objfile ()
4351When auto-loading a Python script (@pxref{Python Auto-loading}), @value{GDBN}
4352sets the ``current objfile'' to the corresponding objfile. This
4353function returns the current objfile. If there is no current objfile,
4354this function returns @code{None}.
4355@end defun
4356
4357@findex gdb.objfiles
4358@defun gdb.objfiles ()
74d3fbbb
SM
4359Return a sequence of objfiles referenced by the current program space.
4360@xref{Objfiles In Python}, and @ref{Progspaces In Python}. This is identical
4361to @code{gdb.selected_inferior().progspace.objfiles()} and is included for
4362historical compatibility.
329baa95
DE
4363@end defun
4364
6dddd6a5
DE
4365@findex gdb.lookup_objfile
4366@defun gdb.lookup_objfile (name @r{[}, by_build_id{]})
4367Look up @var{name}, a file name or build ID, in the list of objfiles
4368for the current program space (@pxref{Progspaces In Python}).
4369If the objfile is not found throw the Python @code{ValueError} exception.
4370
4371If @var{name} is a relative file name, then it will match any
4372source file name with the same trailing components. For example, if
4373@var{name} is @samp{gcc/expr.c}, then it will match source file
4374name of @file{/build/trunk/gcc/expr.c}, but not
4375@file{/build/trunk/libcpp/expr.c} or @file{/build/trunk/gcc/x-expr.c}.
4376
4377If @var{by_build_id} is provided and is @code{True} then @var{name}
4378is the build ID of the objfile. Otherwise, @var{name} is a file name.
4379This is supported only on some operating systems, notably those which use
4380the ELF format for binary files and the @sc{gnu} Binutils. For more details
4381about this feature, see the description of the @option{--build-id}
f5a476a7 4382command-line option in @ref{Options, , Command Line Options, ld,
6dddd6a5
DE
4383The GNU Linker}.
4384@end defun
4385
329baa95
DE
4386Each objfile is represented by an instance of the @code{gdb.Objfile}
4387class.
4388
4389@defvar Objfile.filename
1b549396
DE
4390The file name of the objfile as a string, with symbolic links resolved.
4391
4392The value is @code{None} if the objfile is no longer valid.
4393See the @code{gdb.Objfile.is_valid} method, described below.
329baa95
DE
4394@end defvar
4395
3a8b707a
DE
4396@defvar Objfile.username
4397The file name of the objfile as specified by the user as a string.
4398
4399The value is @code{None} if the objfile is no longer valid.
4400See the @code{gdb.Objfile.is_valid} method, described below.
4401@end defvar
4402
a0be3e44
DE
4403@defvar Objfile.owner
4404For separate debug info objfiles this is the corresponding @code{gdb.Objfile}
4405object that debug info is being provided for.
4406Otherwise this is @code{None}.
4407Separate debug info objfiles are added with the
4408@code{gdb.Objfile.add_separate_debug_file} method, described below.
4409@end defvar
4410
7c50a931
DE
4411@defvar Objfile.build_id
4412The build ID of the objfile as a string.
4413If the objfile does not have a build ID then the value is @code{None}.
4414
4415This is supported only on some operating systems, notably those which use
4416the ELF format for binary files and the @sc{gnu} Binutils. For more details
4417about this feature, see the description of the @option{--build-id}
f5a476a7 4418command-line option in @ref{Options, , Command Line Options, ld,
7c50a931
DE
4419The GNU Linker}.
4420@end defvar
4421
d096d8c1
DE
4422@defvar Objfile.progspace
4423The containing program space of the objfile as a @code{gdb.Progspace}
4424object. @xref{Progspaces In Python}.
4425@end defvar
4426
329baa95
DE
4427@defvar Objfile.pretty_printers
4428The @code{pretty_printers} attribute is a list of functions. It is
4429used to look up pretty-printers. A @code{Value} is passed to each
4430function in order; if the function returns @code{None}, then the
4431search continues. Otherwise, the return value should be an object
4432which is used to format the value. @xref{Pretty Printing API}, for more
4433information.
4434@end defvar
4435
4436@defvar Objfile.type_printers
4437The @code{type_printers} attribute is a list of type printer objects.
4438@xref{Type Printing API}, for more information.
4439@end defvar
4440
4441@defvar Objfile.frame_filters
4442The @code{frame_filters} attribute is a dictionary of frame filter
4443objects. @xref{Frame Filter API}, for more information.
4444@end defvar
4445
02be9a71
DE
4446One may add arbitrary attributes to @code{gdb.Objfile} objects
4447in the usual Python way.
4448This is useful if, for example, one needs to do some extra record keeping
4449associated with the objfile.
4450
4451In this contrived example we record the time when @value{GDBN}
4452loaded the objfile.
4453
4454@smallexample
4455(gdb) python
4456import datetime
4457def new_objfile_handler(event):
4458 # Set the time_loaded attribute of the new objfile.
4459 event.new_objfile.time_loaded = datetime.datetime.today()
4460gdb.events.new_objfile.connect(new_objfile_handler)
4461end
4462(gdb) file ./hello
0bab6cf1 4463Reading symbols from ./hello...
02be9a71
DE
4464(gdb) python print gdb.objfiles()[0].time_loaded
44652014-10-09 11:41:36.770345
4466@end smallexample
4467
329baa95
DE
4468A @code{gdb.Objfile} object has the following methods:
4469
4470@defun Objfile.is_valid ()
4471Returns @code{True} if the @code{gdb.Objfile} object is valid,
4472@code{False} if not. A @code{gdb.Objfile} object can become invalid
4473if the object file it refers to is not loaded in @value{GDBN} any
4474longer. All other @code{gdb.Objfile} methods will throw an exception
4475if it is invalid at the time the method is called.
4476@end defun
4477
86e4ed39
DE
4478@defun Objfile.add_separate_debug_file (file)
4479Add @var{file} to the list of files that @value{GDBN} will search for
4480debug information for the objfile.
4481This is useful when the debug info has been removed from the program
4482and stored in a separate file. @value{GDBN} has built-in support for
4483finding separate debug info files (@pxref{Separate Debug Files}), but if
4484the file doesn't live in one of the standard places that @value{GDBN}
4485searches then this function can be used to add a debug info file
4486from a different place.
4487@end defun
4488
c620ed88
CB
4489@defun Objfile.lookup_global_symbol (name @r{[}, domain@r{]})
4490Search for a global symbol named @var{name} in this objfile. Optionally, the
4491search scope can be restricted with the @var{domain} argument.
4492The @var{domain} argument must be a domain constant defined in the @code{gdb}
4493module and described in @ref{Symbols In Python}. This function is similar to
4494@code{gdb.lookup_global_symbol}, except that the search is limited to this
4495objfile.
4496
4497The result is a @code{gdb.Symbol} object or @code{None} if the symbol
4498is not found.
4499@end defun
4500
4501@defun Objfile.lookup_static_symbol (name @r{[}, domain@r{]})
4502Like @code{Objfile.lookup_global_symbol}, but searches for a global
4503symbol with static linkage named @var{name} in this objfile.
4504@end defun
4505
329baa95 4506@node Frames In Python
849cba3b 4507@subsubsection Accessing inferior stack frames from Python
329baa95
DE
4508
4509@cindex frames in python
4510When the debugged program stops, @value{GDBN} is able to analyze its call
4511stack (@pxref{Frames,,Stack frames}). The @code{gdb.Frame} class
4512represents a frame in the stack. A @code{gdb.Frame} object is only valid
4513while its corresponding frame exists in the inferior's stack. If you try
4514to use an invalid frame object, @value{GDBN} will throw a @code{gdb.error}
4515exception (@pxref{Exception Handling}).
4516
4517Two @code{gdb.Frame} objects can be compared for equality with the @code{==}
4518operator, like:
4519
4520@smallexample
4521(@value{GDBP}) python print gdb.newest_frame() == gdb.selected_frame ()
4522True
4523@end smallexample
4524
4525The following frame-related functions are available in the @code{gdb} module:
4526
4527@findex gdb.selected_frame
4528@defun gdb.selected_frame ()
4529Return the selected frame object. (@pxref{Selection,,Selecting a Frame}).
4530@end defun
4531
4532@findex gdb.newest_frame
4533@defun gdb.newest_frame ()
4534Return the newest frame object for the selected thread.
4535@end defun
4536
4537@defun gdb.frame_stop_reason_string (reason)
4538Return a string explaining the reason why @value{GDBN} stopped unwinding
4539frames, as expressed by the given @var{reason} code (an integer, see the
4540@code{unwind_stop_reason} method further down in this section).
4541@end defun
4542
e0f3fd7c
TT
4543@findex gdb.invalidate_cached_frames
4544@defun gdb.invalidate_cached_frames
4545@value{GDBN} internally keeps a cache of the frames that have been
4546unwound. This function invalidates this cache.
4547
4548This function should not generally be called by ordinary Python code.
4549It is documented for the sake of completeness.
4550@end defun
4551
329baa95
DE
4552A @code{gdb.Frame} object has the following methods:
4553
4554@defun Frame.is_valid ()
4555Returns true if the @code{gdb.Frame} object is valid, false if not.
4556A frame object can become invalid if the frame it refers to doesn't
4557exist anymore in the inferior. All @code{gdb.Frame} methods will throw
4558an exception if it is invalid at the time the method is called.
4559@end defun
4560
4561@defun Frame.name ()
4562Returns the function name of the frame, or @code{None} if it can't be
4563obtained.
4564@end defun
4565
4566@defun Frame.architecture ()
4567Returns the @code{gdb.Architecture} object corresponding to the frame's
4568architecture. @xref{Architectures In Python}.
4569@end defun
4570
4571@defun Frame.type ()
4572Returns the type of the frame. The value can be one of:
4573@table @code
4574@item gdb.NORMAL_FRAME
4575An ordinary stack frame.
4576
4577@item gdb.DUMMY_FRAME
4578A fake stack frame that was created by @value{GDBN} when performing an
4579inferior function call.
4580
4581@item gdb.INLINE_FRAME
4582A frame representing an inlined function. The function was inlined
4583into a @code{gdb.NORMAL_FRAME} that is older than this one.
4584
4585@item gdb.TAILCALL_FRAME
4586A frame representing a tail call. @xref{Tail Call Frames}.
4587
4588@item gdb.SIGTRAMP_FRAME
4589A signal trampoline frame. This is the frame created by the OS when
4590it calls into a signal handler.
4591
4592@item gdb.ARCH_FRAME
4593A fake stack frame representing a cross-architecture call.
4594
4595@item gdb.SENTINEL_FRAME
4596This is like @code{gdb.NORMAL_FRAME}, but it is only used for the
4597newest frame.
4598@end table
4599@end defun
4600
4601@defun Frame.unwind_stop_reason ()
4602Return an integer representing the reason why it's not possible to find
4603more frames toward the outermost frame. Use
4604@code{gdb.frame_stop_reason_string} to convert the value returned by this
4605function to a string. The value can be one of:
4606
4607@table @code
4608@item gdb.FRAME_UNWIND_NO_REASON
4609No particular reason (older frames should be available).
4610
4611@item gdb.FRAME_UNWIND_NULL_ID
4612The previous frame's analyzer returns an invalid result. This is no
4613longer used by @value{GDBN}, and is kept only for backward
4614compatibility.
4615
4616@item gdb.FRAME_UNWIND_OUTERMOST
4617This frame is the outermost.
4618
4619@item gdb.FRAME_UNWIND_UNAVAILABLE
4620Cannot unwind further, because that would require knowing the
4621values of registers or memory that have not been collected.
4622
4623@item gdb.FRAME_UNWIND_INNER_ID
4624This frame ID looks like it ought to belong to a NEXT frame,
4625but we got it for a PREV frame. Normally, this is a sign of
4626unwinder failure. It could also indicate stack corruption.
4627
4628@item gdb.FRAME_UNWIND_SAME_ID
4629This frame has the same ID as the previous one. That means
4630that unwinding further would almost certainly give us another
4631frame with exactly the same ID, so break the chain. Normally,
4632this is a sign of unwinder failure. It could also indicate
4633stack corruption.
4634
4635@item gdb.FRAME_UNWIND_NO_SAVED_PC
4636The frame unwinder did not find any saved PC, but we needed
4637one to unwind further.
4638
53e8a631
AB
4639@item gdb.FRAME_UNWIND_MEMORY_ERROR
4640The frame unwinder caused an error while trying to access memory.
4641
329baa95
DE
4642@item gdb.FRAME_UNWIND_FIRST_ERROR
4643Any stop reason greater or equal to this value indicates some kind
4644of error. This special value facilitates writing code that tests
4645for errors in unwinding in a way that will work correctly even if
4646the list of the other values is modified in future @value{GDBN}
4647versions. Using it, you could write:
4648@smallexample
4649reason = gdb.selected_frame().unwind_stop_reason ()
4650reason_str = gdb.frame_stop_reason_string (reason)
4651if reason >= gdb.FRAME_UNWIND_FIRST_ERROR:
4652 print "An error occured: %s" % reason_str
4653@end smallexample
4654@end table
4655
4656@end defun
4657
4658@defun Frame.pc ()
4659Returns the frame's resume address.
4660@end defun
4661
4662@defun Frame.block ()
60c0454d
TT
4663Return the frame's code block. @xref{Blocks In Python}. If the frame
4664does not have a block -- for example, if there is no debugging
4665information for the code in question -- then this will throw an
4666exception.
329baa95
DE
4667@end defun
4668
4669@defun Frame.function ()
4670Return the symbol for the function corresponding to this frame.
4671@xref{Symbols In Python}.
4672@end defun
4673
4674@defun Frame.older ()
4675Return the frame that called this frame.
4676@end defun
4677
4678@defun Frame.newer ()
4679Return the frame called by this frame.
4680@end defun
4681
4682@defun Frame.find_sal ()
4683Return the frame's symtab and line object.
4684@xref{Symbol Tables In Python}.
4685@end defun
4686
5f3b99cf
SS
4687@defun Frame.read_register (register)
4688Return the value of @var{register} in this frame. The @var{register}
4689argument must be a string (e.g., @code{'sp'} or @code{'rax'}).
4690Returns a @code{Gdb.Value} object. Throws an exception if @var{register}
4691does not exist.
4692@end defun
4693
329baa95
DE
4694@defun Frame.read_var (variable @r{[}, block@r{]})
4695Return the value of @var{variable} in this frame. If the optional
4696argument @var{block} is provided, search for the variable from that
4697block; otherwise start at the frame's current block (which is
697aa1b7
EZ
4698determined by the frame's current program counter). The @var{variable}
4699argument must be a string or a @code{gdb.Symbol} object; @var{block} must be a
329baa95
DE
4700@code{gdb.Block} object.
4701@end defun
4702
4703@defun Frame.select ()
4704Set this frame to be the selected frame. @xref{Stack, ,Examining the
4705Stack}.
4706@end defun
4707
4708@node Blocks In Python
849cba3b 4709@subsubsection Accessing blocks from Python
329baa95
DE
4710
4711@cindex blocks in python
4712@tindex gdb.Block
4713
4714In @value{GDBN}, symbols are stored in blocks. A block corresponds
4715roughly to a scope in the source code. Blocks are organized
4716hierarchically, and are represented individually in Python as a
4717@code{gdb.Block}. Blocks rely on debugging information being
4718available.
4719
4720A frame has a block. Please see @ref{Frames In Python}, for a more
4721in-depth discussion of frames.
4722
4723The outermost block is known as the @dfn{global block}. The global
4724block typically holds public global variables and functions.
4725
4726The block nested just inside the global block is the @dfn{static
4727block}. The static block typically holds file-scoped variables and
4728functions.
4729
4730@value{GDBN} provides a method to get a block's superblock, but there
4731is currently no way to examine the sub-blocks of a block, or to
4732iterate over all the blocks in a symbol table (@pxref{Symbol Tables In
4733Python}).
4734
4735Here is a short example that should help explain blocks:
4736
4737@smallexample
4738/* This is in the global block. */
4739int global;
4740
4741/* This is in the static block. */
4742static int file_scope;
4743
4744/* 'function' is in the global block, and 'argument' is
4745 in a block nested inside of 'function'. */
4746int function (int argument)
4747@{
4748 /* 'local' is in a block inside 'function'. It may or may
4749 not be in the same block as 'argument'. */
4750 int local;
4751
4752 @{
4753 /* 'inner' is in a block whose superblock is the one holding
4754 'local'. */
4755 int inner;
4756
4757 /* If this call is expanded by the compiler, you may see
4758 a nested block here whose function is 'inline_function'
4759 and whose superblock is the one holding 'inner'. */
4760 inline_function ();
4761 @}
4762@}
4763@end smallexample
4764
4765A @code{gdb.Block} is iterable. The iterator returns the symbols
4766(@pxref{Symbols In Python}) local to the block. Python programs
4767should not assume that a specific block object will always contain a
4768given symbol, since changes in @value{GDBN} features and
4769infrastructure may cause symbols move across blocks in a symbol
0b27c27d
CB
4770table. You can also use Python's @dfn{dictionary syntax} to access
4771variables in this block, e.g.:
4772
4773@smallexample
4774symbol = some_block['variable'] # symbol is of type gdb.Symbol
4775@end smallexample
329baa95
DE
4776
4777The following block-related functions are available in the @code{gdb}
4778module:
4779
4780@findex gdb.block_for_pc
4781@defun gdb.block_for_pc (pc)
4782Return the innermost @code{gdb.Block} containing the given @var{pc}
4783value. If the block cannot be found for the @var{pc} value specified,
8743a9cd
TT
4784the function will return @code{None}. This is identical to
4785@code{gdb.current_progspace().block_for_pc(pc)} and is included for
4786historical compatibility.
329baa95
DE
4787@end defun
4788
4789A @code{gdb.Block} object has the following methods:
4790
4791@defun Block.is_valid ()
4792Returns @code{True} if the @code{gdb.Block} object is valid,
4793@code{False} if not. A block object can become invalid if the block it
4794refers to doesn't exist anymore in the inferior. All other
4795@code{gdb.Block} methods will throw an exception if it is invalid at
4796the time the method is called. The block's validity is also checked
4797during iteration over symbols of the block.
4798@end defun
4799
4800A @code{gdb.Block} object has the following attributes:
4801
4802@defvar Block.start
4803The start address of the block. This attribute is not writable.
4804@end defvar
4805
4806@defvar Block.end
22eb9e92
TT
4807One past the last address that appears in the block. This attribute
4808is not writable.
329baa95
DE
4809@end defvar
4810
4811@defvar Block.function
4812The name of the block represented as a @code{gdb.Symbol}. If the
4813block is not named, then this attribute holds @code{None}. This
4814attribute is not writable.
4815
4816For ordinary function blocks, the superblock is the static block.
4817However, you should note that it is possible for a function block to
4818have a superblock that is not the static block -- for instance this
4819happens for an inlined function.
4820@end defvar
4821
4822@defvar Block.superblock
4823The block containing this block. If this parent block does not exist,
4824this attribute holds @code{None}. This attribute is not writable.
4825@end defvar
4826
4827@defvar Block.global_block
4828The global block associated with this block. This attribute is not
4829writable.
4830@end defvar
4831
4832@defvar Block.static_block
4833The static block associated with this block. This attribute is not
4834writable.
4835@end defvar
4836
4837@defvar Block.is_global
4838@code{True} if the @code{gdb.Block} object is a global block,
4839@code{False} if not. This attribute is not
4840writable.
4841@end defvar
4842
4843@defvar Block.is_static
4844@code{True} if the @code{gdb.Block} object is a static block,
4845@code{False} if not. This attribute is not writable.
4846@end defvar
4847
4848@node Symbols In Python
849cba3b 4849@subsubsection Python representation of Symbols
329baa95
DE
4850
4851@cindex symbols in python
4852@tindex gdb.Symbol
4853
4854@value{GDBN} represents every variable, function and type as an
4855entry in a symbol table. @xref{Symbols, ,Examining the Symbol Table}.
4856Similarly, Python represents these symbols in @value{GDBN} with the
4857@code{gdb.Symbol} object.
4858
4859The following symbol-related functions are available in the @code{gdb}
4860module:
4861
4862@findex gdb.lookup_symbol
4863@defun gdb.lookup_symbol (name @r{[}, block @r{[}, domain@r{]]})
4864This function searches for a symbol by name. The search scope can be
4865restricted to the parameters defined in the optional domain and block
4866arguments.
4867
4868@var{name} is the name of the symbol. It must be a string. The
4869optional @var{block} argument restricts the search to symbols visible
4870in that @var{block}. The @var{block} argument must be a
4871@code{gdb.Block} object. If omitted, the block for the current frame
4872is used. The optional @var{domain} argument restricts
4873the search to the domain type. The @var{domain} argument must be a
4874domain constant defined in the @code{gdb} module and described later
4875in this chapter.
4876
4877The result is a tuple of two elements.
4878The first element is a @code{gdb.Symbol} object or @code{None} if the symbol
4879is not found.
4880If the symbol is found, the second element is @code{True} if the symbol
4881is a field of a method's object (e.g., @code{this} in C@t{++}),
4882otherwise it is @code{False}.
4883If the symbol is not found, the second element is @code{False}.
4884@end defun
4885
4886@findex gdb.lookup_global_symbol
4887@defun gdb.lookup_global_symbol (name @r{[}, domain@r{]})
4888This function searches for a global symbol by name.
4889The search scope can be restricted to by the domain argument.
4890
4891@var{name} is the name of the symbol. It must be a string.
4892The optional @var{domain} argument restricts the search to the domain type.
4893The @var{domain} argument must be a domain constant defined in the @code{gdb}
4894module and described later in this chapter.
4895
4896The result is a @code{gdb.Symbol} object or @code{None} if the symbol
4897is not found.
4898@end defun
4899
2906593f
CB
4900@findex gdb.lookup_static_symbol
4901@defun gdb.lookup_static_symbol (name @r{[}, domain@r{]})
4902This function searches for a global symbol with static linkage by name.
4903The search scope can be restricted to by the domain argument.
4904
4905@var{name} is the name of the symbol. It must be a string.
4906The optional @var{domain} argument restricts the search to the domain type.
4907The @var{domain} argument must be a domain constant defined in the @code{gdb}
4908module and described later in this chapter.
4909
4910The result is a @code{gdb.Symbol} object or @code{None} if the symbol
4911is not found.
4912
4913Note that this function will not find function-scoped static variables. To look
4914up such variables, iterate over the variables of the function's
4915@code{gdb.Block} and check that @code{block.addr_class} is
4916@code{gdb.SYMBOL_LOC_STATIC}.
09ff83af
AB
4917
4918There can be multiple global symbols with static linkage with the same
4919name. This function will only return the first matching symbol that
4920it finds. Which symbol is found depends on where @value{GDBN} is
4921currently stopped, as @value{GDBN} will first search for matching
4922symbols in the current object file, and then search all other object
4923files. If the application is not yet running then @value{GDBN} will
4924search all object files in the order they appear in the debug
4925information.
2906593f
CB
4926@end defun
4927
086baaf1
AB
4928@findex gdb.lookup_static_symbols
4929@defun gdb.lookup_static_symbols (name @r{[}, domain@r{]})
4930Similar to @code{gdb.lookup_static_symbol}, this function searches for
4931global symbols with static linkage by name, and optionally restricted
4932by the domain argument. However, this function returns a list of all
4933matching symbols found, not just the first one.
4934
4935@var{name} is the name of the symbol. It must be a string.
4936The optional @var{domain} argument restricts the search to the domain type.
4937The @var{domain} argument must be a domain constant defined in the @code{gdb}
4938module and described later in this chapter.
4939
4940The result is a list of @code{gdb.Symbol} objects which could be empty
4941if no matching symbols were found.
4942
4943Note that this function will not find function-scoped static variables. To look
4944up such variables, iterate over the variables of the function's
4945@code{gdb.Block} and check that @code{block.addr_class} is
4946@code{gdb.SYMBOL_LOC_STATIC}.
4947@end defun
4948
329baa95
DE
4949A @code{gdb.Symbol} object has the following attributes:
4950
4951@defvar Symbol.type
4952The type of the symbol or @code{None} if no type is recorded.
4953This attribute is represented as a @code{gdb.Type} object.
4954@xref{Types In Python}. This attribute is not writable.
4955@end defvar
4956
4957@defvar Symbol.symtab
4958The symbol table in which the symbol appears. This attribute is
4959represented as a @code{gdb.Symtab} object. @xref{Symbol Tables In
4960Python}. This attribute is not writable.
4961@end defvar
4962
4963@defvar Symbol.line
4964The line number in the source code at which the symbol was defined.
4965This is an integer.
4966@end defvar
4967
4968@defvar Symbol.name
4969The name of the symbol as a string. This attribute is not writable.
4970@end defvar
4971
4972@defvar Symbol.linkage_name
4973The name of the symbol, as used by the linker (i.e., may be mangled).
4974This attribute is not writable.
4975@end defvar
4976
4977@defvar Symbol.print_name
4978The name of the symbol in a form suitable for output. This is either
4979@code{name} or @code{linkage_name}, depending on whether the user
4980asked @value{GDBN} to display demangled or mangled names.
4981@end defvar
4982
4983@defvar Symbol.addr_class
4984The address class of the symbol. This classifies how to find the value
4985of a symbol. Each address class is a constant defined in the
4986@code{gdb} module and described later in this chapter.
4987@end defvar
4988
4989@defvar Symbol.needs_frame
4990This is @code{True} if evaluating this symbol's value requires a frame
4991(@pxref{Frames In Python}) and @code{False} otherwise. Typically,
4992local variables will require a frame, but other symbols will not.
4993@end defvar
4994
4995@defvar Symbol.is_argument
4996@code{True} if the symbol is an argument of a function.
4997@end defvar
4998
4999@defvar Symbol.is_constant
5000@code{True} if the symbol is a constant.
5001@end defvar
5002
5003@defvar Symbol.is_function
5004@code{True} if the symbol is a function or a method.
5005@end defvar
5006
5007@defvar Symbol.is_variable
5008@code{True} if the symbol is a variable.
5009@end defvar
5010
5011A @code{gdb.Symbol} object has the following methods:
5012
5013@defun Symbol.is_valid ()
5014Returns @code{True} if the @code{gdb.Symbol} object is valid,
5015@code{False} if not. A @code{gdb.Symbol} object can become invalid if
5016the symbol it refers to does not exist in @value{GDBN} any longer.
5017All other @code{gdb.Symbol} methods will throw an exception if it is
5018invalid at the time the method is called.
5019@end defun
5020
5021@defun Symbol.value (@r{[}frame@r{]})
5022Compute the value of the symbol, as a @code{gdb.Value}. For
5023functions, this computes the address of the function, cast to the
5024appropriate type. If the symbol requires a frame in order to compute
5025its value, then @var{frame} must be given. If @var{frame} is not
5026given, or if @var{frame} is invalid, then this method will throw an
5027exception.
5028@end defun
5029
5030The available domain categories in @code{gdb.Symbol} are represented
5031as constants in the @code{gdb} module:
5032
b3ce5e5f
DE
5033@vtable @code
5034@vindex SYMBOL_UNDEF_DOMAIN
329baa95
DE
5035@item gdb.SYMBOL_UNDEF_DOMAIN
5036This is used when a domain has not been discovered or none of the
5037following domains apply. This usually indicates an error either
5038in the symbol information or in @value{GDBN}'s handling of symbols.
b3ce5e5f
DE
5039
5040@vindex SYMBOL_VAR_DOMAIN
329baa95
DE
5041@item gdb.SYMBOL_VAR_DOMAIN
5042This domain contains variables, function names, typedef names and enum
5043type values.
b3ce5e5f
DE
5044
5045@vindex SYMBOL_STRUCT_DOMAIN
329baa95
DE
5046@item gdb.SYMBOL_STRUCT_DOMAIN
5047This domain holds struct, union and enum type names.
b3ce5e5f
DE
5048
5049@vindex SYMBOL_LABEL_DOMAIN
329baa95
DE
5050@item gdb.SYMBOL_LABEL_DOMAIN
5051This domain contains names of labels (for gotos).
b3ce5e5f 5052
51e78fc5
TT
5053@vindex SYMBOL_MODULE_DOMAIN
5054@item gdb.SYMBOL_MODULE_DOMAIN
5055This domain contains names of Fortran module types.
5056
5057@vindex SYMBOL_COMMON_BLOCK_DOMAIN
5058@item gdb.SYMBOL_COMMON_BLOCK_DOMAIN
5059This domain contains names of Fortran common blocks.
b3ce5e5f 5060@end vtable
329baa95
DE
5061
5062The available address class categories in @code{gdb.Symbol} are represented
5063as constants in the @code{gdb} module:
5064
b3ce5e5f
DE
5065@vtable @code
5066@vindex SYMBOL_LOC_UNDEF
329baa95
DE
5067@item gdb.SYMBOL_LOC_UNDEF
5068If this is returned by address class, it indicates an error either in
5069the symbol information or in @value{GDBN}'s handling of symbols.
b3ce5e5f
DE
5070
5071@vindex SYMBOL_LOC_CONST
329baa95
DE
5072@item gdb.SYMBOL_LOC_CONST
5073Value is constant int.
b3ce5e5f
DE
5074
5075@vindex SYMBOL_LOC_STATIC
329baa95
DE
5076@item gdb.SYMBOL_LOC_STATIC
5077Value is at a fixed address.
b3ce5e5f
DE
5078
5079@vindex SYMBOL_LOC_REGISTER
329baa95
DE
5080@item gdb.SYMBOL_LOC_REGISTER
5081Value is in a register.
b3ce5e5f
DE
5082
5083@vindex SYMBOL_LOC_ARG
329baa95
DE
5084@item gdb.SYMBOL_LOC_ARG
5085Value is an argument. This value is at the offset stored within the
5086symbol inside the frame's argument list.
b3ce5e5f
DE
5087
5088@vindex SYMBOL_LOC_REF_ARG
329baa95
DE
5089@item gdb.SYMBOL_LOC_REF_ARG
5090Value address is stored in the frame's argument list. Just like
5091@code{LOC_ARG} except that the value's address is stored at the
5092offset, not the value itself.
b3ce5e5f
DE
5093
5094@vindex SYMBOL_LOC_REGPARM_ADDR
329baa95
DE
5095@item gdb.SYMBOL_LOC_REGPARM_ADDR
5096Value is a specified register. Just like @code{LOC_REGISTER} except
5097the register holds the address of the argument instead of the argument
5098itself.
b3ce5e5f
DE
5099
5100@vindex SYMBOL_LOC_LOCAL
329baa95
DE
5101@item gdb.SYMBOL_LOC_LOCAL
5102Value is a local variable.
b3ce5e5f
DE
5103
5104@vindex SYMBOL_LOC_TYPEDEF
329baa95
DE
5105@item gdb.SYMBOL_LOC_TYPEDEF
5106Value not used. Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all
5107have this class.
b3ce5e5f
DE
5108
5109@vindex SYMBOL_LOC_BLOCK
329baa95
DE
5110@item gdb.SYMBOL_LOC_BLOCK
5111Value is a block.
b3ce5e5f
DE
5112
5113@vindex SYMBOL_LOC_CONST_BYTES
329baa95
DE
5114@item gdb.SYMBOL_LOC_CONST_BYTES
5115Value is a byte-sequence.
b3ce5e5f
DE
5116
5117@vindex SYMBOL_LOC_UNRESOLVED
329baa95
DE
5118@item gdb.SYMBOL_LOC_UNRESOLVED
5119Value is at a fixed address, but the address of the variable has to be
5120determined from the minimal symbol table whenever the variable is
5121referenced.
b3ce5e5f
DE
5122
5123@vindex SYMBOL_LOC_OPTIMIZED_OUT
329baa95
DE
5124@item gdb.SYMBOL_LOC_OPTIMIZED_OUT
5125The value does not actually exist in the program.
b3ce5e5f
DE
5126
5127@vindex SYMBOL_LOC_COMPUTED
329baa95
DE
5128@item gdb.SYMBOL_LOC_COMPUTED
5129The value's address is a computed location.
51e78fc5
TT
5130
5131@vindex SYMBOL_LOC_COMPUTED
5132@item gdb.SYMBOL_LOC_COMPUTED
5133The value's address is a symbol. This is only used for Fortran common
5134blocks.
b3ce5e5f 5135@end vtable
329baa95
DE
5136
5137@node Symbol Tables In Python
849cba3b 5138@subsubsection Symbol table representation in Python
329baa95
DE
5139
5140@cindex symbol tables in python
5141@tindex gdb.Symtab
5142@tindex gdb.Symtab_and_line
5143
5144Access to symbol table data maintained by @value{GDBN} on the inferior
5145is exposed to Python via two objects: @code{gdb.Symtab_and_line} and
5146@code{gdb.Symtab}. Symbol table and line data for a frame is returned
5147from the @code{find_sal} method in @code{gdb.Frame} object.
5148@xref{Frames In Python}.
5149
5150For more information on @value{GDBN}'s symbol table management, see
5151@ref{Symbols, ,Examining the Symbol Table}, for more information.
5152
5153A @code{gdb.Symtab_and_line} object has the following attributes:
5154
5155@defvar Symtab_and_line.symtab
5156The symbol table object (@code{gdb.Symtab}) for this frame.
5157This attribute is not writable.
5158@end defvar
5159
5160@defvar Symtab_and_line.pc
5161Indicates the start of the address range occupied by code for the
5162current source line. This attribute is not writable.
5163@end defvar
5164
5165@defvar Symtab_and_line.last
5166Indicates the end of the address range occupied by code for the current
5167source line. This attribute is not writable.
5168@end defvar
5169
5170@defvar Symtab_and_line.line
5171Indicates the current line number for this object. This
5172attribute is not writable.
5173@end defvar
5174
5175A @code{gdb.Symtab_and_line} object has the following methods:
5176
5177@defun Symtab_and_line.is_valid ()
5178Returns @code{True} if the @code{gdb.Symtab_and_line} object is valid,
5179@code{False} if not. A @code{gdb.Symtab_and_line} object can become
5180invalid if the Symbol table and line object it refers to does not
5181exist in @value{GDBN} any longer. All other
5182@code{gdb.Symtab_and_line} methods will throw an exception if it is
5183invalid at the time the method is called.
5184@end defun
5185
5186A @code{gdb.Symtab} object has the following attributes:
5187
5188@defvar Symtab.filename
5189The symbol table's source filename. This attribute is not writable.
5190@end defvar
5191
5192@defvar Symtab.objfile
5193The symbol table's backing object file. @xref{Objfiles In Python}.
5194This attribute is not writable.
5195@end defvar
5196
2b4fd423
DE
5197@defvar Symtab.producer
5198The name and possibly version number of the program that
5199compiled the code in the symbol table.
5200The contents of this string is up to the compiler.
5201If no producer information is available then @code{None} is returned.
5202This attribute is not writable.
5203@end defvar
5204
329baa95
DE
5205A @code{gdb.Symtab} object has the following methods:
5206
5207@defun Symtab.is_valid ()
5208Returns @code{True} if the @code{gdb.Symtab} object is valid,
5209@code{False} if not. A @code{gdb.Symtab} object can become invalid if
5210the symbol table it refers to does not exist in @value{GDBN} any
5211longer. All other @code{gdb.Symtab} methods will throw an exception
5212if it is invalid at the time the method is called.
5213@end defun
5214
5215@defun Symtab.fullname ()
5216Return the symbol table's source absolute file name.
5217@end defun
5218
5219@defun Symtab.global_block ()
5220Return the global block of the underlying symbol table.
5221@xref{Blocks In Python}.
5222@end defun
5223
5224@defun Symtab.static_block ()
5225Return the static block of the underlying symbol table.
5226@xref{Blocks In Python}.
5227@end defun
5228
5229@defun Symtab.linetable ()
5230Return the line table associated with the symbol table.
5231@xref{Line Tables In Python}.
5232@end defun
5233
5234@node Line Tables In Python
5235@subsubsection Manipulating line tables using Python
5236
5237@cindex line tables in python
5238@tindex gdb.LineTable
5239
5240Python code can request and inspect line table information from a
5241symbol table that is loaded in @value{GDBN}. A line table is a
5242mapping of source lines to their executable locations in memory. To
5243acquire the line table information for a particular symbol table, use
5244the @code{linetable} function (@pxref{Symbol Tables In Python}).
5245
5246A @code{gdb.LineTable} is iterable. The iterator returns
5247@code{LineTableEntry} objects that correspond to the source line and
5248address for each line table entry. @code{LineTableEntry} objects have
5249the following attributes:
5250
5251@defvar LineTableEntry.line
5252The source line number for this line table entry. This number
5253corresponds to the actual line of source. This attribute is not
5254writable.
5255@end defvar
5256
5257@defvar LineTableEntry.pc
5258The address that is associated with the line table entry where the
5259executable code for that source line resides in memory. This
5260attribute is not writable.
5261@end defvar
5262
5263As there can be multiple addresses for a single source line, you may
5264receive multiple @code{LineTableEntry} objects with matching
5265@code{line} attributes, but with different @code{pc} attributes. The
5266iterator is sorted in ascending @code{pc} order. Here is a small
5267example illustrating iterating over a line table.
5268
5269@smallexample
5270symtab = gdb.selected_frame().find_sal().symtab
5271linetable = symtab.linetable()
5272for line in linetable:
5273 print "Line: "+str(line.line)+" Address: "+hex(line.pc)
5274@end smallexample
5275
5276This will have the following output:
5277
5278@smallexample
5279Line: 33 Address: 0x4005c8L
5280Line: 37 Address: 0x4005caL
5281Line: 39 Address: 0x4005d2L
5282Line: 40 Address: 0x4005f8L
5283Line: 42 Address: 0x4005ffL
5284Line: 44 Address: 0x400608L
5285Line: 42 Address: 0x40060cL
5286Line: 45 Address: 0x400615L
5287@end smallexample
5288
5289In addition to being able to iterate over a @code{LineTable}, it also
5290has the following direct access methods:
5291
5292@defun LineTable.line (line)
5293Return a Python @code{Tuple} of @code{LineTableEntry} objects for any
697aa1b7
EZ
5294entries in the line table for the given @var{line}, which specifies
5295the source code line. If there are no entries for that source code
329baa95
DE
5296@var{line}, the Python @code{None} is returned.
5297@end defun
5298
5299@defun LineTable.has_line (line)
5300Return a Python @code{Boolean} indicating whether there is an entry in
5301the line table for this source line. Return @code{True} if an entry
5302is found, or @code{False} if not.
5303@end defun
5304
5305@defun LineTable.source_lines ()
5306Return a Python @code{List} of the source line numbers in the symbol
5307table. Only lines with executable code locations are returned. The
5308contents of the @code{List} will just be the source line entries
5309represented as Python @code{Long} values.
5310@end defun
5311
5312@node Breakpoints In Python
5313@subsubsection Manipulating breakpoints using Python
5314
5315@cindex breakpoints in python
5316@tindex gdb.Breakpoint
5317
5318Python code can manipulate breakpoints via the @code{gdb.Breakpoint}
5319class.
5320
0b982d68
SM
5321A breakpoint can be created using one of the two forms of the
5322@code{gdb.Breakpoint} constructor. The first one accepts a string
5323like one would pass to the @code{break}
5324(@pxref{Set Breaks,,Setting Breakpoints}) and @code{watch}
5325(@pxref{Set Watchpoints, , Setting Watchpoints}) commands, and can be used to
5326create both breakpoints and watchpoints. The second accepts separate Python
5327arguments similar to @ref{Explicit Locations}, and can only be used to create
5328breakpoints.
5329
b89641ba 5330@defun Breakpoint.__init__ (spec @r{[}, type @r{][}, wp_class @r{][}, internal @r{][}, temporary @r{][}, qualified @r{]})
0b982d68
SM
5331Create a new breakpoint according to @var{spec}, which is a string naming the
5332location of a breakpoint, or an expression that defines a watchpoint. The
5333string should describe a location in a format recognized by the @code{break}
5334command (@pxref{Set Breaks,,Setting Breakpoints}) or, in the case of a
5335watchpoint, by the @code{watch} command
5336(@pxref{Set Watchpoints, , Setting Watchpoints}).
5337
5338The optional @var{type} argument specifies the type of the breakpoint to create,
5339as defined below.
5340
5341The optional @var{wp_class} argument defines the class of watchpoint to create,
5342if @var{type} is @code{gdb.BP_WATCHPOINT}. If @var{wp_class} is omitted, it
5343defaults to @code{gdb.WP_WRITE}.
5344
5345The optional @var{internal} argument allows the breakpoint to become invisible
5346to the user. The breakpoint will neither be reported when created, nor will it
5347be listed in the output from @code{info breakpoints} (but will be listed with
5348the @code{maint info breakpoints} command).
5349
5350The optional @var{temporary} argument makes the breakpoint a temporary
5351breakpoint. Temporary breakpoints are deleted after they have been hit. Any
5352further access to the Python breakpoint after it has been hit will result in a
5353runtime error (as that breakpoint has now been automatically deleted).
b89641ba
SM
5354
5355The optional @var{qualified} argument is a boolean that allows interpreting
5356the function passed in @code{spec} as a fully-qualified name. It is equivalent
5357to @code{break}'s @code{-qualified} flag (@pxref{Linespec Locations} and
5358@ref{Explicit Locations}).
5359
0b982d68
SM
5360@end defun
5361
b89641ba 5362@defun Breakpoint.__init__ (@r{[} source @r{][}, function @r{][}, label @r{][}, line @r{]}, @r{][} internal @r{][}, temporary @r{][}, qualified @r{]})
0b982d68
SM
5363This second form of creating a new breakpoint specifies the explicit
5364location (@pxref{Explicit Locations}) using keywords. The new breakpoint will
5365be created in the specified source file @var{source}, at the specified
5366@var{function}, @var{label} and @var{line}.
5367
b89641ba
SM
5368@var{internal}, @var{temporary} and @var{qualified} have the same usage as
5369explained previously.
329baa95
DE
5370@end defun
5371
cda75e70
TT
5372The available types are represented by constants defined in the @code{gdb}
5373module:
5374
5375@vtable @code
5376@vindex BP_BREAKPOINT
5377@item gdb.BP_BREAKPOINT
5378Normal code breakpoint.
5379
5380@vindex BP_WATCHPOINT
5381@item gdb.BP_WATCHPOINT
5382Watchpoint breakpoint.
5383
5384@vindex BP_HARDWARE_WATCHPOINT
5385@item gdb.BP_HARDWARE_WATCHPOINT
5386Hardware assisted watchpoint.
5387
5388@vindex BP_READ_WATCHPOINT
5389@item gdb.BP_READ_WATCHPOINT
5390Hardware assisted read watchpoint.
5391
5392@vindex BP_ACCESS_WATCHPOINT
5393@item gdb.BP_ACCESS_WATCHPOINT
5394Hardware assisted access watchpoint.
5395@end vtable
5396
5397The available watchpoint types represented by constants are defined in the
5398@code{gdb} module:
5399
5400@vtable @code
5401@vindex WP_READ
5402@item gdb.WP_READ
5403Read only watchpoint.
5404
5405@vindex WP_WRITE
5406@item gdb.WP_WRITE
5407Write only watchpoint.
5408
5409@vindex WP_ACCESS
5410@item gdb.WP_ACCESS
5411Read/Write watchpoint.
5412@end vtable
5413
329baa95
DE
5414@defun Breakpoint.stop (self)
5415The @code{gdb.Breakpoint} class can be sub-classed and, in
5416particular, you may choose to implement the @code{stop} method.
5417If this method is defined in a sub-class of @code{gdb.Breakpoint},
5418it will be called when the inferior reaches any location of a
5419breakpoint which instantiates that sub-class. If the method returns
5420@code{True}, the inferior will be stopped at the location of the
5421breakpoint, otherwise the inferior will continue.
5422
5423If there are multiple breakpoints at the same location with a
5424@code{stop} method, each one will be called regardless of the
5425return status of the previous. This ensures that all @code{stop}
5426methods have a chance to execute at that location. In this scenario
5427if one of the methods returns @code{True} but the others return
5428@code{False}, the inferior will still be stopped.
5429
5430You should not alter the execution state of the inferior (i.e.@:, step,
5431next, etc.), alter the current frame context (i.e.@:, change the current
5432active frame), or alter, add or delete any breakpoint. As a general
5433rule, you should not alter any data within @value{GDBN} or the inferior
5434at this time.
5435
5436Example @code{stop} implementation:
5437
5438@smallexample
5439class MyBreakpoint (gdb.Breakpoint):
5440 def stop (self):
5441 inf_val = gdb.parse_and_eval("foo")
5442 if inf_val == 3:
5443 return True
5444 return False
5445@end smallexample
5446@end defun
5447
329baa95
DE
5448@defun Breakpoint.is_valid ()
5449Return @code{True} if this @code{Breakpoint} object is valid,
5450@code{False} otherwise. A @code{Breakpoint} object can become invalid
5451if the user deletes the breakpoint. In this case, the object still
5452exists, but the underlying breakpoint does not. In the cases of
5453watchpoint scope, the watchpoint remains valid even if execution of the
5454inferior leaves the scope of that watchpoint.
5455@end defun
5456
fab3a15d 5457@defun Breakpoint.delete ()
329baa95
DE
5458Permanently deletes the @value{GDBN} breakpoint. This also
5459invalidates the Python @code{Breakpoint} object. Any further access
5460to this object's attributes or methods will raise an error.
5461@end defun
5462
5463@defvar Breakpoint.enabled
5464This attribute is @code{True} if the breakpoint is enabled, and
fab3a15d
SM
5465@code{False} otherwise. This attribute is writable. You can use it to enable
5466or disable the breakpoint.
329baa95
DE
5467@end defvar
5468
5469@defvar Breakpoint.silent
5470This attribute is @code{True} if the breakpoint is silent, and
5471@code{False} otherwise. This attribute is writable.
5472
5473Note that a breakpoint can also be silent if it has commands and the
5474first command is @code{silent}. This is not reported by the
5475@code{silent} attribute.
5476@end defvar
5477
93daf339
TT
5478@defvar Breakpoint.pending
5479This attribute is @code{True} if the breakpoint is pending, and
5480@code{False} otherwise. @xref{Set Breaks}. This attribute is
5481read-only.
5482@end defvar
5483
22a02324 5484@anchor{python_breakpoint_thread}
329baa95 5485@defvar Breakpoint.thread
5d5658a1
PA
5486If the breakpoint is thread-specific, this attribute holds the
5487thread's global id. If the breakpoint is not thread-specific, this
5488attribute is @code{None}. This attribute is writable.
329baa95
DE
5489@end defvar
5490
5491@defvar Breakpoint.task
5492If the breakpoint is Ada task-specific, this attribute holds the Ada task
5493id. If the breakpoint is not task-specific (or the underlying
5494language is not Ada), this attribute is @code{None}. This attribute
5495is writable.
5496@end defvar
5497
5498@defvar Breakpoint.ignore_count
5499This attribute holds the ignore count for the breakpoint, an integer.
5500This attribute is writable.
5501@end defvar
5502
5503@defvar Breakpoint.number
5504This attribute holds the breakpoint's number --- the identifier used by
5505the user to manipulate the breakpoint. This attribute is not writable.
5506@end defvar
5507
5508@defvar Breakpoint.type
5509This attribute holds the breakpoint's type --- the identifier used to
5510determine the actual breakpoint type or use-case. This attribute is not
5511writable.
5512@end defvar
5513
5514@defvar Breakpoint.visible
5515This attribute tells whether the breakpoint is visible to the user
5516when set, or when the @samp{info breakpoints} command is run. This
5517attribute is not writable.
5518@end defvar
5519
5520@defvar Breakpoint.temporary
5521This attribute indicates whether the breakpoint was created as a
5522temporary breakpoint. Temporary breakpoints are automatically deleted
5523after that breakpoint has been hit. Access to this attribute, and all
5524other attributes and functions other than the @code{is_valid}
5525function, will result in an error after the breakpoint has been hit
5526(as it has been automatically deleted). This attribute is not
5527writable.
5528@end defvar
5529
329baa95
DE
5530@defvar Breakpoint.hit_count
5531This attribute holds the hit count for the breakpoint, an integer.
5532This attribute is writable, but currently it can only be set to zero.
5533@end defvar
5534
5535@defvar Breakpoint.location
5536This attribute holds the location of the breakpoint, as specified by
5537the user. It is a string. If the breakpoint does not have a location
5538(that is, it is a watchpoint) the attribute's value is @code{None}. This
5539attribute is not writable.
5540@end defvar
5541
5542@defvar Breakpoint.expression
5543This attribute holds a breakpoint expression, as specified by
5544the user. It is a string. If the breakpoint does not have an
5545expression (the breakpoint is not a watchpoint) the attribute's value
5546is @code{None}. This attribute is not writable.
5547@end defvar
5548
5549@defvar Breakpoint.condition
5550This attribute holds the condition of the breakpoint, as specified by
5551the user. It is a string. If there is no condition, this attribute's
5552value is @code{None}. This attribute is writable.
5553@end defvar
5554
5555@defvar Breakpoint.commands
5556This attribute holds the commands attached to the breakpoint. If
5557there are commands, this attribute's value is a string holding all the
5558commands, separated by newlines. If there are no commands, this
a913fffb 5559attribute is @code{None}. This attribute is writable.
329baa95
DE
5560@end defvar
5561
5562@node Finish Breakpoints in Python
5563@subsubsection Finish Breakpoints
5564
5565@cindex python finish breakpoints
5566@tindex gdb.FinishBreakpoint
5567
5568A finish breakpoint is a temporary breakpoint set at the return address of
5569a frame, based on the @code{finish} command. @code{gdb.FinishBreakpoint}
5570extends @code{gdb.Breakpoint}. The underlying breakpoint will be disabled
5571and deleted when the execution will run out of the breakpoint scope (i.e.@:
5572@code{Breakpoint.stop} or @code{FinishBreakpoint.out_of_scope} triggered).
5573Finish breakpoints are thread specific and must be create with the right
5574thread selected.
5575
5576@defun FinishBreakpoint.__init__ (@r{[}frame@r{]} @r{[}, internal@r{]})
5577Create a finish breakpoint at the return address of the @code{gdb.Frame}
5578object @var{frame}. If @var{frame} is not provided, this defaults to the
5579newest frame. The optional @var{internal} argument allows the breakpoint to
5580become invisible to the user. @xref{Breakpoints In Python}, for further
5581details about this argument.
5582@end defun
5583
5584@defun FinishBreakpoint.out_of_scope (self)
5585In some circumstances (e.g.@: @code{longjmp}, C@t{++} exceptions, @value{GDBN}
5586@code{return} command, @dots{}), a function may not properly terminate, and
5587thus never hit the finish breakpoint. When @value{GDBN} notices such a
5588situation, the @code{out_of_scope} callback will be triggered.
5589
5590You may want to sub-class @code{gdb.FinishBreakpoint} and override this
5591method:
5592
5593@smallexample
5594class MyFinishBreakpoint (gdb.FinishBreakpoint)
5595 def stop (self):
5596 print "normal finish"
5597 return True
5598
5599 def out_of_scope ():
5600 print "abnormal finish"
5601@end smallexample
5602@end defun
5603
5604@defvar FinishBreakpoint.return_value
5605When @value{GDBN} is stopped at a finish breakpoint and the frame
5606used to build the @code{gdb.FinishBreakpoint} object had debug symbols, this
5607attribute will contain a @code{gdb.Value} object corresponding to the return
5608value of the function. The value will be @code{None} if the function return
5609type is @code{void} or if the return value was not computable. This attribute
5610is not writable.
5611@end defvar
5612
5613@node Lazy Strings In Python
849cba3b 5614@subsubsection Python representation of lazy strings
329baa95
DE
5615
5616@cindex lazy strings in python
5617@tindex gdb.LazyString
5618
5619A @dfn{lazy string} is a string whose contents is not retrieved or
5620encoded until it is needed.
5621
5622A @code{gdb.LazyString} is represented in @value{GDBN} as an
5623@code{address} that points to a region of memory, an @code{encoding}
5624that will be used to encode that region of memory, and a @code{length}
5625to delimit the region of memory that represents the string. The
5626difference between a @code{gdb.LazyString} and a string wrapped within
5627a @code{gdb.Value} is that a @code{gdb.LazyString} will be treated
5628differently by @value{GDBN} when printing. A @code{gdb.LazyString} is
5629retrieved and encoded during printing, while a @code{gdb.Value}
5630wrapping a string is immediately retrieved and encoded on creation.
5631
5632A @code{gdb.LazyString} object has the following functions:
5633
5634@defun LazyString.value ()
5635Convert the @code{gdb.LazyString} to a @code{gdb.Value}. This value
5636will point to the string in memory, but will lose all the delayed
5637retrieval, encoding and handling that @value{GDBN} applies to a
5638@code{gdb.LazyString}.
5639@end defun
5640
5641@defvar LazyString.address
5642This attribute holds the address of the string. This attribute is not
5643writable.
5644@end defvar
5645
5646@defvar LazyString.length
5647This attribute holds the length of the string in characters. If the
5648length is -1, then the string will be fetched and encoded up to the
5649first null of appropriate width. This attribute is not writable.
5650@end defvar
5651
5652@defvar LazyString.encoding
5653This attribute holds the encoding that will be applied to the string
5654when the string is printed by @value{GDBN}. If the encoding is not
5655set, or contains an empty string, then @value{GDBN} will select the
5656most appropriate encoding when the string is printed. This attribute
5657is not writable.
5658@end defvar
5659
5660@defvar LazyString.type
5661This attribute holds the type that is represented by the lazy string's
f8d99587 5662type. For a lazy string this is a pointer or array type. To
329baa95
DE
5663resolve this to the lazy string's character type, use the type's
5664@code{target} method. @xref{Types In Python}. This attribute is not
5665writable.
5666@end defvar
5667
5668@node Architectures In Python
5669@subsubsection Python representation of architectures
5670@cindex Python architectures
5671
5672@value{GDBN} uses architecture specific parameters and artifacts in a
5673number of its various computations. An architecture is represented
5674by an instance of the @code{gdb.Architecture} class.
5675
5676A @code{gdb.Architecture} class has the following methods:
5677
5678@defun Architecture.name ()
5679Return the name (string value) of the architecture.
5680@end defun
5681
5682@defun Architecture.disassemble (@var{start_pc} @r{[}, @var{end_pc} @r{[}, @var{count}@r{]]})
5683Return a list of disassembled instructions starting from the memory
5684address @var{start_pc}. The optional arguments @var{end_pc} and
5685@var{count} determine the number of instructions in the returned list.
5686If both the optional arguments @var{end_pc} and @var{count} are
5687specified, then a list of at most @var{count} disassembled instructions
5688whose start address falls in the closed memory address interval from
5689@var{start_pc} to @var{end_pc} are returned. If @var{end_pc} is not
5690specified, but @var{count} is specified, then @var{count} number of
5691instructions starting from the address @var{start_pc} are returned. If
5692@var{count} is not specified but @var{end_pc} is specified, then all
5693instructions whose start address falls in the closed memory address
5694interval from @var{start_pc} to @var{end_pc} are returned. If neither
5695@var{end_pc} nor @var{count} are specified, then a single instruction at
5696@var{start_pc} is returned. For all of these cases, each element of the
5697returned list is a Python @code{dict} with the following string keys:
5698
5699@table @code
5700
5701@item addr
5702The value corresponding to this key is a Python long integer capturing
5703the memory address of the instruction.
5704
5705@item asm
5706The value corresponding to this key is a string value which represents
5707the instruction with assembly language mnemonics. The assembly
5708language flavor used is the same as that specified by the current CLI
5709variable @code{disassembly-flavor}. @xref{Machine Code}.
5710
5711@item length
5712The value corresponding to this key is the length (integer value) of the
5713instruction in bytes.
5714
5715@end table
5716@end defun
5717
01b1af32
TT
5718@node TUI Windows In Python
5719@subsubsection Implementing new TUI windows
5720@cindex Python TUI Windows
5721
5722New TUI (@pxref{TUI}) windows can be implemented in Python.
5723
5724@findex gdb.register_window_type
5725@defun gdb.register_window_type (@var{name}, @var{factory})
5726Because TUI windows are created and destroyed depending on the layout
5727the user chooses, new window types are implemented by registering a
5728factory function with @value{GDBN}.
5729
5730@var{name} is the name of the new window. It's an error to try to
5731replace one of the built-in windows, but other window types can be
5732replaced.
5733
5734@var{function} is a factory function that is called to create the TUI
5735window. This is called with a single argument of type
5736@code{gdb.TuiWindow}, described below. It should return an object
5737that implements the TUI window protocol, also described below.
5738@end defun
5739
5740As mentioned above, when a factory function is called, it is passed a
5741an object of type @code{gdb.TuiWindow}. This object has these
5742methods and attributes:
5743
5744@defun TuiWindow.is_valid ()
5745This method returns @code{True} when this window is valid. When the
5746user changes the TUI layout, windows no longer visible in the new
5747layout will be destroyed. At this point, the @code{gdb.TuiWindow}
5748will no longer be valid, and methods (and attributes) other than
5749@code{is_valid} will throw an exception.
5750@end defun
5751
5752@defvar TuiWindow.width
5753This attribute holds the width of the window. It is not writable.
5754@end defvar
5755
5756@defvar TuiWindow.height
5757This attribute holds the height of the window. It is not writable.
5758@end defvar
5759
5760@defvar TuiWindow.title
5761This attribute holds the window's title, a string. This is normally
5762displayed above the window. This attribute can be modified.
5763@end defvar
5764
5765@defun TuiWindow.erase ()
5766Remove all the contents of the window.
5767@end defun
5768
5769@defun TuiWindow.write (@var{string})
5770Write @var{string} to the window. @var{string} can contain ANSI
5771terminal escape styling sequences; @value{GDBN} will translate these
5772as appropriate for the terminal.
5773@end defun
5774
5775The factory function that you supply should return an object
5776conforming to the TUI window protocol. These are the method that can
5777be called on this object, which is referred to below as the ``window
5778object''. The methods documented below are optional; if the object
5779does not implement one of these methods, @value{GDBN} will not attempt
5780to call it. Additional new methods may be added to the window
5781protocol in the future. @value{GDBN} guarantees that they will begin
5782with a lower-case letter, so you can start implementation methods with
5783upper-case letters or underscore to avoid any future conflicts.
5784
5785@defun Window.close ()
5786When the TUI window is closed, the @code{gdb.TuiWindow} object will be
5787put into an invalid state. At this time, @value{GDBN} will call
5788@code{close} method on the window object.
5789
5790After this method is called, @value{GDBN} will discard any references
5791it holds on this window object, and will no longer call methods on
5792this object.
5793@end defun
5794
5795@defun Window.render ()
5796In some situations, a TUI window can change size. For example, this
5797can happen if the user resizes the terminal, or changes the layout.
5798When this happens, @value{GDBN} will call the @code{render} method on
5799the window object.
5800
5801If your window is intended to update in response to changes in the
5802inferior, you will probably also want to register event listeners and
5803send output to the @code{gdb.TuiWindow}.
5804@end defun
5805
5806@defun Window.hscroll (@var{num})
5807This is a request to scroll the window horizontally. @var{num} is the
5808amount by which to scroll, with negative numbers meaning to scroll
5809right. In the TUI model, it is the viewport that moves, not the
5810contents. A positive argument should cause the viewport to move
5811right, and so the content should appear to move to the left.
5812@end defun
5813
5814@defun Window.vscroll (@var{num})
5815This is a request to scroll the window vertically. @var{num} is the
5816amount by which to scroll, with negative numbers meaning to scroll
5817backward. In the TUI model, it is the viewport that moves, not the
5818contents. A positive argument should cause the viewport to move down,
5819and so the content should appear to move up.
5820@end defun
5821
329baa95
DE
5822@node Python Auto-loading
5823@subsection Python Auto-loading
5824@cindex Python auto-loading
5825
5826When a new object file is read (for example, due to the @code{file}
5827command, or because the inferior has loaded a shared library),
5828@value{GDBN} will look for Python support scripts in several ways:
5829@file{@var{objfile}-gdb.py} and @code{.debug_gdb_scripts} section.
5830@xref{Auto-loading extensions}.
5831
5832The auto-loading feature is useful for supplying application-specific
5833debugging commands and scripts.
5834
5835Auto-loading can be enabled or disabled,
5836and the list of auto-loaded scripts can be printed.
5837
5838@table @code
5839@anchor{set auto-load python-scripts}
5840@kindex set auto-load python-scripts
5841@item set auto-load python-scripts [on|off]
5842Enable or disable the auto-loading of Python scripts.
5843
5844@anchor{show auto-load python-scripts}
5845@kindex show auto-load python-scripts
5846@item show auto-load python-scripts
5847Show whether auto-loading of Python scripts is enabled or disabled.
5848
5849@anchor{info auto-load python-scripts}
5850@kindex info auto-load python-scripts
5851@cindex print list of auto-loaded Python scripts
5852@item info auto-load python-scripts [@var{regexp}]
5853Print the list of all Python scripts that @value{GDBN} auto-loaded.
5854
5855Also printed is the list of Python scripts that were mentioned in
9f050062
DE
5856the @code{.debug_gdb_scripts} section and were either not found
5857(@pxref{dotdebug_gdb_scripts section}) or were not auto-loaded due to
5858@code{auto-load safe-path} rejection (@pxref{Auto-loading}).
329baa95
DE
5859This is useful because their names are not printed when @value{GDBN}
5860tries to load them and fails. There may be many of them, and printing
5861an error message for each one is problematic.
5862
5863If @var{regexp} is supplied only Python scripts with matching names are printed.
5864
5865Example:
5866
5867@smallexample
5868(gdb) info auto-load python-scripts
5869Loaded Script
5870Yes py-section-script.py
5871 full name: /tmp/py-section-script.py
5872No my-foo-pretty-printers.py
5873@end smallexample
5874@end table
5875
9f050062 5876When reading an auto-loaded file or script, @value{GDBN} sets the
329baa95
DE
5877@dfn{current objfile}. This is available via the @code{gdb.current_objfile}
5878function (@pxref{Objfiles In Python}). This can be useful for
5879registering objfile-specific pretty-printers and frame-filters.
5880
5881@node Python modules
5882@subsection Python modules
5883@cindex python modules
5884
5885@value{GDBN} comes with several modules to assist writing Python code.
5886
5887@menu
5888* gdb.printing:: Building and registering pretty-printers.
5889* gdb.types:: Utilities for working with types.
5890* gdb.prompt:: Utilities for prompt value substitution.
5891@end menu
5892
5893@node gdb.printing
5894@subsubsection gdb.printing
5895@cindex gdb.printing
5896
5897This module provides a collection of utilities for working with
5898pretty-printers.
5899
5900@table @code
5901@item PrettyPrinter (@var{name}, @var{subprinters}=None)
5902This class specifies the API that makes @samp{info pretty-printer},
5903@samp{enable pretty-printer} and @samp{disable pretty-printer} work.
5904Pretty-printers should generally inherit from this class.
5905
5906@item SubPrettyPrinter (@var{name})
5907For printers that handle multiple types, this class specifies the
5908corresponding API for the subprinters.
5909
5910@item RegexpCollectionPrettyPrinter (@var{name})
5911Utility class for handling multiple printers, all recognized via
5912regular expressions.
5913@xref{Writing a Pretty-Printer}, for an example.
5914
5915@item FlagEnumerationPrinter (@var{name})
5916A pretty-printer which handles printing of @code{enum} values. Unlike
5917@value{GDBN}'s built-in @code{enum} printing, this printer attempts to
5918work properly when there is some overlap between the enumeration
697aa1b7
EZ
5919constants. The argument @var{name} is the name of the printer and
5920also the name of the @code{enum} type to look up.
329baa95
DE
5921
5922@item register_pretty_printer (@var{obj}, @var{printer}, @var{replace}=False)
5923Register @var{printer} with the pretty-printer list of @var{obj}.
5924If @var{replace} is @code{True} then any existing copy of the printer
5925is replaced. Otherwise a @code{RuntimeError} exception is raised
5926if a printer with the same name already exists.
5927@end table
5928
5929@node gdb.types
5930@subsubsection gdb.types
5931@cindex gdb.types
5932
5933This module provides a collection of utilities for working with
5934@code{gdb.Type} objects.
5935
5936@table @code
5937@item get_basic_type (@var{type})
5938Return @var{type} with const and volatile qualifiers stripped,
5939and with typedefs and C@t{++} references converted to the underlying type.
5940
5941C@t{++} example:
5942
5943@smallexample
5944typedef const int const_int;
5945const_int foo (3);
5946const_int& foo_ref (foo);
5947int main () @{ return 0; @}
5948@end smallexample
5949
5950Then in gdb:
5951
5952@smallexample
5953(gdb) start
5954(gdb) python import gdb.types
5955(gdb) python foo_ref = gdb.parse_and_eval("foo_ref")
5956(gdb) python print gdb.types.get_basic_type(foo_ref.type)
5957int
5958@end smallexample
5959
5960@item has_field (@var{type}, @var{field})
5961Return @code{True} if @var{type}, assumed to be a type with fields
5962(e.g., a structure or union), has field @var{field}.
5963
5964@item make_enum_dict (@var{enum_type})
5965Return a Python @code{dictionary} type produced from @var{enum_type}.
5966
5967@item deep_items (@var{type})
5968Returns a Python iterator similar to the standard
5969@code{gdb.Type.iteritems} method, except that the iterator returned
5970by @code{deep_items} will recursively traverse anonymous struct or
5971union fields. For example:
5972
5973@smallexample
5974struct A
5975@{
5976 int a;
5977 union @{
5978 int b0;
5979 int b1;
5980 @};
5981@};
5982@end smallexample
5983
5984@noindent
5985Then in @value{GDBN}:
5986@smallexample
5987(@value{GDBP}) python import gdb.types
5988(@value{GDBP}) python struct_a = gdb.lookup_type("struct A")
5989(@value{GDBP}) python print struct_a.keys ()
5990@{['a', '']@}
5991(@value{GDBP}) python print [k for k,v in gdb.types.deep_items(struct_a)]
5992@{['a', 'b0', 'b1']@}
5993@end smallexample
5994
5995@item get_type_recognizers ()
5996Return a list of the enabled type recognizers for the current context.
5997This is called by @value{GDBN} during the type-printing process
5998(@pxref{Type Printing API}).
5999
6000@item apply_type_recognizers (recognizers, type_obj)
6001Apply the type recognizers, @var{recognizers}, to the type object
6002@var{type_obj}. If any recognizer returns a string, return that
6003string. Otherwise, return @code{None}. This is called by
6004@value{GDBN} during the type-printing process (@pxref{Type Printing
6005API}).
6006
6007@item register_type_printer (locus, printer)
697aa1b7
EZ
6008This is a convenience function to register a type printer
6009@var{printer}. The printer must implement the type printer protocol.
6010The @var{locus} argument is either a @code{gdb.Objfile}, in which case
6011the printer is registered with that objfile; a @code{gdb.Progspace},
6012in which case the printer is registered with that progspace; or
6013@code{None}, in which case the printer is registered globally.
329baa95
DE
6014
6015@item TypePrinter
6016This is a base class that implements the type printer protocol. Type
6017printers are encouraged, but not required, to derive from this class.
6018It defines a constructor:
6019
6020@defmethod TypePrinter __init__ (self, name)
6021Initialize the type printer with the given name. The new printer
6022starts in the enabled state.
6023@end defmethod
6024
6025@end table
6026
6027@node gdb.prompt
6028@subsubsection gdb.prompt
6029@cindex gdb.prompt
6030
6031This module provides a method for prompt value-substitution.
6032
6033@table @code
6034@item substitute_prompt (@var{string})
6035Return @var{string} with escape sequences substituted by values. Some
6036escape sequences take arguments. You can specify arguments inside
6037``@{@}'' immediately following the escape sequence.
6038
6039The escape sequences you can pass to this function are:
6040
6041@table @code
6042@item \\
6043Substitute a backslash.
6044@item \e
6045Substitute an ESC character.
6046@item \f
6047Substitute the selected frame; an argument names a frame parameter.
6048@item \n
6049Substitute a newline.
6050@item \p
6051Substitute a parameter's value; the argument names the parameter.
6052@item \r
6053Substitute a carriage return.
6054@item \t
6055Substitute the selected thread; an argument names a thread parameter.
6056@item \v
6057Substitute the version of GDB.
6058@item \w
6059Substitute the current working directory.
6060@item \[
6061Begin a sequence of non-printing characters. These sequences are
6062typically used with the ESC character, and are not counted in the string
6063length. Example: ``\[\e[0;34m\](gdb)\[\e[0m\]'' will return a
6064blue-colored ``(gdb)'' prompt where the length is five.
6065@item \]
6066End a sequence of non-printing characters.
6067@end table
6068
6069For example:
6070
6071@smallexample
77bb17b6 6072substitute_prompt ("frame: \f, args: \p@{print frame-arguments@}")
329baa95
DE
6073@end smallexample
6074
6075@exdent will return the string:
6076
6077@smallexample
77bb17b6 6078"frame: main, args: scalars"
329baa95
DE
6079@end smallexample
6080@end table
This page took 0.832605 seconds and 4 git commands to generate.