diff options
Diffstat (limited to 'gdb/doc')
| -rw-r--r-- | gdb/doc/gdb.texinfo | 370 | ||||
| -rw-r--r-- | gdb/doc/python.texi | 21 |
2 files changed, 351 insertions, 40 deletions
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 2bbaf14..a13d5c0 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} @@ -13104,11 +13173,11 @@ variable which may be @samp{truecolor} or @samp{24bit}. Other color spaces are determined by the "Co" termcap which in turn depends on the @env{TERM} environment variable. -@vindex $_active_linker_namespaces@r{, convenience variable} -@item $_active_linker_namespaces +@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, this variable will always be set to -@samp{1}. +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 @@ -26996,6 +27065,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 @@ -27037,6 +27132,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 @@ -38880,7 +39015,7 @@ Example output: @smallexample (gdb) -list-features -^done,result=["feature1","feature2"] +^done,features=["feature1","feature2"] @end smallexample The current list of features is: @@ -38945,7 +39080,7 @@ Example output: @smallexample (gdb) -list-target-features -^done,result=["async"] +^done,features=["async"] @end smallexample The current list of features is: @@ -41277,6 +41412,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 @@ -41722,6 +41865,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 @@ -42698,6 +42842,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] @@ -42766,22 +42930,6 @@ reports and error and the command is aborted. @item show watchdog Show the current setting of the target wait timeout. -@kindex maint set console-translation-mode -@kindex maint show console-translation-mode -@item maint set console-translation-mode @r{[}binary|text@r{]} -@itemx maint show console-translation-mode -Controls the translation mode of @value{GDBN} stdout/stderr. MS-Windows -only. Useful for running the @value{GDBN} testsuite. - -The translation mode values are as follows: -@table @code -@item binary -No translation. -@item text -Translate @samp{\n} (LF, a single Line Feed) into @samp{\r\n} (CR-LF, a -Carriage Return-Line Feed combination). -@end table - @end table @node Remote Protocol @@ -43638,6 +43786,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}). @@ -44879,7 +45033,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 @@ -45021,6 +45176,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 @@ -45324,6 +45487,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: @@ -45573,6 +45741,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:: @@ -49554,6 +49728,63 @@ 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 @@ -50028,6 +50259,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 @@ -50547,17 +50784,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. @@ -50576,7 +50809,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. @@ -50669,6 +50903,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 @@ -51101,9 +51337,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 @@ -51118,7 +51355,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}. @@ -51460,6 +51734,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 @@ -51522,6 +51808,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/python.texi b/gdb/doc/python.texi index 6fa2285..3763eee 100644 --- a/gdb/doc/python.texi +++ b/gdb/doc/python.texi @@ -910,7 +910,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 |