Parameters In Python (Debugging with GDB)

23.3.2.24 Parameters In Python

You can implement new GDB parameters using Python. A new parameter is implemented as an instance of the gdb.Parameter class.

Parameters are exposed to the user via the set and show commands. See Help.

There are many parameters that already exist and can be set in GDB. Two examples are: set follow fork and set charset. Setting these parameters influences certain behavior in GDB. Similarly, you can define parameters that can be used to influence behavior in custom Python scripts and commands.

Function: Parameter.__init__ (name, command_class, parameter_class [, enum_sequence])

The object initializer for Parameter registers the new parameter with GDB. This initializer is normally invoked from the subclass’ own __init__ method.

name is the name of the new parameter. If name consists of multiple words, then the initial words are looked for as prefix parameters. An example of this can be illustrated with the set print set of parameters. If name is print foo, then print will be searched as the prefix parameter. In this case the parameter can subsequently be accessed in GDB as set print foo.

If name consists of multiple words, and no prefix parameter group can be found, an exception is raised.

command_class should be one of the ‘COMMAND_’ constants (see CLI Commands In Python). This argument tells GDB how to categorize the new parameter in the help system.

parameter_class should be one of the ‘PARAM_’ constants defined below. This argument tells GDB the type of the new parameter; this information is used for input validation and completion.

If parameter_class is PARAM_ENUM, then enum_sequence must be a sequence of strings. These strings represent the possible values for the parameter.

If parameter_class is not PARAM_ENUM, then the presence of a fourth argument will cause an exception to be thrown.

The help text for the new parameter includes the Python documentation string from the parameter’s class, if there is one. If there is no documentation string, a default value is used. The documentation string is included in the output of the parameters help set and help show commands, and should be written taking this into account. If the documentation string for the parameter’s class is the empty string then GDB will only use Parameter.set_doc or Parameter.show_doc (see below) in the help output.

Variable: Parameter.set_doc

If this attribute exists, and is a string, then its value is used as the first part of the help text for this parameter’s set command. The second part of the help text is taken from the documentation string for the parameter’s class, if there is one.

The value of set_doc should give a brief summary specific to the set action, this text is only displayed when the user runs the help set command for this parameter. The class documentation should be used to give a fuller description of what the parameter does, this text is displayed for both the help set and help show commands.

The set_doc value is examined when Parameter.__init__ is invoked; subsequent changes have no effect.

Variable: Parameter.show_doc

If this attribute exists, and is a string, then its value is used as the first part of the help text for this parameter’s show command. The second part of the help text is taken from the documentation string for the parameter’s class, if there is one.

The value of show_doc should give a brief summary specific to the show action, this text is only displayed when the user runs the help show command for this parameter. The class documentation should be used to give a fuller description of what the parameter does, this text is displayed for both the help set and help show commands.

The show_doc value is examined when Parameter.__init__ is invoked; subsequent changes have no effect.

Variable: Parameter.value: The value attribute holds the underlying value of the parameter. It can be read and assigned to just as any other attribute. GDB does validation when assignments are made.

There are two methods that may be implemented in any Parameter class. These are:

Function: Parameter.get_set_string (self)

If this method exists, GDB will call it when a parameter’s value has been changed via the set API (for example, set foo off). The value attribute has already been populated with the new value and may be used in output. This method must return a string. If the returned string is not empty, GDB will present it to the user.

If this method raises the gdb.GdbError exception (see Exception Handling), then GDB will print the exception’s string and the set command will fail. Note, however, that the value attribute will not be reset in this case. So, if your parameter must validate values, it should store the old value internally and reset the exposed value, like so:

class ExampleParam (gdb.Parameter):
   def __init__ (self, name):
      super (ExampleParam, self).__init__ (name,
                   gdb.COMMAND_DATA,
                   gdb.PARAM_BOOLEAN)
      self.value = True
      self.saved_value = True
   def validate(self):
      return False
   def get_set_string (self):
      if not self.validate():
        self.value = self.saved_value
        raise gdb.GdbError('Failed to validate')
      self.saved_value = self.value
      return ""

Function: Parameter.get_show_string (self, svalue): GDB will call this method when a parameter’s show API has been invoked (for example, show foo). The argument svalue receives the string representation of the current value. This method must return a string.

When a new parameter is defined, its type must be specified. The available types are represented by constants defined in the gdb module:

gdb.PARAM_BOOLEAN: The value is a plain boolean. The Python boolean values, True and False are the only valid values.
gdb.PARAM_AUTO_BOOLEAN: The value has three possible states: true, false, and ‘auto’. In Python, true and false are represented using boolean constants, and ‘auto’ is represented using None.
gdb.PARAM_UINTEGER: The value is an unsigned integer. The value of None should be interpreted to mean “unlimited” (literal 'unlimited' can also be used to set that value), and the value of 0 is reserved and should not be used.
gdb.PARAM_INTEGER: The value is a signed integer. The value of None should be interpreted to mean “unlimited” (literal 'unlimited' can also be used to set that value), and the value of 0 is reserved and should not be used.
gdb.PARAM_STRING: The value is a string. When the user modifies the string, any escape sequences, such as ‘\t’, ‘\f’, and octal escapes, are translated into corresponding characters and encoded into the current host charset.
gdb.PARAM_STRING_NOESCAPE: The value is a string. When the user modifies the string, escapes are passed through untranslated.
gdb.PARAM_OPTIONAL_FILENAME: The value is a either a filename (a string), or None.
gdb.PARAM_FILENAME: The value is a filename. This is just like PARAM_STRING_NOESCAPE, but uses file names for completion.
gdb.PARAM_ZINTEGER: The value is a signed integer. This is like PARAM_INTEGER, except that 0 is allowed and the value of None is not supported.
gdb.PARAM_ZUINTEGER: The value is an unsigned integer. This is like PARAM_UINTEGER, except that 0 is allowed and the value of None is not supported.
gdb.PARAM_ZUINTEGER_UNLIMITED: The value is a signed integer. This is like PARAM_INTEGER including that the value of None should be interpreted to mean “unlimited” (literal 'unlimited' can also be used to set that value), except that 0 is allowed, and the value cannot be negative, except the special value -1 is returned for the setting of “unlimited”.
gdb.PARAM_ENUM: The value is a string, which must be one of a collection string constants provided when the parameter is created.
gdb.PARAM_COLOR: The value is gdb.Color instance.

When creating multiple new parameters using gdb.Parameter, it is often desirable to create a prefix command that can be used to group related parameters together, for example, if you wished to add the parameters plugin-name feature-1 and plugin-name feature-2, then the plugin-name would need to be a prefix command (see CLI Commands In Python).

However, when creating parameters, you will almost always need to create two prefix commands, one as a set sub-command, and one as a show sub-command. GDB provides the gdb.ParameterPrefix helper class to make creation of these two prefixes easier.

Function: ParameterPrefix.__init__ (name, command_class, doc = None)

The object initializer for ParameterPrefix registers two new gdb.Command prefixes, one as a set sub-command, and the other as a show sub-command.

name, a string, is the name of the new prefix, without either set or show, similar to the name passed to gdb.Parameter (see Parameters In Python). For example, to create the prefixes set plugin-name and show plugin-name, you would pass the string plugin-name.

command_class should be one of the ‘COMMAND_’ constants (see CLI Commands In Python). This argument tells GDB how to categorize the new parameter prefixes in the help system.

There are a number of ways in which the help text for the two new prefix commands can be provided. If the doc parameter is not None, then this will be used as the documentation string for both prefix commands.

If doc is None, but gdb.ParameterPrefix has been sub-classed, then the prefix command documentation will be taken from sub-classes documentation string (i.e., the __doc__ attribute).

If doc is None, and there is no __doc__ string, then the default value ‘This command is not documented.’ is used.

When writing the help text, keep in mind that the same text is used for both the set and show prefix commands.

Function: ParameterPrefix.invoke_set (argument, from_tty)

If a sub-class defines this method, then GDB will call this when the prefix command is used with an unknown sub-command. The argument and from_tty parameters are the same as for gdb.Command.invoke (see Command.invoke).

If this method throws an exception, it is turned into a GDB error call. Otherwise, the return value is ignored.

It is not required that a ParameterPrefix sub-class override this method. Usually, a parameter prefix only exists as a means to group related parameters together. GDB handles this use case automatically with no need to implement invoke_set.

Function: ParameterPrefix.invoke_show (argument, from_tty): This is like the invoke_set method, but for the show prefix command. As with invoke_set, implementation of this method is optional, and usually not required.

Function: ParameterPrefix.dont_repeat (): Like Command.dont_repeat (see Command.dont_repeat), this can be called from ParameterPrefix.invoke_set or ParameterPrefix.invoke_show to prevent the prefix commands from being repeated.

Here is a small example that uses gdb.ParameterPrefix along with gdb.Parameter to create two new parameters plugin-name feature-1 and plugin-name feature-2. As neither invoke_set or invoke_show is needed, this example does not sub-class gdb.ParameterPrefix:

class ExampleParam(gdb.Parameter):
   def __init__ (self, name):
      super ().__init__ (name, gdb.COMMAND_DATA, gdb.PARAM_BOOLEAN)
      self.value = True

gdb.ParameterPrefix("plugin-name", gdb.COMMAND_NONE,
                    """An example parameter prefix.

                    This groups together some parameters.""")
ExampleParam("plugin-name feature-1")
ExampleParam("plugin-name feature-2")

The helper class gdb.StyleParameterSet exists to make it easier to create new styles. GDB places style settings under ‘show style …’ and ‘set style …’, an example of a style is ‘filename’. Each style is really a prefix command (see CLI Commands In Python), with sub-commands ‘foreground’, ‘background’, and optionally, ‘intensity’.

It is simple enough to create a new style using two gdb.Command objects for the prefix commands (one for ‘set’, and one for ‘show’), and three gdb.Parameter objects, one each for the ‘foreground’, ‘background’, and ‘intensity’. You would also want to take care to craft the help text so that the new style behaves the same as the existing styles.

Or, you can use the gdb.StyleParameterSet class, which takes care of all this, as the following example shows:

(gdb) python s = gdb.StyleParameterSet("my-style")
(gdb) show style my-style
style my-style background:  The "my-style" style background color is: none
style my-style foreground:  The "my-style" style foreground color is: none
style my-style intensity:  The "my-style" style display intensity is: normal
(gdb)

You might also want to group a number of styles within a new prefix, similar to how GDB groups disassembler related styles within the ‘style disassembler’ prefix. This can be done using gdb.ParameterPrefix (see gdb.ParameterPrefix), as in this example:

(gdb) python gdb.ParameterPrefix("style group", gdb.COMMAND_NONE)
(gdb) python s_a = gdb.StyleParameterSet("group aa")
(gdb) python s_b = gdb.StyleParameterSet("group bb")
(gdb) show style group
style group aa background:  The "group aa" style background color is: none
style group aa foreground:  The "group aa" style foreground color is: none
style group aa intensity:  The "group aa" style display intensity is: normal
style group bb background:  The "group bb" style background color is: none
style group bb foreground:  The "group bb" style foreground color is: none
style group bb intensity:  The "group bb" style display intensity is: normal
(gdb)

The gdb.StyleParameterSet class has the following methods and attributes:

Function: StyleParameterSet.__init__(name, add_intensity=True, doc=None)

Create a new style group based on name, which is a string. For example if name is ‘my-style’, then GDB will create the prefix commands ‘set style my-style’ and ‘show style my-style’. Within these prefix commands will be ‘foreground’, ‘background’, and ‘intensity’ parameters with the appropriate types.

It is also possible for name to consist of multiple words, so long as each prefix command (except the last one) already exists. For example, it is valid to use a name value of ‘disassembler my-style’, as the ‘disassembler’ prefix command already exists. GDB would then create ‘set style disassembler my-style’ and ‘show style disassembler my-style’, and within the ‘my-style’ prefixes will be the ‘foreground’, ‘background’, and ‘intensity’ parameters with the appropriate types.

Every style requires a ‘foreground’ and ‘background’, but not every style needs an ‘intensity’. If add_intensity is True (the default), then the ‘intensity’ parameter will be created. If add_intensity is False, then the ‘intensity’ parameter will not be created.

If the ‘intensity’ parameter is not created, then the gdb.Style (see Styles In Python) created from this gdb.StyleParameterSet will have gdb.INTENSITY_NORMAL.

The doc should be a string which will be used as the help text for the name prefix command. This text is used as the Command.__doc__ value for the gdb.Command object that is the prefix command object (see CLI Commands In Python). If doc is None (the default) then a basic default help text is used.

Function: StyleParameterSet.apply(string)

Equivalent to StyleParameterSet.style.apply(string). Returns a copy of string with escape sequences added to the start and end. The escape sequence at the start applies this style, and the escape sequence at the end restores the terminal default.

If styling is disabled (i.e. ‘set style enabled off’), then no escape sequences are added and this method returns a copy of string.

Variable: StyleParameterSet.style: This read/write attribute holds a gdb.Style object (see Styles In Python), that is a named style associated with this style parameter group.

Variable: StyleParameterSet.value: This is an alias for StyleParameterSet.style, see above.