@cindex @code{-c}
Use file @var{file} as a core dump to examine.
-@item -c @var{number}
@item -pid @var{number}
@itemx -p @var{number}
@cindex @code{--pid}
@cindex @code{-p}
Connect to process ID @var{number}, as with the @code{attach} command.
-If there is no such process, @value{GDBN} will attempt to open a core
-file named @var{number}.
@item -command @var{file}
@itemx -x @var{file}
@item @samp{thread apply [@var{threadno}] [@var{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
+messages on thread start and exit.
@end itemize
@quotation
shown in the first field of the @samp{info threads} display; or it
could be a range of thread numbers, as in @code{2-4}. To apply a
command to all threads, type @kbd{thread apply all @var{command}}.
+
+@kindex set print thread-events
+@cindex print messages on thread start and exit
+@item set print thread-events
+@itemx set print thread-events on
+@itemx set print thread-events off
+The @code{set print thread-events} command allows you to enable or
+disable printing of messages when @value{GDBN} notices that new threads have
+started or that threads have exited. By default, these messages will
+be printed if detection of these events is supported by the target.
+Note that these messages cannot be disabled on all targets.
+
+@kindex show print thread-events
+@item show print thread-events
+Show whether messages will be printed when @value{GDBN} detects that threads
+have started and exited.
@end table
@cindex automatic thread selection
On some systems, @value{GDBN} provides support for debugging programs that
create additional processes using the @code{fork} or @code{vfork} functions.
Currently, the only platforms with this feature are HP-UX (11.x and later
-only?) and GNU/Linux (kernel version 2.5.60 and later).
+only?) and @sc{gnu}/Linux (kernel version 2.5.60 and later).
By default, when a program forks, @value{GDBN} will continue to debug
the parent process and the child process will run unimpeded.
Vars,, Convenience Variables}, for a discussion of what you can do with
convenience variables.
-You have several ways to say where the breakpoint should go.
-
@table @code
-@item break @var{function}
-Set a breakpoint at entry to function @var{function}.
+@item break @var{location}
+Set a breakpoint at the given @var{location}, which can specify a
+function name, a line number, or an address of an instruction.
+(@xref{Specify Location}, for a list of all the possible ways to
+specify a @var{location}.) The breakpoint will stop your program just
+before it executes any of the code in the specified @var{location}.
+
When using source languages that permit overloading of symbols, such as
-C@t{++}, @var{function} may refer to more than one possible place to break.
+C@t{++}, a function name may refer to more than one possible place to break.
@xref{Breakpoint Menus,,Breakpoint Menus}, for a discussion of that situation.
-@item break +@var{offset}
-@itemx break -@var{offset}
-Set a breakpoint some number of lines forward or back from the position
-at which execution stopped in the currently selected @dfn{stack frame}.
-(@xref{Frames, ,Frames}, for a description of stack frames.)
-
-@item break @var{linenum}
-Set a breakpoint at line @var{linenum} in the current source file.
-The current source file is the last file whose source text was printed.
-The breakpoint will stop your program just before it executes any of the
-code on that line.
-
-@item break @var{filename}:@var{linenum}
-Set a breakpoint at line @var{linenum} in source file @var{filename}.
-
-@item break @var{filename}:@var{function}
-Set a breakpoint at entry to function @var{function} found in file
-@var{filename}. Specifying a file name as well as a function name is
-superfluous except when multiple files contain similarly named
-functions.
-
-@item break *@var{address}
-Set a breakpoint at address @var{address}. You can use this to set
-breakpoints in parts of your program which do not have debugging
-information or source files.
-
@item break
When called without any arguments, @code{break} sets a breakpoint at
the next instruction to be executed in the selected stack frame
breakpoints @value{GDBN} will use, see @ref{set remote
hardware-breakpoint-limit}.
-
@kindex thbreak
@item thbreak @var{args}
Set a hardware-assisted breakpoint enabled only for one stop. @var{args}
@item Enabled or Disabled
Enabled breakpoints are marked with @samp{y}. @samp{n} marks breakpoints
that are not enabled. An optional @samp{(p)} suffix marks pending
-breakpoints --- breakpoints for which address is either not yet
+breakpoints---breakpoints for which address is either not yet
resolved, pending load of a shared library, or for which address was
in a shared library that was since unloaded. Such breakpoint won't
fire until a shared library that has the symbol or line referred by
Where the breakpoint is in your program, as a memory address. For a
pending breakpoint whose address is not yet known, this field will
contain @samp{<PENDING>}. A breakpoint with several locations will
-have @samp{<MULTIPLE>} in this field --- see below for details.
+have @samp{<MULTIPLE>} in this field---see below for details.
@item What
Where the breakpoint is in the source for your program, as a file and
line number. For a pending breakpoint, the original string passed to
the breakpoints are conditional, this is even useful
(@pxref{Conditions, ,Break Conditions}).
-It is possible that a breakpoint correspond to several locations
+It is possible that a breakpoint corresponds to several locations
in your program. Examples of this situation are:
@itemize @bullet
In all those cases, @value{GDBN} will insert a breakpoint at all
the relevant locations.
-A breakpoint with multiple locations is displayed in the
-breakpoint table using several rows --- one header row, followed
-by one row for each breakpoint location. The header row
-has @samp{<MULTIPLE>} in the address column. The rows for
-individual locations contain the actual addresses for locations,
-and say what functions those locations are in. The number
-column for a location has number in the format
+A breakpoint with multiple locations is displayed in the breakpoint
+table using several rows---one header row, followed by one row for
+each breakpoint location. The header row has @samp{<MULTIPLE>} in the
+address column. The rows for individual locations contain the actual
+addresses for locations, and show the functions to which those
+locations belong. The number column for a location is of the form
@var{breakpoint-number}.@var{location-number}.
For example:
+
@smallexample
Num Type Disp Enb Address What
1 breakpoint keep y <MULTIPLE>
Each location can be individually enabled or disabled by passing
@var{breakpoint-number}.@var{location-number} as argument to the
-@code{enable} and @code{disable} commands.
+@code{enable} and @code{disable} commands. Note that you cannot
+delete the individual locations from the list, you can only delete the
+entire list of locations that belong to their parent breakpoint (with
+the @kbd{delete @var{num}} command, where @var{num} is the number of
+the parent breakpoint, 1 in the above example). Disabling or enabling
+the parent breakpoint (@pxref{Disabling}) affects all of the locations
+that belong to that breakpoint.
@cindex pending breakpoints
It's quite common to have a breakpoint inside a shared library.
-The shared library may be loaded and unloaded explicitly,
+Shared libraries can be loaded and unloaded explicitly,
and possibly repeatedly, as the program is executed. To support
this use case, @value{GDBN} updates breakpoint locations whenever
any shared library is loaded or unloaded. Typically, you would
-set a breakpoint in a shared library at the beginning of your
+set a breakpoint in a shared library at the beginning of your
debugging session, when the library is not loaded, and when the
symbols from the library are not available. When you try to set
breakpoint, @value{GDBN} will ask you if you want to set
-a so called @dfn{pending breakpoint} --- breakpoint whose address
+a so called @dfn{pending breakpoint}---breakpoint whose address
is not yet resolved.
After the program is run, whenever a new shared library is loaded,
breakpoint address is read-only or read-write. This applies to
breakpoints set with the @code{break} command as well as to internal
breakpoints set by commands like @code{next} and @code{finish}. For
-breakpoints set with @code{hbreak}, @value{GDBN} will always use hardware
+breakpoints set with @code{hbreak}, @value{GDBN} will always use hardware
breakpoints.
You can control this automatic behaviour with the following commands::
catch errors where you have no clue what part of your program is the
culprit.)
-On some systems, such as HP-UX, @sc{gnu}/Linux and most other
+On some systems, such as HP-UX, PowerPC, @sc{gnu}/Linux and most other
x86-based targets, @value{GDBN} includes support for hardware
watchpoints, which do not slow down the running of your program.
@table @code
@kindex watch
-@item watch @var{expr}
+@item watch @var{expr} @r{[}thread @var{threadnum}@r{]}
Set a watchpoint for an expression. @value{GDBN} will break when the
expression @var{expr} is written into by the program and its value
changes. The simplest (and the most popular) use of this command is
(@value{GDBP}) watch foo
@end smallexample
+If the command includes a @code{@r{[}thread @var{threadnum}@r{]}}
+clause, @value{GDBN} breaks only when the thread identified by
+@var{threadnum} changes the value of @var{expr}. If any other threads
+change the value of @var{expr}, @value{GDBN} will not break. Note
+that watchpoints restricted to a single thread in this way only work
+with Hardware Watchpoints.
+
@kindex rwatch
-@item rwatch @var{expr}
+@item rwatch @var{expr} @r{[}thread @var{threadnum}@r{]}
Set a watchpoint that will break when the value of @var{expr} is read
by the program.
@kindex awatch
-@item awatch @var{expr}
+@item awatch @var{expr} @r{[}thread @var{threadnum}@r{]}
Set a watchpoint that will break when @var{expr} is either read from
or written into by the program.
way of doing that would be to set a code breakpoint at the entry to the
@code{main} function and when it breaks, set all the watchpoints.
-@quotation
@cindex watchpoints and threads
@cindex threads and watchpoints
-@emph{Warning:} In multi-thread programs, watchpoints have only limited
-usefulness. With the current watchpoint implementation, @value{GDBN}
-can only watch the value of an expression @emph{in a single thread}. If
-you are confident that the expression can only change due to the current
-thread's activity (and if you are also confident that no other thread
-can become current), then you can use watchpoints as usual. However,
-@value{GDBN} may not notice when a non-current thread's activity changes
-the expression.
-
-@c FIXME: this is almost identical to the previous paragraph.
-@emph{HP-UX Warning:} In multi-thread programs, software watchpoints
+In multi-threaded programs, watchpoints will detect changes to the
+watched expression from every thread.
+
+@quotation
+@emph{Warning:} In multi-threaded programs, software watchpoints
have only limited usefulness. If @value{GDBN} creates a software
watchpoint, it can only watch the value of an expression @emph{in a
single thread}. If you are confident that the expression can only
the innermost frame is selected, this is a good way to delete a
breakpoint where your program just stopped.
+@item clear @var{location}
+Delete any breakpoints set at the specified @var{location}.
+@xref{Specify Location}, for the various forms of @var{location}; the
+most useful ones are listed below:
+
+@table @code
@item clear @var{function}
@itemx clear @var{filename}:@var{function}
Delete any breakpoints set at entry to the named @var{function}.
@itemx clear @var{filename}:@var{linenum}
Delete any breakpoints set at or within the code of the specified
@var{linenum} of the specified @var{filename}.
+@end table
@cindex delete breakpoints
@kindex delete
@code{info watch} to print a list of breakpoints, watchpoints, and
catchpoints if you do not know which numbers to use.
+Disabling and enabling a breakpoint that has multiple locations
+affects all of its locations.
+
A breakpoint, watchpoint, or catchpoint can have any of four different
states of enablement:
to be defined several times, for application in different contexts.
This is called @dfn{overloading}. When a function name is overloaded,
@samp{break @var{function}} is not enough to tell @value{GDBN} where you want
-a breakpoint. If you realize this is a problem, you can use
-something like @samp{break @var{function}(@var{types})} to specify which
+a breakpoint. You can use explicit signature of the function, as in
+@samp{break @var{function}(@var{types})}, to specify which
particular version of the function you want. Otherwise, @value{GDBN} offers
you a menu of numbered choices for different possible breakpoints, and
waits for your selection with the prompt @samp{>}. The first two
@itemx u @var{location}
Continue running your program until either the specified location is
reached, or the current stack frame returns. @var{location} is any of
-the forms of argument acceptable to @code{break} (@pxref{Set Breaks,
-,Setting Breakpoints}). This form of the command uses breakpoints, and
+the forms described in @ref{Specify Location}.
+This form of the command uses temporary breakpoints, and
hence is quicker than @code{until} without an argument. The specified
location is actually reached only if it is in the current frame. This
implies that @code{until} can be used to skip over recursive function
@kindex advance @var{location}
@itemx advance @var{location}
Continue running the program up to the given @var{location}. An argument is
-required, which should be of the same form as arguments for the @code{break}
-command. Execution will also stop upon exit from the current stack
+required, which should be of one of the forms described in
+@ref{Specify Location}.
+Execution will also stop upon exit from the current stack
frame. This command is similar to @code{until}, but @code{advance} will
not skip over recursive function calls, and the target location doesn't
have to be in the same frame as the current one.
@item break @var{linespec} thread @var{threadno}
@itemx break @var{linespec} thread @var{threadno} if @dots{}
@var{linespec} specifies source lines; there are several ways of
-writing them, but the effect is always to specify some source line.
+writing them (@pxref{Specify Location}), but the effect is always to
+specify some source line.
Use the qualifier @samp{thread @var{threadno}} with a breakpoint command
to specify that you only want @value{GDBN} to stop the program when a
@menu
* List:: Printing source lines
+* Specify Location:: How to specify code locations
* Edit:: Editing source files
* Search:: Searching source files
* Source Path:: Specifying source directories
@kindex l @r{(@code{list})}
To print lines from a source file, use the @code{list} command
(abbreviated @code{l}). By default, ten lines are printed.
-There are several ways to specify what part of the file you want to print.
+There are several ways to specify what part of the file you want to
+print; see @ref{Specify Location}, for the full list.
Here are the forms of the @code{list} command most commonly used:
argument of @samp{-}; that argument is preserved in repetition so that
each repetition moves up in the source file.
-@cindex linespec
In general, the @code{list} command expects you to supply zero, one or two
@dfn{linespecs}. Linespecs specify source lines; there are several ways
-of writing them, but the effect is always to specify some source line.
+of writing them (@pxref{Specify Location}), but the effect is always
+to specify some source line.
+
Here is a complete description of the possible arguments for @code{list}:
@table @code
@item list @var{first},@var{last}
Print lines from @var{first} to @var{last}. Both arguments are
-linespecs.
+linespecs. When a @code{list} command has two linespecs, and the
+source file of the second linespec is omitted, this refers to
+the same source file as the first linespec.
@item list ,@var{last}
Print lines ending with @var{last}.
As described in the preceding table.
@end table
-Here are the ways of specifying a single source line---all the
-kinds of linespec.
+@node Specify Location
+@section Specifying a Location
+@cindex specifying location
+@cindex linespec
-@table @code
-@item @var{number}
-Specifies line @var{number} of the current source file.
-When a @code{list} command has two linespecs, this refers to
-the same source file as the first linespec.
+Several @value{GDBN} commands accept arguments that specify a location
+of your program's code. Since @value{GDBN} is a source-level
+debugger, a location usually specifies some line in the source code;
+for that reason, locations are also known as @dfn{linespecs}.
-@item +@var{offset}
-Specifies the line @var{offset} lines after the last line printed.
-When used as the second linespec in a @code{list} command that has
-two, this specifies the line @var{offset} lines down from the
-first linespec.
+Here are all the different ways of specifying a code location that
+@value{GDBN} understands:
-@item -@var{offset}
-Specifies the line @var{offset} lines before the last line printed.
+@table @code
+@item @var{linenum}
+Specifies the line number @var{linenum} of the current source file.
-@item @var{filename}:@var{number}
-Specifies line @var{number} in the source file @var{filename}.
+@item -@var{offset}
+@itemx +@var{offset}
+Specifies the line @var{offset} lines before or after the @dfn{current
+line}. For the @code{list} command, the current line is the last one
+printed; for the breakpoint commands, this is the line at which
+execution stopped in the currently selected @dfn{stack frame}
+(@pxref{Frames, ,Frames}, for a description of stack frames.) When
+used as the second of the two linespecs in a @code{list} command,
+this specifies the line @var{offset} lines up or down from the first
+linespec.
+
+@item @var{filename}:@var{linenum}
+Specifies the line @var{linenum} in the source file @var{filename}.
@item @var{function}
Specifies the line that begins the body of the function @var{function}.
-For example: in C, this is the line with the open brace.
+For example, in C, this is the line with the open brace.
@item @var{filename}:@var{function}
-Specifies the line of the open-brace that begins the body of the
-function @var{function} in the file @var{filename}. You only need the
-file name with a function name to avoid ambiguity when there are
-identically named functions in different source files.
+Specifies the line that begins the body of the function @var{function}
+in the file @var{filename}. You only need the file name with a
+function name to avoid ambiguity when there are identically named
+functions in different source files.
@item *@var{address}
-Specifies the line containing the program address @var{address}.
-@var{address} may be any expression.
+Specifies the program address @var{address}. For line-oriented
+commands, such as @code{list} and @code{edit}, this specifies a source
+line that contains @var{address}. For @code{break} and other
+breakpoint oriented commands, this can be used to set breakpoints in
+parts of your program which do not have debugging information or
+source files.
+
+Here @var{address} may be any expression valid in the current working
+language (@pxref{Languages, working language}) that specifies a code
+address. As a convenience, @value{GDBN} extends the semantics of
+expressions used in locations to cover the situations that frequently
+happen during debugging. Here are the various forms of @var{address}:
+
+@table @code
+@item @var{expression}
+Any expression valid in the current working language.
+
+@item @var{funcaddr}
+An address of a function or procedure derived from its name. In C,
+C@t{++}, Java, Objective-C, Fortran, minimal, and assembly, this is
+simply the function's name @var{function} (and actually a special case
+of a valid expression). In Pascal and Modula-2, this is
+@code{&@var{function}}. In Ada, this is @code{@var{function}'Address}
+(although the Pascal form also works).
+
+This form specifies the address of the function's first instruction,
+before the stack frame and arguments have been set up.
+
+@item '@var{filename}'::@var{funcaddr}
+Like @var{funcaddr} above, but also specifies the name of the source
+file explicitly. This is useful if the name of the function does not
+specify the function unambiguously, e.g., if there are several
+functions with identical names in different source files.
+@end table
+
@end table
+
@node Edit
@section Editing Source Files
@cindex editing source files
is invoked with the current line set to
the active line in the program.
Alternatively, there are several ways to specify what part of the file you
-want to print if you want to see other parts of the program.
-
-Here are the forms of the @code{edit} command most commonly used:
+want to print if you want to see other parts of the program:
@table @code
-@item edit
-Edit the current source file at the active line number in the program.
+@item edit @var{location}
+Edit the source file specified by @code{location}. Editing starts at
+that @var{location}, e.g., at the specified source line of the
+specified file. @xref{Specify Location}, for all the possible forms
+of the @var{location} argument; here are the forms of the @code{edit}
+command most commonly used:
+@table @code
@item edit @var{number}
Edit the current source file with @var{number} as the active line number.
@item edit @var{function}
Edit the file containing @var{function} at the beginning of its definition.
+@end table
-@item edit @var{filename}:@var{number}
-Specifies line @var{number} in the source file @var{filename}.
-
-@item edit @var{filename}:@var{function}
-Specifies the line that begins the body of the
-function @var{function} in the file @var{filename}. You only need the
-file name with a function name to avoid ambiguity when there are
-identically named functions in different source files.
-
-@item edit *@var{address}
-Specifies the line containing the program address @var{address}.
-@var{address} may be any expression.
@end table
@subsection Choosing your Editor
@item info line @var{linespec}
Print the starting and ending addresses of the compiled code for
source line @var{linespec}. You can specify source lines in any of
-the ways understood by the @code{list} command (@pxref{List, ,Printing
-Source Lines}).
+the ways documented in @ref{Specify Location}.
@end table
For example, we can use @code{info line} to discover the location of
Display the number of elements of a large array that @value{GDBN} will print.
If the number is 0, then the printing is unlimited.
+@item set print frame-arguments @var{value}
+@cindex printing frame argument values
+@cindex print all frame argument values
+@cindex print frame argument values for scalars only
+@cindex do not print frame argument values
+This command allows to control how the values of arguments are printed
+when the debugger prints a frame (@pxref{Frames}). The possible
+values are:
+
+@table @code
+@item all
+The values of all arguments are printed. This is the default.
+
+@item scalars
+Print the value of an argument only if it is a scalar. The value of more
+complex arguments such as arrays, structures, unions, etc, is replaced
+by @code{@dots{}}. Here is an example where only scalar arguments are shown:
+
+@smallexample
+#1 0x08048361 in call_me (i=3, s=@dots{}, ss=0xbf8d508c, u=@dots{}, e=green)
+ at frame-args.c:23
+@end smallexample
+
+@item none
+None of the argument values are printed. Instead, the value of each argument
+is replaced by @code{@dots{}}. In this case, the example above now becomes:
+
+@smallexample
+#1 0x08048361 in call_me (i=@dots{}, s=@dots{}, ss=@dots{}, u=@dots{}, e=@dots{})
+ at frame-args.c:23
+@end smallexample
+@end table
+
+By default, all argument values are always printed. But this command
+can be useful in several cases. For instance, it can be used to reduce
+the amount of information printed in each frame, making the backtrace
+more readable. Also, this command can be used to improve performance
+when displaying Ada frames, because the computation of large arguments
+can sometimes be CPU-intensive, especiallly in large applications.
+Setting @code{print frame-arguments} to @code{scalars} or @code{none}
+avoids this computation, thus speeding up the display of each Ada frame.
+
+@item show print frame-arguments
+Show how the value of arguments should be displayed when printing a frame.
+
@item set print repeats
@cindex repeated array elements
Set the threshold for suppressing display of repeated array
to such memory. The checks are only performed if there's at least one
memory range defined. If @code{off} is specified, make @value{GDBN}
treat the memory not explicitly described by the memory ranges as RAM.
-The default value is @code{off}.
+The default value is @code{on}.
@kindex show mem inaccessible-by-default
@item show mem inaccessible-by-default
Show the current handling of accesses to unknown memory.
* C Checks:: C and C@t{++} type and range checks
* Debugging C:: @value{GDBN} and C
* Debugging C Plus Plus:: @value{GDBN} features for C@t{++}
+* Decimal Floating Point:: Numbers in Decimal Floating Point format
@end menu
@node C Operators
For debugging C@t{++}, @value{GDBN} implements a use of @samp{&} beyond what is
allowed in the C@t{++} language itself: you can use @samp{&(&@var{ref})}
-(or, if you prefer, simply @samp{&&@var{ref}}) to examine the address
+to examine the address
where a C@t{++} reference variable (declared with @samp{&@var{ref}}) is
stored.
@xref{Completion,, Command Completion}, for details on how to do this.
@end table
+@node Decimal Floating Point
+@subsubsection Decimal Floating Point format
+@cindex decimal floating point format
+
+@value{GDBN} can examine, set and perform computations with numbers in
+decimal floating point format, which in the C language correspond to the
+@code{_Decimal32}, @code{_Decimal64} and @code{_Decimal128} types as
+specified by the extension to support decimal floating-point arithmetic.
+
+There are two encodings in use, depending on the architecture: BID (Binary
+Integer Decimal) for x86 and x86-64, and DPD (Densely Packed Decimal) for
+PowerPC. @value{GDBN} will use the appropriate encoding for the configured
+target.
+
+Because of a limitation in @file{libdecnumber}, the library used by @value{GDBN}
+to manipulate decimal floating point numbers, it is not possible to convert
+(using a cast, for example) integers wider than 32-bit to decimal float.
+
+In addition, in order to imitate @value{GDBN}'s behaviour with binary floating
+point computations, error checking in decimal float operations ignores
+underflow, overflow and divide by zero exceptions.
+
@node Objective-C
@subsection Objective-C
@item TRUNC(@var{r})
Returns the integral part of @var{r}.
+@item TSIZE(@var{x})
+Returns the size of its argument. @var{x} can be a variable or a type.
+
@item VAL(@var{t},@var{i})
Returns the member of the type @var{t} whose ordinal value is @var{i}.
@end table
Note that the array handling is not yet complete and although the type
is printed correctly, expression handling still assumes that all
arrays have a lower bound of zero and not @code{-10} as in the example
-above. Unbounded arrays are also not yet recognized in @value{GDBN}.
+above.
Here are some more type related Modula-2 examples:
List all the variables local to a particular scope. This command
accepts a @var{location} argument---a function name, a source line, or
an address preceded by a @samp{*}, and prints all the variables local
-to the scope defined by that location. For example:
+to the scope defined by that location. (@xref{Specify Location}, for
+details about supported forms of @var{location}.) For example:
@smallexample
(@value{GDBP}) @b{info scope command_line_handler}
dirname (null)
fullname (null)
blockvector ((struct blockvector *) 0x86c1bd0) (primary)
+ linetable ((struct linetable *) 0x8370fa0)
debugformat DWARF 2
@}
@}
@table @code
@kindex jump
@item jump @var{linespec}
-Resume execution at line @var{linespec}. Execution stops again
-immediately if there is a breakpoint there. @xref{List, ,Printing
-Source Lines}, for a description of the different forms of
-@var{linespec}. It is common practice to use the @code{tbreak} command
-in conjunction with @code{jump}. @xref{Set Breaks, ,Setting
-Breakpoints}.
+@itemx jump @var{location}
+Resume execution at line @var{linespec} or at address given by
+@var{location}. Execution stops again immediately if there is a
+breakpoint there. @xref{Specify Location}, for a description of the
+different forms of @var{linespec} and @var{location}. It is common
+practice to use the @code{tbreak} command in conjunction with
+@code{jump}. @xref{Set Breaks, ,Setting Breakpoints}.
The @code{jump} command does not change the current stack frame, or
the stack pointer, or the contents of any memory location or any
confirmation if the specified line is not in the function currently
executing. However, even bizarre results are predictable if you are
well acquainted with the machine-language code of your program.
-
-@item jump *@var{address}
-Resume execution at the instruction at address @var{address}.
@end table
@c Doesn't work on HP-UX; have to set $pcoqh and $pcoqt.
name and remembers it that way.
@cindex shared libraries
-@value{GDBN} supports GNU/Linux, MS-Windows, HP-UX, SunOS, SVr4, Irix,
+@anchor{Shared Libraries}
+@value{GDBN} supports @sc{gnu}/Linux, MS-Windows, HP-UX, SunOS, SVr4, Irix,
and IBM RS/6000 AIX shared libraries.
+On MS-Windows @value{GDBN} must be linked with the Expat library to support
+shared libraries. @xref{Expat}.
+
@value{GDBN} automatically loads symbol definitions from shared libraries
when you use the @code{run} command, or when you examine a core file.
(Before you issue the @code{run} command, @value{GDBN} does not understand
@menu
* Connecting:: Connecting to a remote target
+* File Transfer:: Sending files to a remote system
* Server:: Using the gdbserver program
* Remote Configuration:: Remote configuration
* Remote Stub:: Implementing a remote stub
and implement.
@end table
+@node File Transfer
+@section Sending files to a remote system
+@cindex remote target, file transfer
+@cindex file transfer
+@cindex sending files to remote systems
+
+Some remote targets offer the ability to transfer files over the same
+connection used to communicate with @value{GDBN}. This is convenient
+for targets accessible through other means, e.g.@: @sc{gnu}/Linux systems
+running @code{gdbserver} over a network interface. For other targets,
+e.g.@: embedded devices with only a single serial port, this may be
+the only way to upload or download files.
+
+Not all remote targets support these commands.
+
+@table @code
+@kindex remote put
+@item remote put @var{hostfile} @var{targetfile}
+Copy file @var{hostfile} from the host system (the machine running
+@value{GDBN}) to @var{targetfile} on the target system.
+
+@kindex remote get
+@item remote get @var{targetfile} @var{hostfile}
+Copy file @var{targetfile} from the target system to @var{hostfile}
+on the host system.
+
+@kindex remote delete
+@item remote delete @var{targetfile}
+Delete @var{targetfile} from the target system.
+
+@end table
+
@node Server
@section Using the @code{gdbserver} Program
@tab @code{QPassSignals}
@tab @code{handle @var{signal}}
+@item @code{hostio-close-packet}
+@tab @code{vFile:close}
+@tab @code{remote get}, @code{remote put}
+
+@item @code{hostio-open-packet}
+@tab @code{vFile:open}
+@tab @code{remote get}, @code{remote put}
+
+@item @code{hostio-pread-packet}
+@tab @code{vFile:pread}
+@tab @code{remote get}, @code{remote put}
+
+@item @code{hostio-pwrite-packet}
+@tab @code{vFile:pwrite}
+@tab @code{remote get}, @code{remote put}
+
+@item @code{hostio-unlink-packet}
+@tab @code{vFile:unlink}
+@tab @code{remote delete}
@end multitable
@node Remote Stub
@node PowerPC
@subsection PowerPC
+@value{GDBN} provides the following PowerPC-specific commands:
+
@table @code
+@kindex set powerpc
+@item set powerpc soft-float
+@itemx show powerpc soft-float
+Force @value{GDBN} to use (or not use) a software floating point calling
+convention. By default, @value{GDBN} selects the calling convention based
+on the selected architecture and the provided executable file.
+
+@item set powerpc vector-abi
+@itemx show powerpc vector-abi
+Force @value{GDBN} to use the specified calling convention for vector
+arguments and return values. The valid options are @samp{auto};
+@samp{generic}, to avoid vector registers even if they are present;
+@samp{altivec}, to use AltiVec registers; and @samp{spe} to use SPE
+registers. By default, @value{GDBN} selects the calling convention
+based on the selected architecture and the provided executable file.
+
@kindex target dink32
@item target dink32 @var{dev}
DINK32 ROM monitor.
@cindex SDS protocol
The following commands specific to the SDS protocol are supported
-by@value{GDBN}:
+by @value{GDBN}:
@table @code
@item set sdstimeout @var{nsec}
@samp{\a}, and @samp{\f}, that consist of backslash followed by a
single character. Octal and hexadecimal escape sequences are not
supported.
+
+Additionally, @code{printf} supports conversion specifications for DFP
+(@dfn{Decimal Floating Point}) types using the following length modifiers
+together with a floating point specifier.
+letters:
+
+@itemize @bullet
+@item
+@samp{H} for printing @code{Decimal32} types.
+
+@item
+@samp{D} for printing @code{Decimal64} types.
+
+@item
+@samp{DD} for printing @code{Decimal128} types.
+@end itemize
+
+If the underlying @code{C} implementation used to build @value{GDBN} has
+support for the three length modifiers for DFP types, other modifiers
+such as width and precision will also be available for @value{GDBN} to use.
+
+In case there is no such @code{C} support, no additional modifiers will be
+available and the value will be printed in the standard way.
+
+Here's an example of printing DFP types using the above conversion letters:
+@smallexample
+printf "D32: %Hf - D64: %Df - D128: %DDf\n",1.2345df,1.2E10dd,1.2E1dl
+@end smallexample
+
@end table
@node Interpreters
* GDB/MI Signal Handling Commands::
@end ignore
* GDB/MI Target Manipulation::
+* GDB/MI File Transfer Commands::
* GDB/MI Miscellaneous Commands::
@end menu
@subsubheading Synopsis
@smallexample
- -break-insert [ -t ] [ -h ] [ -r ]
+ -break-insert [ -t ] [ -h ] [ -f ]
[ -c @var{condition} ] [ -i @var{ignore-count} ]
- [ -p @var{thread} ] [ @var{line} | @var{addr} ]
+ [ -p @var{thread} ] [ @var{location} ]
@end smallexample
@noindent
-If specified, @var{line}, can be one of:
+If specified, @var{location}, can be one of:
@itemize @bullet
@item function
Make the breakpoint conditional on @var{condition}.
@item -i @var{ignore-count}
Initialize the @var{ignore-count}.
-@item -r
-Insert a regular breakpoint in all the functions whose names match the
-given regular expression. Other flags are not applicable to regular
-expressions.
+@item -f
+If @var{location} cannot be parsed (for example if it
+refers to unknown files or functions), create a pending
+breakpoint. Without this flag, @value{GDBN} will report
+an error, and won't create a breakpoint, if @var{location}
+cannot be parsed.
@end table
@subsubheading Result
(gdb)
@end smallexample
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI File Transfer Commands
+@section @sc{gdb/mi} File Transfer Commands
+
+
+@subheading The @code{-target-file-put} Command
+@findex -target-file-put
+
+@subsubheading Synopsis
+
+@smallexample
+ -target-file-put @var{hostfile} @var{targetfile}
+@end smallexample
+
+Copy file @var{hostfile} from the host system (the machine running
+@value{GDBN}) to @var{targetfile} on the target system.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{remote put}.
+
+@subsubheading Example
+
+@smallexample
+(gdb)
+-target-file-put localfile remotefile
+^done
+(gdb)
+@end smallexample
+
+
+@subheading The @code{-target-file-put} Command
+@findex -target-file-get
+
+@subsubheading Synopsis
+
+@smallexample
+ -target-file-get @var{targetfile} @var{hostfile}
+@end smallexample
+
+Copy file @var{targetfile} from the target system to @var{hostfile}
+on the host system.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{remote get}.
+
+@subsubheading Example
+
+@smallexample
+(gdb)
+-target-file-get remotefile localfile
+^done
+(gdb)
+@end smallexample
+
+
+@subheading The @code{-target-file-delete} Command
+@findex -target-file-delete
+
+@subsubheading Synopsis
+
+@smallexample
+ -target-file-delete @var{targetfile}
+@end smallexample
+
+Delete @var{targetfile} from the target system.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{remote delete}.
+
+@subsubheading Example
+
+@smallexample
+(gdb)
+-target-file-delete remotefile
+^done
+(gdb)
+@end smallexample
+
+
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Miscellaneous Commands
@section Miscellaneous @sc{gdb/mi} Commands
@samp{frozen-varobjs}---indicates presence of the
@code{-var-set-frozen} command, as well as possible presense of the
@code{frozen} field in the output of @code{-varobj-create}.
+@item
+@samp{pending-breakpoints}---indicates presence of the @code{-f}
+option to the @code{-break-insert} command.
+
@end itemize
@subheading The @code{-interpreter-exec} Command
standard locations; if it is installed in an unusual path, you can
use the @option{--with-libexpat-prefix} option to specify its location.
-Expat is used for remote protocol memory maps (@pxref{Memory Map Format})
-and for target descriptions (@pxref{Target Descriptions}).
+Expat is used for:
+
+@itemize @bullet
+@item
+Remote protocol memory maps (@pxref{Memory Map Format})
+@item
+Target descriptions (@pxref{Target Descriptions})
+@item
+Remote shared library lists (@pxref{Library List Format})
+@item
+MS-Windows shared libraries (@pxref{Shared Libraries})
+@end itemize
@end table
Print the entire architecture configuration. The optional argument
@var{file} names the file where the output goes.
+@kindex maint print c-tdesc
+@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.
+
@kindex maint print dummy-frames
@item maint print dummy-frames
Prints the contents of @value{GDBN}'s internal dummy-frame stack.
* General Query Packets::
* Register Packet Format::
* Tracepoint Packets::
+* Host I/O Packets::
* Interrupts::
* Examples::
* File-I/O Remote Protocol Extension::
is not interpreted as the start of a run-length encoded sequence
(described next).
-Response @var{data} can be run-length encoded to save space. A @samp{*}
-means that the next character is an @sc{ascii} encoding giving a repeat count
-which stands for that many repetitions of the character preceding the
-@samp{*}. The encoding is @code{n+29}, yielding a printable character
-where @code{n >=3} (which is where rle starts to win). The printable
-characters @samp{$}, @samp{#}, @samp{+} and @samp{-} or with a numeric
-value greater than 126 should not be used.
-
-So:
-@smallexample
-"@code{0* }"
-@end smallexample
-@noindent
-means the same as "0000".
+Response @var{data} can be run-length encoded to save space.
+Run-length encoding replaces runs of identical characters with one
+instance of the repeated character, followed by a @samp{*} and a
+repeat count. The repeat count is itself sent encoded, to avoid
+binary characters in @var{data}: a value of @var{n} is sent as
+@code{@var{n}+29}. For a repeat count greater or equal to 3, this
+produces a printable @sc{ascii} character, e.g.@: a space (@sc{ascii}
+code 32) for a repeat count of 3. (This is because run-length
+encoding starts to win for counts 3 or more.) Thus, for example,
+@samp{0* } is a run-length encoding of ``0000'': the space character
+after @samp{*} means repeat the leading @code{0} @w{@code{32 - 29 =
+3}} more times.
+
+The printable characters @samp{#} and @samp{$} or with a numeric value
+greater than 126 must not be used. Runs of six repeats (@samp{#}) or
+seven repeats (@samp{$}) can be expanded using a repeat count of only
+five (@samp{"}). For example, @samp{00000000} can be encoded as
+@samp{0*"00}.
The error response returned for some packets includes a two character
error number. That number is not well defined.
The @samp{vCont} packet is not supported.
@end table
+@item vFile:@var{operation}:@var{parameter}@dots{}
+@cindex @samp{vFile} packet
+Perform a file operation on the target system. For details,
+see @ref{Host I/O Packets}.
+
@item vFlashErase:@var{addr},@var{length}
@cindex @samp{vFlashErase} packet
Direct the stub to erase @var{length} bytes of flash starting at
@end table
+@node Host I/O Packets
+@section Host I/O Packets
+@cindex Host I/O, remote protocol
+@cindex file transfer, remote protocol
+
+The @dfn{Host I/O} packets allow @value{GDBN} to perform I/O
+operations on the far side of a remote link. For example, Host I/O is
+used to upload and download files to a remote target with its own
+filesystem. Host I/O uses the same constant values and data structure
+layout as the target-initiated File-I/O protocol. However, the
+Host I/O packets are structured differently. The target-initiated
+protocol relies on target memory to store parameters and buffers.
+Host I/O requests are initiated by @value{GDBN}, and the
+target's memory is not involved. @xref{File-I/O Remote Protocol
+Extension}, for more details on the target-initiated protocol.
+
+The Host I/O request packets all encode a single operation along with
+its arguments. They have this format:
+
+@table @samp
+
+@item vFile:@var{operation}: @var{parameter}@dots{}
+@var{operation} is the name of the particular request; the target
+should compare the entire packet name up to the second colon when checking
+for a supported operation. The format of @var{parameter} depends on
+the operation. Numbers are always passed in hexadecimal. Negative
+numbers have an explicit minus sign (i.e.@: two's complement is not
+used). Strings (e.g.@: filenames) are encoded as a series of
+hexadecimal bytes. The last argument to a system call may be a
+buffer of escaped binary data (@pxref{Binary Data}).
+
+@end table
+
+The valid responses to Host I/O packets are:
+
+@table @samp
+
+@item F @var{result} [, @var{errno}] [; @var{attachment}]
+@var{result} is the integer value returned by this operation, usually
+non-negative for success and -1 for errors. If an error has occured,
+@var{errno} will be included in the result. @var{errno} will have a
+value defined by the File-I/O protocol (@pxref{Errno Values}). For
+operations which return data, @var{attachment} supplies the data as a
+binary buffer. Binary buffers in response packets are escaped in the
+normal way (@pxref{Binary Data}). See the individual packet
+documentation for the interpretation of @var{result} and
+@var{attachment}.
+
+@item
+An empty response indicates that this operation is not recognized.
+
+@end table
+
+These are the supported Host I/O operations:
+
+@table @samp
+@item vFile:open: @var{pathname}, @var{flags}, @var{mode}
+Open a file at @var{pathname} and return a file descriptor for it, or
+return -1 if an error occurs. @var{pathname} is a string,
+@var{flags} is an integer indicating a mask of open flags
+(@pxref{Open Flags}), and @var{mode} is an integer indicating a mask
+of mode bits to use if the file is created (@pxref{mode_t Values}).
+@xref{open}, for details of the open flags and mode values.
+
+@item vFile:close: @var{fd}
+Close the open file corresponding to @var{fd} and return 0, or
+-1 if an error occurs.
+
+@item vFile:pread: @var{fd}, @var{count}, @var{offset}
+Read data from the open file corresponding to @var{fd}. Up to
+@var{count} bytes will be read from the file, starting at @var{offset}
+relative to the start of the file. The target may read fewer bytes;
+common reasons include packet size limits and an end-of-file
+condition. The number of bytes read is returned. Zero should only be
+returned for a successful read at the end of the file, or if
+@var{count} was zero.
+
+The data read should be returned as a binary attachment on success.
+If zero bytes were read, the response should include an empty binary
+attachment (i.e.@: a trailing semicolon). The return value is the
+number of target bytes read; the binary attachment may be longer if
+some characters were escaped.
+
+@item vFile:pwrite: @var{fd}, @var{offset}, @var{data}
+Write @var{data} (a binary buffer) to the open file corresponding
+to @var{fd}. Start the write at @var{offset} from the start of the
+file. Unlike many @code{write} system calls, there is no
+separate @var{count} argument; the length of @var{data} in the
+packet is used. @samp{vFile:write} returns the number of bytes written,
+which may be shorter than the length of @var{data}, or -1 if an
+error occurred.
+
+@item vFile:unlink: @var{pathname}
+Delete the file at @var{pathname} on the target. Return 0,
+or -1 if an error occurs. @var{pathname} is a string.
+
+@end table
+
@node Interrupts
@section Interrupts
@cindex interrupts (remote protocol)
addresses, not relocation offsets; they do not depend on the library's
link-time base addresses.
+@value{GDBN} must be linked with the Expat library to support XML
+library lists. @xref{Expat}.
+
A simple memory map, with one loaded library relocated by a single
offset, looks like this:
The memory map is obtained using the @samp{qXfer:memory-map:read}
(@pxref{qXfer memory map read}) packet and is an XML document that
-lists memory regions. The top-level structure of the document is shown below:
+lists memory regions.
+
+@value{GDBN} must be linked with the Expat library to support XML
+memory maps. @xref{Expat}.
+
+The top-level structure of the document is shown below:
@smallexample
<?xml version="1.0"?>
processor variants it has never seen before --- to the extent that the
descriptions are accurate, and that @value{GDBN} understands them.
-@value{GDBN} must be compiled with Expat support to support XML target
-descriptions. @xref{Expat}.
+@value{GDBN} must be linked with the Expat library to support XML
+target descriptions. @xref{Expat}.
@menu
* Retrieving Descriptions:: How descriptions are fetched from a target.
@itemx int16
@itemx int32
@itemx int64
+@itemx int128
Signed integer types holding the specified number of bits.
@item uint8
@itemx uint16
@itemx uint32
@itemx uint64
+@itemx uint128
Unsigned integer types holding the specified number of bits.
@item code_ptr
@samp{fpiaddr}.
@end table
+@subsection PowerPC Features
+@cindex target descriptions, PowerPC features
+
+The @samp{org.gnu.gdb.power.core} feature is required for PowerPC
+targets. It should contain registers @samp{r0} through @samp{r31},
+@samp{pc}, @samp{msr}, @samp{cr}, @samp{lr}, @samp{ctr}, and
+@samp{xer}. They may be 32-bit or 64-bit depending on the target.
+
+The @samp{org.gnu.gdb.power.fpu} feature is optional. It should
+contain registers @samp{f0} through @samp{f31} and @samp{fpscr}.
+
+The @samp{org.gnu.gdb.power.altivec} feature is optional. It should
+contain registers @samp{vr0} through @samp{vr31}, @samp{vscr},
+and @samp{vrsave}.
+
+The @samp{org.gnu.gdb.power.spe} feature is optional. It should
+contain registers @samp{ev0h} through @samp{ev31h}, @samp{acc}, and
+@samp{spefscr}. SPE targets should provide 32-bit registers in
+@samp{org.gnu.gdb.power.core} and provide the upper halves in
+@samp{ev0h} through @samp{ev31h}. @value{GDBN} will combine
+these to present registers @samp{ev0} through @samp{ev31} to the
+user.
+
@include gpl.texi
@raisesections
projects / deliverable / binutils-gdb.git / blobdiff