diff options
Diffstat (limited to 'gdb/doc')
| -rw-r--r-- | gdb/doc/gdb.texinfo | 1279 | ||||
| -rw-r--r-- | gdb/doc/guile.texi | 25 | ||||
| -rw-r--r-- | gdb/doc/python.texi | 629 |
3 files changed, 1476 insertions, 457 deletions
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index b251c8e..e0fc0ff 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -898,14 +898,17 @@ debugger attached to a bare board, there may not be any notion of ``process'', and there is often no way to get a core dump. @value{GDBN} will warn you if it is unable to attach or to read core dumps. -You can optionally have @code{@value{GDBP}} pass any arguments after the -executable file to the inferior using @code{--args}. This option stops -option processing. +You can optionally have @code{@value{GDBP}} pass any arguments after +the executable file to the inferior using @code{--args} or +@code{--no-escape-args}. These options stop option processing. @smallexample @value{GDBP} --args gcc -O2 -c foo.c @end smallexample This will cause @code{@value{GDBP}} to debug @code{gcc}, and to set -@code{gcc}'s command-line arguments (@pxref{Arguments}) to @samp{-O2 -c foo.c}. +@code{gcc}'s command-line arguments (@pxref{Arguments}) to @samp{-O2 +-c foo.c}. For the differences between @code{--args} and +@code{--no-escape-args}, see @ref{--args and --no-escape-args options, +,@code{--args} and @code{--no-escape-args}}. You can run @code{@value{GDBP}} without printing the front material, which describes @value{GDBN}'s non-warranty, by specifying @code{--silent} @@ -1212,6 +1215,17 @@ Run @value{GDBN} using @var{directory} as its data directory. The data directory is where @value{GDBN} searches for its auxiliary files. @xref{Data Files}. +@item -binary-output +@cindex @code{--binary-output} + +Instructs @value{GDBN} to set the translation mode of its +@code{stdout}/@code{stderr} to binary. MS-Windows only. Useful for +running the @value{GDBN} testsuite. By default, @value{GDBN} opens +@code{stdout}/@code{stderr} in text mode, and translates @samp{\n} +(LF, a single Line Feed) into @samp{\r\n} (CR-LF, a Carriage +Return-Line Feed combination). If this option is set, no translation +is done. + @item -fullname @itemx -f @cindex @code{--fullname} @@ -1240,12 +1254,67 @@ that control @value{GDBN}, and level 2 has been deprecated. The annotation mechanism has largely been superseded by @sc{gdb/mi} (@pxref{GDB/MI}). +@anchor{--args and --no-escape-args options} @item --args @cindex @code{--args} Change interpretation of command line so that arguments following the executable file are passed as command line arguments to the inferior. This option stops option processing. +Arguments supplied using @code{--args} will have backslashes applied +to escape any special shell characters. This ensures that when the +inferior starts it is passed arguments exactly as @value{GDBN} +receives them. + +For example, consider the following command run under a shell: + +@smallexample +$ @value{GDBP} --args ls *.c +@end smallexample + +@noindent +In this case the shell will expand @kbd{*.c} at the time @value{GDBN} +is invoked, not at the time that the inferior is invoked. As a +result, if an additional @kbd{.c} file is created after @value{GDBN} +is started, but before the inferior is started, then the inferior will +not show the file in its output; the list of matching files was +resolved at the time @value{GDBN} was started. + +If you quote the @kbd{*} character used on the @value{GDBN} command +line argument then this will prevent the shell that starts +@value{GDBN} from expanding the @kbd{*.c} pattern, however, this +quoting will also be passed to the shell that @value{GDBN} invokes in +order to start the inferior (@pxref{set startup-with-shell}), and this +will prevent the @kbd{*.c} pattern being expanded at this point either: + +@smallexample +$ @value{GDBP} --args ls '*.c' +(@value{GDBP}) show args +Argument list to give program being debugged when it is started is "\*.log". +@end smallexample + +@noindent +If this quoting behaviour does not meet your needs, then you could use +@code{--no-escape-args} instead, which is described below. + +@item --no-escape-args +@cindex @code{--no-escape-args} +Change interpretation of command line so that arguments following the +executable file are passed as command line arguments to the inferior. +This option stops option processing. + +Unlike @code{--args}, arguments after the executable name will not +have any escaping applied to them. As a result, any special shell +characters that are not expanded by the shell that invokes +@value{GDBN} will be expanded by the shell that @value{GDBN} uses to +start the inferior. + +@smallexample +$ @value{GDBP} --no-escape-args ls '*.c' +(@value{GDBP}) show args +Argument list to give program being debugged when it is started is "*.log". +@end smallexample + @item -baud @var{bps} @itemx -b @var{bps} @cindex @code{--baud} @@ -3298,6 +3367,7 @@ elements, even duplicates or overlapping ranges are valid. E.g.@: To find out what inferiors exist at any moment, use @w{@code{info inferiors}}: +@anchor{info inferiors command} @table @code @kindex info inferiors [ @var{id}@dots{} ] @item info inferiors @@ -3321,10 +3391,14 @@ the connection. @item the name of the executable the inferior is running. - @end enumerate @noindent +If an inferior is currently debugging a core file, then an additional +line will be printed after the line describing the inferior, this +additional line gives the file name of the core file being debugged. + +@noindent An asterisk @samp{*} preceding the @value{GDBN} inferior number indicates the current inferior. @@ -3336,7 +3410,19 @@ For example, (@value{GDBP}) info inferiors Num Description Connection Executable * 1 process 3401 1 (native) goodbye + 2 process 2307 2 (extended0remote host:10000) hello +@end smallexample + +Adding an additional inferior that is debugging a core file causes the +additional core file line to be displayed, for example@: + +@smallexample +(@value{GDBP}) info inferiors + Num Description Connection Executable +* 1 process 3401 1 (native) goodbye 2 process 2307 2 (extended-remote host:10000) hello + 3 process 1578 3 (core) broken + core file core.1578 @end smallexample To get information about the current inferior, use @code{inferior}: @@ -3439,8 +3525,40 @@ with no connection yet. You can then for example use the @code{target remote} command to connect to some other @code{gdbserver} instance, use @code{run} to spawn a local program, etc. +Not all connections can be shared between inferiors. For example, the +@code{target core} target is unique for each inferior. That is, +multiple inferiors can use @code{target core} at the same time, but +each @code{target core} is different. If you try to +@code{add-inferior}, and the current inferior is @code{target core}, +then @value{GDBN} will give a warning and create the new inferior +without a connection, like this@: + +@smallexample +(@value{GDBP}) file test1 +Reading symbols from test1... +(@value{GDBP}) target core core.test1.433190 +[New LWP 433190] +Core was generated by `./test1'. +Program terminated with signal SIGSEGV, Segmentation fault. +#0 0x0000000000401111 in foo () at test1.c:6 +6 return *global_ptr; +(@value{GDBP}) add-inferior +[New inferior 2] +warning: can't share connection 1 (core) between inferiors +Added inferior 2 +@end smallexample + +Another target that cannot be shared is @code{target remote} +(@pxref{Connecting,,Types of Remote Connections}). A remote target +doesn't allow new inferiors to be started, as such creating a new, +non-running, inferior that shares a remote connection doesn't make +sense. As with the core target above, if you try to +@code{add-inferior}, and the current inferior is @code{target remote}, +then @value{GDBN} will give a warning and create the new inferior +without a connection. + @kindex clone-inferior -@item clone-inferior [ -copies @var{n} ] [ @var{infno} ] +@item clone-inferior [ -copies @var{n} ] [ -no-connection ] [ @var{infno} ] Adds @var{n} inferiors ready to execute the same program as inferior @var{infno}; @var{n} defaults to 1, and @var{infno} defaults to the number of the current inferior. This command copies the values of the @@ -3465,6 +3583,13 @@ Added inferior 2. You can now simply switch focus to inferior 2 and run it. +Like @code{add-inferior}, @code{clone-inferior} shares the connection +with the inferior @var{infno}. If the @var{-no-connection} option is +given, then the new inferior will be created without a connection. If +the connection of inferior @var{infno} can't be shared, then +@value{GDBN} will give a warning, and the new inferior will be created +without a connection. + @anchor{remove_inferiors_cli} @kindex remove-inferiors @item remove-inferiors @var{infno}@dots{} @@ -3547,10 +3672,6 @@ the program space number assigned by @value{GDBN} the name of the executable loaded into the program space, with e.g., the @code{file} command. -@item -the name of the core file loaded into the program space, with e.g., -the @code{core-file} command. - @end enumerate @noindent @@ -3563,7 +3684,7 @@ example, the list of inferiors bound to the program space. @smallexample (@value{GDBP}) maint info program-spaces - Id Executable Core File + Id Executable * 1 hello 2 goodbye Bound inferiors: ID 1 (process 21561) @@ -3577,7 +3698,7 @@ the parent and child processes of a @code{vfork} call. For example, @smallexample (@value{GDBP}) maint info program-spaces - Id Executable Core File + Id Executable * 1 vfork-test Bound inferiors: ID 2 (process 18050), ID 1 (process 18045) @end smallexample @@ -3661,7 +3782,7 @@ programs: @item @samp{thread apply [@var{thread-id-list} | all] @var{args}}, a command to apply a command to a list of threads @item thread-specific breakpoints -@item @samp{set print thread-events}, which controls printing of +@item @samp{set print thread-events}, which controls printing of messages on thread start and exit. @item @samp{set libthread-db-search-path @var{path}}, which lets the user specify which @code{libthread_db} to use if the default choice @@ -3807,7 +3928,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 +3978,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: @@ -3992,8 +4121,8 @@ system-give name, and removing the user-specified name will cause Search for and display thread ids whose name or @var{systag} matches the supplied regular expression. -As well as being the complement to the @samp{thread name} command, -this command also allows you to identify a thread by its target +As well as being the complement to the @samp{thread name} command, +this command also allows you to identify a thread by its target @var{systag}. For instance, on @sc{gnu}/Linux, the target @var{systag} is the LWP id. @@ -4001,7 +4130,7 @@ is the LWP id. (@value{GDBP}) thread find 26688 Thread 4 has target id 'Thread 0x41e02940 (LWP 26688)' (@value{GDBP}) info thread 4 - Id Target Id Frame + Id Target Id Frame 4 Thread 0x41e02940 (LWP 26688) 0x00000031ca6cd372 in select () @end smallexample @@ -4069,8 +4198,8 @@ If none of @code{libthread_db} libraries initialize successfully, Setting @code{libthread-db-search-path} is currently implemented only on some platforms. -@kindex show libthread-db-search-path -@item show libthread-db-search-path +@kindex show libthread-db-search-path +@item show libthread-db-search-path Display current libthread_db search path. @kindex set debug libthread-db @@ -4090,6 +4219,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 @@ -4166,14 +4345,14 @@ retain debugger control over them both. @table @code @item on The child process (or parent process, depending on the value of -@code{follow-fork-mode}) will be detached and allowed to run +@code{follow-fork-mode}) will be detached and allowed to run independently. This is the default. @item off Both processes will be held under the control of @value{GDBN}. -One process (child or parent, depending on the value of +One process (child or parent, depending on the value of @code{follow-fork-mode}) is debugged as usual, while the other -is held suspended. +is held suspended. @end table @@ -4302,8 +4481,8 @@ the critical statement, instead of having to restart your program from the beginning, you can just go back to the checkpoint and start again from there. -This can be especially useful if it takes a lot of time or -steps to reach the point where you think the bug occurs. +This can be especially useful if it takes a lot of time or +steps to reach the point where you think the bug occurs. To use the @code{checkpoint}/@code{restart} method of debugging: @@ -4387,7 +4566,7 @@ different execution path this time. @cindex checkpoints and process id Finally, there is one bit of internal program state that will be different when you return to a checkpoint --- the program's process -id. Each checkpoint will have a unique process id (or @var{pid}), +id. Each checkpoint will have a unique process id (or @var{pid}), and each will be different from the program's original @var{pid}. If your program has saved a local copy of its process id, this could potentially pose a problem. @@ -4395,15 +4574,15 @@ potentially pose a problem. @subsection A Non-obvious Benefit of Using Checkpoints On some systems such as @sc{gnu}/Linux, address space randomization -is performed on new processes for security reasons. This makes it +is performed on new processes for security reasons. This makes it difficult or impossible to set a breakpoint, or watchpoint, on an -absolute address if you have to restart the program, since the +absolute address if you have to restart the program, since the absolute location of a symbol will change from one execution to the next. -A checkpoint, however, is an @emph{identical} copy of a process. -Therefore if you create a checkpoint at (eg.@:) the start of main, -and simply return to that checkpoint instead of restarting the +A checkpoint, however, is an @emph{identical} copy of a process. +Therefore if you create a checkpoint at (eg.@:) the start of main, +and simply return to that checkpoint instead of restarting the process, you can avoid the effects of address randomization and your symbols will all stay in the same place. @@ -6228,7 +6407,7 @@ for more information on how to add @code{SystemTap} @acronym{SDT} probes in your applications.}. @code{SystemTap} probes are usable from assembly, C and C@t{++} languages@footnote{See @uref{http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation} -for a good reference on how the @acronym{SDT} probes are implemented.}. +for a good reference on how the @acronym{SDT} probes are implemented.}. @item @code{DTrace} (@uref{http://oss.oracle.com/projects/DTrace}) @acronym{USDT} probes. @code{DTrace} probes are usable from C and @@ -7144,9 +7323,9 @@ Depending on target support, @code{$_siginfo} may also be writable. (@pxref{Threads,, Debugging Programs with Multiple Threads}). There are two modes of controlling execution of your program within the debugger. In the default mode, referred to as @dfn{all-stop mode}, -when any thread in your program stops (for example, at a breakpoint -or while being stepped), all other threads in the program are also stopped by -@value{GDBN}. On some targets, @value{GDBN} also supports +when any thread in your program stops (for example, at a breakpoint +or while being stepped), all other threads in the program are also stopped by +@value{GDBN}. On some targets, @value{GDBN} also supports @dfn{non-stop mode}, in which other threads can continue to run freely while you examine the stopped thread in the debugger. @@ -7194,7 +7373,7 @@ Whenever @value{GDBN} stops your program, due to a breakpoint or a signal, it automatically selects the thread where that breakpoint or signal happened. @value{GDBN} alerts you to the context switch with a message such as @samp{[Switching to Thread @var{n}]} to identify the -thread. +thread. @anchor{set scheduler-locking} @@ -7499,7 +7678,7 @@ Tasks}); using more than one of the @code{thread}, @code{inferior}, or @code{task} keywords when creating a breakpoint will give an error. @node Interrupted System Calls -@subsection Interrupted System Calls +@subsection Interrupted System Calls @cindex thread breakpoints and system calls @cindex system calls and thread breakpoints @@ -7673,7 +7852,7 @@ targets may be able undo things like device I/O, and some may not. The contract between @value{GDBN} and the reverse executing target requires only that the target do something reasonable when -@value{GDBN} tells it to execute backwards, and then report the +@value{GDBN} tells it to execute backwards, and then report the results back to @value{GDBN}. Whatever the target reports back to @value{GDBN}, @value{GDBN} will report back to the user. @value{GDBN} assumes that the memory and registers that the target reports are in a @@ -7732,7 +7911,7 @@ the current (innermost) stack frame. If the line contains function calls, they will be ``un-executed'' without stopping. Starting from the first line of a function, @code{reverse-next} will take you back to the caller of that function, @emph{before} the function was called, -just as the normal @code{next} command would take you from the last +just as the normal @code{next} command would take you from the last line of a function back to its return to its caller @footnote{Unless the code is too heavily optimized.}. @@ -7807,9 +7986,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. @@ -10737,7 +10916,7 @@ Enter the index of the element you want to explore in `cs.arr': 5 (cs.arr)[5] = 4 -Press enter to return to parent value: +Press enter to return to parent value: @end smallexample In general, at any stage of exploration, you can go deeper towards the @@ -12588,7 +12767,7 @@ with the corresponding objfile (e.g., shared library). @xref{Objfiles In Python}, for more details on objfiles in Python. @end itemize -@xref{Selecting Pretty-Printers}, for further information on how +@xref{Selecting Pretty-Printers}, for further information on how pretty-printers are selected, @xref{Writing a Pretty-Printer}, for implementing pretty printers @@ -12602,7 +12781,7 @@ Here is how a C@t{++} @code{std::string} looks without a pretty-printer: @smallexample (@value{GDBP}) print s $1 = @{ - static npos = 4294967295, + static npos = 4294967295, _M_dataplus = @{ <std::allocator<char>> = @{ <__gnu_cxx::new_allocator<char>> = @{ @@ -13046,6 +13225,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 $_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 $_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 @@ -15659,7 +15850,7 @@ Num Type Disp Enb Address What end collect globfoo2 end - pass count 1200 + pass count 1200 2 tracepoint keep y <MULTIPLE> collect $eip 2.1 y 0x0804859c in func4 at change-loc.h:35 @@ -18669,7 +18860,7 @@ type = POINTER TO ARRAY [-2..2] OF foo = RECORD f1 : CARDINAL; f2 : CHAR; f3 : ARRAY [-2..2] OF CARDINAL; -END +END @end smallexample @node M2 Defaults @@ -18818,8 +19009,8 @@ to be difficult. @cindex expressions in Ada @menu -* Ada Mode Intro:: General remarks on the Ada syntax - and semantics supported by Ada mode +* Ada Mode Intro:: General remarks on the Ada syntax + and semantics supported by Ada mode in @value{GDBN}. * Omissions from Ada:: Restrictions on the Ada expression syntax. * Additions to Ada:: Extensions of the Ada expression syntax. @@ -18839,22 +19030,22 @@ to be difficult. @subsubsection Introduction @cindex Ada mode, general -The Ada mode of @value{GDBN} supports a fairly large subset of Ada expression +The Ada mode of @value{GDBN} supports a fairly large subset of Ada expression syntax, with some extensions. -The philosophy behind the design of this subset is +The philosophy behind the design of this subset is @itemize @bullet @item -That @value{GDBN} should provide basic literals and access to operations for -arithmetic, dereferencing, field selection, indexing, and subprogram calls, +That @value{GDBN} should provide basic literals and access to operations for +arithmetic, dereferencing, field selection, indexing, and subprogram calls, leaving more sophisticated computations to subprograms written into the program (which therefore may be called from @value{GDBN}). -@item +@item That type safety and strict adherence to Ada language restrictions are not particularly important to the @value{GDBN} user. -@item +@item That brevity is important to the @value{GDBN} user. @end itemize @@ -18864,13 +19055,13 @@ according to Ada rules, thus making it unnecessary to fully qualify most names with their packages, regardless of context. Where this causes ambiguity, @value{GDBN} asks the user's intent. -The debugger will start in Ada mode if it detects an Ada main program. +The debugger will start in Ada mode if it detects an Ada main program. As for other languages, it will enter Ada mode when stopped in a program that was translated from an Ada source file. -While in Ada mode, you may use `@t{--}' for comments. This is useful -mostly for documenting command files. The standard @value{GDBN} comment -(@samp{#}) still works at the beginning of a line in Ada mode, but not in the +While in Ada mode, you may use `@t{--}' for comments. This is useful +mostly for documenting command files. The standard @value{GDBN} comment +(@samp{#}) still works at the beginning of a line in Ada mode, but not in the middle (to allow based literals). @node Omissions from Ada @@ -18889,10 +19080,10 @@ Only a subset of the attributes are supported: on array objects (not on types and subtypes). @item -@t{'Min} and @t{'Max}. +@t{'Min} and @t{'Max}. -@item -@t{'Pos} and @t{'Val}. +@item +@t{'Pos} and @t{'Val}. @item @t{'Tag}. @@ -18901,8 +19092,8 @@ Only a subset of the attributes are supported: @t{'Range} on array objects (not subtypes), but only as the right operand of the membership (@code{in}) operator. -@item -@t{'Access}, @t{'Unchecked_Access}, and +@item +@t{'Access}, @t{'Unchecked_Access}, and @t{'Unrestricted_Access} (a GNAT extension). @item @@ -18923,20 +19114,20 @@ Equality tests (@samp{=} and @samp{/=}) on arrays test for bitwise equality of representations. They will generally work correctly for strings and arrays whose elements have integer or enumeration types. They may not work correctly for arrays whose element -types have user-defined equality, for arrays of real values +types have user-defined equality, for arrays of real values (in particular, IEEE-conformant floating point, because of negative zeroes and NaNs), and for arrays whose elements contain unused bits with -indeterminate values. +indeterminate values. @item -The other component-by-component array operations (@code{and}, @code{or}, +The other component-by-component array operations (@code{and}, @code{or}, @code{xor}, @code{not}, and relational tests other than equality) -are not implemented. +are not implemented. -@item +@item @cindex array aggregates (Ada) @cindex record aggregates (Ada) -@cindex aggregates (Ada) +@cindex aggregates (Ada) There is limited support for array and record aggregates. They are permitted only on the right sides of assignments, as in these examples: @@ -18954,7 +19145,7 @@ discriminant's value by assigning an aggregate has an undefined effect if that discriminant is used within the record. However, you can first modify discriminants by directly assigning to them (which normally would not be allowed in Ada), and then performing an -aggregate assignment. For example, given a variable @code{A_Rec} +aggregate assignment. For example, given a variable @code{A_Rec} declared to have a type such as: @smallexample @@ -18974,7 +19165,7 @@ assignments: As this example also illustrates, @value{GDBN} is very loose about the usual rules concerning aggregates. You may leave out some of the -components of an array or record aggregate (such as the @code{Len} +components of an array or record aggregate (such as the @code{Len} component in the assignment to @code{A_Rec} above); they will retain their original values upon assignment. You may freely use dynamic values as indices in component associations. You may even use overlapping or @@ -18998,16 +19189,16 @@ The @code{new} operator is not implemented. @item Entry calls are not implemented. -@item -Aside from printing, arithmetic operations on the native VAX floating-point +@item +Aside from printing, arithmetic operations on the native VAX floating-point formats are not supported. @item It is not possible to slice a packed array. @item -The names @code{True} and @code{False}, when not part of a qualified name, -are interpreted as if implicitly prefixed by @code{Standard}, regardless of +The names @code{True} and @code{False}, when not part of a qualified name, +are interpreted as if implicitly prefixed by @code{Standard}, regardless of context. Should your program redefine these names in a package or procedure (at best a dubious practice), @@ -19019,7 +19210,7 @@ Based real literals are not implemented. @node Additions to Ada @subsubsection Additions to Ada -@cindex Ada, deviations from +@cindex Ada, deviations from As it does for other languages, @value{GDBN} makes certain generic extensions to Ada (@pxref{Expressions}): @@ -19040,12 +19231,12 @@ which certain debugging information has been optimized away. appears in function or file @var{B}.'' When @var{B} is a file name, you must typically surround it in single quotes. -@item +@item The expression @code{@{@var{type}@} @var{addr}} means ``the variable of type @var{type} that appears at address @var{addr}.'' @item -A name starting with @samp{$} is a convenience variable +A name starting with @samp{$} is a convenience variable (@pxref{Convenience Vars}) or a machine register (@pxref{Registers}). @end itemize @@ -19053,7 +19244,7 @@ In addition, @value{GDBN} provides a few other shortcuts and outright additions specific to Ada: @itemize @bullet -@item +@item The assignment statement is allowed as an expression, returning its right-hand operand as its value. Thus, you may enter @@ -19062,8 +19253,8 @@ its right-hand operand as its value. Thus, you may enter (@value{GDBP}) print A(tmp := y + 1) @end smallexample -@item -The semicolon is allowed as an ``operator,'' returning as its value +@item +The semicolon is allowed as an ``operator,'' returning as its value the value of its right-hand operand. This allows, for example, complex conditional breaks: @@ -19086,13 +19277,13 @@ constant: zero means @code{Float} is used, one means $1 = 23.0 @end smallexample -@item -Rather than use catenation and symbolic character names to introduce special -characters into strings, one may instead use a special bracket notation, -which is also used to print strings. A sequence of characters of the form -@samp{["@var{XX}"]} within a string or character literal denotes the +@item +Rather than use catenation and symbolic character names to introduce special +characters into strings, one may instead use a special bracket notation, +which is also used to print strings. A sequence of characters of the form +@samp{["@var{XX}"]} within a string or character literal denotes the (single) character whose numeric encoding is @var{XX} in hexadecimal. The -sequence of characters @samp{["""]} also denotes a single quotation mark +sequence of characters @samp{["""]} also denotes a single quotation mark in strings. For example, @smallexample "One line.["0a"]Next line.["0a"]" @@ -19111,7 +19302,7 @@ to write @end smallexample @item -When printing arrays, @value{GDBN} uses positional notation when the +When printing arrays, @value{GDBN} uses positional notation when the array has a lower bound of 1, and uses a modified named notation otherwise. For example, a one-dimensional array of three integers with a lower bound of 3 might print as @@ -19121,30 +19312,30 @@ of 3 might print as @end smallexample @noindent -That is, in contrast to valid Ada, only the first component has a @code{=>} +That is, in contrast to valid Ada, only the first component has a @code{=>} clause. @item You may abbreviate attributes in expressions with any unique, -multi-character subsequence of +multi-character subsequence of their names (an exact match gets preference). For example, you may use @t{a'len}, @t{a'gth}, or @t{a'lh} in place of @t{a'length}. @item @cindex quoting Ada internal identifiers -Since Ada is case-insensitive, the debugger normally maps identifiers you type -to lower case. The GNAT compiler uses upper-case characters for +Since Ada is case-insensitive, the debugger normally maps identifiers you type +to lower case. The GNAT compiler uses upper-case characters for some of its internal identifiers, which are normally of no interest to users. For the rare occasions when you actually have to look at them, -enclose them in angle brackets to avoid the lower-case mapping. +enclose them in angle brackets to avoid the lower-case mapping. For example, @smallexample (@value{GDBP}) print <JMPBUF_SAVE>[0] @end smallexample @item -Printing an object of class-wide type or dereferencing an +Printing an object of class-wide type or dereferencing an access-to-class-wide value will display all the components of the object's specific type (as indicated by its run-time tag). Likewise, component selection on such a value will operate on the specific type of the @@ -19173,7 +19364,7 @@ Multiple matches for f [0] cancel [1] foo.f (integer) return boolean at foo.adb:23 [2] foo.f (foo.new_integer) return boolean at foo.adb:28 -> +> @end smallexample In this case, just select one menu entry either to cancel expression evaluation @@ -19610,12 +19801,12 @@ Show the current source character set for Ada. Besides the omissions listed previously (@pxref{Omissions from Ada}), we know of several problems with and limitations of Ada mode in @value{GDBN}, -some of which will be fixed with planned future releases of the debugger +some of which will be fixed with planned future releases of the debugger and the GNU Ada compiler. @itemize @bullet -@item -Static constants that the compiler chooses not to materialize as objects in +@item +Static constants that the compiler chooses not to materialize as objects in storage are invisible to the debugger. @item @@ -19626,22 +19817,22 @@ argument lists are treated as positional). Many useful library packages are currently invisible to the debugger. @item -Fixed-point arithmetic, conversions, input, and output is carried out using -floating-point arithmetic, and may give results that only approximate those on +Fixed-point arithmetic, conversions, input, and output is carried out using +floating-point arithmetic, and may give results that only approximate those on the host machine. @item -The GNAT compiler never generates the prefix @code{Standard} for any of -the standard symbols defined by the Ada language. @value{GDBN} knows about +The GNAT compiler never generates the prefix @code{Standard} for any of +the standard symbols defined by the Ada language. @value{GDBN} knows about this: it will strip the prefix from names when you use it, and will never look for a name you have so qualified among local symbols, nor match against -symbols in other packages or subprograms. If you have -defined entities anywhere in your program other than parameters and -local variables whose simple names match names in @code{Standard}, +symbols in other packages or subprograms. If you have +defined entities anywhere in your program other than parameters and +local variables whose simple names match names in @code{Standard}, GNAT's lack of qualification here can cause confusion. When this happens, -you can usually resolve the confusion +you can usually resolve the confusion by qualifying the problematic names with package -@code{Standard} explicitly. +@code{Standard} explicitly. @end itemize Older versions of the compiler sometimes generate erroneous debugging @@ -21896,6 +22087,9 @@ wish to debug a core file instead, you must kill the subprocess in which the program is running. To do this, use the @code{kill} command (@pxref{Kill Process, ,Killing the Child Process}). +To see which core files are loaded into which inferiors, use the +@kbd{info inferiors} command (@pxref{info inferiors command}). + @kindex add-symbol-file @cindex dynamic linking @item add-symbol-file @var{filename} @r{[} -readnow @r{|} -readnever @r{]} @r{[} -o @var{offset} @r{]} @r{[} @var{textaddress} @r{]} @r{[} -s @var{section} @var{address} @dots{} @r{]} @@ -22172,11 +22366,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 +22413,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 @@ -23614,7 +23831,7 @@ current exec-file loaded by @value{GDBN} (@pxref{set exec-file-mismatch}). @cindex symbol files, remote debugging @value{GDBN}, running on the host, needs access to symbol and debugging -information for your program running on the target. This requires +information for your program running on the target. This requires access to an unstripped copy of your program, and possibly any associated symbol files. Note that this section applies equally to both @code{target remote} mode and @code{target extended-remote} mode. @@ -24453,6 +24670,12 @@ extended-remote}. This should be set to a filename valid on the target system. If it is not set, the target will use a default filename (e.g.@: the last program run). +When connecting to a remote system, with @kbd{target extended-remote} +or @kbd{target remote}, if the remote server supports the +@code{qExecAndArgs} packet (@pxref{qExecAndArgs}), then the +@kbd{remote exec-file} will be updated to reflect the executable +currently running on the remote system. + @item set remote interrupt-sequence @cindex interrupt remote programs @cindex select Ctrl-C, BREAK or BREAK-g @@ -24490,7 +24713,7 @@ debugging agent is launched in parallel with @value{GDBN}; there is a race condition because the agent may not become ready to accept the connection before @value{GDBN} attempts to connect. When auto-retry is enabled, if the initial attempt to connect fails, @value{GDBN} reattempts -to establish the connection using the timeout specified by +to establish the connection using the timeout specified by @code{set tcp connect-timeout}. @item set tcp auto-retry off @@ -24504,7 +24727,7 @@ Show the current auto-retry setting. @cindex connection timeout, for remote TCP target @cindex timeout, for remote target connection Set the timeout for establishing a TCP connection to the remote target to -@var{seconds}. The timeout affects both polling to retry failed connections +@var{seconds}. The timeout affects both polling to retry failed connections (enabled by @code{set tcp auto-retry on}) and waiting for connections that are merely slow to complete, and represents an approximate cumulative value. If @var{seconds} is @code{unlimited}, there is no timeout and @@ -24689,6 +24912,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 @@ -26207,7 +26434,7 @@ Show whether ARM-specific debugging messages are enabled. @end table @table @code -@item target sim @r{[}@var{simargs}@r{]} @dots{} +@item target sim @r{[}@var{simargs}@r{]} @dots{} The @value{GDBN} ARM simulator accepts the following optional arguments. @table @code @@ -26260,8 +26487,8 @@ This host system is used to download the configuration bitstream to the target FPGA. The Xilinx Microprocessor Debugger (XMD) program communicates with the target board using the JTAG interface and presents a @code{gdbserver} interface to the board. By default -@code{xmd} uses port @code{1234}. (While it is possible to change -this default port, it requires the use of undocumented @code{xmd} +@code{xmd} uses port @code{1234}. (While it is possible to change +this default port, it requires the use of undocumented @code{xmd} commands. Contact Xilinx support if you need to do this.) Use these GDB commands to connect to the MicroBlaze target processor. @@ -26471,7 +26698,7 @@ Show the current CRIS version. @item set cris-dwarf2-cfi @cindex DWARF-2 CFI and CRIS Set the usage of DWARF-2 CFI for CRIS debugging. The default is @samp{on}. -Change to @samp{off} when using @code{gcc-cris} whose version is below +Change to @samp{off} when using @code{gcc-cris} whose version is below @code{R59}. @item show cris-dwarf2-cfi @@ -26480,7 +26707,7 @@ Show the current state of using DWARF-2 CFI. @item set cris-mode @var{mode} @cindex CRIS mode Set the current CRIS mode to @var{mode}. It should only be changed when -debugging in guru mode, in which case it should be set to +debugging in guru mode, in which case it should be set to @samp{guru} (the default is @samp{normal}). @item show cris-mode @@ -26552,8 +26779,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 +26820,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 +27015,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 +27058,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 +27070,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 @@ -26898,6 +27126,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 @@ -26939,6 +27193,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 @@ -27104,7 +27398,7 @@ given @var{address}. @subsection PowerPC @cindex PowerPC architecture -When @value{GDBN} is debugging the PowerPC architecture, it provides a set of +When @value{GDBN} is debugging the PowerPC architecture, it provides a set of pseudo-registers to enable inspection of 128-bit wide Decimal Floating Point numbers stored in the floating point registers. These values must be stored in two consecutive registers, always starting at an even register like @@ -27123,38 +27417,38 @@ wide Extended Floating Point Registers (@samp{f32} through @samp{f63}). @cindex Application Data Integrity @subsubsection ADI Support -The M7 processor supports an Application Data Integrity (ADI) feature that -detects invalid data accesses. When software allocates memory and enables -ADI on the allocated memory, it chooses a 4-bit version number, sets the -version in the upper 4 bits of the 64-bit pointer to that data, and stores -the 4-bit version in every cacheline of that data. Hardware saves the latter -in spare bits in the cache and memory hierarchy. On each load and store, -the processor compares the upper 4 VA (virtual address) bits to the -cacheline's version. If there is a mismatch, the processor generates a -version mismatch trap which can be either precise or disrupting. The trap -is an error condition which the kernel delivers to the process as a SIGSEGV +The M7 processor supports an Application Data Integrity (ADI) feature that +detects invalid data accesses. When software allocates memory and enables +ADI on the allocated memory, it chooses a 4-bit version number, sets the +version in the upper 4 bits of the 64-bit pointer to that data, and stores +the 4-bit version in every cacheline of that data. Hardware saves the latter +in spare bits in the cache and memory hierarchy. On each load and store, +the processor compares the upper 4 VA (virtual address) bits to the +cacheline's version. If there is a mismatch, the processor generates a +version mismatch trap which can be either precise or disrupting. The trap +is an error condition which the kernel delivers to the process as a SIGSEGV signal. Note that only 64-bit applications can use ADI and need to be built with ADI-enabled. -Values of the ADI version tags, which are in granularity of a -cacheline (64 bytes), can be viewed or modified. +Values of the ADI version tags, which are in granularity of a +cacheline (64 bytes), can be viewed or modified. @table @code @kindex adi examine @item adi (examine | x) [ / @var{n} ] @var{addr} -The @code{adi examine} command displays the value of one ADI version tag per -cacheline. +The @code{adi examine} command displays the value of one ADI version tag per +cacheline. -@var{n} is a decimal integer specifying the number in bytes; the default -is 1. It specifies how much ADI version information, at the ratio of 1:ADI -block size, to display. +@var{n} is a decimal integer specifying the number in bytes; the default +is 1. It specifies how much ADI version information, at the ratio of 1:ADI +block size, to display. -@var{addr} is the address in user address space where you want @value{GDBN} -to begin displaying the ADI version tags. +@var{addr} is the address in user address space where you want @value{GDBN} +to begin displaying the ADI version tags. Below is an example of displaying ADI versions of variable "shmaddr". @@ -27166,19 +27460,19 @@ Below is an example of displaying ADI versions of variable "shmaddr". @kindex adi assign @item adi (assign | a) [ / @var{n} ] @var{addr} = @var{tag} -The @code{adi assign} command is used to assign new ADI version tag -to an address. +The @code{adi assign} command is used to assign new ADI version tag +to an address. -@var{n} is a decimal integer specifying the number in bytes; -the default is 1. It specifies how much ADI version information, at the -ratio of 1:ADI block size, to modify. +@var{n} is a decimal integer specifying the number in bytes; +the default is 1. It specifies how much ADI version information, at the +ratio of 1:ADI block size, to modify. -@var{addr} is the address in user address space where you want @value{GDBN} -to begin modifying the ADI version tags. +@var{addr} is the address in user address space where you want @value{GDBN} +to begin modifying the ADI version tags. @var{tag} is the new ADI version tag. -For example, do the following to modify then verify ADI versions of +For example, do the following to modify then verify ADI versions of variable "shmaddr": @smallexample @@ -27561,6 +27855,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}} @@ -27896,6 +28200,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 +28229,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}. @@ -28957,7 +29286,7 @@ Show the current state of @sc{gnu}/Hurd debugging messages. @item set debug infrun @cindex inferior debugging info Turns on or off display of @value{GDBN} debugging info for running the inferior. -The default is off. @file{infrun.c} contains GDB's runtime state machine used +The default is off. @file{infrun.c} contains GDB's runtime state machine used for implementing operations such as single-stepping the inferior. @item show debug infrun Displays the current state of @value{GDBN} inferior debugging. @@ -31214,138 +31543,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. - -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. +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. -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}). @@ -31366,7 +31570,7 @@ in the form of a reference manual. Note that @sc{gdb/mi} is still under construction, so some of the features described below are incomplete and subject to change -(@pxref{GDB/MI Development and Front Ends, , @sc{gdb/mi} Development and Front Ends}). +(@pxref{GDB/MI Development and Front Ends, , @sc{gdb/mi} Development and Front Ends}). @unnumberedsec Notation and Terminology @@ -31452,7 +31656,7 @@ a command and reported as part of that command response. The important examples of notifications are: @itemize @bullet -@item +@item Exec notifications. These are used to report changes in target state---when a target is resumed, or stopped. It would not be feasible to include this information in response of resuming @@ -31461,7 +31665,7 @@ different threads. Also, quite some time may pass before any event happens in the target, while a frontend needs to know whether the resuming command itself was successfully executed. -@item +@item Console output, and status notifications. Console output notifications are used to report output of CLI commands, as well as diagnostics for other commands. Status notifications are used to @@ -31481,8 +31685,8 @@ orthogonal frontend design. There's no guarantee that whenever an MI command reports an error, @value{GDBN} or the target are in any specific state, and especially, the state is not reverted to the state before the MI command was -processed. Therefore, whenever an MI command results in an error, -we recommend that the frontend refreshes all the information shown in +processed. Therefore, whenever an MI command results in an error, +we recommend that the frontend refreshes all the information shown in the user interface. @@ -31504,7 +31708,7 @@ be specified. The CLI interface maintains the selected thread and frame, and supplies them to target on each command. This is convenient, because a command line user would not want to specify that information explicitly on each command, and because user interacts with -@value{GDBN} via a single terminal, so no confusion is possible as +@value{GDBN} via a single terminal, so no confusion is possible as to what thread and frame are the current ones. In the case of MI, the concept of selected thread and frame is less @@ -31530,7 +31734,7 @@ frontend's selection to the one specified by user. @value{GDBN} communicates the suggestion to change current thread and frame using the @samp{=thread-selected} notification. -Note that historically, MI shares the selected thread with CLI, so +Note that historically, MI shares the selected thread with CLI, so frontends used the @code{-thread-select} to execute commands in the right context. However, getting this to work right is cumbersome. The simplest way is for frontend to emit @code{-thread-select} command @@ -31559,7 +31763,7 @@ For instance: @smallexample -data-evaluate-expression --language c "sizeof (void*)" ^done,value="4" -(gdb) +(gdb) @end smallexample The valid language names are the same names accepted by the @@ -31640,8 +31844,8 @@ hardware systems, each one having several cores with several different processes running on each core. This section describes the MI mechanism to support such debugging scenarios. -The key observation is that regardless of the structure of the -target, MI can have a global list of threads, because most commands that +The key observation is that regardless of the structure of the +target, MI can have a global list of threads, because most commands that accept the @samp{--thread} option do not need to know what process that thread belongs to. Therefore, it is not necessary to introduce neither additional @samp{--process} option, nor an notion of the @@ -32182,7 +32386,7 @@ A breakpoint was reached. A watchpoint was triggered. @item read-watchpoint-trigger A read watchpoint was triggered. -@item access-watchpoint-trigger +@item access-watchpoint-trigger An access watchpoint was triggered. @item function-finished An -exec-finish or similar CLI command was accomplished. @@ -32191,15 +32395,15 @@ An -exec-until or similar CLI command was accomplished. @item watchpoint-scope A watchpoint has gone out of scope. @item end-stepping-range -An -exec-next, -exec-next-instruction, -exec-step, -exec-step-instruction or +An -exec-next, -exec-next-instruction, -exec-step, -exec-step-instruction or similar CLI command was accomplished. -@item exited-signalled +@item exited-signalled The inferior exited because of a signal. -@item exited +@item exited The inferior exited. -@item exited-normally +@item exited-normally The inferior exited normally. -@item signal-received +@item signal-received A signal was received by the inferior. @item solib-event The inferior has stopped due to a library being loaded or unloaded. @@ -34272,8 +34476,8 @@ other cases. @end smallexample Resumes the execution of the inferior program, which will continue -to execute until it reaches a debugger stop event. If the -@samp{--reverse} option is specified, execution resumes in reverse until +to execute until it reaches a debugger stop event. If the +@samp{--reverse} option is specified, execution resumes in reverse until it reaches a stop event. Stop events may include @itemize @bullet @item @@ -35268,10 +35472,10 @@ object, or to change display format. Variable objects have hierarchical tree structure. Any variable object that corresponds to a composite type, such as structure in C, has a number of child variable objects, for example corresponding to each -element of a structure. A child variable object can itself have -children, recursively. Recursion ends when we reach +element of a structure. A child variable object can itself have +children, recursively. Recursion ends when we reach leaf variable objects, which always have built-in types. Child variable -objects are created only by explicit request, so if a frontend +objects are created only by explicit request, so if a frontend is not interested in the children of a particular variable object, no child will be created. @@ -35280,7 +35484,7 @@ string, or set the value from a string. String value can be also obtained for a non-leaf variable object, but it's generally a string that only indicates the type of the object, and does not list its contents. Assignment to a non-leaf variable object is not allowed. - + A frontend does not need to read the values of all variable objects each time the program stops. Instead, MI provides an update command that lists all variable objects whose values has changed since the last update @@ -35297,7 +35501,7 @@ relatively slow for embedded targets, so a frontend might want to disable automatic update for the variables that are either not visible on the screen, or ``closed''. This is possible using so called ``frozen variable objects''. Such variable objects are never -implicitly updated. +implicitly updated. Variable objects can be either @dfn{fixed} or @dfn{floating}. For the fixed variable object, the expression is parsed when the variable @@ -35538,8 +35742,8 @@ but with padding zeroes to the left of the value. For example, a 32-bit hexadecimal value of 0x1234 would be represented as 0x00001234 in the zero-hexadecimal format. -For a variable with children, the format is set only on the -variable itself, and the children are not affected. +For a variable with children, the format is set only on the +variable itself, and the children are not affected. @findex -var-show-format @subheading The @code{-var-show-format} Command @@ -35755,7 +35959,7 @@ Returns an expression that can be evaluated in the current context and will yield the same value that a variable object has. Compare this with the @code{-var-info-expression} command, which result can be used only for UI presentation. Typical use of -the @code{-var-info-path-expression} command is creating a +the @code{-var-info-path-expression} command is creating a watchpoint from a variable object. This command is currently not valid for children of a dynamic varobj, @@ -35800,10 +36004,10 @@ where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}. Evaluates the expression that is represented by the specified variable object and returns its value as a string. The format of the string -can be specified with the @samp{-f} option. The possible values of -this option are the same as for @code{-var-set-format} +can be specified with the @samp{-f} option. The possible values of +this option are the same as for @code{-var-set-format} (@pxref{-var-set-format}). If the @samp{-f} option is not specified, -the current display format will be used. The current display format +the current display format will be used. The current display format can be changed using the @code{-var-set-format} command. @smallexample @@ -35980,12 +36184,12 @@ type_changed="false"@}] Set the frozenness flag on the variable object @var{name}. The @var{flag} parameter should be either @samp{1} to make the variable frozen or @samp{0} to make it unfrozen. If a variable object is -frozen, then neither itself, nor any of its children, are -implicitly updated by @code{-var-update} of +frozen, then neither itself, nor any of its children, are +implicitly updated by @code{-var-update} of a parent variable or by @code{-var-update *}. Only @code{-var-update} of the variable itself will update its value and values of its children. After a variable object is unfrozen, it is -implicitly updated by all subsequent @code{-var-update} operations. +implicitly updated by all subsequent @code{-var-update} operations. Unfreezing a variable does not update it, only subsequent @code{-var-update} does. @@ -38319,7 +38523,7 @@ Signal handling commands are not implemented. Attach to a process @var{pid} or a file @var{file} outside of @value{GDBN}, or a thread group @var{gid}. If attaching to a thread -group, the id previously returned by +group, the id previously returned by @samp{-list-thread-groups --available} must be used. @subsubheading @value{GDBN} Command @@ -38872,7 +39076,7 @@ Example output: @smallexample (gdb) -list-features -^done,result=["feature1","feature2"] +^done,features=["feature1","feature2"] @end smallexample The current list of features is: @@ -38927,7 +39131,7 @@ to an array, structure, or union. @subheading The @code{-list-target-features} Command Returns a list of particular features that are supported by the -target. Those features affect the permitted MI commands, but +target. Those features affect the permitted MI commands, but unlike the features reported by the @code{-list-features} command, the features depend on which target GDB is using at the moment. Whenever a target can change, due to commands such as @code{-target-select}, @@ -38937,7 +39141,7 @@ Example output: @smallexample (gdb) -list-target-features -^done,result=["async"] +^done,features=["async"] @end smallexample The current list of features is: @@ -39315,6 +39519,11 @@ with no connection yet. You can then for example use the @code{gdbserver} instance, use @code{-exec-run} to spawn a local program, etc. +If the connection of the current inferior cannot be shared, e.g.@: the +@code{-target-select core} target cannot be shared between inferiors, +then @value{GDBN} will give a warning and create the new inferior +without a connection. + The command response always has a field, @var{inferior}, whose value is the identifier of the thread group corresponding to the new inferior. @@ -39386,7 +39595,7 @@ The corresponding @value{GDBN} command is @samp{remove-inferiors} @smallexample -interpreter-exec @var{interpreter} @var{command} @end smallexample -@anchor{-interpreter-exec} +@anchor{-interpreter-exec} Execute the specified @var{command} in the given @var{interpreter}. @@ -40013,7 +40222,7 @@ normal exception and not normally be logged. This chapter documents @value{GDBN}'s @dfn{just-in-time} (JIT) compilation interface. A JIT compiler is a program or library that generates native executable code at runtime and executes it, usually in order to achieve good -performance while maintaining platform independence. +performance while maintaining platform independence. Programs that use JIT compilation are normally difficult to debug because portions of their code are generated at runtime, instead of being loaded from @@ -41269,6 +41478,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 @@ -41356,7 +41573,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. @@ -41445,7 +41662,7 @@ If @value{GDBN} has been configured with the option @option{--prefix=$prefix}, they may be subject to relocation. Two possible cases: @itemize @bullet -@item +@item If the default location of this init file/directory contains @file{$prefix}, it will be subject to relocation. Suppose that the configure options are @option{--prefix=$prefix --with-system-gdbinit=$prefix/etc/gdbinit}; @@ -41554,6 +41771,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 @@ -41707,6 +41931,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 @@ -42683,6 +42908,26 @@ These are representative commands for each @var{kind} of setting type @value{GDBN} supports. They are used by the testsuite for exercising the settings infrastructure. +@kindex maint test-remote-args +@item maint test-remote-args @var{args} +For targets that don't support passing inferior arguments as a single +string (@pxref{single-inf-arg}), @value{GDBN} will attempt to split +the inferior arguments before passing them to the remote target, and +the remote target might choose to join the inferior arguments upon +receipt. Historically gdbserver did join inferior arguments, but now +it will request inferior arguments be passed as a single string if +@value{GDBN} supports this feature. + +This maintenance command splits @var{args} as @value{GDBN} would +normally split such an argument string before passing the arguments to +a remote target, the split arguments are then printed. + +The split arguments are then joined together as gdbserver would join +them, and the result is printed. + +This command is intended to help diagnose issues passing inferior +arguments to remote targets. + @kindex maint set backtrace-on-fatal-signal @kindex maint show backtrace-on-fatal-signal @item maint set backtrace-on-fatal-signal [on|off] @@ -42750,6 +42995,7 @@ reports and error and the command is aborted. @item show watchdog Show the current setting of the target wait timeout. + @end table @node Remote Protocol @@ -42843,7 +43089,7 @@ debugging stub incorporated in your program) sends a @var{response}. In the case of step and continue @var{command}s, the response is only sent when the operation has completed, and the target has again stopped all threads in all attached processes. This is the default all-stop mode -behavior, but the remote protocol also supports @value{GDBN}'s non-stop +behavior, but the remote protocol also supports @value{GDBN}'s non-stop execution mode; see @ref{Remote Non-Stop}, for details. @var{packet-data} consists of a sequence of characters with the @@ -42979,7 +43225,7 @@ bytes @samp{foo}, followed by a @var{bar}, followed directly by a @var{baz}. @cindex @var{thread-id}, in remote protocol -@anchor{thread-id syntax} +@anchor{thread-id syntax} Several packets and replies include a @var{thread-id} field to identify a thread. Normally these are positive numbers with a target-specific interpretation, formatted as big-endian hex strings. A @var{thread-id} @@ -43121,7 +43367,7 @@ Don't use this packet; instead, define a general set packet @item D @itemx D;@var{pid} @cindex @samp{D} packet -The first form of the packet is used to detach @value{GDBN} from the +The first form of the packet is used to detach @value{GDBN} from the remote system. It is sent to the remote target before @value{GDBN} disconnects via the @code{detach} command. @@ -43402,10 +43648,10 @@ attached without being stopped if that is supported by the target. @c In non-stop mode, on a successful vAttach, the stub should set the @c current thread to a thread of the newly-attached process. After @c attaching, GDB queries for the attached process's thread ID with qC. -@c Also note that, from a user perspective, whether or not the -@c target is stopped on attach in non-stop mode depends on whether you -@c use the foreground or background version of the attach command, not -@c on what vAttach does; GDB does the right thing with respect to either +@c Also note that, from a user perspective, whether or not the +@c target is stopped on attach in non-stop mode depends on whether you +@c use the foreground or background version of the attach command, not +@c on what vAttach does; GDB does the right thing with respect to either @c stopping or restarting threads. This packet is only available in extended mode (@pxref{extended mode}). @@ -43464,7 +43710,7 @@ in a degenerate way as a single instruction step operation.) @end table -The optional argument @var{addr} normally associated with the +The optional argument @var{addr} normally associated with the @samp{c}, @samp{C}, @samp{s}, and @samp{S} packets is not supported in @samp{vCont}. @@ -43606,6 +43852,12 @@ command line. The file and arguments are hex-encoded strings. If (e.g.@: the last program run). The program is created in the stopped state. +If @value{GDBN} sent the @samp{single-inf-arg} feature in the +@samp{qSupported} packet (@pxref{single-inf-arg}), and the stub replied +with @samp{single-inf-arg+}, then there will only be a single +@var{argument} string, which includes all inferior arguments, +separated with whitespace. + @c FIXME: What about non-stop mode? This packet is only available in extended mode (@pxref{extended mode}). @@ -43893,10 +44145,10 @@ list of loaded libraries. The @var{r} part is ignored. @cindex replay log events, remote reply @item replaylog -The packet indicates that the target cannot continue replaying +The packet indicates that the target cannot continue replaying logged execution events, because it has reached the end (or the beginning when executing backward) of the log. The value of @var{r} -will be either @samp{begin} or @samp{end}. @xref{Reverse Execution}, +will be either @samp{begin} or @samp{end}. @xref{Reverse Execution}, for more information. @item swbreak @@ -44148,7 +44400,7 @@ Return the current thread ID. Reply: @table @samp @item QC @var{thread-id} -Where @var{thread-id} is a thread ID as documented in +Where @var{thread-id} is a thread ID as documented in @ref{thread-id syntax}. @item @r{(anything else)} Any other reply implies the old thread ID. @@ -44402,7 +44654,7 @@ information associated with the variable.) @var{lm} is the (big endian, hex encoded) OS/ABI-specific encoding of the load module associated with the thread local storage. For example, a @sc{gnu}/Linux system will pass the link map address of the shared -object associated with the thread local storage under consideration. +object associated with the thread local storage under consideration. Other operating environments may choose to represent the load module differently, so the precise meaning of this parameter will vary. @@ -44573,7 +44825,7 @@ kept at fixed offsets relative to the last relocated segment. @cindex thread information, remote request @cindex @samp{qP} packet Returns information on @var{thread-id}. Where: @var{mode} is a hex -encoded 32 bit mode; @var{thread-id} is a thread ID +encoded 32 bit mode; @var{thread-id} is a thread ID (@pxref{thread-id syntax}). Don't use this packet; use the @samp{qThreadExtraInfo} query instead @@ -44597,7 +44849,7 @@ The request succeeded. This packet is not probed by default; the remote stub must request it, by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). -Use of this packet is controlled by the @code{set non-stop} command; +Use of this packet is controlled by the @code{set non-stop} command; @pxref{Non-Stop Mode}. @item QCatchSyscalls:1 @r{[};@var{sysno}@r{]}@dots{} @@ -44640,7 +44892,7 @@ by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). @cindex pass signals to inferior, remote request @cindex @samp{QPassSignals} packet @anchor{QPassSignals} -Each listed @var{signal} should be passed directly to the inferior process. +Each listed @var{signal} should be passed directly to the inferior process. Signals are numbered identically to continue packets and stop replies (@pxref{Stop Reply Packets}). Each @var{signal} list item should be strictly greater than the previous item. These signals do not need to stop @@ -44847,7 +45099,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 @@ -44928,11 +45181,11 @@ state, even if the stub had previously been communicating with a different version of @value{GDBN}. The following values of @var{gdbfeature} (for the packet sent by @value{GDBN}) -are defined: +are defined: @table @samp @item multiprocess -This feature indicates whether @value{GDBN} supports multiprocess +This feature indicates whether @value{GDBN} supports multiprocess extensions to the remote protocol. @value{GDBN} does not use such extensions unless the stub also reports that it supports them by including @samp{multiprocess+} in its @samp{qSupported} reply. @@ -44989,6 +45242,14 @@ didn't support @samp{E.@var{errtext}}, and older versions of New packets should be written to support @samp{E.@var{errtext}} regardless of this feature being true or not. + +@anchor{single-inf-arg} +@item single-inf-arg +This feature indicates that @value{GDBN} would like to send the +inferior arguments as a single string within the @samp{vRun} packet. +@value{GDBN} will not send the arguments as a single string unless the +stub also reports that it supports this behaviour by including +@samp{single-inf-arg+} in its @samp{qSupported} reply. @end table Stubs should ignore any unknown values for @@ -45292,6 +45553,11 @@ These are the currently defined stub features and their properties: @tab @samp{-} @tab No +@item @samp{single-inf-arg} +@tab No +@tab @samp{-} +@tab No + @end multitable These are the currently defined stub features, in more detail: @@ -45541,6 +45807,12 @@ if it sent the @samp{error-message} feature. @item binary-upload The remote stub supports the @samp{x} packet (@pxref{x packet}). + +@item single-inf-arg +The remote stub would like to receive the inferior arguments as a +single string within the @samp{vRun} packet. The stub should only +send this feature if @value{GDBN} sent @samp{single-inf-arg+} in the +@samp{qSupported} packet. @end table @item qSymbol:: @@ -45624,13 +45896,13 @@ packets.) @itemx QTSave @itemx qTsP @itemx qTsV -@itemx QTStart -@itemx QTStop +@itemx QTStart +@itemx QTStop @itemx QTEnable @itemx QTDisable -@itemx QTinit -@itemx QTro -@itemx qTStatus +@itemx QTinit +@itemx QTro +@itemx qTStatus @itemx qTV @itemx qTfSTM @itemx qTsSTM @@ -45758,7 +46030,7 @@ stub indicated it supports the augmented form of this packet by supplying an appropriate @samp{qSupported} response (@pxref{qXfer read}, @ref{qSupported}). -This packet is optional for better performance on SVR4 targets. +This packet is optional for better performance on SVR4 targets. @value{GDBN} uses memory read packets to read the SVR4 library list otherwise. This packet is not probed by default; the remote stub must request it, @@ -45929,6 +46201,45 @@ The remote server attached to an existing process. The remote server created a new process. @end table +@cindex query executable, remote request +@cindex query program arguments, remote request +@cindex @samp{qExecAndArgs} packet +@item qExecAndArgs +@anchor{qExecAndArgs} +Return the program filename and arguments string with which the remote +server was started, if the remote server was started with such things. +If the remote server was started without the filename of a program to +execute, or without any arguments, then the reply indicates this. + +Reply: +@table @samp +@item U +The program filename and arguments are unset. If @value{GDBN} wants +to start a new inferior, for example with @samp{vRun}, then it will +need to provide the filename of a program to use. + +@item S;@var{prog};@var{args}; +@itemx S;;@var{args}; +The program filename provided to the remote server when it started was +@var{prog}, which is a hex encoded string. The complete argument +string passed to the inferior when it started as @var{args}, this is +also a hex encoded string. + +If no arguments were passed when the inferior started then @var{args} +be an empty string. + +It is valid for @var{prog} to be the empty string, this indicates that +the server has no program set, @value{GDBN} will need to supply a +program name in order to start a new inferior. It is valid to reply +with an empty @var{prog} and non-empty @var{args}, @value{GDBN} will +set the inferior arguments, but the user will need to supply a remote +exec-file before an inferior can be started. + +The argument string @var{args} is passed directly to @value{GDBN} as +if to the @kbd{set args} command. And escaping required should be +present in @var{args}, no changes are made by @value{GDBN}. +@end table + @item Qbtrace:bts Enable branch tracing for the current thread using Branch Trace Store. @@ -46726,12 +47037,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. @@ -46801,7 +47128,7 @@ packet}) with the usual packet framing instead of the single byte Stubs are not required to recognize these interrupt mechanisms and the precise meaning associated with receipt of the interrupt is implementation defined. If the target supports debugging of multiple -threads and/or processes, it should attempt to interrupt all +threads and/or processes, it should attempt to interrupt all currently-executing threads and processes. If the stub is successful at interrupting the running program, it should send one of the stop @@ -46933,7 +47260,7 @@ The following notifications are defined: @tab vStopped @tab @var{reply}. The @var{reply} has the form of a stop reply, as described in @ref{Stop Reply Packets}. Refer to @ref{Remote Non-Stop}, -for information on how these notifications are acknowledged by +for information on how these notifications are acknowledged by @value{GDBN}. @tab Report an asynchronous stop event in non-stop mode. @@ -46967,7 +47294,7 @@ to run. When reporting a @samp{W} or @samp{X} response, all running threads belonging to other attached processes continue to run. In non-stop mode, the target shall respond to the @samp{?} packet as -follows. First, any incomplete stop reply notification/@samp{vStopped} +follows. First, any incomplete stop reply notification/@samp{vStopped} sequence in progress is abandoned. The target must begin a new sequence reporting stop events for all stopped threads, whether or not it has previously reported those events to @value{GDBN}. The first @@ -47102,12 +47429,12 @@ It uses its own internal representation of datatypes and values. Both translating the system-dependent value representations into the internal protocol representations when data is transmitted. -The communication is synchronous. A system call is possible only when -@value{GDBN} is waiting for a response from the @samp{C}, @samp{c}, @samp{S} +The communication is synchronous. A system call is possible only when +@value{GDBN} is waiting for a response from the @samp{C}, @samp{c}, @samp{S} or @samp{s} packets. While @value{GDBN} handles the request for a system call, the target is stopped to allow deterministic access to the target's memory. Therefore File-I/O is not interruptible by target signals. On -the other hand, it is possible to interrupt File-I/O by a user interrupt +the other hand, it is possible to interrupt File-I/O by a user interrupt (@samp{Ctrl-C}) within @value{GDBN}. The target's request to perform a host system call does not finish @@ -47125,7 +47452,7 @@ request from @value{GDBN} is required. <- target hits breakpoint and sends a Txx packet @end smallexample -The protocol only supports I/O on the console and to regular files on +The protocol only supports I/O on the console and to regular files on the host file system. Character or block special devices, pipes, named pipes, sockets or any other communication method on the host system are not supported by this protocol. @@ -47138,7 +47465,7 @@ File I/O is not supported in non-stop mode. The File-I/O protocol uses the @code{F} packet as the request as well as reply packet. Since a File-I/O system call can only occur when -@value{GDBN} is waiting for a response from the continuing or stepping target, +@value{GDBN} is waiting for a response from the continuing or stepping target, the File-I/O request is a reply that @value{GDBN} has to expect as a result of a previous @samp{C}, @samp{c}, @samp{S} or @samp{s} packet. This @code{F} packet contains all information needed to allow @value{GDBN} @@ -47160,7 +47487,7 @@ At this point, @value{GDBN} has to perform the following actions. @itemize @bullet @item -If the parameters include pointer values to data needed as input to a +If the parameters include pointer values to data needed as input to a system call, @value{GDBN} requests this data from the target with a standard @code{m} packet request. This additional communication has to be expected by the target implementation and is handled as any other @code{m} @@ -47216,11 +47543,11 @@ The @code{F} request packet has the following format: @var{call-id} is the identifier to indicate the host system call to be called. This is just the name of the function. -@var{parameter@dots{}} are the parameters to the system call. +@var{parameter@dots{}} are the parameters to the system call. Parameters are hexadecimal integer values, either the actual values in case of scalar datatypes, pointers to target buffer space in case of compound datatypes and unspecified memory areas, or pointer/length pairs in case -of string parameters. These are appended to the @var{call-id} as a +of string parameters. These are appended to the @var{call-id} as a comma-delimited list. All values are transmitted in ASCII string representation, pointer/length pairs separated by a slash. @@ -47888,10 +48215,10 @@ The call was interrupted by the user. @end table -@value{GDBN} takes over the full task of calling the necessary host calls -to perform the @code{system} call. The return value of @code{system} on +@value{GDBN} takes over the full task of calling the necessary host calls +to perform the @code{system} call. The return value of @code{system} on the host is simplified before it's returned -to the target. Any termination signal information from the child process +to the target. Any termination signal information from the child process is discarded, and the return value consists entirely of the exit status of the called command. @@ -47927,9 +48254,9 @@ protocol. @unnumberedsubsubsec Integral Datatypes @cindex integral datatypes, in file-i/o protocol -The integral datatypes used in the system calls are @code{int}, +The integral datatypes used in the system calls are @code{int}, @code{unsigned int}, @code{long}, @code{unsigned long}, -@code{mode_t}, and @code{time_t}. +@code{mode_t}, and @code{time_t}. @code{int}, @code{unsigned int}, @code{mode_t} and @code{time_t} are implemented as 32 bit values in this protocol. @@ -47973,10 +48300,10 @@ at address 0x123456 is transmitted as @cindex memory transfer, in file-i/o protocol Structured data which is transferred using a memory read or write (for -example, a @code{struct stat}) is expected to be in a protocol-specific format +example, a @code{struct stat}) is expected to be in a protocol-specific format with all scalar multibyte datatypes being big endian. Translation to -this representation needs to be done both by the target before the @code{F} -packet is sent, and by @value{GDBN} before +this representation needs to be done both by the target before the @code{F} +packet is sent, and by @value{GDBN} before it transfers memory to the target. Transferred pointers to structured data should point to the already-coerced data at any time. @@ -47985,7 +48312,7 @@ data should point to the already-coerced data at any time. @unnumberedsubsubsec struct stat @cindex struct stat, in file-i/o protocol -The buffer of type @code{struct stat} used by the target and @value{GDBN} +The buffer of type @code{struct stat} used by the target and @value{GDBN} is defined as follows: @smallexample @@ -48126,6 +48453,7 @@ All values are given in decimal representation. EPERM 1 ENOENT 2 EINTR 4 + EIO 5 EBADF 9 EACCES 13 EFAULT 14 @@ -48141,6 +48469,7 @@ All values are given in decimal representation. ENOSPC 28 ESPIPE 29 EROFS 30 + ENOSYS 88 ENAMETOOLONG 91 EUNKNOWN 9999 @end smallexample @@ -49199,6 +49528,7 @@ registers using the capitalization used in the description. @menu * AArch64 Features:: +* Alpha Features:: * ARC Features:: * ARM Features:: * i386 Features:: @@ -49505,6 +49835,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 @@ -49854,9 +50282,9 @@ targets. It should describe the following registers: @item @samp{eflags}, @samp{cs}, @samp{ss}, @samp{ds}, @samp{es}, @samp{fs}, @samp{gs} -@item +@item @samp{st0} through @samp{st7} -@item +@item @samp{fctrl}, @samp{fstat}, @samp{ftag}, @samp{fiseg}, @samp{fioff}, @samp{foseg}, @samp{fooff} and @samp{fop} @end itemize @@ -49871,7 +50299,7 @@ describe registers: @samp{xmm0} through @samp{xmm7} for i386 @item @samp{xmm0} through @samp{xmm15} for amd64 -@item +@item @samp{mxcsr} @end itemize @@ -49938,6 +50366,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 @@ -49999,7 +50433,7 @@ Linux kernel to control restartable syscalls. @item @samp{org.gnu.gdb.m68k.core} @itemx @samp{org.gnu.gdb.coldfire.core} @itemx @samp{org.gnu.gdb.fido.core} -One of those features must be always present. +One of those features must be always present. The feature that is present determines which flavor of m68k is used. The feature that is present should contain registers @samp{d0} through @samp{d7}, @samp{a0} through @samp{a5}, @samp{fp}, @@ -50303,7 +50737,7 @@ contain registers @samp{TSR}, @samp{ILC} and @samp{RILC}. Users of @value{GDBN} often wish to obtain information about the state of the operating system running on the target---for example the list of processes, or the list of open files. This section describes the -mechanism that makes it possible. This mechanism is similar to the +mechanism that makes it possible. This mechanism is similar to the target features mechanism (@pxref{Target Descriptions}), but focuses on a different aspect of target. @@ -50457,17 +50891,13 @@ unless otherwise noted: @enumerate @item -The version number, currently 9. Versions 1, 2 and 3 are obsolete. -Version 4 uses a different hashing function from versions 5 and 6. -Version 6 includes symbols for inlined functions, whereas versions 4 -and 5 do not. Version 7 adds attributes to the CU indices in the -symbol table. Version 8 specifies that symbols from DWARF type units +The version number, currently 9. Versions 1 through 6 are obsolete. +Version 7 adds attributes to the CU indices in the symbol table. +Version 8 specifies that symbols from DWARF type units (@samp{DW_TAG_type_unit}) refer to the type unit's symbol table and not the compilation unit (@samp{DW_TAG_comp_unit}) using the type. Version 9 adds the name and the language of the main function to the index. -@value{GDBN} will only read version 4, 5, or 6 indices -by specifying @code{set use-deprecated-index-sections on}. GDB has a workaround for potentially broken version 7 indices so it is currently not flagged as deprecated. @@ -50486,7 +50916,8 @@ The offset, from the start of the file, of the address area. The offset, from the start of the file, of the symbol table. @item -The offset, from the start of the file, of the shortcut table. +The offset, from the start of the file, of the shortcut table. This +field was introduced with index version 9. @item The offset, from the start of the file, of the constant pool. @@ -50579,6 +51010,8 @@ in the constant pool. This value must be ignored if the value for the language of main is zero. @end table +This data structure was introduced in index version 9. + @item The constant pool. This is simply a bunch of bytes. It is organized so that alignment is correct: CU vectors are stored first, followed by @@ -51011,9 +51444,10 @@ Note that targets that give their output via @value{GDBN}, as opposed to writing directly to @code{stdout}, will also be made silent. @item --args @var{prog} [@var{arglist}] -Change interpretation of command line so that arguments following this -option are passed as arguments to the inferior. As an example, take -the following command: +@itemx --no-escape-args @var{prog} [@var{arglist}] +Change interpretation of command line so that arguments following +either of these options are passed as arguments to the inferior. As +an example, take the following command: @smallexample gdb ./a.out -q @@ -51028,7 +51462,44 @@ gdb --args ./a.out -q @end smallexample @noindent -starts @value{GDBN} with the introductory message, and passes the option to the inferior. +starts @value{GDBN} with the introductory message, and passes the +option @code{-q} to the inferior. + +The difference between @option{--args} and @option{--no-escape-args} +is whether @value{GDBN} applies escapes to the arguments it sees: + +@smallexample +gdb --args ./a.out *.c +@end smallexample + +@noindent +in this case the @code{*.c} is expanded by the shell that invokes +@value{GDBN}, the list of matching files will be fixed in the inferior +argument list. If instead this is used: + +@smallexample +gdb --args ./a.out '*.c' +@end smallexample + +@noindent +then the shell that invokes @value{GDBN} will not expand @code{*.c}, +instead @value{GDBN} will escape the @code{*} character, so when a.out +is invoked it will be passed a literal @code{*.c}. If instead this is +used: + +@smallexample +gdb --no-escape-args ./a.out '*.c' +@end smallexample + +@noindent +now @value{GDBN} will not escape the @code{*} character. When the +inferior is invoked the @code{*.c} will be expanded, and the inferior +will be passed the list of files as present at the time the inferior +is invoked. + +This change of behaviour can be important if the list of matching +files could change between the time that @value{GDBN} is started, and +the time the inferior is started. @item --pid=@var{pid} Attach @value{GDBN} to an already running program, with the PID @var{pid}. @@ -51370,6 +51841,18 @@ additional connections are possible. However, if you start @code{gdbserver} with the @option{--once} option, it will stop listening for any further connection attempts after connecting to the first @value{GDBN} session. +@item --no-escape-args +By default, inferior arguments passed on the @command{gdbserver} +command line will have any special shell characters escaped by +@command{gdbserver}. This ensures that when @command{gdbserver} +invokes the inferior, the arguments passed to the inferior are +identical to the arguments passed to @command{gdbserver}. + +To disable this escaping, use @option{--no-escape-args}. With this +option special shell characters will not be escaped. When +@command{gdbserver} starts a new shell in order to invoke the +inferior, this new shell will expand any special shell characters. + @c --disable-packet is not documented for users. @c --disable-randomization and --no-disable-randomization are superseded by @@ -51432,6 +51915,12 @@ composed as @file{@var{prefix}.@var{pid}}, where @var{pid} is the process ID of the running program being analyzed by @command{gcore}. If not specified, @var{prefix} defaults to @var{core}. +@item -g @var{gdb} +Use @var{gdb} as the executable binary to invoke @value{GDBN} for +running the gcore command. This argument is optional, and defaults to +invoking the @value{GDBN} binary that is installed alongside +@command{gcore}. + @item -d @var{directory} Use @var{directory} as the data directory when invoking @value{GDBN} for running the gcore command. This argument is optional. diff --git a/gdb/doc/guile.texi b/gdb/doc/guile.texi index c6808ef..fcedef0 100644 --- a/gdb/doc/guile.texi +++ b/gdb/doc/guile.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.'' @@ -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}. @@ -1826,7 +1836,7 @@ $1 = ("1" "2 \"3" "4 \"5" "6 '7") @deffn {Scheme Procedure} throw-user-error message . args Throw a @code{gdb:user-error} exception. -The argument @var{message} is the error message as a format string, like the +The argument @var{message} is the error message as a format string, like the @var{fmt} argument to the @code{format} Scheme function. @xref{Formatted Output,,, guile, GNU Guile Reference Manual}. The argument @var{args} is a list of the optional arguments of @var{message}. @@ -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. @@ -2425,7 +2437,7 @@ The previous frame's analyzer returns an invalid result. This frame is the outermost. @item 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 FRAME_UNWIND_INNER_ID @@ -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 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 |