diff options
Diffstat (limited to 'gdb/doc')
| -rw-r--r-- | gdb/doc/gdb.texinfo | 297 | ||||
| -rw-r--r-- | gdb/doc/guile.texi | 19 | ||||
| -rw-r--r-- | gdb/doc/python.texi | 127 |
3 files changed, 276 insertions, 167 deletions
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index b9fc160..35b770f 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -3807,7 +3807,7 @@ Thread 1 "main" received signal SIGINT, Interrupt. @table @code @anchor{info_threads} @kindex info threads -@item info threads @r{[}-gid@r{]} @r{[}@var{thread-id-list}@r{]} +@item info threads @r{[}-gid@r{]} @r{[}-stopped@r{]} @r{[}-running@r{]} @r{[}@var{thread-id-list}@r{]} Display information about one or more threads. With no arguments displays information about all threads. You can specify the list of @@ -3857,6 +3857,14 @@ If you're debugging multiple inferiors, @value{GDBN} displays thread IDs using the qualified @var{inferior-num}.@var{thread-num} format. Otherwise, only @var{thread-num} is shown. +If you specify the @samp{-stopped} option, @value{GDBN} filters the +output of the command to print the stopped threads only. Similarly, +if you specify the @samp{-running} option, @value{GDBN} filters the +output to print the running threads only. These options can be +helpful to reduce the output list if there is a large number of +threads. If you specify both options, @value{GDBN} prints both +stopped and running threads. + If you specify the @samp{-gid} option, @value{GDBN} displays a column indicating each thread's global thread ID: @@ -13098,15 +13106,15 @@ environment variable. @vindex $_active_linker_namespaces@r{, convenience variable} @item $_active_linker_namespaces -Number of active linkage namespaces in the inferior. In systems with no -support for linkage namespaces, this variable will always be set to @samp{1}. +Number of active linker namespaces in the inferior (@pxref{Files}). In systems +with no support for linker namespaces, this variable will always be set to +@samp{1}. -@vindex $_current_linker_namespace@r{, convenience variable} -@item $_current_linker_namespace -The namespace which contains the current location in the inferior. This -returns GDB's internal identifier for namespaces, which is @samp{[[@var{n}]]} -where @var{n} is a zero-based namespace number. In systems with no support -for linkage namespaces, this variable will always be set to @samp{[[0]]}. +@vindex $_linker_namespace@r{, convenience variable} +@item $_linker_namespace +The namespace which contains the current location in the inferior. This returns +@value{GDBN}'s internal numbering for the namespace. In systems with no support +for linker namespaces, this variable will always be set to @samp{0}. @end table @@ -22234,11 +22242,18 @@ be determined then the address range for the @code{.text} section from the library will be listed. If the @code{.text} section cannot be found then no addresses will be listed. -On systems that support linkage namespaces, the output includes an +On systems that support linker namespaces, the output includes an additional column @code{NS} if the inferior has more than one active -namespace when the command is used. This column the linkage namespace +namespace when the command is used. This column the linker namespace that the shared library was loaded into. +@cindex linker namespaces +@dfn{Linker namespaces} are a feature of some standard libraries, that allow +shared objects to be loaded in isolated environment, eliminating the +possibility that those objects may cross-talk. Each set of isolated +shared objects is said to belong to a ``namespace'', and linker related +actions such as relocations do not cross namespace boundaries. + @kindex info dll @item info dll @var{regex} This is an alias of @code{info sharedlibrary}. @@ -24767,6 +24782,10 @@ future connections is shown. The available settings are: @tab @code{vFile:stat} @tab Host I/O +@item @code{hostio-lstat-packet} +@tab @code{vFile:lstat} +@tab Host I/O + @item @code{hostio-setfs-packet} @tab @code{vFile:setfs} @tab Host I/O @@ -26630,8 +26649,9 @@ Show whether AArch64 debugging messages are displayed. @end table -@subsubsection AArch64 SVE. -@cindex AArch64 SVE. +@subsubsection AArch64 Scalable Vector Extension +@cindex Scalable Vector Extension, AArch64 +@cindex SVE, AArch64 When @value{GDBN} is debugging the AArch64 architecture, if the Scalable Vector Extension (SVE) is present, then @value{GDBN} will provide the vector registers @@ -26670,11 +26690,10 @@ internally by @value{GDBN} and the Linux Kernel. @end itemize -@subsubsection AArch64 SME. +@subsubsection AArch64 Scalable Matrix Extension @anchor{AArch64 SME} -@cindex SME -@cindex AArch64 SME -@cindex Scalable Matrix Extension +@cindex Scalable Matrix Extension, AArch64 +@cindex SME, AArch64 The Scalable Matrix Extension (@url{https://community.arm.com/arm-community-blogs/b/architectures-and-processors-blog/posts/scalable-matrix-extension-armv9-a-architecture, @acronym{SME}}) is an AArch64 architecture extension that expands on the concept of the @@ -26866,11 +26885,10 @@ incorrect values for SVE registers (when in streaming mode). This is the same limitation we have for the @acronym{SVE} registers, and there are plans to address this limitation going forward. -@subsubsection AArch64 SME2. +@subsubsection AArch64 Scalable Matrix Extension 2 @anchor{AArch64 SME2} -@cindex SME2 -@cindex AArch64 SME2 -@cindex Scalable Matrix Extension 2 +@cindex Scalable Matrix Extension 2, AArch64 +@cindex SME2, AArch64 The Scalable Matrix Extension 2 is an AArch64 architecture extension that further expands the @acronym{SME} extension with the following: @@ -26910,8 +26928,9 @@ For more information about @acronym{SME2}, please refer to the official @url{https://developer.arm.com/documentation/ddi0487/latest, architecture documentation}. -@subsubsection AArch64 Pointer Authentication. -@cindex AArch64 Pointer Authentication. +@subsubsection AArch64 Pointer Authentication +@cindex Pointer Authentication, AArch64 +@cindex PAC, AArch64 @anchor{AArch64 PAC} When @value{GDBN} is debugging the AArch64 architecture, and the program is @@ -26921,8 +26940,9 @@ When GDB prints a backtrace, any addresses that required unmasking will be postfixed with the marker [PAC]. When using the MI, this is printed as part of the @code{addr_flags} field. -@subsubsection AArch64 Memory Tagging Extension. -@cindex AArch64 Memory Tagging Extension. +@subsubsection AArch64 Memory Tagging Extension +@cindex Memory Tagging Extension, AArch64 +@cindex MTE, AArch64 When @value{GDBN} is debugging the AArch64 architecture, the program is using the v8.5-A feature Memory Tagging Extension (MTE) and there is support @@ -28000,6 +28020,10 @@ is used. Otherwise, if @value{GDBN} was configured with Python scripting support, and if the Python Pygments package is available, then it will be used. +@item show style sources +Show the current state of source code styling. + +@anchor{warning-prefix} @item set style warning-prefix @itemx show style warning-prefix @itemx set style error-prefix @@ -28011,9 +28035,6 @@ emoji display, and so the prefixes are only displayed if emoji styling is enabled. The defaults are the warning sign emoji for warnings, and and the cross mark emoji for errors. -@item show style sources -Show the current state of source code styling. - @item set style tui-current-position @samp{on|off} Enable or disable styling of the source and assembly code highlighted by the TUI's current position indicator. The default is @samp{off}. @@ -31316,138 +31337,13 @@ appropriate @code{set style} commands. @xref{Output Styling}. @cindex Emacs @cindex @sc{gnu} Emacs -A special interface allows you to use @sc{gnu} Emacs to view (and -edit) the source files for the program you are debugging with -@value{GDBN}. - -To use this interface, use the command @kbd{M-x gdb} in Emacs. Give the -executable file you want to debug as an argument. This command starts -@value{GDBN} as a subprocess of Emacs, with input and output through a newly -created Emacs buffer. -@c (Do not use the @code{-tui} option to run @value{GDBN} from Emacs.) - -Running @value{GDBN} under Emacs can be just like running @value{GDBN} normally except for two -things: - -@itemize @bullet -@item -All ``terminal'' input and output goes through an Emacs buffer, called -the GUD buffer. - -This applies both to @value{GDBN} commands and their output, and to the input -and output done by the program you are debugging. - -This is useful because it means that you can copy the text of previous -commands and input them again; you can even use parts of the output -in this way. - -All the facilities of Emacs' Shell mode are available for interacting -with your program. In particular, you can send signals the usual -way---for example, @kbd{C-c C-c} for an interrupt, @kbd{C-c C-z} for a -stop. - -@item -@value{GDBN} displays source code through Emacs. - -Each time @value{GDBN} displays a stack frame, Emacs automatically finds the -source file for that frame and puts an arrow (@samp{=>}) at the -left margin of the current line. Emacs uses a separate buffer for -source display, and splits the screen to show both your @value{GDBN} session -and the source. - -Explicit @value{GDBN} @code{list} or search commands still produce output as -usual, but you probably have no reason to use them from Emacs. -@end itemize - -We call this @dfn{text command mode}. Emacs 22.1, and later, also uses -a graphical mode, enabled by default, which provides further buffers -that can control the execution and describe the state of your program. -@xref{GDB Graphical Interface,,, Emacs, The @sc{gnu} Emacs Manual}. - -If you specify an absolute file name when prompted for the @kbd{M-x -gdb} argument, then Emacs sets your current working directory to where -your program resides. If you only specify the file name, then Emacs -sets your current working directory to the directory associated -with the previous buffer. In this case, @value{GDBN} may find your -program by searching your environment's @env{PATH} variable, but on -some operating systems it might not find the source. So, although the -@value{GDBN} input and output session proceeds normally, the auxiliary -buffer does not display the current source and line of execution. - -The initial working directory of @value{GDBN} is printed on the top -line of the GUD buffer and this serves as a default for the commands -that specify files for @value{GDBN} to operate on. @xref{Files, -,Commands to Specify Files}. - -By default, @kbd{M-x gdb} calls the program called @file{gdb}. If you -need to call @value{GDBN} by a different name (for example, if you -keep several configurations around, with different names) you can -customize the Emacs variable @code{gud-gdb-command-name} to run the -one you want. - -In the GUD buffer, you can use these special Emacs commands in -addition to the standard Shell mode commands: - -@table @kbd -@item C-h m -Describe the features of Emacs' GUD Mode. - -@item C-c C-s -Execute to another source line, like the @value{GDBN} @code{step} command; also -update the display window to show the current file and location. - -@item C-c C-n -Execute to next source line in this function, skipping all function -calls, like the @value{GDBN} @code{next} command. Then update the display window -to show the current file and location. - -@item C-c C-i -Execute one instruction, like the @value{GDBN} @code{stepi} command; update -display window accordingly. - -@item C-c C-f -Execute until exit from the selected stack frame, like the @value{GDBN} -@code{finish} command. - -@item C-c C-r -Continue execution of your program, like the @value{GDBN} @code{continue} -command. - -@item C-c < -Go up the number of frames indicated by the numeric argument -(@pxref{Arguments, , Numeric Arguments, Emacs, The @sc{gnu} Emacs Manual}), -like the @value{GDBN} @code{up} command. - -@item C-c > -Go down the number of frames indicated by the numeric argument, like the -@value{GDBN} @code{down} command. -@end table -In any source file, the Emacs command @kbd{C-x @key{SPC}} (@code{gud-break}) -tells @value{GDBN} to set a breakpoint on the source line point is on. +In @sc{gnu} Emacs there is a special interface to @value{GDBN}, which +facilitates viewing the source code for the program you are debugging. +There is also an IDE-like interface to GDB, with specialized buffers for +breakpoints, stack frames and other aspects of the debugger state. -In text command mode, if you type @kbd{M-x speedbar}, Emacs displays a -separate frame which shows a backtrace when the GUD buffer is current. -Move point to any frame in the stack and type @key{RET} to make it -become the current frame and display the associated source in the -source buffer. Alternatively, click @kbd{Mouse-2} to make the -selected frame become the current one. In graphical mode, the -speedbar displays watch expressions. - -If you accidentally delete the source-display buffer, an easy way to get -it back is to type the command @code{f} in the @value{GDBN} buffer, to -request a frame display; when you run under Emacs, this recreates -the source buffer if necessary to show you the context of the current -frame. - -The source files displayed in Emacs are in ordinary Emacs buffers -which are visiting the source files in the usual way. You can edit -the files with these buffers if you wish; but keep in mind that @value{GDBN} -communicates with Emacs in terms of line numbers. If you add or -delete lines from the text, the line numbers that @value{GDBN} knows cease -to correspond properly with the code. - -A more detailed description of Emacs' interaction with @value{GDBN} is +A detailed description of Emacs' interaction with @value{GDBN} is given in the Emacs manual (@pxref{Debuggers,,, Emacs, The @sc{gnu} Emacs Manual}). @@ -41458,7 +41354,7 @@ libpython is present and found at configure time.) Python makes @value{GDBN} scripting much more powerful than the restricted CLI scripting language. If your host does not have Python installed, you can find it on @url{http://www.python.org/download/}. The oldest version -of Python supported by GDB is 3.0.1. The optional argument @var{python} +of Python supported by GDB is 3.4. The optional argument @var{python} is used to find the Python headers and libraries. It can be either the name of a Python executable, or the name of the directory in which Python is installed. @@ -42859,6 +42755,23 @@ reports and error and the command is aborted. @item show watchdog Show the current setting of the target wait timeout. + +@kindex maint set console-translation-mode +@kindex maint show console-translation-mode +@item maint set console-translation-mode @r{[}binary|text@r{]} +@itemx maint show console-translation-mode +Controls the translation mode of @value{GDBN} stdout/stderr. MS-Windows +only. Useful for running the @value{GDBN} testsuite. + +The translation mode values are as follows: +@table @code +@item binary +No translation. +@item text +Translate @samp{\n} (LF, a single Line Feed) into @samp{\r\n} (CR-LF, a +Carriage Return-Line Feed combination). +@end table + @end table @node Remote Protocol @@ -46835,12 +46748,28 @@ If an error occurs the return value is -1. The format of the returned binary attachment is as described in @ref{struct stat}. @item vFile:stat: @var{filename} -Get information about the file @var{filename} on the target. -On success the information is returned as a binary attachment -and the return value is the size of this attachment in bytes. -If an error occurs the return value is -1. The format of the +Get information about the file @var{filename} on the target as if from +a @samp{stat} call. On success the information is returned as a binary +attachment and the return value is the size of this attachment in +bytes. If an error occurs the return value is -1. The format of the returned binary attachment is as described in @ref{struct stat}. +If @var{filename} is a symbolic link, then the information returned is +about the file the link refers to, this is inline with the @samp{stat} +library call. + +@item vFile:lstat: @var{filename} +Get information about the file @var{filename} on the target as if from +an @samp{lstat} call. On success the information is returned as a +binary attachment and the return value is the size of this attachment +in bytes. If an error occurs the return value is -1. The format of +the returned binary attachment is as described in @ref{struct stat}. + +This packet is identical to @samp{vFile:stat}, except if +@var{filename} is a symbolic link, then this packet returns +information about the link itself, not the file that the link refers +to, this is inline with the @samp{lstat} library call. + @item vFile:unlink: @var{filename} Delete the file at @var{filename} on the target. Return 0, or -1 if an error occurs. The @var{filename} is a string. @@ -49308,6 +49237,7 @@ registers using the capitalization used in the description. @menu * AArch64 Features:: +* Alpha Features:: * ARC Features:: * ARM Features:: * i386 Features:: @@ -49614,6 +49544,47 @@ of bytes. Extra registers are allowed in this feature, but they will not affect @value{GDBN}. +@node Alpha Features +@subsection Alpha Features +@cindex target descriptions, Alpha Features + +The @samp{org.gnu.gdb.alpha.core} feature is required for Alpha targets. It +must contain the following 64-bit registers; note that @value{GDBN} uses the +software names for Alpha registers: + +@itemize @minus +@item +@samp{v0}: function return value +@item +@samp{t0} through @samp{t12}: temporary registers +@item +@samp{s0} through @samp{s5}: saved registers +@item +@samp{fp}: frame pointer +@item +@samp{a0} through @samp{a5}: argument registers +@item +@samp{ra}: return address +@item +@samp{at}: assembler temporary register +@item +@samp{gp}: global pointer +@item +@samp{sp}: stack pointer +@item +@samp{zero}: always zero +@item +@samp{f0} through @samp{f30}: floating-point registers +@item +@samp{fpcr}: floating-point control register +@item +@samp{pc}: program counter +@item +@samp{}: an anonymous register for historical purpose +@item +@samp{unique}: PALcode memory slot +@end itemize + @node ARC Features @subsection ARC Features @cindex target descriptions, ARC Features diff --git a/gdb/doc/guile.texi b/gdb/doc/guile.texi index c6808ef..9677229 100644 --- a/gdb/doc/guile.texi +++ b/gdb/doc/guile.texi @@ -1772,6 +1772,16 @@ invoking it interactively. If this function throws an exception, it is turned into a @value{GDBN} @code{error} call. Otherwise, the return value is ignored. +For non-prefix commands, @var{invoke} is required. For prefix +commands @var{invoke} is optional. Only prefix commands that need to +handle unknown sub-commands should supply @var{invoke}. + +For prefix commands that don't supply @var{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. + The argument @var{command-class} is one of the @samp{COMMAND_} constants defined below. This argument tells @value{GDBN} how to categorize the new command in the help system. The default is @code{COMMAND_NONE}. @@ -2098,8 +2108,10 @@ is the @code{<gdb:parameter>} object representing the parameter, and This function must return a string, and will be displayed to the user. @value{GDBN} will add a trailing newline. -The argument @var{doc} is the help text for the new parameter. -If there is no documentation string, a default value is used. +The argument @var{doc} is the help text for the new parameter. If +there is no documentation string, a default value is used. If the +documentation string is empty, then @value{GDBN} will print just the +@var{set-doc} and @var{show-doc} strings (see below). The argument @var{set-doc} is the help text for this parameter's @code{set} command. @@ -3899,6 +3911,9 @@ Return string to change terminal's color to this. If @var{is_foreground} is @code{#t}, 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 procedure will return an empty string. @end deffn When color is initialized, its color space must be specified. The diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index afbd62f..6fa2285 100644 --- a/gdb/doc/python.texi +++ b/gdb/doc/python.texi @@ -479,7 +479,7 @@ 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 @@ -509,6 +509,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 @@ -4525,6 +4536,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 @@ -4558,6 +4570,7 @@ 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 +4581,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 +4595,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 +5104,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 +5285,99 @@ 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}). + +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 + @node Functions In Python @subsubsection Writing new convenience functions @@ -7101,6 +7221,9 @@ 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 |