diff options
Diffstat (limited to 'gdb/doc')
| -rw-r--r-- | gdb/doc/gdb.texinfo | 450 | ||||
| -rw-r--r-- | gdb/doc/guile.texi | 16 | ||||
| -rw-r--r-- | gdb/doc/python.texi | 124 |
3 files changed, 421 insertions, 169 deletions
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 5e5e888..4c33cd2 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: @@ -13096,17 +13104,17 @@ variable which may be @samp{truecolor} or @samp{24bit}. Other color spaces are determined by the "Co" termcap which in turn depends on the @env{TERM} 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}. +@vindex $_linker_namespace_count@r{, convenience variable} +@item $_linker_namespace_count +Number of active linker namespaces in the inferior (@pxref{Files}). In systems +with no support for linker namespaces or if the inferior hasn't started, this +variable will always be set to @samp{0}. -@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 @@ -26976,6 +26996,32 @@ information automatically from the core file, and will show one of the above messages depending on whether the synchronous or asynchronous mode is selected. @xref{Memory Tagging}. @xref{Memory}. +@subsubsection AArch64 Guarded Control Stack +@cindex Guarded Control Stack, AArch64 +@cindex GCS, AArch64 + +When @value{GDBN} is debugging the AArch64 architecture, the program is +using the feature Guarded Control Stack (GCS), the operating system kernel +is Linux and it supports GCS, @value{GDBN} will make a couple of special +registers --- @code{gcs_features_enabled} and @code{gcs_features_locked} +--- available through the @code{org.gnu.gdb.aarch64.gcs.linux} feature. +These registers expose some options that can be controlled at runtime and +emulate the @code{prctl} option @code{PR_SET_SHADOW_STACK_STATUS}. For +further information, see the +@uref{https://www.kernel.org/doc/html/latest/arch/arm64/gcs.html,ignored, +documentation} in the Linux kernel. + +Naturally the Guarded Control Stack pointer at @code{EL0} is also +available, as the @code{gcspr} register. + +To aid debugging, @value{GDBN} will note when SIGSEGV signals are generated +as a result of a Guarded Control Stack error: + +@smallexample +Program received signal SIGSEGV, Segmentation fault +Guarded Control Stack error. +@end smallexample + @node x86 @subsection x86 @@ -27017,6 +27063,46 @@ registers @end itemize +@subsubsection Intel Control-Flow Enforcement Technology. +@cindex Intel Control-Flow Enforcement Technology. + +The @dfn{Intel Control-Flow Enforcement Technology} (@acronym{Intel CET}) +provides two capabilities to defend against ``Return-oriented Programming'' +and ``call/jmp-oriented programming'' style control-flow attacks: + +@itemize @bullet +@item Shadow Stack: +A shadow stack is a second stack for a program. It holds the return +addresses pushed by the call instruction. The @code{RET} instruction pops the +return addresses from both call and shadow stack. If the return addresses from +the two stacks do not match, the processor signals a control protection +exception. +@item Indirect Branch Tracking (IBT): +When IBT is enabled, the CPU implements a state machine that tracks +indirect @code{JMP} and @code{CALL} instructions. The state machine can +be either IDLE or WAIT_FOR_ENDBRANCH. When a @code{JMP} or @code{CALL} is +executed the state machine chages to the WAIT_FOR_ENDBRANCH state. In +WAIT_FOR_ENDBRANCH state the next instruction in the program stream +must be an @code{ENDBR} instruction, otherwise the processor signals a +control protection exception. After executing a @code{ENDBR} instruction +the state machine returns to the IDLE state. +@end itemize + +Impact on @value{GDBN} commands: +@itemize @bullet +@item Call/Print: +Inferior calls in @value{GDBN} reset the current PC to the beginning of the +function that is called. No call instruction is executed, but the @code{RET} +instruction actually is. To avoid a control protection exception due to the +missing return address on the shadow stack, @value{GDBN} pushes the new return +address to the shadow stack and updates the shadow stack pointer. +@item Step: +With displaced stepping, @value{GDBN} may run an out of line copy of a call +instruction. In this case, the wrong return address is pushed to the shadow +stack. @value{GDBN} corrects this value to avoid a control protection +exception. For more details on displaced stepping, see @ref{displaced-stepping}. +@end itemize + @node Alpha @subsection Alpha @@ -27639,6 +27725,16 @@ or a prompt that does not. @item set prompt @var{newprompt} Directs @value{GDBN} to use @var{newprompt} as its prompt string henceforth. +For example, this will set a blue-colored ``(gdb)'' prompt: + +@smallexample +set prompt \001\033[0;34m\002(gdb)\001\033[0m\002 +@end smallexample + +It uses @samp{\001} and @samp{\002} to begin and end a sequence of +non-printing characters, to make sure they're not counted in the string +length. + @kindex show prompt @item show prompt Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}} @@ -28003,6 +28099,7 @@ 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 @@ -31316,138 +31413,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. +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. -@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 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}). @@ -38974,7 +38946,7 @@ Example output: @smallexample (gdb) -list-features -^done,result=["feature1","feature2"] +^done,features=["feature1","feature2"] @end smallexample The current list of features is: @@ -39039,7 +39011,7 @@ Example output: @smallexample (gdb) -list-target-features -^done,result=["async"] +^done,features=["async"] @end smallexample The current list of features is: @@ -41371,6 +41343,14 @@ Configure @value{GDBN} for cross-debugging programs running on the specified list of targets. The special value @samp{all} configures @value{GDBN} for debugging programs running on any target it supports. +@item --enable-binary-file-formats=@r{[}@var{format}@r{]}@dots{} +@itemx --enable-binary-file-formats=all +Configure @value{GDBN} to support certain binary file formats. If a +format is the main (or only) file format for a given target, the +configure script may add support to it anyway, and warn the user. +If not given, all file formats that @value{GDBN} supports are compiled +in. + @item --with-gdb-datadir=@var{path} Set the @value{GDBN}-specific data directory. @value{GDBN} will look here for certain supporting files or scripts. This defaults to the @@ -41458,7 +41438,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. @@ -41816,6 +41796,7 @@ GLOBAL Disassembler_2 (Matches current architecture) @cindex out-of-line single-stepping @item set displaced-stepping @itemx show displaced-stepping +@anchor{displaced-stepping} Control whether or not @value{GDBN} will do @dfn{displaced stepping} if the target supports it. Displaced stepping is a way to single-step over breakpoints without removing them from the inferior, by executing @@ -42859,6 +42840,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 @@ -44956,7 +44954,8 @@ packets.) @anchor{qSearch memory} Search @var{length} bytes at @var{address} for @var{search-pattern}. Both @var{address} and @var{length} are encoded in hex; -@var{search-pattern} is a sequence of bytes, also hex encoded. +@var{search-pattern} is a sequence of binary-encoded bytes +(@pxref{Binary Data}). Reply: @table @samp @@ -46835,12 +46834,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 +49323,7 @@ registers using the capitalization used in the description. @menu * AArch64 Features:: +* Alpha Features:: * ARC Features:: * ARM Features:: * i386 Features:: @@ -49614,6 +49630,104 @@ of bytes. Extra registers are allowed in this feature, but they will not affect @value{GDBN}. +@subsubsection AArch64 GCS registers feature + +The @samp{org.gnu.gdb.aarch64.gcs} feature is optional. If present, it +means the target supports Guarded Control Stacks and must contain the +following register: + +@itemize @minus + +@item +@code{gcspr}, which points to the thread's Guarded Control Stack. It is 64 +bits in size and has a type of @samp{data_ptr}. + +@end itemize + +The @samp{org.gnu.gdb.aarch64.gcs.linux} feature is optional. If present, +then the @samp{org.gnu.gdb.aarch64.gcs} feature must also be present. The +@samp{org.gnu.gdb.aarch64.gcs.linux} feature represents facilities provided +by the Linux kernel for GCS support and should contain the following: + +@itemize @minus + +@item +@code{gcs_features_enabled} shows the features currently enabled via the +prctl or ptrace system calls. It is represented as if it were a 64-bit +register with a custom flags type. + +@item +@code{gcs_features_locked} shows the features currently locked via the +prctl or ptrace system calls. It is represented as if it were a 64-bit +register with a custom flags type. + +@end itemize + +The custom flags type allows @value{GDBN} to print a human-friendly +representation of the contents of @code{gcs_features_enabled} and +@code{gcs_features_locked} and should contain: + +@itemize @minus + +@item +@code{PR_SHADOW_STACK_ENABLE} + +@item +@code{PR_SHADOW_STACK_WRITE} + +@item +@code{PR_SHADOW_STACK_PUSH} + +@end itemize + +For further information, see the +@uref{https://www.kernel.org/doc/html/latest/arch/arm64/gcs.html,ignored, +documentation} in the Linux kernel. + +Extra registers are allowed in these features, 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 @@ -50047,6 +50161,12 @@ The @samp{org.gnu.gdb.i386.pkeys} feature is optional. It should describe a single register, @samp{pkru}. It is a 32-bit register valid for i386 and amd64. +The @samp{org.gnu.gdb.i386.pl3_ssp} feature is optional. It should +describe the user mode register @samp{pl3_ssp} which has 64 bits on +amd64, 32 bits on amd64 with 32-bit pointer size (X32) and 32 bits on i386. +Following the restriction of the Linux kernel, only @value{GDBN} for amd64 +targets makes use of this feature for now. + @node LoongArch Features @subsection LoongArch Features @cindex target descriptions, LoongArch Features diff --git a/gdb/doc/guile.texi b/gdb/doc/guile.texi index c6d889f..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. diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index 7bb6503..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 |