diff options
Diffstat (limited to 'gdb/doc/gdb.texinfo')
| -rw-r--r-- | gdb/doc/gdb.texinfo | 390 |
1 files changed, 235 insertions, 155 deletions
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index b251c8e..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: @@ -4090,6 +4098,56 @@ When @samp{on} @value{GDBN} will print additional messages when threads are created and deleted. @end table +@cindex thread local storage +@cindex @acronym{TLS} +For some debugging targets, @value{GDBN} has support for accessing +variables that reside in Thread Local Storage (@acronym{TLS}). +@acronym{TLS} variables are similar to global variables, except that +each thread has its own copy of the variable. While often used in +multi-threaded programs, @acronym{TLS} variables can also be used in +programs without threads. The C library variable @var{errno} is, +perhaps, the most prominent example of a @acronym{TLS} variable that +is frequently used in non-threaded programs. For targets where +@value{GDBN} does not have good @acronym{TLS} support, printing or +changing the value of @var{errno} might not be directly possible. + +@sc{gnu}/Linux and FreeBSD targets have support for accessing +@acronym{TLS} variables. On @sc{gnu}/Linux, the helper library, +@code{libthread_db}, is used to help resolve the addresses of +@acronym{TLS} variables. Some FreeBSD and some @sc{gnu}/Linux targets +also have @value{GDBN}-internal @acronym{TLS} resolution code. +@sc{gnu}/Linux targets will attempt to use the @acronym{TLS} address +lookup functionality provided by @code{libthread_db}, but will fall +back to using its internal @acronym{TLS} support when +@code{libthread_db} is not available. This can happen in +cross-debugging scenarios or when debugging programs that are linked +in such a way that @code{libthread_db} support is unavailable -- this +includes statically linked programs, linking against @acronym{GLIBC} +versions earlier than 2.34, but not with @code{libpthread}, and use of +other (non-@acronym{GLIBC}) C libraries. + +@table @code +@kindex maint set force-internal-tls-address-lookup +@kindex maint show force-internal-tls-address-lookup +@cindex internal @acronym{TLS} address lookup +@item maint set force-internal-tls-address-lookup +@itemx maint show force-internal-tls-address-lookup +Turns on or off forced use of @value{GDBN}-internal @acronym{TLS} +address lookup code. Use @code{on} to enable and @code{off} to +disable. The default for this setting is @code{off}. + +When disabled, @value{GDBN} will attempt to use a helper +@code{libthread_db} library if possible, but will fall back to use of +its own internal @acronym{TLS} address lookup mechanisms if necessary. + +When enabled, @value{GDBN} will only use @value{GDBN}'s internal +@acronym{TLS} address lookup mechanisms, if they exist. + +This command is only available for @sc{gnu}/Linux targets. Its +primary use is for testing -- certain tests in the @value{GDBN} test +suite use this command to force use of internal TLS address lookup. +@end table + @node Forks @section Debugging Forks @@ -7807,9 +7865,9 @@ previous instruction; otherwise, it will work in record mode, if the platform supports reverse execution, or stop if not. Currently, process record and replay is supported on ARM, Aarch64, -LoongArch, Moxie, PowerPC, PowerPC64, S/390, and x86 (i386/amd64) running -GNU/Linux. Process record and replay can be used both when native -debugging, and when remote debugging via @code{gdbserver}. +LoongArch, Moxie, PowerPC, PowerPC64, S/390, RISC-V and x86 (i386/amd64) +running GNU/Linux. Process record and replay can be used both when +native debugging, and when remote debugging via @code{gdbserver}. When recording an inferior, @value{GDBN} may print auxiliary information during stepping commands and commands displaying the execution history. @@ -13046,6 +13104,18 @@ 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 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 $_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 @node Convenience Funs @@ -22172,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}. @@ -22212,6 +22289,22 @@ less useful than setting a catchpoint, because it does not allow for conditions or commands as a catchpoint does. @table @code +@kindex info linker-namespaces +@item info linker-namespaces +@item info linker-namespaces @code{[[@var{n}]]} + +With no argument, print the number of linker namespaces which are +currently active --- that is, namespaces that have libraries loaded +into them. Then, it prints the number of libraries loaded into each +namespace, and all the libraries loaded into them, in the same way +as @code{info sharedlibrary}. + +If an argument @code{[[@var{n}]]} is provided, only prints the +library count and the libraried for the provided namespace @var{n}. +The surrounding square brackets are optional. +@end table + +@table @code @item set stop-on-solib-events @kindex set stop-on-solib-events This command controls whether @value{GDBN} should give you control @@ -24689,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 @@ -26552,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 @@ -26592,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 @@ -26788,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: @@ -26832,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 @@ -26843,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 @@ -27896,6 +27994,19 @@ value, then @value{GDBN} will change this to @samp{off} at startup. @item show style enabled Show the current state of styling. +@item set style emoji @samp{auto|on|off} +Enable or disable the use of emoji. On most hosts, the default is +@samp{auto}, meaning that emoji will only be used if the host +character set is @samp{UTF-8}; however, on Windows the default is +@samp{off} when using the console. Note that disabling styling as a +whole will also prevent emoji display. + +Currently, emoji are printed whenever @value{GDBN} reports an error or +a warning. + +@item show style emoji +Show the current state of emoji output. + @item set style sources @samp{on|off} Enable or disable source code styling. This affects whether source code, such as the output of the @code{list} command, is styled. The @@ -27912,6 +28023,18 @@ 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 +@itemx show style error-prefix + +These commands control the prefix that is printed before warnings and +errors, respectively. This functionality is intended for use with +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 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}. @@ -31214,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 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. +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. -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}). @@ -41356,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. @@ -41554,6 +41552,13 @@ into remote agent bytecodes and display them as a disassembled list. This command is useful for debugging the agent version of dynamic printf (@pxref{Dynamic Printf}). +@kindex maint canonicalize +@item maint canonicalize @var{name} +Print the canonical form of @var{name}, a C@t{++} name. Because a +C@t{++} name may have multiple possible spellings, @value{GDBN} +computes a canonical form of a name for internal use. For example, +@code{short int} and @code{short} are two ways to name the same type. + @kindex maint info breakpoints @anchor{maint info breakpoints} @item maint info breakpoints @@ -42750,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 @@ -46726,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. @@ -49199,6 +49237,7 @@ registers using the capitalization used in the description. @menu * AArch64 Features:: +* Alpha Features:: * ARC Features:: * ARM Features:: * i386 Features:: @@ -49505,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 |