\input texinfo @c -*-texinfo-*-
-@c Copyright (C) 1988-2016 Free Software Foundation, Inc.
+@c Copyright (C) 1988-2017 Free Software Foundation, Inc.
@c
@c %**start of header
@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use
@copying
@c man begin COPYRIGHT
-Copyright @copyright{} 1988-2016 Free Software Foundation, Inc.
+Copyright @copyright{} 1988-2017 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@end ifset
Version @value{GDBVN}.
-Copyright (C) 1988-2016 Free Software Foundation, Inc.
+Copyright (C) 1988-2017 Free Software Foundation, Inc.
This edition of the GDB manual is dedicated to the memory of Fred
Fish. Fred was a long-standing contributor to GDB and to Free
Michael Eager and staff of Xilinx, Inc., contributed support for the
Xilinx MicroBlaze architecture.
+Initial support for the FreeBSD/mips target and native configuration
+was developed by SRI International and the University of Cambridge
+Computer Laboratory under DARPA/AFRL contract FA8750-10-C-0237
+("CTSRD"), as part of the DARPA CRASH research programme.
+
@node Sample Session
@chapter A Sample @value{GDBN} Session
your program. @xref{Environment, ,Your Program's Environment}.
@item The @emph{working directory.}
-Your program inherits its working directory from @value{GDBN}. You can set
-the @value{GDBN} working directory with the @code{cd} command in @value{GDBN}.
+You can set your program's working directory with the command
+@kbd{set cwd}. If you do not set any working directory with this
+command, your program will inherit @value{GDBN}'s working directory.
@xref{Working Directory, ,Your Program's Working Directory}.
@item The @emph{standard input and output.}
@samp{start} or @samp{run}.
It is sometimes necessary to debug the program during elaboration. In
-these cases, using the @code{start} command would stop the execution of
-your program too late, as the program would have already completed the
-elaboration phase. Under these circumstances, insert breakpoints in your
-elaboration code before running your program.
+these cases, using the @code{start} command would stop the execution
+of your program too late, as the program would have already completed
+the elaboration phase. Under these circumstances, either insert
+breakpoints in your elaboration code before running your program or
+use the @code{starti} command.
+
+@kindex starti
+@item starti
+@cindex run to first instruction
+The @samp{starti} command does the equivalent of setting a temporary
+breakpoint at the first instruction of a program's execution and then
+invoking the @samp{run} command. For programs containing an
+elaboration phase, the @code{starti} command will stop execution at
+the start of the elaboration phase.
@anchor{set exec-wrapper}
@kindex set exec-wrapper
@sc{djgpp}, Cygwin, MS Windows, and QNX Neutrino.
@kindex set startup-with-shell
+@anchor{set startup-with-shell}
@item set startup-with-shell
@itemx set startup-with-shell on
@itemx set startup-with-shell off
-@itemx show set startup-with-shell
+@itemx show startup-with-shell
On Unix systems, by default, if a shell is available on your target,
@value{GDBN}) uses it to start your program. Arguments of the
@code{run} command are passed to the shell, which does variable
your program. You can abbreviate @code{environment} as @code{env}.
@kindex set environment
+@anchor{set environment}
@item set environment @var{varname} @r{[}=@var{value}@r{]}
Set environment variable @var{varname} to @var{value}. The value
changes for your program (and the shell @value{GDBN} uses to launch
wrapper instead of using @code{set environment}. @xref{set
exec-wrapper}, for an example doing just that.
+Environment variables that are set by the user are also transmitted to
+@command{gdbserver} to be used when starting the remote inferior.
+@pxref{QEnvironmentHexEncoded}.
+
@kindex unset environment
+@anchor{unset environment}
@item unset environment @var{varname}
Remove variable @var{varname} from the environment to be passed to your
program. This is different from @samp{set env @var{varname} =};
@code{unset environment} removes the variable from the environment,
rather than assigning it an empty value.
+
+Environment variables that are unset by the user are also unset on
+@command{gdbserver} when starting the remote inferior.
+@pxref{QEnvironmentUnset}.
@end table
@emph{Warning:} On Unix systems, @value{GDBN} runs your program using
@section Your Program's Working Directory
@cindex working directory (of your program)
-Each time you start your program with @code{run}, it inherits its
-working directory from the current working directory of @value{GDBN}.
-The @value{GDBN} working directory is initially whatever it inherited
-from its parent process (typically the shell), but you can specify a new
-working directory in @value{GDBN} with the @code{cd} command.
-
-The @value{GDBN} working directory also serves as a default for the commands
-that specify files for @value{GDBN} to operate on. @xref{Files, ,Commands to
-Specify Files}.
+Each time you start your program with @code{run}, the inferior will be
+initialized with the current working directory specified by the
+@kbd{set cwd} command. If no directory has been specified by this
+command, then the inferior will inherit @value{GDBN}'s current working
+directory as its working directory.
+
+@table @code
+@kindex set cwd
+@cindex change inferior's working directory
+@anchor{set cwd command}
+@item set cwd @r{[}@var{directory}@r{]}
+Set the inferior's working directory to @var{directory}, which will be
+@code{glob}-expanded in order to resolve tildes (@file{~}). If no
+argument has been specified, the command clears the setting and resets
+it to an empty state. This setting has no effect on @value{GDBN}'s
+working directory, and it only takes effect the next time you start
+the inferior. The @file{~} in @var{directory} is a short for the
+@dfn{home directory}, usually pointed to by the @env{HOME} environment
+variable. On MS-Windows, if @env{HOME} is not defined, @value{GDBN}
+uses the concatenation of @env{HOMEDRIVE} and @env{HOMEPATH} as
+fallback.
+
+You can also change @value{GDBN}'s current working directory by using
+the @code{cd} command.
+@xref{cd command}
+
+@kindex show cwd
+@cindex show inferior's working directory
+@item show cwd
+Show the inferior's working directory. If no directory has been
+specified by @kbd{set cwd}, then the default inferior's working
+directory is the same as @value{GDBN}'s working directory.
-@table @code
@kindex cd
-@cindex change working directory
+@cindex change @value{GDBN}'s working directory
+@anchor{cd command}
@item cd @r{[}@var{directory}@r{]}
Set the @value{GDBN} working directory to @var{directory}. If not
given, @var{directory} uses @file{'~'}.
+The @value{GDBN} working directory serves as a default for the
+commands that specify files for @value{GDBN} to operate on.
+@xref{Files, ,Commands to Specify Files}.
+@xref{set cwd command}
+
@kindex pwd
@item pwd
Print the @value{GDBN} working directory.
enable it again.
@cindex breakpoint ranges
+@cindex breakpoint lists
@cindex ranges of breakpoints
-Some @value{GDBN} commands accept a range of breakpoints on which to
-operate. A breakpoint range is either a single breakpoint number, like
-@samp{5}, or two such numbers, in increasing order, separated by a
-hyphen, like @samp{5-7}. When a breakpoint range is given to a command,
-all breakpoints in that range are operated on.
+@cindex lists of breakpoints
+Some @value{GDBN} commands accept a space-separated list of breakpoints
+on which to operate. A list element can be either a single breakpoint number,
+like @samp{5}, or a range of such numbers, like @samp{5-7}.
+When a breakpoint list is given to a command, all breakpoints in that list
+are operated on.
@menu
* Set Breaks:: Setting breakpoints
@kindex info breakpoints
@cindex @code{$_} and @code{info breakpoints}
-@item info breakpoints @r{[}@var{n}@dots{}@r{]}
-@itemx info break @r{[}@var{n}@dots{}@r{]}
+@item info breakpoints @r{[}@var{list}@dots{}@r{]}
+@itemx info break @r{[}@var{list}@dots{}@r{]}
Print a table of all breakpoints, watchpoints, and catchpoints set and
not deleted. Optional argument @var{n} means print information only
about the specified breakpoint(s) (or watchpoint(s) or catchpoint(s)).
breakpoints set with @code{hbreak}, @value{GDBN} will always use hardware
breakpoints.
-You can control this automatic behaviour with the following commands::
+You can control this automatic behaviour with the following commands:
@kindex set breakpoint auto-hw
@kindex show breakpoint auto-hw
Set a watchpoint that will break when @var{expr} is either read from
or written into by the program.
-@kindex info watchpoints @r{[}@var{n}@dots{}@r{]}
-@item info watchpoints @r{[}@var{n}@dots{}@r{]}
+@kindex info watchpoints @r{[}@var{list}@dots{}@r{]}
+@item info watchpoints @r{[}@var{list}@dots{}@r{]}
This command prints a list of watchpoints, using the same format as
@code{info break} (@pxref{Set Breaks}).
@end table
@cindex delete breakpoints
@kindex delete
@kindex d @r{(@code{delete})}
-@item delete @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
+@item delete @r{[}breakpoints@r{]} @r{[}@var{list}@dots{}@r{]}
Delete the breakpoints, watchpoints, or catchpoints of the breakpoint
-ranges specified as arguments. If no argument is specified, delete all
+list specified as argument. If no argument is specified, delete all
breakpoints (@value{GDBN} asks confirmation, unless you have @code{set
confirm off}). You can abbreviate this command as @code{d}.
@end table
@table @code
@kindex disable
@kindex dis @r{(@code{disable})}
-@item disable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
+@item disable @r{[}breakpoints@r{]} @r{[}@var{list}@dots{}@r{]}
Disable the specified breakpoints---or all breakpoints, if none are
listed. A disabled breakpoint has no effect but is not forgotten. All
options such as ignore-counts, conditions and commands are remembered in
@code{disable} as @code{dis}.
@kindex enable
-@item enable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
+@item enable @r{[}breakpoints@r{]} @r{[}@var{list}@dots{}@r{]}
Enable the specified breakpoints (or all defined breakpoints). They
become effective once again in stopping your program.
-@item enable @r{[}breakpoints@r{]} once @var{range}@dots{}
+@item enable @r{[}breakpoints@r{]} once @var{list}@dots{}
Enable the specified breakpoints temporarily. @value{GDBN} disables any
of these breakpoints immediately after stopping your program.
-@item enable @r{[}breakpoints@r{]} count @var{count} @var{range}@dots{}
+@item enable @r{[}breakpoints@r{]} count @var{count} @var{list}@dots{}
Enable the specified breakpoints temporarily. @value{GDBN} records
@var{count} with each of the specified breakpoints, and decrements a
breakpoint's count when it is hit. When any count reaches 0,
count (@pxref{Conditions, ,Break Conditions}), that will be
decremented to 0 before @var{count} is affected.
-@item enable @r{[}breakpoints@r{]} delete @var{range}@dots{}
+@item enable @r{[}breakpoints@r{]} delete @var{list}@dots{}
Enable the specified breakpoints to work once, then die. @value{GDBN}
deletes any of these breakpoints as soon as your program stops there.
Breakpoints set by the @code{tbreak} command start out in this state.
@table @code
@kindex commands
@kindex end@r{ (breakpoint commands)}
-@item commands @r{[}@var{range}@dots{}@r{]}
+@item commands @r{[}@var{list}@dots{}@r{]}
@itemx @dots{} @var{command-list} @dots{}
@itemx end
Specify a list of commands for the given breakpoints. The commands
print commands, simply define normal breakpoints with
explicitly-supplied command lists.)
+@table @code
@item gdb
@kindex dprintf-style gdb
Handle the output using the @value{GDBN} @code{printf} command.
Have the remote debugging agent (such as @code{gdbserver}) handle
the output itself. This style is only available for agents that
support running commands on the target.
+@end table
@item set dprintf-function @var{function}
Set the function to call if the dprintf style is @code{call}. By
location of the relocation table. On some architectures, @value{GDBN}
might be able to resolve these to actual function names.
+@table @code
+@kindex set disassembler-options
+@cindex disassembler options
+@item set disassembler-options @var{option1}[,@var{option2}@dots{}]
+This command controls the passing of target specific information to
+the disassembler. For a list of valid options, please refer to the
+@code{-M}/@code{--disassembler-options} section of the @samp{objdump}
+manual and/or the output of @kbd{objdump --help}
+(@pxref{objdump,,objdump,binutils.info,The GNU Binary Utilities}).
+The default value is the empty string.
+
+If it is necessary to specify more than one disassembler option, then
+multiple options can be placed together into a comma separated list.
+Currently this command is only supported on targets ARM, PowerPC
+and S/390.
+
+@kindex show disassembler-options
+@item show disassembler-options
+Show the current setting of the disassembler options.
+@end table
+
@table @code
@kindex set disassembly-flavor
@cindex Intel disassembly flavor
by the debug information, @value{GDBN} will say @samp{<incomplete
type>}. @xref{Symbols, incomplete type}, for more about this.
+@cindex no debug info variables
+If you try to examine or use the value of a (global) variable for
+which @value{GDBN} has no type information, e.g., because the program
+includes no debug information, @value{GDBN} displays an error message.
+@xref{Symbols, unknown type}, for more about unknown types. If you
+cast the variable to its declared type, @value{GDBN} gets the
+variable's value using the cast-to type as the variable's type. For
+example, in a C program:
+
+@smallexample
+ (@value{GDBP}) p var
+ 'var' has unknown type; cast it to its declared type
+ (@value{GDBP}) p (float) var
+ $1 = 3.14
+@end smallexample
+
If you append @kbd{@@entry} string to a function parameter name you get its
value at the time the function got called. If the value is not available an
error message is printed. Entry values are available only with some compilers.
@code{no} setting.
This functionality is currently supported only by DWARF 2 debugging format and
-the compiler has to produce @samp{DW_TAG_GNU_call_site} tags. With
+the compiler has to produce @samp{DW_TAG_call_site} tags. With
@value{NGCC}, you need to specify @option{-O -g} during compilation, to get
this information.
return address set up as if @code{B} called @code{C} normally.
This functionality is currently supported only by DWARF 2 debugging format and
-the compiler has to produce @samp{DW_TAG_GNU_call_site} tags. With
+the compiler has to produce @samp{DW_TAG_call_site} tags. With
@value{NGCC}, you need to specify @option{-O -g} during compilation, to get
this information.
static void __attribute__((noinline, noclone)) c (void) @{ a (); @}
int main (void) @{ x (); return 0; @}
-Breakpoint 1, DW_OP_GNU_entry_value resolving cannot find
-DW_TAG_GNU_call_site 0x40039a in main
+Breakpoint 1, DW_OP_entry_value resolving cannot find
+DW_TAG_call_site 0x40039a in main
a () at t.c:3
3 static void __attribute__((noinline, noclone)) a (void) @{ x++; @}
(gdb) bt
(gdb) bt
#0 c (i=i@@entry=0) at t.c:2
-#1 0x0000000000400428 in a (DW_OP_GNU_entry_value resolving has found
+#1 0x0000000000400428 in a (DW_OP_entry_value resolving has found
function "a" at 0x400420 can call itself via tail calls
i=<optimized out>) at t.c:6
#2 0x000000000040036e in main () at t.c:7
@cindex reference declarations
@item
-@value{GDBN} understands variables declared as C@t{++} references; you can use
-them in expressions just as you do in C@t{++} source---they are automatically
-dereferenced.
+@value{GDBN} understands variables declared as C@t{++} lvalue or rvalue
+references; you can use them in expressions just as you do in C@t{++}
+source---they are automatically dereferenced.
In the parameter list shown when @value{GDBN} displays a frame, the values of
reference variables are not displayed (unlike other variables); this
``Incomplete type'' is C terminology for data types that are not
completely specified.
+@cindex unknown type
+Othertimes, information about a variable's type is completely absent
+from the debug information included in the program. This most often
+happens when the program or library where the variable is defined
+includes no debug information at all. @value{GDBN} knows the variable
+exists from inspecting the linker/loader symbol table (e.g., the ELF
+dynamic symbol table), but such symbols do not contain type
+information. Inspecting the type of a (global) variable for which
+@value{GDBN} has no type information shows:
+
+@smallexample
+ (@value{GDBP}) ptype var
+ type = <data variable, no debug info>
+@end smallexample
+
+@xref{Variables, no debug info variables}, for how to print the values
+of such variables.
+
@kindex info types
@item info types @var{regexp}
@itemx info types
@cindex partial symbol dump
@kindex maint print msymbols
@cindex minimal symbol dump
-@item maint print symbols @var{filename}
-@itemx maint print psymbols @var{filename}
-@itemx maint print msymbols @var{filename}
-Write a dump of debugging symbol data into the file @var{filename}.
-These commands are used to debug the @value{GDBN} symbol-reading code. Only
-symbols with debugging data are included. If you use @samp{maint print
-symbols}, @value{GDBN} includes all the symbols for which it has already
-collected full details: that is, @var{filename} reflects symbols for
-only those files whose symbols @value{GDBN} has read. You can use the
-command @code{info sources} to find out which files these are. If you
-use @samp{maint print psymbols} instead, the dump shows information about
-symbols that @value{GDBN} only knows partially---that is, symbols defined in
-files that @value{GDBN} has skimmed, but not yet read completely. Finally,
-@samp{maint print msymbols} dumps just the minimal symbol information
-required for each object file from which @value{GDBN} has read some symbols.
+@item maint print symbols @r{[}-pc @var{address}@r{]} @r{[}@var{filename}@r{]}
+@itemx maint print symbols @r{[}-objfile @var{objfile}@r{]} @r{[}-source @var{source}@r{]} @r{[}--@r{]} @r{[}@var{filename}@r{]}
+@itemx maint print psymbols @r{[}-objfile @var{objfile}@r{]} @r{[}-pc @var{address}@r{]} @r{[}--@r{]} @r{[}@var{filename}@r{]}
+@itemx maint print psymbols @r{[}-objfile @var{objfile}@r{]} @r{[}-source @var{source}@r{]} @r{[}--@r{]} @r{[}@var{filename}@r{]}
+@itemx maint print msymbols @r{[}-objfile @var{objfile}@r{]} @r{[}--@r{]} @r{[}@var{filename}@r{]}
+Write a dump of debugging symbol data into the file @var{filename} or
+the terminal if @var{filename} is unspecified.
+If @code{-objfile @var{objfile}} is specified, only dump symbols for
+that objfile.
+If @code{-pc @var{address}} is specified, only dump symbols for the file
+with code at that address. Note that @var{address} may be a symbol like
+@code{main}.
+If @code{-source @var{source}} is specified, only dump symbols for that
+source file.
+
+These commands are used to debug the @value{GDBN} symbol-reading code.
+These commands do not modify internal @value{GDBN} state, therefore
+@samp{maint print symbols} will only print symbols for already expanded symbol
+tables.
+You can use the command @code{info sources} to find out which files these are.
+If you use @samp{maint print psymbols} instead, the dump shows information
+about symbols that @value{GDBN} only knows partially---that is, symbols
+defined in files that @value{GDBN} has skimmed, but not yet read completely.
+Finally, @samp{maint print msymbols} just dumps ``minimal symbols'', e.g.,
+``ELF symbols''.
+
@xref{Files, ,Commands to Specify Files}, for a discussion of how
@value{GDBN} reads symbols (in the description of @code{symbol-file}).
@end table
-@cindex weak alias functions
-Sometimes, a function you wish to call is actually a @dfn{weak alias}
-for another function. In such case, @value{GDBN} might not pick up
-the type information, including the types of the function arguments,
-which causes @value{GDBN} to call the inferior function incorrectly.
-As a result, the called function will function erroneously and may
-even crash. A solution to that is to use the name of the aliased
-function instead.
+@subsection Calling functions with no debug info
+
+@cindex no debug info functions
+Sometimes, a function you wish to call is missing debug information.
+In such case, @value{GDBN} does not know the type of the function,
+including the types of the function's parameters. To avoid calling
+the inferior function incorrectly, which could result in the called
+function functioning erroneously and even crash, @value{GDBN} refuses
+to call the function unless you tell it the type of the function.
+
+For prototyped (i.e.@: ANSI/ISO style) functions, there are two ways
+to do that. The simplest is to cast the call to the function's
+declared return type. For example:
+
+@smallexample
+(@value{GDBP}) p getenv ("PATH")
+'getenv' has unknown return type; cast the call to its declared return type
+(@value{GDBP}) p (char *) getenv ("PATH")
+$1 = 0x7fffffffe7ba "/usr/local/bin:/"...
+@end smallexample
+
+Casting the return type of a no-debug function is equivalent to
+casting the function to a pointer to a prototyped function that has a
+prototype that matches the types of the passed-in arguments, and
+calling that. I.e., the call above is equivalent to:
+
+@smallexample
+(@value{GDBP}) p ((char * (*) (const char *)) getenv) ("PATH")
+@end smallexample
+
+@noindent
+and given this prototyped C or C++ function with float parameters:
+
+@smallexample
+float multiply (float v1, float v2) @{ return v1 * v2; @}
+@end smallexample
+
+@noindent
+these calls are equivalent:
+
+@smallexample
+(@value{GDBP}) p (float) multiply (2.0f, 3.0f)
+(@value{GDBP}) p ((float (*) (float, float)) multiply) (2.0f, 3.0f)
+@end smallexample
+
+If the function you wish to call is declared as unprototyped (i.e.@:
+old K&R style), you must use the cast-to-function-pointer syntax, so
+that @value{GDBN} knows that it needs to apply default argument
+promotions (promote float arguments to double). @xref{ABI, float
+promotion}. For example, given this unprototyped C function with
+float parameters, and no debug info:
+
+@smallexample
+float
+multiply_noproto (v1, v2)
+ float v1, v2;
+@{
+ return v1 * v2;
+@}
+@end smallexample
+
+@noindent
+you call it like this:
+
+@smallexample
+ (@value{GDBP}) p ((float (*) ()) multiply_noproto) (2.0f, 3.0f)
+@end smallexample
@node Patching
@section Patching Programs
@subsection Compiler search for the @code{compile} command
-@value{GDBN} needs to find @value{NGCC} for the inferior being debugged which
-may not be obvious for remote targets of different architecture than where
-@value{GDBN} is running. Environment variable @code{PATH} (@code{PATH} from
-shell that executed @value{GDBN}, not the one set by @value{GDBN}
-command @code{set environment}). @xref{Environment}. @code{PATH} on
+@value{GDBN} needs to find @value{NGCC} for the inferior being debugged
+which may not be obvious for remote targets of different architecture
+than where @value{GDBN} is running. Environment variable @code{PATH} on
@value{GDBN} host is searched for @value{NGCC} binary matching the
-target architecture and operating system.
+target architecture and operating system. This search can be overriden
+by @code{set compile-gcc} @value{GDBN} command below. @code{PATH} is
+taken from shell that executed @value{GDBN}, it is not the value set by
+@value{GDBN} command @code{set environment}). @xref{Environment}.
+
Specifically @code{PATH} is searched for binaries matching regular expression
@code{@var{arch}(-[^-]*)?-@var{os}-gcc} according to the inferior target being
for pattern @code{s390x?}. @var{os} is currently supported only for
pattern @code{linux(-gnu)?}.
+On Posix hosts the compiler driver @value{GDBN} needs to find also
+shared library @file{libcc1.so} from the compiler. It is searched in
+default shared library search path (overridable with usual environment
+variable @code{LD_LIBRARY_PATH}), unrelated to @code{PATH} or @code{set
+compile-gcc} settings. Contrary to it @file{libcc1plugin.so} is found
+according to the installation of the found compiler --- as possibly
+specified by the @code{set compile-gcc} command.
+
+@table @code
+@item set compile-gcc
+@cindex compile command driver filename override
+Set compilation command used for compiling and injecting code with the
+@code{compile} commands. If this option is not set (it is set to
+an empty string), the search described above will occur --- that is the
+default.
+
+@item show compile-gcc
+Displays the current compile command @value{NGCC} driver filename.
+If set, it is the main command @command{gcc}, found usually for example
+under name @file{x86_64-linux-gnu-gcc}.
+@end table
+
@node GDB Files
@chapter @value{GDBN} Files
@table @code
-@kindex load @var{filename}
-@item load @var{filename}
+@kindex load @var{filename} @var{offset}
+@item load @var{filename} @var{offset}
@anchor{load}
Depending on what remote debugging facilities are configured into
@value{GDBN}, the @code{load} command may be available. Where it exists, it
specifies a fixed address.
@c FIXME! This would be a good place for an xref to the GNU linker doc.
+It is also possible to tell @value{GDBN} to load the executable file at a
+specific offset described by the optional argument @var{offset}. When
+@var{offset} is provided, @var{filename} must also be provided.
+
Depending on the remote side capabilities, @value{GDBN} may be able to
load programs into flash memory.
@code{load} does not repeat if you press @key{RET} again after using it.
@end table
+@table @code
+
+@kindex flash-erase
+@item flash-erase
+@anchor{flash-erase}
+
+Erases all known flash memory regions on the target.
+
+@end table
+
@node Byte Order
@section Choosing Target Byte Order
$ gdbserver --wrapper env LD_PRELOAD=libtest.so -- :2222 ./testprog
@end smallexample
+@cindex @option{--selftest}
+The @option{--selftest} option runs the self tests in @code{gdbserver}:
+
+@smallexample
+$ gdbserver --selftest
+Ran 2 unit tests, 0 failed
+@end smallexample
+
+These tests are disabled in release.
@subsection Connecting to @code{gdbserver}
The basic procedure for connecting to the remote target is:
@tab @code{QDisableRandomization}
@tab @code{set disable-randomization}
+@item @code{startup-with-shell}
+@tab @code{QStartupWithShell}
+@tab @code{set startup-with-shell}
+
+@item @code{environment-hex-encoded}
+@tab @code{QEnvironmentHexEncoded}
+@tab @code{set environment}
+
+@item @code{environment-unset}
+@tab @code{QEnvironmentUnset}
+@tab @code{unset environment}
+
+@item @code{environment-reset}
+@tab @code{QEnvironmentReset}
+@tab @code{Reset the inferior environment (i.e., unset user-set variables)}
+
@item @code{conditional-breakpoints-packet}
@tab @code{Z0 and Z1}
@tab @code{Support for target-side breakpoint condition evaluation}
@smallexample
(@value{GDBP}) print 'cygwin1!__argv'
-$1 = 268572168
+'cygwin1!__argv' has unknown type; cast it to its declared type
@end smallexample
@smallexample
(@value{GDBP}) x 'cygwin1!__argv'
-0x10021610: "\230y\""
+'cygwin1!__argv' has unknown type; cast it to its declared type
@end smallexample
And two possible solutions:
@item set debug arc
@kindex set debug arc
Control the level of ARC specific debug messages. Use 0 for no messages (the
-default) and 1 for debug messages. At present higher values offer no further
-messages.
+default), 1 for debug messages, and 2 for even more debug messages.
@item show debug arc
@kindex show debug arc
Show the level of ARC specific debugging in operation.
+@item maint print arc arc-instruction @var{address}
+@kindex maint print arc arc-instruction
+Print internal disassembler information about instruction at a given address.
+
@end table
@node ARM
* SPU:: Cell Broadband Engine SPU architecture
* PowerPC::
* Nios II::
+* Sparc64::
@end menu
@node AArch64
for lower and upper bounds respectively.
@end table
+When you call an inferior function on an Intel MPX enabled program,
+GDB sets the inferior's bound registers to the init (disabled) state
+before calling the function. As a consequence, bounds checks for the
+pointer arguments passed to the function will always pass.
+
+This is necessary because when you call an inferior function, the
+program is usually in the middle of the execution of other function.
+Since at that point bound registers are in an arbitrary state, not
+clearing them would lead to random bound violations in the called
+function.
+
+You can still examine the influence of the bound registers on the
+execution of the called function by stopping the execution of the
+called function at its prologue, setting bound registers, and
+continuing the execution. For example:
+
+@smallexample
+ $ break *upper
+ Breakpoint 2 at 0x4009de: file i386-mpx-call.c, line 47.
+ $ print upper (a, b, c, d, 1)
+ Breakpoint 2, upper (a=0x0, b=0x6e0000005b, c=0x0, d=0x0, len=48)....
+ $ print $bnd0
+ @{lbound = 0x0, ubound = ffffffff@} : size -1
+@end smallexample
+
+At this last step the value of bnd0 can be changed for investigation of bound
+violations caused along the execution of the call. In order to know how to
+set the bound registers or bound table for the call consult the ABI.
+
@node Alpha
@subsection Alpha
Show the current setting of Nios II debugging messages.
@end table
+@node Sparc64
+@subsection Sparc64
+@cindex Sparc64 support
+@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
+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.
+
+
+@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.
+
+@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.
+
+Below is an example of displaying ADI versions of variable "shmaddr".
+
+@smallexample
+(@value{GDBP}) adi x/100 shmaddr
+ 0xfff800010002c000: 0 0
+@end smallexample
+
+@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.
+
+@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{tag} is the new ADI version tag.
+
+For example, do the following to modify then verify ADI versions of
+variable "shmaddr":
+
+@smallexample
+(@value{GDBP}) adi a/100 shmaddr = 7
+(@value{GDBP}) adi x/100 shmaddr
+ 0xfff800010002c000: 7 7
+@end smallexample
+
+@end table
+
@node Controlling GDB
@chapter Controlling @value{GDBN}
@value{GDBN} standard output stream. The default is off.
@item show debug remote
Displays the state of display of remote packets.
+
+@item set debug separate-debug-file
+Turns on or off display of debug output about separate debug file search.
+@item show debug separate-debug-file
+Displays the state of separate debug file search debug output.
+
@item set debug serial
Turns on or off display of @value{GDBN} serial debugging info. The
default is off.
@cindex arguments, to user-defined commands
A @dfn{user-defined command} is a sequence of @value{GDBN} commands to
which you assign a new name as a command. This is done with the
-@code{define} command. User commands may accept up to 10 arguments
+@code{define} command. User commands may accept an unlimited number of arguments
separated by whitespace. Arguments are accessed within the user command
-via @code{$arg0@dots{}$arg9}. A trivial example:
+via @code{$arg0@dots{}$argN}. A trivial example:
@smallexample
define adder
@cindex argument count in user-defined commands
@cindex how many arguments (user-defined commands)
In addition, @code{$argc} may be used to find out how many arguments have
-been passed. This expands to a number in the range 0@dots{}10.
+been passed.
@smallexample
define adder
@item n
next
+@kindex o @r{(SingleKey TUI key)}
+@item o
+nexti. The shortcut letter @samp{o} stands for ``step Over''.
+
@kindex q @r{(SingleKey TUI key)}
@item q
exit the SingleKey mode.
@item s
step
+@kindex i @r{(SingleKey TUI key)}
+@item i
+stepi. The shortcut letter @samp{i} stands for ``step Into''.
+
@kindex u @r{(SingleKey TUI key)}
@item u
up
@item =library-loaded,...
Reports that a new library file was loaded by the program. This
-notification has 4 fields---@var{id}, @var{target-name},
-@var{host-name}, and @var{symbols-loaded}. The @var{id} field is an
+notification has 5 fields---@var{id}, @var{target-name},
+@var{host-name}, @var{symbols-loaded} and @var{ranges}. The @var{id} field is an
opaque identifier of the library. For remote debugging case,
@var{target-name} and @var{host-name} fields give the name of the
library file on the target, and on the host respectively. For native
@var{thread-group} field, if present, specifies the id of the thread
group in whose context the library was loaded. If the field is
absent, it means the library was loaded in the context of all present
-thread groups.
+thread groups. The @var{ranges} field specifies the ranges of addresses belonging
+to this library.
@item =library-unloaded,...
Reports that a library was unloaded by the program. This notification
@subsection @sc{gdb/mi} Thread Information
Whenever @value{GDBN} has to report an information about a thread, it
-uses a tuple with the following fields:
+uses a tuple with the following fields. The fields are always present unless
+stated otherwise.
@table @code
@item id
-The global numeric id assigned to the thread by @value{GDBN}. This field is
-always present.
+The global numeric id assigned to the thread by @value{GDBN}.
@item target-id
-Target-specific string identifying the thread. This field is always present.
+The target-specific string identifying the thread.
@item details
Additional information about the thread provided by the target.
It is supposed to be human-readable and not interpreted by the
frontend. This field is optional.
+@item name
+The name of the thread. If the user specified a name using the
+@code{thread name} command, then this name is given. Otherwise, if
+@value{GDBN} can extract the thread name from the target, then that
+name is given. If @value{GDBN} cannot find the thread name, then this
+field is omitted.
+
@item state
-Either @samp{stopped} or @samp{running}, depending on whether the
-thread is presently running. This field is always present.
+The execution state of the thread, either @samp{stopped} or @samp{running},
+depending on whether the thread is presently running.
+
+@item frame
+The stack frame currently executing in the thread. This field is only present
+if the thread is stopped. Its format is documented in
+@ref{GDB/MI Frame Information}.
@item core
The value of this field is an integer number of the processor core the
@subsubheading Result
-The result is a list of threads. The following attributes are
-defined for a given thread:
+The result contains the following attributes:
@table @samp
-@item current
-This field exists only for the current thread. It has the value @samp{*}.
-
-@item id
-The global identifier that @value{GDBN} uses to refer to the thread.
-
-@item target-id
-The identifier that the target uses to refer to the thread.
-
-@item details
-Extra information about the thread, in a target-specific format. This
-field is optional.
-
-@item name
-The name of the thread. If the user specified a name using the
-@code{thread name} command, then this name is given. Otherwise, if
-@value{GDBN} can extract the thread name from the target, then that
-name is given. If @value{GDBN} cannot find the thread name, then this
-field is omitted.
-
-@item frame
-The stack frame currently executing in the thread.
-
-@item state
-The thread's state. The @samp{state} field may have the following
-values:
-
-@table @code
-@item stopped
-The thread is stopped. Frame information is available for stopped
-threads.
-
-@item running
-The thread is running. There's no frame information for running
-threads.
+@item threads
+A list of threads. The format of the elements of the list is described in
+@ref{GDB/MI Thread Information}.
-@end table
-
-@item core
-If @value{GDBN} can find the CPU core on which this thread is running,
-then this field is the core identifier. This field is optional.
+@item current-thread-id
+The global id of the currently selected thread. This field is omitted if there
+is no selected thread (for example, when the selected inferior is not running,
+and therefore has no threads) or if a @var{thread-id} argument was passed to
+the command.
@end table
(gdb)
@end smallexample
-@ignore
@subheading The @code{-file-list-shared-libraries} Command
@findex -file-list-shared-libraries
@subsubheading Synopsis
@smallexample
- -file-list-shared-libraries
+ -file-list-shared-libraries [ @var{regexp} ]
@end smallexample
List the shared libraries in the program.
+With a regular expression @var{regexp}, only those libraries whose
+names match @var{regexp} are listed.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{info shared}.
+The corresponding @value{GDBN} command is @samp{info shared}. The fields
+have a similar meaning to the @code{=library-loaded} notification.
+The @code{ranges} field specifies the multiple segments belonging to this
+library. Each range has the following fields:
+
+@table @samp
+@item from
+The address defining the inclusive lower bound of the segment.
+@item to
+The address defining the exclusive upper bound of the segment.
+@end table
@subsubheading Example
-N.A.
+@smallexample
+(gdb)
+-file-list-exec-source-files
+^done,shared-libraries=[
+@{id="/lib/libfoo.so",target-name="/lib/libfoo.so",host-name="/lib/libfoo.so",symbols-loaded="1",thread-group="i1",ranges=[@{from="0x72815989",to="0x728162c0"@}]@},
+@{id="/lib/libbar.so",target-name="/lib/libbar.so",host-name="/lib/libbar.so",symbols-loaded="1",thread-group="i1",ranges=[@{from="0x76ee48c0",to="0x76ee9160"@}]@}]
+(gdb)
+@end smallexample
+@ignore
@subheading The @code{-file-list-symbol-files} Command
@findex -file-list-symbol-files
@subsubheading Example
N.A.
+@subheading The @code{-target-flash-erase} Command
+@findex -target-flash-erase
+
+@subsubheading Synopsis
+
+@smallexample
+ -target-flash-erase
+@end smallexample
+
+Erases all known flash memory regions on the target.
+
+The corresponding @value{GDBN} command is @samp{flash-erase}.
+
+The output is a list of flash regions that have been erased, with starting
+addresses and memory region sizes.
+
+@smallexample
+(gdb)
+-target-flash-erase
+^done,erased-regions=@{address="0x0",size="0x40000"@}
+(gdb)
+@end smallexample
@subheading The @code{-target-select} Command
@findex -target-select
Print the entire architecture configuration. The optional argument
@var{file} names the file where the output goes.
-@kindex maint print c-tdesc
+@kindex maint print c-tdesc @r{[}@var{file}@r{]}
@item maint print c-tdesc
-Print the current target description (@pxref{Target Descriptions}) as
-a C source file. The created source file can be used in @value{GDBN}
-when an XML parser is not available to parse the description.
+Print the target description (@pxref{Target Descriptions}) as
+a C source file. By default, the target description is for the current
+target, but if the optional argument @var{file} is provided, that file
+is used to produce the description. The @var{file} should be an XML
+document, of the form described in @ref{Target Description Format}.
+The created source file is built into @value{GDBN} when @value{GDBN} is
+built again. This command is used by developers after they add or
+modify XML target descriptions.
+
+@kindex maint check xml-descriptions
+@item maint check xml-descriptions @var{dir}
+Check that the target descriptions dynamically created by @value{GDBN}
+equal the descriptions created from XML files found in @var{dir}.
@kindex maint print dummy-frames
@item maint print dummy-frames
@kindex maint selftest
@cindex self tests
+@item maint selftest @r{[}@var{filter}@r{]}
Run any self tests that were compiled in to @value{GDBN}. This will
print a message showing how many tests were run, and how many failed.
+If a @var{filter} is passed, only the tests with @var{filter} in their
+name will by ran.
+
+@kindex "maint info selftests"
+@cindex self tests
+@item maint info selftests
+List the selftests compiled in to @value{GDBN}.
@kindex maint set dwarf always-disassemble
@kindex maint show dwarf always-disassemble
for success
@end table
+@item vMustReplyEmpty
+@cindex @samp{vMustReplyEmpty} packet
+The correct reply to an unknown @samp{v} packet is to return the empty
+string, however, some older versions of @command{gdbserver} would
+incorrectly return @samp{OK} for unknown @samp{v} packets.
+
+The @samp{vMustReplyEmpty} is used as a feature test to check how
+@command{gdbserver} handles unknown packets, it is important that this
+packet be handled in the same way as other unknown @samp{v} packets.
+If this packet is handled differently to other unknown @samp{v}
+packets then it is possile that @value{GDBN} may run into problems in
+other areas, specifically around use of @samp{vFile:setfs:}.
+
@item vRun;@var{filename}@r{[};@var{argument}@r{]}@dots{}
@cindex @samp{vRun} packet
Run the program @var{filename}, passing it each @var{argument} on its
@item X @var{len},@var{expr}
@var{len} is the length of the bytecode expression and @var{expr} is the
-actual conditional expression in bytecode form.
+actual commands expression in bytecode form.
@end table
This should only be done on targets that actually support disabling
address space randomization.
+@item QStartupWithShell:@var{value}
+@cindex startup with shell, remote request
+@cindex @samp{QStartupWithShell} packet
+On UNIX-like targets, it is possible to start the inferior using a
+shell program. This is the default behavior on both @value{GDBN} and
+@command{gdbserver} (@pxref{set startup-with-shell}). This packet is
+used to inform @command{gdbserver} whether it should start the
+inferior using a shell or not.
+
+If @var{value} is @samp{0}, @command{gdbserver} will not use a shell
+to start the inferior. If @var{value} is @samp{1},
+@command{gdbserver} will use a shell to start the inferior. All other
+values are considered an error.
+
+This packet is only available in extended mode (@pxref{extended
+mode}).
+
+Reply:
+@table @samp
+@item OK
+The request succeeded.
+
+@item E @var{nn}
+An error occurred. The error number @var{nn} is given as hex digits.
+@end table
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response
+(@pxref{qSupported}). This should only be done on targets that
+actually support starting the inferior using a shell.
+
+Use of this packet is controlled by the @code{set startup-with-shell}
+command; @pxref{set startup-with-shell}.
+
+@item QEnvironmentHexEncoded:@var{hex-value}
+@anchor{QEnvironmentHexEncoded}
+@cindex set environment variable, remote request
+@cindex @samp{QEnvironmentHexEncoded} packet
+On UNIX-like targets, it is possible to set environment variables that
+will be passed to the inferior during the startup process. This
+packet is used to inform @command{gdbserver} of an environment
+variable that has been defined by the user on @value{GDBN} (@pxref{set
+environment}).
+
+The packet is composed by @var{hex-value}, an hex encoded
+representation of the @var{name=value} format representing an
+environment variable. The name of the environment variable is
+represented by @var{name}, and the value to be assigned to the
+environment variable is represented by @var{value}. If the variable
+has no value (i.e., the value is @code{null}), then @var{value} will
+not be present.
+
+This packet is only available in extended mode (@pxref{extended
+mode}).
+
+Reply:
+@table @samp
+@item OK
+The request succeeded.
+@end table
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response
+(@pxref{qSupported}). This should only be done on targets that
+actually support passing environment variables to the starting
+inferior.
+
+This packet is related to the @code{set environment} command;
+@pxref{set environment}.
+
+@item QEnvironmentUnset:@var{hex-value}
+@anchor{QEnvironmentUnset}
+@cindex unset environment variable, remote request
+@cindex @samp{QEnvironmentUnset} packet
+On UNIX-like targets, it is possible to unset environment variables
+before starting the inferior in the remote target. This packet is
+used to inform @command{gdbserver} of an environment variable that has
+been unset by the user on @value{GDBN} (@pxref{unset environment}).
+
+The packet is composed by @var{hex-value}, an hex encoded
+representation of the name of the environment variable to be unset.
+
+This packet is only available in extended mode (@pxref{extended
+mode}).
+
+Reply:
+@table @samp
+@item OK
+The request succeeded.
+@end table
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response
+(@pxref{qSupported}). This should only be done on targets that
+actually support passing environment variables to the starting
+inferior.
+
+This packet is related to the @code{unset environment} command;
+@pxref{unset environment}.
+
+@item QEnvironmentReset
+@anchor{QEnvironmentReset}
+@cindex reset environment, remote request
+@cindex @samp{QEnvironmentReset} packet
+On UNIX-like targets, this packet is used to reset the state of
+environment variables in the remote target before starting the
+inferior. In this context, reset means unsetting all environment
+variables that were previously set by the user (i.e., were not
+initially present in the environment). It is sent to
+@command{gdbserver} before the @samp{QEnvironmentHexEncoded}
+(@pxref{QEnvironmentHexEncoded}) and the @samp{QEnvironmentUnset}
+(@pxref{QEnvironmentUnset}) packets.
+
+This packet is only available in extended mode (@pxref{extended
+mode}).
+
+Reply:
+@table @samp
+@item OK
+The request succeeded.
+@end table
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response
+(@pxref{qSupported}). This should only be done on targets that
+actually support passing environment variables to the starting
+inferior.
+
@item qfThreadInfo
@itemx qsThreadInfo
@cindex list active threads, remote request
the thread was last executing on. The @samp{name} attribute, if
present, specifies the human-readable name of the thread. The content
of the of @samp{thread} element is interpreted as human-readable
-auxiliary information.
+auxiliary information. The @samp{handle} attribute, if present,
+is a hex encoded representation of the thread handle.
+
@node Traceframe Info Format
@section Traceframe Info Format
* Nios II Features::
* PowerPC Features::
* S/390 and System z Features::
+* Sparc Features::
* TIC6x Features::
@end menu
The @samp{org.gnu.gdb.i386.linux} feature is optional. It should
describe a single register, @samp{orig_eax}.
+The @samp{org.gnu.gdb.i386.segments} feature is optional. It should
+describe two system registers: @samp{fs_base} and @samp{gs_base}.
+
The @samp{org.gnu.gdb.i386.avx512} feature is optional and requires the
@samp{org.gnu.gdb.i386.avx} feature. It should
describe additional @sc{xmm} registers:
@samp{zmm16h} through @samp{zmm31h}, only valid for amd64.
@end itemize
+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.
+
@node MicroBlaze Features
@subsection MicroBlaze Features
@cindex target descriptions, MicroBlaze features
contain the 128-bit wide vector registers @samp{v16} through
@samp{v31}.
+The @samp{org.gnu.gdb.s390.gs} feature is optional. It should contain
+the 64-bit wide guarded-storage-control registers @samp{gsd},
+@samp{gssm}, and @samp{gsepla}.
+
+The @samp{org.gnu.gdb.s390.gsbc} feature is optional. It should contain
+the 64-bit wide guarded-storage broadcast control registers
+@samp{bc_gsd}, @samp{bc_gssm}, and @samp{bc_gsepla}.
+
+@node Sparc Features
+@subsection Sparc Features
+@cindex target descriptions, sparc32 features
+@cindex target descriptions, sparc64 features
+The @samp{org.gnu.gdb.sparc.cpu} feature is required for sparc32/sparc64
+targets. It should describe the following registers:
+
+@itemize @minus
+@item
+@samp{g0} through @samp{g7}
+@item
+@samp{o0} through @samp{o7}
+@item
+@samp{l0} through @samp{l7}
+@item
+@samp{i0} through @samp{i7}
+@end itemize
+
+They may be 32-bit or 64-bit depending on the target.
+
+Also the @samp{org.gnu.gdb.sparc.fpu} feature is required for sparc32/sparc64
+targets. It should describe the following registers:
+
+@itemize @minus
+@item
+@samp{f0} through @samp{f31}
+@item
+@samp{f32} through @samp{f62} for sparc64
+@end itemize
+
+The @samp{org.gnu.gdb.sparc.cp0} feature is required for sparc32/sparc64
+targets. It should describe the following registers:
+
+@itemize @minus
+@item
+@samp{y}, @samp{psr}, @samp{wim}, @samp{tbr}, @samp{pc}, @samp{npc},
+@samp{fsr}, and @samp{csr} for sparc32
+@item
+@samp{pc}, @samp{npc}, @samp{state}, @samp{fsr}, @samp{fprs}, and @samp{y}
+for sparc64
+@end itemize
+
@node TIC6x Features
@subsection TMS320C6x Features
@cindex target descriptions, TIC6x features
projects / deliverable / binutils-gdb.git / blobdiff