diff options
Diffstat (limited to 'gdb/doc/python.texi')
| -rw-r--r-- | gdb/doc/python.texi | 629 |
1 files changed, 572 insertions, 57 deletions
diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index 50342bb..ed11317 100644 --- a/gdb/doc/python.texi +++ b/gdb/doc/python.texi @@ -5,7 +5,7 @@ @c Invariant Sections being ``Free Software'' and ``Free Software Needs @c Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' @c and with the Back-Cover Texts as in (a) below. -@c +@c @c (a) The FSF's Back-Cover Text is: ``You are free to copy and modify @c this GNU Manual. Buying copies from GNU Press supports the FSF in @c developing GNU and promoting software freedom.'' @@ -226,6 +226,7 @@ optional arguments while skipping others. Example: using Python. * Lazy Strings In Python:: Python representation of lazy strings. * Colors In Python:: Python representation of colors. +* Styles In Python:: Python representation of styles. * Architectures In Python:: Python representation of architectures. * Registers In Python:: Python representation of registers. * Connections In Python:: Python representation of connections. @@ -233,6 +234,7 @@ optional arguments while skipping others. Example: * Disassembly In Python:: Instruction Disassembly In Python * Missing Debug Info In Python:: Handle missing debug info from Python. * Missing Objfiles In Python:: Handle objfiles from Python. +* Core Files In Python:: Python representation of core files. @end menu @node Basic Python @@ -257,7 +259,7 @@ Python code must not override these, or even change the options using signals, @value{GDBN} will most likely stop working correctly. Note that it is unfortunately common for GUI toolkits to install a @code{SIGCHLD} handler. When creating a new Python thread, you can -use @code{gdb.block_signals} or @code{gdb.Thread} to handle this +use @code{gdb.blocked_signals} or @code{gdb.Thread} to handle this correctly; see @ref{Threading in GDB}. @item @@ -451,7 +453,7 @@ will be @code{None} and 0 respectively. This is identical to historical compatibility. @end defun -@defun gdb.write (string @r{[}, stream@r{]}) +@defun gdb.write (string @r{[}, stream@r{]} @r{[}, style@r{]}) Print a string to @value{GDBN}'s paginated output stream. The optional @var{stream} determines the stream to print to. The default stream is @value{GDBN}'s standard output stream. Possible stream @@ -474,18 +476,25 @@ values are: @value{GDBN}'s log stream (@pxref{Logging Output}). @end table +The @var{style} should be a @code{gdb.Style} object (@pxref{Styles In +Python}), or @code{None} (the default). If @var{style} is @code{None} +then the current style for @var{stream} will be applied to @var{text}. +If @var{style} is a @code{gdb.Style} object, then this style is +applied to @var{text}, after which the default output style is +restored. + Writing to @code{sys.stdout} or @code{sys.stderr} will automatically call this function and will automatically direct the output to the relevant stream. @end defun -@defun gdb.flush (@r{[}, stream@r{]}) +@defun gdb.flush (@r{[}stream@r{]}) Flush the buffer of a @value{GDBN} paginated stream so that the contents are displayed immediately. @value{GDBN} will flush the contents of a stream automatically when it encounters a newline in the buffer. The optional @var{stream} determines the stream to flush. The default stream is @value{GDBN}'s standard output stream. Possible -stream values are: +stream values are: @table @code @findex STDOUT @@ -509,6 +518,17 @@ Flushing @code{sys.stdout} or @code{sys.stderr} will automatically call this function for the relevant stream. @end defun +@defun gdb.warning (text) +Print a warning message to @value{GDBN}'s standard output stream. The +warning message is the warning prefix (@pxref{warning-prefix}), the +string @w{@samp{warning: }}, and then @var{text}, which must be a +non-empty string. + +Due to the warning prefix, @var{text} should not begin with a capital +letter (except for proper nouns), and @var{text} should end with a +period. +@end defun + @defun gdb.target_charset () Return the name of the current target character set (@pxref{Character Sets}). This differs from @code{gdb.parameter('target-charset')} in @@ -557,7 +577,7 @@ If @var{prompt_hook} is callable, @value{GDBN} will call the method assigned to this operation before a prompt is displayed by @value{GDBN}. -The parameter @code{current_prompt} contains the current @value{GDBN} +The parameter @code{current_prompt} contains the current @value{GDBN} prompt. This method must return a Python string, or @code{None}. If a string is returned, the @value{GDBN} prompt will be set to that string. If @code{None} is returned, @value{GDBN} will continue to use @@ -654,22 +674,22 @@ threads, you must be careful to only call @value{GDBN}-specific functions in the @value{GDBN} thread. @value{GDBN} provides some functions to help with this. -@defun gdb.block_signals () +@defun gdb.blocked_signals () As mentioned earlier (@pxref{Basic Python}), certain signals must be -delivered to the @value{GDBN} main thread. The @code{block_signals} +delivered to the @value{GDBN} main thread. The @code{blocked_signals} function returns a context manager that will block these signals on entry. This can be used when starting a new thread to ensure that the signals are blocked there, like: @smallexample -with gdb.block_signals(): +with gdb.blocked_signals(): start_new_thread() @end smallexample @end defun @deftp {class} gdb.Thread This is a subclass of Python's @code{threading.Thread} class. It -overrides the @code{start} method to call @code{block_signals}, making +overrides the @code{start} method to call @code{blocked_signals}, making this an easy-to-use drop-in replacement for creating threads that will work well in @value{GDBN}. @end deftp @@ -899,7 +919,26 @@ this attribute holds @code{None}. @cindex optimized out value in Python @defvar Value.is_optimized_out This read-only boolean attribute is true if the compiler optimized out -this value, thus it is not available for fetching from the inferior. +this value, or any part of this value, and thus it is not available +for fetching from the inferior. +@end defvar + +@cindex unavailable values in Python +@defvar Value.is_unavailable +This read-only boolean attribute is true if this value, or any part of +this value, is not available to @value{GDBN}. Where an optimized out +value has been removed from the program by the compiler, an +unavailable value does exist in the program, but @value{GDBN} is +unable to fetch it. + +Some reasons why this might occur include, but are not limited to: a +core file format that @value{GDBN} doesn't fully understand; during +live debugging if the debug API has no mechanism to access the +required state, e.g.@: the kernel gives an error when trying to read a +particular register set; or reading a value from @value{GDBN}'s +history, when only a partial value was stored, e.g.@: due to the +@kbd{max-value-size} setting (@pxref{set +max-value-size,,max-value-size}). @end defvar @defvar Value.type @@ -925,17 +964,17 @@ it will just return the static type of the value as in @kbd{ptype foo} @defvar Value.is_lazy The value of this read-only boolean attribute is @code{True} if this -@code{gdb.Value} has not yet been fetched from the inferior. -@value{GDBN} does not fetch values until necessary, for efficiency. +@code{gdb.Value} has not yet been fetched from the inferior. +@value{GDBN} does not fetch values until necessary, for efficiency. For example: @smallexample myval = gdb.parse_and_eval ('somevar') @end smallexample -The value of @code{somevar} is not fetched at this time. It will be +The value of @code{somevar} is not fetched at this time. It will be fetched when the value is needed, or when the @code{fetch_lazy} -method is invoked. +method is invoked. @end defvar @defvar Value.bytes @@ -1313,7 +1352,7 @@ and encoded until a null of appropriate width is found. @end defun @defun Value.fetch_lazy () -If the @code{gdb.Value} object is currently a lazy value +If the @code{gdb.Value} object is currently a lazy value (@code{gdb.Value.is_lazy} is @code{True}), then the value is fetched from the inferior. Any errors that occur in the process will produce a Python exception. @@ -3357,27 +3396,27 @@ defined as follows: class MyClass_geta(gdb.xmethod.XMethod): def __init__(self): gdb.xmethod.XMethod.__init__(self, 'geta') - + def get_worker(self, method_name): if method_name == 'geta': return MyClassWorker_geta() - - + + class MyClass_sum(gdb.xmethod.XMethod): def __init__(self): gdb.xmethod.XMethod.__init__(self, 'sum') - + def get_worker(self, method_name): if method_name == 'operator+': return MyClassWorker_plus() - - + + class MyClassMatcher(gdb.xmethod.XMethodMatcher): def __init__(self): gdb.xmethod.XMethodMatcher.__init__(self, 'MyClassMatcher') # List of methods 'managed' by this matcher self.methods = [MyClass_geta(), MyClass_sum()] - + def match(self, class_type, method_name): if class_type.tag != 'MyClass': return None @@ -3387,7 +3426,7 @@ class MyClassMatcher(gdb.xmethod.XMethodMatcher): worker = method.get_worker(method_name) if worker: workers.append(worker) - + return workers @end smallexample @@ -3415,18 +3454,18 @@ class MyClassWorker_geta(gdb.xmethod.XMethodWorker): def get_result_type(self, obj): return gdb.lookup_type('int') - + def __call__(self, obj): return obj['a_'] - - + + class MyClassWorker_plus(gdb.xmethod.XMethodWorker): def get_arg_types(self): return gdb.lookup_type('MyClass') def get_result_type(self, obj): return gdb.lookup_type('int') - + def __call__(self, obj, other): return obj['a_'] + other['a_'] @end smallexample @@ -3469,12 +3508,12 @@ class MyTemplate public: MyTemplate () : dsize_(10), data_ (new T [10]) @{ @} ~MyTemplate () @{ delete [] data_; @} - + int footprint (void) @{ return sizeof (T) * dsize_ + sizeof (MyTemplate<T>); @} - + private: int dsize_; T *data_; @@ -3500,12 +3539,12 @@ class MyTemplateWorker_footprint(gdb.xmethod.XMethodWorker): return (self.class_type.sizeof + obj['dsize_'] * self.class_type.template_argument(0).sizeof) - - + + class MyTemplateMatcher_footprint(gdb.xmethod.XMethodMatcher): def __init__(self): gdb.xmethod.XMethodMatcher.__init__(self, 'MyTemplateMatcher') - + def match(self, class_type, method_name): if (re.match('MyTemplate<[ \t\n]*[_a-zA-Z][ _a-zA-Z0-9]*>', class_type.tag) and @@ -3596,6 +3635,15 @@ necessary quoting for the shell; when a sequence is assigned, the quoting is applied by @value{GDBN}. @end defvar +@defvar Inferior.corefile +If a core file has been loaded into this inferior (@pxref{core-file +command}), then this contains a @code{gdb.Corefile} object that +represents the loaded core file (@pxref{Core Files In Python}). + +If no core file has been loaded into this inferior, then this +attribute contains @code{None}. +@end defvar + A @code{gdb.Inferior} object has the following methods: @defun Inferior.is_valid () @@ -3797,7 +3845,7 @@ Emits @code{events.ExitedEvent}, which indicates that the inferior has exited. @code{events.ExitedEvent} has two attributes: @defvar ExitedEvent.exit_code -An integer representing the exit code, if available, which the inferior +An integer representing the exit code, if available, which the inferior has returned. (The exit code could be unavailable if, for example, @value{GDBN} detaches from the inferior.) If the exit code is unavailable, the attribute does not exist. @@ -3852,7 +3900,7 @@ Also emits @code{gdb.BreakpointEvent}, which extends been hit, and has the following attributes: @defvar BreakpointEvent.breakpoints -A sequence containing references to all the breakpoints (type +A sequence containing references to all the breakpoints (type @code{gdb.Breakpoint}) that were hit. @xref{Breakpoints In Python}, for details of the @code{gdb.Breakpoint} object. @end defvar @@ -4525,6 +4573,7 @@ You can implement new @value{GDBN} CLI commands in Python. A CLI command is implemented using an instance of the @code{gdb.Command} class, most commonly using a subclass. +@anchor{Command.__init__} @defun Command.__init__ (name, command_class @r{[}, completer_class @r{[}, prefix@r{]]}) The object initializer for @code{Command} registers the new command with @value{GDBN}. This initializer is normally invoked from the @@ -4554,10 +4603,11 @@ registered. The help text for the new command is taken from the Python documentation string for the command's class, if there is one. If no -documentation string is provided, the default value ``This command is -not documented.'' is used. +documentation string is provided, the default value @samp{This command +is not documented.} is used. @end defun +@anchor{Command.dont_repeat} @cindex don't repeat Python command @defun Command.dont_repeat () By default, a @value{GDBN} command is repeated when the user enters a @@ -4568,6 +4618,7 @@ exception). This is similar to the user command @code{dont-repeat}, see @ref{Define, dont-repeat}. @end defun +@anchor{Command.invoke} @defun Command.invoke (argument, from_tty) This method is called by @value{GDBN} when this command is invoked. @@ -4581,6 +4632,17 @@ that the command came from elsewhere. If this method throws an exception, it is turned into a @value{GDBN} @code{error} call. Otherwise, the return value is ignored. +For non-prefix commands (@pxref{Command.__init__}), the @code{invoke} +method is required. For prefix commands the @code{invoke} method is +optional. Only prefix commands that need to handle unknown +sub-commands should implement the @code{invoke} method. + +For prefix commands that don't implement @code{invoke}, if the prefix +command is used without a sub-command name then @value{GDBN} will +display the help text for every sub-command, unless the prefix command +is a @kbd{show} sub-command, in which case @value{GDBN} will list the +values of all sub-commands. + @findex gdb.string_to_argv To break @var{argument} up into an argv-like string use @code{gdb.string_to_argv}. This function behaves identically to @@ -5079,7 +5141,9 @@ 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 @code{help set} and @code{help show} commands, and should be written taking this into -account. +account. If the documentation string for the parameter's class is the +empty string then @value{GDBN} will only use @code{Parameter.set_doc} +or @code{Parameter.show_doc} (see below) in the @kbd{help} output. @end defun @defvar Parameter.set_doc @@ -5258,6 +5322,211 @@ constants provided when the parameter is created. The value is @code{gdb.Color} instance. @end table +When creating multiple new parameters using @code{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 @kbd{plugin-name feature-1} and @kbd{plugin-name +feature-2}, then the @kbd{plugin-name} would need to be a prefix +command (@pxref{CLI Commands In Python}). + +@anchor{gdb.ParameterPrefix} +However, when creating parameters, you will almost always need to +create two prefix commands, one as a @kbd{set} sub-command, and one as +a @kbd{show} sub-command. @value{GDBN} provides the +@code{gdb.ParameterPrefix} helper class to make creation of these two +prefixes easier. + +@defun ParameterPrefix.__init__ (name, command_class, doc = @code{None}) +The object initializer for @code{ParameterPrefix} registers two new +@code{gdb.Command} prefixes, one as a @kbd{set} sub-command, and the +other as a @kbd{show} sub-command. + +@var{name}, a string, is the name of the new prefix, without either +@kbd{set} or @kbd{show}, similar to the @var{name} passed to +@code{gdb.Parameter} (@pxref{Parameters In Python}). For example, to +create the prefixes @kbd{set plugin-name} and @kbd{show plugin-name}, +you would pass the string @kbd{plugin-name}. + +@var{command_class} should be one of the @samp{COMMAND_} constants +(@pxref{CLI Commands In Python}). This argument tells @value{GDBN} 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 @var{doc} parameter is not +@code{None}, then this will be used as the documentation string for +both prefix commands. + +If @var{doc} is @code{None}, but @code{gdb.ParameterPrefix} has been +sub-classed, then the prefix command documentation will be taken from +sub-classes documentation string (i.e., the @code{__doc__} attribute). + +If @var{doc} is @code{None}, and there is no @code{__doc__} string, +then the default value @samp{This command is not documented.} is used. + +When writing the help text, keep in mind that the same text is used +for both the @kbd{set} and @kbd{show} prefix commands. +@end defun + +@defun ParameterPrefix.invoke_set (argument, from_tty) +If a sub-class defines this method, then @value{GDBN} will call this +when the prefix command is used with an unknown sub-command. The +@var{argument} and @var{from_tty} parameters are the same as for +@code{gdb.Command.invoke} (@pxref{Command.invoke}). + +If this method throws an exception, it is turned into a @value{GDBN} +@code{error} call. Otherwise, the return value is ignored. + +It is not required that a @code{ParameterPrefix} sub-class override +this method. Usually, a parameter prefix only exists as a means to +group related parameters together. @value{GDBN} handles this use case +automatically with no need to implement @code{invoke_set}. +@end defun + +@defun ParameterPrefix.invoke_show (argument, from_tty) +This is like the @code{invoke_set} method, but for the @kbd{show} +prefix command. As with @code{invoke_set}, implementation of this +method is optional, and usually not required. +@end defun + +@cindex don't repeat Python command +@defun ParameterPrefix.dont_repeat () +Like @code{Command.dont_repeat} (@pxref{Command.dont_repeat}), this +can be called from @code{ParameterPrefix.invoke_set} or +@code{ParameterPrefix.invoke_show} to prevent the prefix commands from +being repeated. +@end defun + +Here is a small example that uses @code{gdb.ParameterPrefix} along +with @code{gdb.Parameter} to create two new parameters +@kbd{plugin-name feature-1} and @kbd{plugin-name feature-2}. As +neither @code{invoke_set} or @code{invoke_show} is needed, this +example does not sub-class @code{gdb.ParameterPrefix}: + +@smallexample +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") +@end smallexample + +@anchor{Creating Style Parameters} +The helper class @code{gdb.StyleParameterSet} exists to make it easier +to create new styles. @value{GDBN} places style settings under +@samp{show style @dots{}} and @samp{set style @dots{}}, an example of a style +is @samp{filename}. Each style is really a prefix command (@pxref{CLI +Commands In Python}), with sub-commands @samp{foreground}, +@samp{background}, and optionally, @samp{intensity}. + +It is simple enough to create a new style using two @code{gdb.Command} +objects for the prefix commands (one for @samp{set}, and one for +@samp{show}), and three @code{gdb.Parameter} objects, one each for the +@samp{foreground}, @samp{background}, and @samp{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 @code{gdb.StyleParameterSet} class, which takes +care of all this, as the following example shows: + +@smallexample +@group +(@value{GDBP}) python s = gdb.StyleParameterSet("my-style") +(@value{GDBP}) 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 +(@value{GDBP}) +@end group +@end smallexample + +You might also want to group a number of styles within a new prefix, +similar to how @value{GDBN} groups disassembler related styles within +the @samp{style disassembler} prefix. This can be done using +@code{gdb.ParameterPrefix} (@pxref{gdb.ParameterPrefix}), as in this +example: + +@smallexample +@group +(@value{GDBP}) python gdb.ParameterPrefix("style group", gdb.COMMAND_NONE) +(@value{GDBP}) python s_a = gdb.StyleParameterSet("group aa") +(@value{GDBP}) python s_b = gdb.StyleParameterSet("group bb") +(@value{GDBP}) 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 +(@value{GDBP}) +@end group +@end smallexample + +The @code{gdb.StyleParameterSet} class has the following methods and +attributes: + +@defun StyleParameterSet.__init__(name, @w{add_intensity=@code{True}}, @w{doc=@code{None}}) +Create a new style group based on @var{name}, which is a string. For +example if @var{name} is @samp{my-style}, then @value{GDBN} will +create the prefix commands @samp{set style my-style} and @samp{show +style my-style}. Within these prefix commands will be +@samp{foreground}, @samp{background}, and @samp{intensity} parameters +with the appropriate types. + +It is also possible for @var{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 @var{name} value of @samp{disassembler +my-style}, as the @samp{disassembler} prefix command already exists. +@value{GDBN} would then create @samp{set style disassembler my-style} +and @samp{show style disassembler my-style}, and within the +@samp{my-style} prefixes will be the @samp{foreground}, +@samp{background}, and @samp{intensity} parameters with the +appropriate types. + +Every style requires a @samp{foreground} and @samp{background}, but +not every style needs an @samp{intensity}. If @var{add_intensity} is +@code{True} (the default), then the @samp{intensity} parameter will be +created. If @var{add_intensity} is @code{False}, then the +@samp{intensity} parameter will not be created. + +If the @samp{intensity} parameter is not created, then the +@code{gdb.Style} (@pxref{Styles In Python}) created from this +@code{gdb.StyleParameterSet} will have @code{gdb.INTENSITY_NORMAL}. + +The @var{doc} should be a string which will be used as the help text +for the @var{name} prefix command. This text is used as the +@code{Command.__doc__} value for the @code{gdb.Command} object that is +the prefix command object (@pxref{CLI Commands In Python}). If +@var{doc} is @code{None} (the default) then a basic default help text +is used. +@end defun + +@defun StyleParameterSet.apply(string) +Equivalent to @code{StyleParameterSet.style.apply(string)}. Returns a +copy of @var{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.@: @samp{set style enabled off}), then no +escape sequences are added and this method returns a copy of +@var{string}. +@end defun + +@defvar StyleParameterSet.style +This read/write attribute holds a @code{gdb.Style} object +(@pxref{Styles In Python}), that is a named style associated with this +style parameter group. +@end defvar + +@defvar StyleParameterSet.value +This is an alias for @code{StyleParameterSet.style}, see above. +@end defvar + @node Functions In Python @subsubsection Writing new convenience functions @@ -5808,7 +6077,7 @@ compatibility. This frame is the outermost. @item gdb.FRAME_UNWIND_UNAVAILABLE -Cannot unwind further, because that would require knowing the +Cannot unwind further, because that would require knowing the values of registers or memory that have not been collected. @item gdb.FRAME_UNWIND_INNER_ID @@ -6944,22 +7213,22 @@ is not writable. A finish breakpoint is a temporary breakpoint set at the return address of a frame, based on the @code{finish} command. @code{gdb.FinishBreakpoint} -extends @code{gdb.Breakpoint}. The underlying breakpoint will be disabled -and deleted when the execution will run out of the breakpoint scope (i.e.@: +extends @code{gdb.Breakpoint}. The underlying breakpoint will be disabled +and deleted when the execution will run out of the breakpoint scope (i.e.@: @code{Breakpoint.stop} or @code{FinishBreakpoint.out_of_scope} triggered). -Finish breakpoints are thread specific and must be create with the right -thread selected. - +Finish breakpoints are thread specific and must be create with the right +thread selected. + @defun FinishBreakpoint.__init__ (@r{[}frame@r{]} @r{[}, internal@r{]}) Create a finish breakpoint at the return address of the @code{gdb.Frame} object @var{frame}. If @var{frame} is not provided, this defaults to the newest frame. The optional @var{internal} argument allows the breakpoint to -become invisible to the user. @xref{Breakpoints In Python}, for further +become invisible to the user. @xref{Breakpoints In Python}, for further details about this argument. @end defun @defun FinishBreakpoint.out_of_scope (self) -In some circumstances (e.g.@: @code{longjmp}, C@t{++} exceptions, @value{GDBN} +In some circumstances (e.g.@: @code{longjmp}, C@t{++} exceptions, @value{GDBN} @code{return} command, @dots{}), a function may not properly terminate, and thus never hit the finish breakpoint. When @value{GDBN} notices such a situation, the @code{out_of_scope} callback will be triggered. @@ -6972,17 +7241,17 @@ class MyFinishBreakpoint (gdb.FinishBreakpoint) def stop (self): print ("normal finish") return True - + def out_of_scope (): print ("abnormal finish") -@end smallexample +@end smallexample @end defun @defvar FinishBreakpoint.return_value -When @value{GDBN} is stopped at a finish breakpoint and the frame +When @value{GDBN} is stopped at a finish breakpoint and the frame used to build the @code{gdb.FinishBreakpoint} object had debug symbols, this attribute will contain a @code{gdb.Value} object corresponding to the return -value of the function. The value will be @code{None} if the function return +value of the function. The value will be @code{None} if the function return type is @code{void} or if the return value was not computable. This attribute is not writable. @end defvar @@ -7049,13 +7318,13 @@ writable. @cindex colors in python @tindex gdb.Color -You can assign instance of @code{Color} to the @code{value} of +You can assign instance of @code{gdb.Color} to the @code{value} of a @code{Parameter} instance created with @code{PARAM_COLOR}. -@code{Color} may refer to an index from color palette or contain components -of a color from some colorspace. +@code{gdb.Color} may refer to an index from a color palette or contain +components of a color from some color space. -@defun Color.__init__ (@r{[}@var{value} @r{[}, @var{color-space}@r{]}@r{]}) +@defun Color.__init__ (@r{[}value @r{[}, color_space@r{]}@r{]}) @var{value} is @code{None} (meaning the terminal's default color), an integer index of a color in palette, tuple with color components @@ -7065,8 +7334,9 @@ or one of the following color names: @samp{green}, @samp{yellow}, @samp{blue}, @samp{magenta}, @samp{cyan}, or @samp{white}. -@var{color-space} should be one of the @samp{COLORSPACE_} constants. This -argument tells @value{GDBN} which color space @var{value} belongs. +@var{color_space} should be one of the @samp{COLORSPACE_} constants +listed below. This argument tells @value{GDBN} which color space +@var{value} belongs. @end defun @defvar Color.is_none @@ -7094,12 +7364,15 @@ This attribute exist if @code{is_direct} is @code{True}. Its value is tuple with integer components of a color. @end defvar -@defun Color.escape_sequence (@var{self}, @var{is_foreground}) +@defun Color.escape_sequence (is_foreground) Returns string to change terminal's color to this. If @var{is_foreground} is @code{True}, then the returned sequence will change foreground color. Otherwise, the returned sequence will change background color. + +If styling is currently disabled (@pxref{Output Styling,,@kbd{set style +enabled}}), then this method will return an empty string. @end defun When color is initialized, its color space must be specified. The @@ -7136,6 +7409,148 @@ Direct 24-bit RGB colors. @end table +It is not possible to sub-class the @code{Color} class. + +@node Styles In Python +@subsubsection Python representation of styles + +@cindex styles in python +@tindex gdb.Style + +A style object contains the foreground and background colors +(@pxref{Colors In Python}), along with an intensity, and can be used +to apply this styling to output produced from Python. + +@value{GDBN} has many styles builtin (@pxref{Output Styling}), and +style objects can be created that apply these builtin styles to Python +output. It is also possible to create new styles which can be used to +style Python output (@pxref{Creating Style Parameters}). + +The style class is called @code{gdb.Style}, and has the following +methods and attributes: + +@defun Style.__init__ (style_name) +Create a @code{gdb.Style} that represents a builtin named style. The +@var{style_name} must be a non-empty string that names a style that +exists as a setting in @value{GDBN} within @samp{set style @dots{}}. For +example, the string @samp{"filename"} can be used to create a +@code{gdb.Style} object representing the @samp{set style filename} +style. + +If @var{style_name} names an unknown style then a @code{RuntimeError} +exception is raised. +@end defun + +@defun Style.__init__ (foreground=@code{None}, background=@code{None}, intensity=gdb.INTENSITY_NORMAL) +Create a custom @code{gdb.Style}, manually specifying the three +individual components. All of the arguments are optional. By +default, if no arguments are given, then the default style will be +created, this will produce output with the default terminal foreground +and background colors, along with the normal level of intensity +(i.e.@: neither bold, nor dim). + +The @var{foreground} and @var{background} arguments should either be +@code{None}, in which case the terminal default colors are used, or a +@code{gdb.Color} object (@pxref{Colors In Python}). Any other object +type will result in a @code{TypeError} exception being raised. + +The @var{intensity} argument should be one of the intensity constants +defined below (@pxref{Style Intensities}). Passing a none integer +value results in a @code{TypeError} exception, and passing an invalid +constant results in a @code{ValueError} exception. +@end defun + +@defun Style.escape_sequence () +If styling is enabled (@pxref{Output Styling}, then this method +returns the string which is the terminal escape sequence necessary to +apply this @code{gdb.Style}. + +If styling is disabled then this method returns the empty string. + +If this is a named style, which for some reason can no longer be read, +then a @code{RuntimeError} exception is raised. +@end defun + +@defun Style.apply (string) +This method returns @var{string}, which must be a @code{str} object, +with an escape sequence at both the start, and at the end. The escape +sequence at the start applies this style, while the escape sequence at +the end applies the terminal's default style. + +The effect of this is that, printing the result of this method, will +print @var{string} with this style applied. Future output will be +printed with the terminal's default style. + +If styling is currently disabled (@pxref{Output Styling}), then +@code{Style.apply} just returns a copy of @var{string} with no escape +sequences added. + +If this is a named style, which for some reason can no longer be read, +then a @code{RuntimeError} exception is raised. +@end defun + +@defvar Style.foreground +This read/write attribute contains the @code{gdb.Color} object +representing this style's foreground color. Writing to this attribute +updates the style's foreground color. + +If the @code{gdb.Style} object was created using a named style (i.e.@: +using the single argument @var{style_name} @code{__init__} method), +then the underlying setting will be updated. + +For unnamed styles, only the @code{gdb.Style} object will change. +@end defvar + +@defvar Style.background +This read/write attribute contains the @code{gdb.Color} object +representing this style's background color. Writing to this attribute +updates the style's background color. + +If the @code{gdb.Style} object was created using a named style (i.e.@: +using the single argument @var{style_name} @code{__init__} method), +then the underlying setting will be updated. + +For unnamed styles, only the @code{gdb.Style} object will change. +@end defvar + +@defvar Style.intensity +This read/write attribute contains the intensity for this style, and +will be one of the constants defined below (@pxref{Style +Intensities}). Writing to this attribute updates the style's +intensity. + +It is also possible to write @code{None} to this attribute, this is +equivalent of writing @code{gdb.INTENSITY_NORMAL}. This attribute +will never read as @code{None}. + +If the @code{gdb.Style} object was created using a named style (i.e.@: +using the single argument @var{style_name} @code{__init__} method), +then the underlying setting will be updated. + +For unnamed styles, only the @code{gdb.Style} object will change. +@end defvar + +@anchor{Style Intensities} +The following constants are defined to represent the different style +intensities: + +@table @code +@findex INTENSITY_NORMAL +@findex gdb.INTENSITY_NORMAL +@item gdb.INTENSITY_NORMAL +This is the terminal's default intensity. + +@findex INTENSITY_BOLD +@findex gdb.INTENSITY_BOLD +@item gdb.INTENSITY_BOLD +This is for bold text. + +@findex INTENSITY_DIM +@findex gdb.INTENSITY_DIM +@item gdb.INTENSITY_DIM +This is for dim text. +@end table + @node Architectures In Python @subsubsection Python representation of architectures @cindex Python architectures @@ -8479,6 +8894,106 @@ handlers, all of the matching handlers are enabled. The @code{enabled} field of each matching handler is set to @code{True}. @end table +@node Core Files In Python +@subsubsection Core Files In Python +@cindex python, core files + +When a core file is loaded into an inferior (@pxref{Inferiors In +Python}) for examination (@pxref{core-file command}), information +about the core file is contained in a @code{gdb.Corefile} object. + +The @code{gdb.Corefile} for an inferior can be accessed using the +@code{Inferior.corefile} attribute. This will be @code{None} if +no core file is loaded. + +A @code{gdb.Corefile} object has the following attributes: + +@defvar Corefile.filename +This read only attribute contains a non-empty string, the file name of +the core file. Attempting to access this attribute on an invalid +@code{gdb.Corefile} object will raise a @code{RuntimeError} exception. +@end defvar + +A @code{gdb.Corefile} object has the following methods: + +@defun Corefile.is_valid () +Returns @code{True} if the @code{gdb.Corefile} object is valid, +@code{False} if not. A @code{gdb.Corefile} object will become invalid +when the core file is unloaded from the inferior using the +@kbd{core-file} command (@pxref{core-file command}), or if the +inferior in which the core file is loaded is deleted. All other +@code{gdb.Corefile} methods and attributes will throw an exception if +it is invalid at the time the method is called, or the attribute +accessed. +@end defun + +@defun Corefile.mapped_files () +Return a list of @code{gdb.CorefileMappedFile} (see below) objects +representing files that were mapped into the process when the core +file was created. This information is read from the @samp{NT_FILE} +core file note on Linux. Not every target supports accessing this +information, for targets without support, an empty list will be +returned. +@end defun + +One may add arbitrary attributes to @code{gdb.Corefile} objects in the +usual Python way. This is useful if, for example, one needs to do +some extra record keeping associated with the corefile. +@xref{choosing attribute names}, for guidance on selecting a suitable +name for new attributes. + +The @code{Corefile.mapped_files ()} method returns a list of +@code{gdb.CorefileMappedFile} objects. Each of these objects +represents a file that was fully, or partially, mapped into the +processes address space when the core file was created. + +A @code{gdb.CorefileMappedFile} object has the following attributes: + +@defvar CorefileMappedFile.filename +This read only attribute contains a non-empty string, the file name of +the mapped file. +@end defvar + +@defvar CorefileMappedFile.build_id +This read only attribute contains a non-empty string or @code{None}. +This is the build-id of the mapped file extracted from the core file, +or @code{None} if there was no build-id, or @value{GDBN} was unable to +extract the build-id. +@end defvar + +@defvar CorefileMappedFile.is_main_executable +This read only attribute is @code{True} if @value{GDBN} believes this +mapping represents the main executable for which this core file was +created. This will be @code{False} for all other mappings. +@end defvar + +@defvar CorefileMappedFile.regions +This read only attribute contains a list of +@code{gdb.CorefileMappedFileRegion} objects. Each of these objects +describes a region of the file that was mapped into the process when +the core file was created, further details are given below. +@end defvar + +The @code{gdb.CorefileMappedFileRegion} object describes which part of +a file that was mapped into a process when the core file was created. + +A @code{gdb.CorefileMappedFile} object has the following attributes: + +@defvar CorefileMappedFileRegion.start +This read only attribute contains the start address of this mapping +within the inferior. +@end defvar + +@defvar CorefileMappedFileRegion.end +This read only attribute contains end address of this mapping within +the inferior. +@end defvar + +@defvar CorefileMappedFileRegion.file_offset +This read only attribute contains the offset within the mapped file +for this mapping. +@end defvar + @node Python Auto-loading @subsection Python Auto-loading @cindex Python auto-loading |