Next: , Up: Python API   [Contents][Index]


23.3.2.1 Basic Python

At startup, GDB overrides Python’s sys.stdout and sys.stderr to print using GDB’s output-paging streams. A Python program which outputs to one of these streams may have its output interrupted by the user (see Screen Size). In this situation, a Python KeyboardInterrupt exception is thrown.

Some care must be taken when writing Python code to run in GDB. Two things worth noting in particular:

GDB introduces a new Python module, named gdb. All methods and classes added by GDB are placed in this module. GDB automatically imports the gdb module for use in all scripts evaluated by the python command.

Some types of the gdb module come with a textual representation (accessible through the repr or str functions). These are offered for debugging purposes only, expect them to change over time.

Variable: gdb.PYTHONDIR

A string containing the python directory (see Python).

Function: gdb.execute (command [, from_tty [, to_string]])

Evaluate command, a string, as a GDB CLI command. If a GDB exception happens while command runs, it is translated as described in Exception Handling.

The from_tty flag specifies whether GDB ought to consider this command as having originated from the user invoking it interactively. It must be a boolean value. If omitted, it defaults to False.

By default, any output produced by command is sent to GDB’s standard output (and to the log output if logging is turned on). If the to_string parameter is True, then output will be collected by gdb.execute and returned as a string. The default is False, in which case the return value is None. If to_string is True, the GDB virtual terminal will be temporarily set to unlimited width and height, and its pagination will be disabled; see Screen Size.

Function: gdb.breakpoints ()

Return a sequence holding all of GDB’s breakpoints. See Breakpoints In Python, for more information. In GDB version 7.11 and earlier, this function returned None if there were no breakpoints. This peculiarity was subsequently fixed, and now gdb.breakpoints returns an empty sequence in this case.

Function: gdb.rbreak (regex [, minsyms [, throttle, [, symtabs ]]])

Return a Python list holding a collection of newly set gdb.Breakpoint objects matching function names defined by the regex pattern. If the minsyms keyword is True, all system functions (those not explicitly defined in the inferior) will also be included in the match. The throttle keyword takes an integer that defines the maximum number of pattern matches for functions matched by the regex pattern. If the number of matches exceeds the integer value of throttle, a RuntimeError will be raised and no breakpoints will be created. If throttle is not defined then there is no imposed limit on the maximum number of matches and breakpoints to be created. The symtabs keyword takes a Python iterable that yields a collection of gdb.Symtab objects and will restrict the search to those functions only contained within the gdb.Symtab objects.

Function: gdb.parameter (parameter)

Return the value of a GDB parameter given by its name, a string; the parameter name string may contain spaces if the parameter has a multi-part name. For example, ‘print object’ is a valid parameter name.

If the named parameter does not exist, this function throws a gdb.error (see Exception Handling). Otherwise, the parameter’s value is converted to a Python value of the appropriate type, and returned.

Function: gdb.set_parameter (name, value)

Sets the gdb parameter name to value. As with gdb.parameter, the parameter name string may contain spaces if the parameter has a multi-part name.

Function: gdb.with_parameter (name, value)

Create a Python context manager (for use with the Python with statement) that temporarily sets the gdb parameter name to value. On exit from the context, the previous value will be restored.

This uses gdb.parameter in its implementation, so it can throw the same exceptions as that function.

For example, it’s sometimes useful to evaluate some Python code with a particular gdb language:

with gdb.with_parameter('language', 'pascal'):
  ... language-specific operations
Function: gdb.history (number)

Return a value from GDB’s value history (see Value History). The number argument indicates which history element to return. If number is negative, then GDB will take its absolute value and count backward from the last element (i.e., the most recent element) to find the value to return. If number is zero, then GDB will return the most recent element. If the element specified by number doesn’t exist in the value history, a gdb.error exception will be raised.

If no exception is raised, the return value is always an instance of gdb.Value (see Values From Inferior).

Function: gdb.add_history (value)

Takes value, an instance of gdb.Value (see Values From Inferior), and appends the value this object represents to GDB’s value history (see Value History), and return an integer, its history number. If value is not a gdb.Value, it is is converted using the gdb.Value constructor. If value can’t be converted to a gdb.Value then a TypeError is raised.

When a command implemented in Python prints a single gdb.Value as its result, then placing the value into the history will allow the user convenient access to those values via CLI history facilities.

Function: gdb.history_count ()

Return an integer indicating the number of values in GDB’s value history (see Value History).

Function: gdb.convenience_variable (name)

Return the value of the convenience variable (see Convenience Vars) named name. name must be a string. The name should not include the ‘$’ that is used to mark a convenience variable in an expression. If the convenience variable does not exist, then None is returned.

Function: gdb.set_convenience_variable (name, value)

Set the value of the convenience variable (see Convenience Vars) named name. name must be a string. The name should not include the ‘$’ that is used to mark a convenience variable in an expression. If value is None, then the convenience variable is removed. Otherwise, if value is not a gdb.Value (see Values From Inferior), it is is converted using the gdb.Value constructor.

Function: gdb.parse_and_eval (expression [, global_context])

Parse expression, which must be a string, as an expression in the current language, evaluate it, and return the result as a gdb.Value.

global_context, if provided, is a boolean indicating whether the parsing should be done in the global context. The default is ‘False’, meaning that the current frame or current static context should be used.

This function can be useful when implementing a new command (see CLI Commands In Python, see GDB/MI Commands In Python), as it provides a way to parse the command’s argument as an expression. It is also useful simply to compute values.

Function: gdb.find_pc_line (pc)

Return the gdb.Symtab_and_line object corresponding to the pc value. See Symbol Tables In Python. If an invalid value of pc is passed as an argument, then the symtab and line attributes of the returned gdb.Symtab_and_line object will be None and 0 respectively. This is identical to gdb.current_progspace().find_pc_line(pc) and is included for historical compatibility.

Function: gdb.write (string [, stream])

Print a string to GDB’s paginated output stream. The optional stream determines the stream to print to. The default stream is GDB’s standard output stream. Possible stream values are:

gdb.STDOUT

GDB’s standard output stream.

gdb.STDERR

GDB’s standard error stream.

gdb.STDLOG

GDB’s log stream (see Logging Output).

Writing to sys.stdout or sys.stderr will automatically call this function and will automatically direct the output to the relevant stream.

Function: gdb.flush ([, stream])

Flush the buffer of a GDB paginated stream so that the contents are displayed immediately. GDB will flush the contents of a stream automatically when it encounters a newline in the buffer. The optional stream determines the stream to flush. The default stream is GDB’s standard output stream. Possible stream values are:

gdb.STDOUT

GDB’s standard output stream.

gdb.STDERR

GDB’s standard error stream.

gdb.STDLOG

GDB’s log stream (see Logging Output).

Flushing sys.stdout or sys.stderr will automatically call this function for the relevant stream.

Function: gdb.target_charset ()

Return the name of the current target character set (see Character Sets). This differs from gdb.parameter('target-charset') in that ‘auto’ is never returned.

Function: gdb.target_wide_charset ()

Return the name of the current target wide character set (see Character Sets). This differs from gdb.parameter('target-wide-charset') in that ‘auto’ is never returned.

Function: gdb.host_charset ()

Return a string, the name of the current host character set (see Character Sets). This differs from gdb.parameter('host-charset') in that ‘auto’ is never returned.

Function: gdb.solib_name (address)

Return the name of the shared library holding the given address as a string, or None. This is identical to gdb.current_progspace().solib_name(address) and is included for historical compatibility.

Function: gdb.decode_line ([expression])

Return locations of the line specified by expression, or of the current line if no argument was given. This function returns a Python tuple containing two elements. The first element contains a string holding any unparsed section of expression (or None if the expression has been fully parsed). The second element contains either None or another tuple that contains all the locations that match the expression represented as gdb.Symtab_and_line objects (see Symbol Tables In Python). If expression is provided, it is decoded the way that GDB’s inbuilt break or edit commands do (see Location Specifications).

Function: gdb.prompt_hook (current_prompt)

If prompt_hook is callable, GDB will call the method assigned to this operation before a prompt is displayed by GDB.

The parameter current_prompt contains the current GDB prompt. This method must return a Python string, or None. If a string is returned, the GDB prompt will be set to that string. If None is returned, GDB will continue to use the current prompt.

Some prompts cannot be substituted in GDB. Secondary prompts such as those used by readline for command input, and annotation related prompts are prohibited from being changed.

Function: gdb.architecture_names ()

Return a list containing all of the architecture names that the current build of GDB supports. Each architecture name is a string. The names returned in this list are the same names as are returned from gdb.Architecture.name (see Architecture.name).

Function: gdb.connections

Return a list of gdb.TargetConnection objects, one for each currently active connection (see Connections In Python). The connection objects are in no particular order in the returned list.

Function: gdb.format_address (address [, progspace, architecture])

Return a string in the format ‘addr <symbol+offset>’, where addr is address formatted in hexadecimal, symbol is the symbol whose address is the nearest to address and below it in memory, and offset is the offset from symbol to address in decimal.

If no suitable symbol was found, then the <symbol+offset> part is not included in the returned string, instead the returned string will just contain the address formatted as hexadecimal. How far GDB looks back for a suitable symbol can be controlled with set print max-symbolic-offset (see Print Settings).

Additionally, the returned string can include file name and line number information when set print symbol-filename on (see Print Settings), in this case the format of the returned string is ‘addr <symbol+offset> at filename:line-number’.

The progspace is the gdb.Progspace in which symbol is looked up, and architecture is used when formatting addr, e.g. in order to determine the size of an address in bytes.

If neither progspace or architecture are passed, then by default GDB will use the program space and architecture of the currently selected inferior, thus, the following two calls are equivalent:

gdb.format_address(address)
gdb.format_address(address,
                   gdb.selected_inferior().progspace,
                   gdb.selected_inferior().architecture())

It is not valid to only pass one of progspace or architecture, either they must both be provided, or neither must be provided (and the defaults will be used).

This method uses the same mechanism for formatting address, symbol, and offset information as core GDB does in commands such as disassemble.

Here are some examples of the possible string formats:

0x00001042
0x00001042 <symbol+16>
0x00001042 <symbol+16 at file.c:123>
Function: gdb.current_language ()

Return the name of the current language as a string. Unlike gdb.parameter('language'), this function will never return ‘auto’. If a gdb.Frame object is available (see Frames In Python), the language method might be preferable in some cases, as that is not affected by the user’s language setting.


Next: , Up: Python API   [Contents][Index]