gdb/doc/gdb.info-1 - Issue 124383005: GDB 7.6.50

Unified Diff: gdb/doc/gdb.info-1

Issue 124383005: GDB 7.6.50 (Closed) Base URL: http://git.chromium.org/native_client/nacl-gdb.git@upstream

Patch Set: Created 6 years, 11 months ago

Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.

Jump to:

View side-by-side diff with in-line comments

Index: gdb/doc/gdb.info-1

diff --git a/gdb/doc/gdb.info-1 b/gdb/doc/gdb.info-1

index 0e46981efbbcc6eaaa815f95491e23a9564868ac..508e3d50dc7d5bb851e2169f23a9b4316eb9868a 100644

--- a/gdb/doc/gdb.info-1

+++ b/gdb/doc/gdb.info-1

@@ -1,13 +1,12 @@

-This is gdb.info, produced by makeinfo version 4.8 from ./gdb.texinfo.

+This is gdb.info, produced by makeinfo version 4.13 from ./gdb.texinfo.

INFO-DIR-SECTION Software development

START-INFO-DIR-ENTRY

* Gdb: (gdb). The GNU debugger.

+* gdbserver: (gdb) Server. The GNU debugging server.

END-INFO-DIR-ENTRY

-1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,

-2010 2011, 2012 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

@@ -23,11 +22,9 @@ developing GNU and promoting software freedom."

This file documents the GNU debugger GDB.

This is the Tenth Edition, of `Debugging with GDB: the GNU

-Source-Level Debugger' for GDB (GDB) Version 7.5.1.

+Source-Level Debugger' for GDB (GDB) Version 7.6.50.20131211-cvs.

-1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,

-2010 2011, 2012 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

@@ -48,9 +45,9 @@ Debugging with GDB

This file describes GDB, the GNU symbolic debugger.

- This is the Tenth Edition, for GDB (GDB) Version 7.5.1.

+ This is the Tenth Edition, for GDB (GDB) Version 7.6.50.20131211-cvs.

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 software

@@ -110,6 +107,7 @@ in general. We will miss him.

the operating system

* Trace File Format:: GDB trace file format

* Index Section Format:: .gdb_index section format

+* Man Pages:: Manual pages

* Copying:: GNU General Public License says

how you can copy and share GDB

* GNU Free Documentation License:: The license for this documentation

@@ -141,16 +139,16 @@ these) to help you catch bugs in the act:

correcting the effects of one bug and go on to learn about another.

You can use GDB to debug programs written in C and C++. For more

-information, see *Note Supported Languages: Supported Languages. For

-more information, see *Note C and C++: C.

+information, see *note Supported Languages: Supported Languages. For

+more information, see *note C and C++: C.

- Support for D is partial. For information on D, see *Note D: D.

+ Support for D is partial. For information on D, see *note D: D.

Support for Modula-2 is partial. For information on Modula-2, see

-*Note Modula-2: Modula-2.

+*note Modula-2: Modula-2.

Support for OpenCL C is partial. For information on OpenCL C, see

-*Note OpenCL C: OpenCL C.

+*note OpenCL C: OpenCL C.

Debugging Pascal programs which use sets, subranges, file variables,

or nested functions does not currently work. GDB does not support

@@ -496,7 +494,7 @@ Let us use GDB to try to see what is going on.

There is absolutely no warranty for GDB; type "show warranty"

for details.

(gdb)

GDB reads only enough symbol data to know where to find the rest when

@@ -850,11 +848,34 @@ mode or quiet mode.

`-nx'

`-n'

- Do not execute commands found in any initialization files.

- Normally, GDB executes the commands in these files after all the

- command options and arguments have been processed. *Note Command

+ Do not execute commands found in any initialization file. There

+ are three init files, loaded in the following order:

+ ``system.gdbinit''

+ This is the system-wide init file. Its location is specified

+ with the `--with-system-gdbinit' configure option (*note

+ System-wide configuration::). It is loaded first when GDB

+ starts, before command line options have been processed.

+ ``~/.gdbinit''

+ This is the init file in your home directory. It is loaded

+ next, after `system.gdbinit', and before command options have

+ been processed.

+ ``./.gdbinit''

+ This is the init file in the current directory. It is loaded

+ last, after command line options other than `-x' and `-ex'

+ have been processed. Command line options `-x' and `-ex' are

+ processed last, after `./.gdbinit' has been loaded.

+ For further documentation on startup processing, *Note Startup::.

+ For documentation on how to write command files, *Note Command

Files: Command Files.

+`-nh'

+ Do not execute commands found in `~/.gdbinit', the init file in

+ your home directory. *Note Startup::.

`-quiet'

`-silent'

`-q'

@@ -940,11 +961,6 @@ mode or quiet mode.

the two `\032' characters as a signal to display the source code

for the frame.

-`-epoch'

- The Epoch Emacs-GDB interface sets this option when it runs GDB as

- a subprocess. It tells GDB to modify its print routines so as to

- allow Epoch to display values of expressions in a separate window.

`-annotate LEVEL'

This option sets the "annotation level" inside GDB. Its effect is

identical to using `set annotate LEVEL' (*note Annotations::).

@@ -1008,6 +1024,11 @@ mode or quiet mode.

This option causes GDB to print its version number and no-warranty

blurb, and exit.

+`-configuration'

+ This option causes GDB to print details about its build-time

+ configuration parameters, and then exit. These details can be

+ important when reporting GDB bugs (*note GDB Bugs::).

File: gdb.info, Node: Startup, Prev: Mode Options, Up: Invoking GDB

@@ -1077,9 +1098,9 @@ use `gdb --help'.

The GDB init files are normally called `.gdbinit'. The DJGPP port

of GDB uses the name `gdb.ini', due to the limitations of file names

-imposed by DOS filesystems. The Windows ports of GDB use the standard

-name, but if they find a `gdb.ini' file, they warn you about that and

-suggest to rename the file to the standard name.

+imposed by DOS filesystems. The Windows port of GDB uses the standard

+name, but if it finds a `gdb.ini' file in your home directory, it warns

+you about that and suggests to rename the file to the standard name.

---------- Footnotes ----------

@@ -1208,7 +1229,7 @@ to the `help' command.

previous command. Certain commands (for example, `run') will not

repeat this way; these are commands whose unintentional repetition

might cause trouble and which you are unlikely to want to repeat.

-User-defined commands can disable this feature; see *Note dont-repeat:

+User-defined commands can disable this feature; see *note dont-repeat:

Define.

The `list' and `x' commands, when you repeat them with <RET>,

@@ -1321,9 +1342,9 @@ In general, GDB can tell that a quote is needed (and inserts it) if you

have not yet started typing the argument list when you ask for

completion on an overloaded symbol.

- For more information about overloaded functions, see *Note C++

+ For more information about overloaded functions, see *note C++

Expressions: C Plus Plus Expressions. You can use the command `set

-overload-resolution off' to disable overload resolution; see *Note GDB

+overload-resolution off' to disable overload resolution; see *note GDB

Features for C++: Debugging C Plus Plus.

When completing in an expression which looks up a field in a

@@ -1484,7 +1505,7 @@ point to all the sub-commands. *Note Command and Variable Index::.

you can use `show' with no arguments; you may also use `info set'.

Both commands produce the same display.

- Here are three miscellaneous `show' subcommands, all of which are

+ Here are several miscellaneous `show' subcommands, all of which are

exceptional in lacking corresponding `set' commands:

`show version'

@@ -1506,6 +1527,14 @@ exceptional in lacking corresponding `set' commands:

Display the GNU "NO WARRANTY" statement, or a warranty, if your

version of GDB comes with one.

+`show configuration'

+ Display detailed information about the way GDB was configured when

+ it was built. This displays the optional arguments passed to the

+ `configure' script and also configuration parameters detected

+ automatically by `configure'. When reporting a GDB bug (*note GDB

+ Bugs::), it is important to include this information in your

+ report.

File: gdb.info, Node: Running, Next: Stopping, Prev: Commands, Up: Top

@@ -1563,7 +1592,7 @@ debugging information.

making it possible to debug optimized code. We recommend that you

_always_ use `-g' whenever you compile a program. You may think your

program is correct, but there is no sense in pushing your luck. For

-more information, see *Note Optimized Code::.

+more information, see *note Optimized Code::.

Older versions of the GNU C compiler permitted a variant option

`-gg' for debugging information. GDB no longer supports this format;

@@ -1626,8 +1655,10 @@ The _arguments._

is used to pass the arguments, so that you may use normal

conventions (such as wildcard expansion or variable substitution)

in describing the arguments. In Unix systems, you can control

- which shell is used with the `SHELL' environment variable. *Note

- Your Program's Arguments: Arguments.

+ which shell is used with the `SHELL' environment variable. If you

+ do not define `SHELL', GDB uses the default shell (`/bin/sh').

+ You can disable use of any shell with the `set startup-with-shell'

+ command (see below for details).

The _environment._

Your program normally inherits its environment from GDB, but you

@@ -1690,11 +1721,11 @@ breakpoints.

`start' or `run'.

It is sometimes necessary to debug the program during elaboration.

- In these cases, using the `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.

+ In these cases, using the `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.

`set exec-wrapper WRAPPER'

`show exec-wrapper'

@@ -1721,6 +1752,29 @@ breakpoints.

This command is available when debugging locally on most targets,

excluding DJGPP, Cygwin, MS Windows, and QNX Neutrino.

+`set startup-with-shell'

+`set startup-with-shell on'

+`set startup-with-shell off'

+`show set startup-with-shell'

+ On Unix systems, by default, if a shell is available on your

+ target, GDB) uses it to start your program. Arguments of the

+ `run' command are passed to the shell, which does variable

+ substitution, expands wildcard characters and performs redirection

+ of I/O. In some circumstances, it may be useful to disable such

+ use of a shell, for example, when debugging the shell itself or

+ diagnosing startup failures such as:

+ (gdb) run

+ Starting program: ./a.out

+ During startup program terminated with signal SIGSEGV, Segmentation fault.

+ which indicates the shell or the wrapper specified with

+ `exec-wrapper' crashed, not your program. Most often, this is

+ caused by something odd in your shell's non-interactive mode

+ initialization file--such as `.cshrc' for C-shell, $`.zshenv' for

+ the Z shell, or the file specified in the `BASH_ENV' environment

+ variable for BASH.

`set disable-randomization'

`set disable-randomization on'

This option (enabled by default in GDB) will turn off the native

@@ -1870,10 +1924,12 @@ modified environment without having to start GDB over again.

_Warning:_ On Unix systems, GDB runs your program using the shell

indicated by your `SHELL' environment variable if it exists (or

`/bin/sh' if not). If your `SHELL' variable names a shell that runs an

-initialization file--such as `.cshrc' for C-shell, or `.bashrc' for

-BASH--any variables you set in that file affect your program. You may

-wish to move setting of environment variables to files that are only

-run when you sign on, such as `.login' or `.profile'.

+initialization file when started non-interactively--such as `.cshrc'

+for C-shell, $`.zshenv' for the Z shell, or the file specified in the

+`BASH_ENV' environment variable for BASH--any variables you set in that

+file affect your program. You may wish to move setting of environment

+variables to files that are only run when you sign on, such as `.login'

+or `.profile'.

File: gdb.info, Node: Working Directory, Next: Input/Output, Prev: Environment, Up: Running

@@ -1891,8 +1947,9 @@ GDB with the `cd' command.

that specify files for GDB to operate on. *Note Commands to Specify

Files: Files.

-`cd DIRECTORY'

- Set the GDB working directory to DIRECTORY.

+`cd [DIRECTORY]'

+ Set the GDB working directory to DIRECTORY. If not given,

+ DIRECTORY uses `'~''.

`pwd'

Print the GDB working directory.

@@ -2762,7 +2819,7 @@ exception or the loading of a library. As with watchpoints, you use a

different command to set a catchpoint (*note Setting Catchpoints: Set

Catchpoints.), but aside from that, you can manage a catchpoint like any

other breakpoint. (To stop when your program receives a signal, use the

-`handle' command; see *Note Signals: Signals.)

+`handle' command; see *note Signals: Signals.)

GDB assigns a number to each breakpoint, watchpoint, or catchpoint

when you create it; these numbers are successive integers starting with

@@ -2800,7 +2857,7 @@ File: gdb.info, Node: Set Breaks, Next: Set Watchpoints, Up: Breakpoints

Breakpoints are set with the `break' command (abbreviated `b'). The

debugger convenience variable `$bpnum' records the number of the

-breakpoint you've set most recently; see *Note Convenience Variables:

+breakpoint you've set most recently; see *note Convenience Variables:

Convenience Vars, for a discussion of what you can do with convenience

variables.

@@ -2871,7 +2928,7 @@ variables.

unused hardware breakpoints before setting new ones (*note

Disabling Breakpoints: Disabling.). *Note Break Conditions:

Conditions. For remote targets, you can restrict the number of

- hardware breakpoints GDB will use, see *Note set remote

+ hardware breakpoints GDB will use, see *note set remote

hardware-breakpoint-limit::.

`thbreak ARGS'

@@ -2882,7 +2939,7 @@ variables.

program stops there. Also, like the `hbreak' command, the

breakpoint requires hardware support and some target hardware may

not have this support. *Note Disabling Breakpoints: Disabling.

- See also *Note Break Conditions: Conditions.

+ See also *note Break Conditions: Conditions.

`rbreak REGEX'

Set breakpoints on all functions matching the regular expression

@@ -2943,10 +3000,10 @@ variables.

_Address_

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 `<PENDING>'. Such breakpoint won't

- fire until a shared library that has the symbol or line

- referred by breakpoint is loaded. See below for details. A

+ For a pending breakpoint whose address is not yet known, this

+ field will contain `<PENDING>'. Such breakpoint won't fire

+ until a shared library that has the symbol or line referred

+ by breakpoint is loaded. See below for details. A

breakpoint with several locations will have `<MULTIPLE>' in

this field--see below for details.

@@ -3248,7 +3305,7 @@ do not slow down the running of your program.

The `[mask MASKVALUE]' argument allows creation of masked

watchpoints, if the current architecture supports this feature

- (e.g., PowerPC Embedded architecture, see *Note PowerPC

+ (e.g., PowerPC Embedded architecture, see *note PowerPC

Embedded::.) A "masked watchpoint" specifies a mask in addition

to an address to watch. The mask specifies that some bits of an

address (the bits which are reset in the mask) should be ignored

@@ -3304,7 +3361,7 @@ use the hardware mechanism of watching expression values.)

Show the current mode of using hardware watchpoints.

For remote targets, you can restrict the number of hardware

-watchpoints GDB will use, see *Note set remote

+watchpoints GDB will use, see *note set remote

hardware-breakpoint-limit::.

When you issue the `watch' command, GDB reports

@@ -3389,11 +3446,59 @@ shared library. Use the `catch' command to set a catchpoint.

`catch EVENT'

Stop when EVENT occurs. EVENT can be any of the following:

- `throw'

- The throwing of a C++ exception.

- `catch'

- The catching of a C++ exception.

+ `throw [REGEXP]'

+ `rethrow [REGEXP]'

+ `catch [REGEXP]'

+ The throwing, re-throwing, or catching of a C++ exception.

+ If REGEXP is given, then only exceptions whose type matches

+ the regular expression will be caught.

+ The convenience variable `$_exception' is available at an

+ exception-related catchpoint, on some systems. This holds the

+ exception being thrown.

+ There are currently some limitations to C++ exception

+ handling in GDB:

+ * The support for these commands is system-dependent.

+ Currently, only systems using the `gnu-v3' C++ ABI

+ (*note ABI::) are supported.

+ * The regular expression feature and the `$_exception'

+ convenience variable rely on the presence of some SDT

+ probes in `libstdc++'. If these probes are not present,

+ then these features cannot be used. These probes were

+ first available in the GCC 4.8 release, but whether or

+ not they are available in your GCC also depends on how

+ it was built.

+ * The `$_exception' convenience variable is only valid at

+ the instruction at which an exception-related catchpoint

+ is set.

+ * When an exception-related catchpoint is hit, GDB stops

+ at a location in the system library which implements

+ runtime exception support for C++, usually `libstdc++'.

+ You can use `up' (*note Selection::) to get to your code.

+ * If you call a function interactively, GDB normally

+ returns control to you when the function has finished

+ executing. If the call raises an exception, however,

+ the call may bypass the mechanism that returns control

+ to you and cause your program either to abort or to

+ simply continue running until it hits a breakpoint,

+ catches a signal that GDB is listening for, or exits.

+ This is the case even if you set a catchpoint for the

+ exception; catchpoints on exceptions are disabled within

+ interactive calls. *Note Calling::, for information on

+ controlling this with `set

+ unwind-on-terminating-exception'.

+ * You cannot raise an exception interactively.

+ * You cannot install an exception handler interactively.

`exception'

An Ada exception being raised. If an exception name is

@@ -3555,56 +3660,39 @@ shared library. Use the `catch' command to set a catchpoint.

given, then the catchpoint will stop only if the regular

expression matches one of the affected libraries.

+ `signal [SIGNAL... | `all']'

+ The delivery of a signal.

-`tcatch EVENT'

- Set a catchpoint that is enabled only for one stop. The

- catchpoint is automatically deleted after the first time the event

- is caught.

- Use the `info break' command to list the current catchpoints.

+ With no arguments, this catchpoint will catch any signal that

+ is not used internally by GDB, specifically, all signals

+ except `SIGTRAP' and `SIGINT'.

- There are currently some limitations to C++ exception handling

-(`catch throw' and `catch catch') in GDB:

+ With the argument `all', all signals, including those used by

+ GDB, will be caught. This argument cannot be used with other

+ signal names.

- * If you call a function interactively, GDB normally returns control

- to you when the function has finished executing. If the call

- raises an exception, however, the call may bypass the mechanism

- that returns control to you and cause your program either to abort

- or to simply continue running until it hits a breakpoint, catches

- a signal that GDB is listening for, or exits. This is the case

- even if you set a catchpoint for the exception; catchpoints on

- exceptions are disabled within interactive calls.

+ Otherwise, the arguments are a list of signal names as given

+ to `handle' (*note Signals::). Only signals specified in

+ this list will be caught.

- * You cannot raise an exception interactively.

+ One reason that `catch signal' can be more useful than

+ `handle' is that you can attach commands and conditions to the

+ catchpoint.

- * You cannot install an exception handler interactively.

+ When a signal is caught by a catchpoint, the signal's `stop'

+ and `print' settings, as specified by `handle', are ignored.

+ However, whether the signal is still delivered to the

+ inferior depends on the `pass' setting; this can be changed

+ in the catchpoint's commands.

- Sometimes `catch' is not the best way to debug exception handling:

-if you need to know exactly where an exception is raised, it is better

-to stop _before_ the exception handler is called, since that way you

-can see the stack before any unwinding takes place. If you set a

-breakpoint in an exception handler instead, it may not be easy to find

-out where the exception was raised.

- To stop just before an exception handler is called, you need some

-knowledge of the implementation. In the case of GNU C++, exceptions are

-raised by calling a library function named `__raise_exception' which

-has the following ANSI C interface:

- /* ADDR is where the exception identifier is stored.

- ID is the exception identifier. */

- void __raise_exception (void **addr, void *id);

+`tcatch EVENT'

+ Set a catchpoint that is enabled only for one stop. The

+ catchpoint is automatically deleted after the first time the event

+ is caught.

-To make the debugger catch all exceptions before any stack unwinding

-takes place, set a breakpoint on `__raise_exception' (*note

-Breakpoints; Watchpoints; and Exceptions: Breakpoints.).

- With a conditional breakpoint (*note Break Conditions: Conditions.)

-that depends on the value of ID, you can stop your program when a

-specific exception is raised. You can use multiple conditional

-breakpoints to stop your program when any of a number of exceptions are

-raised.

+ Use the `info break' command to list the current catchpoints.

File: gdb.info, Node: Delete Breaks, Next: Disabling, Prev: Set Catchpoints, Up: Breakpoints

@@ -3729,7 +3817,7 @@ Breakpoints: Set Breaks.), breakpoints that you set are initially

enabled; subsequently, they become disabled or enabled only when you

use one of the commands above. (The command `until' can set and delete

a breakpoint of its own, but it does not change the state of your other

-breakpoints; see *Note Continuing and Stepping: Continuing and

+breakpoints; see *note Continuing and Stepping: Continuing and

Stepping.)

@@ -4340,7 +4428,7 @@ interesting, until you see the problem happen.

`u LOCATION'

Continue running your program until either the specified location

is reached, or the current stack frame returns. LOCATION is any of

- the forms described in *Note Specify Location::. This form of the

+ the forms described in *note Specify Location::. This form of the

command uses temporary breakpoints, and hence is quicker than

`until' without an argument. The specified location is actually

reached only if it is in the current frame. This implies that

@@ -4361,7 +4449,7 @@ interesting, until you see the problem happen.

`advance LOCATION'

Continue running the program up to the given LOCATION. An

argument is required, which should be of one of the forms

- described in *Note Specify Location::. Execution will also stop

+ described in *note Specify Location::. Execution will also stop

upon exit from the current stack frame. This command is similar

to `until', but `advance' will not skip over recursive function

calls, and the target location doesn't have to be in the same

@@ -4388,6 +4476,29 @@ interesting, until you see the problem happen.

An argument is a repeat count, as in `next'.

+ By default, and if available, GDB makes use of target-assisted

+"range stepping". In other words, whenever you use a stepping command

+(e.g., `step', `next'), GDB tells the target to step the corresponding

+range of instruction addresses instead of issuing multiple

+single-steps. This speeds up line stepping, particularly for remote

+targets. Ideally, there should be no reason you would want to turn

+range stepping off. However, it's possible that a bug in the debug

+info, a bug in the remote stub (for remote targets), or even a bug in

+GDB could make line stepping behave incorrectly when target-assisted

+range stepping is enabled. You can use the following command to turn

+off range stepping if necessary:

+`set range-stepping'

+`show range-stepping'

+ Control whether range stepping is enabled.

+ If `on', and the target supports it, GDB tells the target to step

+ a range of addresses itself, instead of issuing multiple

+ single-steps. If `off', GDB always issues single-steps, even if

+ range stepping is supported by the target. The default is `on'.

File: gdb.info, Node: Skipping Over Functions and Files, Next: Signals, Prev: Continuing and Stepping, Up: Stopping

@@ -4532,6 +4643,10 @@ settings with the `handle' command.

`info handle' is an alias for `info signals'.

+`catch signal [SIGNAL... | `all']'

+ Set a catchpoint for the indicated signals. *Note Set

+ Catchpoints::, for details about this command.

`handle SIGNAL [KEYWORDS...]'

Change the way GDB handles signal SIGNAL. SIGNAL can be the

number of a signal or its name (with or without the `SIG' at the

@@ -4726,8 +4841,8 @@ run with the `set schedule-multiple' command.

resumed when an execution command is issued. When `on', all

threads of all processes are allowed to run. When `off', only the

threads of the current process are resumed. The default is `off'.

- The `scheduler-locking' mode takes precedence when set to `on',

- or while you are stepping and set to `step'.

+ The `scheduler-locking' mode takes precedence when set to `on', or

+ while you are stepping and set to `step'.

`show schedule-multiple'

Display the current mode for resuming the execution of threads of

@@ -4876,7 +4991,7 @@ are:

Background execution is especially useful in conjunction with

-non-stop mode for debugging programs with multiple threads; see *Note

+non-stop mode for debugging programs with multiple threads; see *note

Non-Stop Mode::. However, you can also use these commands in the

normal all-stop mode with the restriction that you cannot issue another

execution command until the previous one finishes. Examples of

@@ -4925,6 +5040,21 @@ on all threads, or on a particular thread.

(gdb) break frik.c:13 thread 28 if bartab > lim

+ Thread-specific breakpoints are automatically deleted when GDB

+detects the corresponding thread is no longer in the thread list. For

+example:

+ (gdb) c

+ Thread-specific breakpoint 3 deleted - thread 28 no longer in the thread list.

+ There are several ways for a thread to disappear, such as a regular

+thread exit, but also when you detach from the process with the

+`detach' command (*note Debugging an Already-running Process: Attach.),

+or if GDB loses the remote connection (*note Remote Debugging::), etc.

+Note that with some targets, GDB is only able to detect a thread has

+exited when the user explictly asks for the thread list with the `info

+threads' command.

File: gdb.info, Node: Interrupted System Calls, Next: Observer Mode, Prev: Thread-Specific Breakpoints, Up: Thread Stops

@@ -5204,14 +5334,30 @@ supports reverse execution, or stop if not.

For architecture environments that support process record and replay,

GDB provides the following commands:

-`target record'

+`record METHOD'

This command starts the process record and replay target. The

- process record and replay target can only debug a process that is

- already running. Therefore, you need first to start the process

- with the `run' or `start' commands, and then start the recording

- with the `target record' command.

+ recording method can be specified as parameter. Without a

+ parameter the command uses the `full' recording method. The

+ following recording methods are available:

+ `full'

+ Full record/replay recording using GDB's software record and

+ replay implementation. This method allows replaying and

+ reverse execution.

+ `btrace'

+ Hardware-supported instruction recording. This method does

+ not allow replaying and reverse execution.

- Both `record' and `rec' are aliases of `target record'.

+ This recording method may not be available on all processors.

+ The process record and replay target can only debug a process that

+ is already running. Therefore, you need first to start the

+ process with the `run' or `start' commands, and then start the

+ recording with the `record METHOD' command.

+ Both `record METHOD' and `rec METHOD' are aliases of `target

+ record-METHOD'.

Displaced stepping (*note displaced stepping: Maintenance

Commands.) will be automatically disabled when process record and

@@ -5220,8 +5366,8 @@ GDB provides the following commands:

If the inferior is in the non-stop mode (*note Non-Stop Mode::) or

in the asynchronous execution mode (*note Background Execution::),

- the process record and replay target cannot be started because it

- doesn't support these two modes.

+ not all recording methods are available. The `full' recording

+ method does not support these two modes.

`record stop'

Stop the process record and replay target. When process record and

@@ -5246,18 +5392,35 @@ GDB provides the following commands:

When the inferior process exits, or GDB detaches from it, process

record and replay target will automatically stop itself.

+`record goto'

+ Go to a specific location in the execution log. There are several

+ ways to specify the location to go to:

+ `record goto begin'

+ `record goto start'

+ Go to the beginning of the execution log.

+ `record goto end'

+ Go to the end of the execution log.

+ `record goto N'

+ Go to instruction number N in the execution log.

`record save FILENAME'

Save the execution log to a file `FILENAME'. Default filename is

`gdb_record.PROCESS_ID', where PROCESS_ID is the process ID of the

inferior.

+ This command may not be available for all recording methods.

`record restore FILENAME'

Restore the execution log from a file `FILENAME'. File must have

been created with `record save'.

-`set record insn-number-max LIMIT'

- Set the limit of instructions to be recorded. Default value is

- 200000.

+`set record full insn-number-max LIMIT'

+`set record full insn-number-max unlimited'

+ Set the limit of instructions to be recorded for the `full'

+ recording method. Default value is 200000.

If LIMIT is a positive number, then GDB will start deleting

instructions from the log once the number of the record

@@ -5268,31 +5431,33 @@ GDB provides the following commands:

control what happens when the limit is reached, by means of the

`stop-at-limit' option, described below.)

- If LIMIT is zero, GDB will never delete recorded instructions from

- the execution log. The number of recorded instructions is

- unlimited in this case.

+ If LIMIT is `unlimited' or zero, GDB will never delete recorded

+ instructions from the execution log. The number of recorded

+ instructions is limited only by the available memory.

-`show record insn-number-max'

- Show the limit of instructions to be recorded.

+`show record full insn-number-max'

+ Show the limit of instructions to be recorded with the `full'

+ recording method.

-`set record stop-at-limit'

- Control the behavior when the number of recorded instructions

- reaches the limit. If ON (the default), GDB will stop when the

- limit is reached for the first time and ask you whether you want

- to stop the inferior or continue running it and recording the

- execution log. If you decide to continue recording, each new

- recorded instruction will cause the oldest one to be deleted.

+`set record full stop-at-limit'

+ Control the behavior of the `full' recording method when the

+ number of recorded instructions reaches the limit. If ON (the

+ default), GDB will stop when the limit is reached for the first

+ time and ask you whether you want to stop the inferior or continue

+ running it and recording the execution log. If you decide to

+ continue recording, each new recorded instruction will cause the

+ oldest one to be deleted.

If this option is OFF, GDB will automatically delete the oldest

record to make room for each new one, without asking.

-`show record stop-at-limit'

+`show record full stop-at-limit'

Show the current setting of `stop-at-limit'.

-`set record memory-query'

+`set record full memory-query'

Control the behavior when GDB is unable to record memory changes

- caused by an instruction. If ON, GDB will query whether to stop

- the inferior in that case.

+ caused by an instruction for the `full' recording method. If ON,

+ GDB will query whether to stop the inferior in that case.

If this option is OFF (the default), GDB will automatically ignore

the effect of such instructions on memory. Later, when GDB

@@ -5300,26 +5465,38 @@ GDB provides the following commands:

instruction as not accessible, and it will not affect the replay

results.

-`show record memory-query'

+`show record full memory-query'

Show the current setting of `memory-query'.

`info record'

- Show various statistics about the state of process record and its

- in-memory execution log buffer, including:

+ Show various statistics about the recording depending on the

+ recording method:

- * Whether in record mode or replay mode.

+ `full'

+ For the `full' recording method, it shows the state of process

+ record and its in-memory execution log buffer, including:

- * Lowest recorded instruction number (counting from when the

- current execution log started recording instructions).

+ * Whether in record mode or replay mode.

- * Highest recorded instruction number.

+ * Lowest recorded instruction number (counting from when

+ the current execution log started recording

+ instructions).

- * Current instruction about to be replayed (if in replay mode).

+ * Highest recorded instruction number.

- * Number of instructions contained in the execution log.

+ * Current instruction about to be replayed (if in replay

+ mode).

- * Maximum number of instructions that may be contained in the

- execution log.

+ * Number of instructions contained in the execution log.

+ * Maximum number of instructions that may be contained in

+ the execution log.

+ `btrace'

+ For the `btrace' recording method, it shows the number of

+ instructions that have been recorded and the number of blocks

+ of sequential control-flow that is formed by the recorded

+ instructions.

`record delete'

When record target runs in replay mode ("in the past"), delete the

@@ -5328,6 +5505,107 @@ GDB provides the following commands:

the previously recorded "future" and begin recording a new

"future".

+`record instruction-history'

+ Disassembles instructions from the recorded execution log. By

+ default, ten instructions are disassembled. This can be changed

+ using the `set record instruction-history-size' command.

+ Instructions are printed in execution order. There are several

+ ways to specify what part of the execution log to disassemble:

+ `record instruction-history INSN'

+ Disassembles ten instructions starting from instruction number

+ INSN.

+ `record instruction-history INSN, +/-N'

+ Disassembles N instructions around instruction number INSN.

+ If N is preceded with `+', disassembles N instructions after

+ instruction number INSN. If N is preceded with `-',

+ disassembles N instructions before instruction number INSN.

+ `record instruction-history'

+ Disassembles ten more instructions after the last disassembly.

+ `record instruction-history -'

+ Disassembles ten more instructions before the last

+ disassembly.

+ `record instruction-history BEGIN END'

+ Disassembles instructions beginning with instruction number

+ BEGIN until instruction number END. The instruction number

+ END is not included.

+ This command may not be available for all recording methods.

+`set record instruction-history-size SIZE'

+`set record instruction-history-size unlimited'

+ Define how many instructions to disassemble in the `record

+ instruction-history' command. The default value is 10. A SIZE of

+ `unlimited' means unlimited instructions.

+`show record instruction-history-size'

+ Show how many instructions to disassemble in the `record

+ instruction-history' command.

+`record function-call-history'

+ Prints the execution history at function granularity. It prints one

+ line for each sequence of instructions that belong to the same

+ function giving the name of that function, the source lines for

+ this instruction sequence (if the `/l' modifier is specified), and

+ the instructions numbers that form the sequence (if the `/i'

+ modifier is specified).

+ (gdb) list 1, 10

+ 1 void foo (void)

+ 2 {

+ 3 }

+ 4

+ 5 void bar (void)

+ 6 {

+ 7 ...

+ 8 foo ();

+ 9 ...

+ 10 }

+ (gdb) record function-call-history /l

+ 1 foo.c:6-8 bar

+ 2 foo.c:2-3 foo

+ 3 foo.c:9-10 bar

+ By default, ten lines are printed. This can be changed using the

+ `set record function-call-history-size' command. Functions are

+ printed in execution order. There are several ways to specify what

+ to print:

+ `record function-call-history FUNC'

+ Prints ten functions starting from function number FUNC.

+ `record function-call-history FUNC, +/-N'

+ Prints N functions around function number FUNC. If N is

+ preceded with `+', prints N functions after function number

+ FUNC. If N is preceded with `-', prints N functions before

+ function number FUNC.

+ `record function-call-history'

+ Prints ten more functions after the last ten-line print.

+ `record function-call-history -'

+ Prints ten more functions before the last ten-line print.

+ `record function-call-history BEGIN END'

+ Prints functions beginning with function number BEGIN until

+ function number END. The function number END is not included.

+ This command may not be available for all recording methods.

+`set record function-call-history-size SIZE'

+`set record function-call-history-size unlimited'

+ Define how many lines to print in the `record

+ function-call-history' command. The default value is 10. A size

+ of `unlimited' means unlimited lines.

+`show record function-call-history-size'

+ Show how many lines to print in the `record function-call-history'

+ command.

File: gdb.info, Node: Stack, Next: Source, Prev: Process Record and Replay, Up: Top

@@ -5362,6 +5640,7 @@ command (*note Information about a Frame: Frame Info.).

* Frames:: Stack frames

* Backtrace:: Backtraces

+* Frame Filter Management:: Managing frame filters

* Selection:: Selecting a frame

* Frame Info:: Information on a frame

@@ -5422,7 +5701,7 @@ GDB has no provision for frameless functions elsewhere in the stack.

of `frame'.

-File: gdb.info, Node: Backtrace, Next: Selection, Prev: Frames, Up: Stack

+File: gdb.info, Node: Backtrace, Next: Frame Filter Management, Prev: Frames, Up: Stack

8.2 Backtraces

==============

@@ -5455,6 +5734,18 @@ on up the stack.

Print the values of the local variables also. N specifies the

number of frames to print, as described above.

+`backtrace no-filters'

+`bt no-filters'

+`bt no-filters N'

+`bt no-filters -N'

+`bt no-filters full'

+`bt no-filters full N'

+`bt no-filters full -N'

+ Do not run Python frame filters on this backtrace. *Note Frame

+ Filter API::, for more information. Additionally use *note

+ disable frame-filter all:: to turn off all frame filters. This is

+ only relevant when GDB has been configured with `Python' support.

The names `where' and `info stack' (abbreviated `info s') are

additional aliases for `backtrace'.

@@ -5489,7 +5780,7 @@ for line `993' of `builtin.c'.

The value of parameter `data' in frame 1 has been replaced by `...'.

By default, GDB prints the value of a parameter only if it is a scalar

(integer, pointer, enumeration, etc). See command `set print

-frame-arguments' in *Note Print Settings:: for more details on how to

+frame-arguments' in *note Print Settings:: for more details on how to

configure the way function parameter values are printed.

If your program was compiled with optimizations, some compilers will

@@ -5550,11 +5841,29 @@ levels in a backtrace, you can change this behavior:

`set backtrace limit N'

`set backtrace limit 0'

- Limit the backtrace to N levels. A value of zero means unlimited.

+`set backtrace limit unlimited'

+ Limit the backtrace to N levels. A value of `unlimited' or zero

+ means unlimited levels.

`show backtrace limit'

Display the current limit on backtrace levels.

+ You can control how file names are displayed.

+`set filename-display'

+`set filename-display relative'

+ Display file names relative to the compilation directory. This is

+ the default.

+`set filename-display basename'

+ Display only basename of a filename.

+`set filename-display absolute'

+ Display an absolute filename.

+`show filename-display'

+ Show the current way to display filenames.

---------- Footnotes ----------

(1) Note that embedded programs (the so-called "free-standing"

@@ -5562,9 +5871,139 @@ environment) are not required to have a `main' function as the entry

point. They could even have multiple entry points.

-File: gdb.info, Node: Selection, Next: Frame Info, Prev: Backtrace, Up: Stack

+File: gdb.info, Node: Frame Filter Management, Next: Selection, Prev: Backtrace, Up: Stack

+8.3 Management of Frame Filters.

+================================

+Frame filters are Python based utilities to manage and decorate the

+output of frames. *Note Frame Filter API::, for further information.

+ Managing frame filters is performed by several commands available

+within GDB, detailed here.

+`info frame-filter'

+ Print a list of installed frame filters from all dictionaries,

+ showing their name, priority and enabled status.

+`disable frame-filter FILTER-DICTIONARY FILTER-NAME'

+ Disable a frame filter in the dictionary matching

+ FILTER-DICTIONARY, or `all', and FILTER-NAME. FILTER-DICTIONARY

+ may be `all', `global', `progspace' or the name of the object file

+ where the frame filter dictionary resides. When `all' is

+ specified, all frame filters across all dictionaries are disabled.

+ FILTER-NAME is the name of the frame filter and is used when `all'

+ is not the option for FILTER-DICTIONARY. A disabled frame-filter

+ is not deleted, it may be enabled again later.

+`enable frame-filter FILTER-DICTIONARY FILTER-NAME'

+ Enable a frame filter in the dictionary matching

+ FILTER-DICTIONARY, or `all', and FILTER-NAME. FILTER-DICTIONARY

+ may be `all', `global', `progspace' or the name of the object file

+ where the frame filter dictionary resides. When `all' is

+ specified, all frame filters across all dictionaries are enabled.

+ FILTER-NAME is the name of the frame filter and is used when `all'

+ is not the option for FILTER-DICTIONARY.

+ Example:

+ (gdb) info frame-filter

+ global frame-filters:

+ Priority Enabled Name

+ 1000 No PrimaryFunctionFilter

+ 100 Yes Reverse

+ progspace /build/test frame-filters:

+ Priority Enabled Name

+ 100 Yes ProgspaceFilter

+ objfile /build/test frame-filters:

+ Priority Enabled Name

+ 999 Yes BuildProgra Filter

+ (gdb) disable frame-filter /build/test BuildProgramFilter

+ (gdb) info frame-filter

+ global frame-filters:

+ Priority Enabled Name

+ 1000 No PrimaryFunctionFilter

+ 100 Yes Reverse

+ progspace /build/test frame-filters:

+ Priority Enabled Name

+ 100 Yes ProgspaceFilter

+ objfile /build/test frame-filters:

+ Priority Enabled Name

+ 999 No BuildProgramFilter

+ (gdb) enable frame-filter global PrimaryFunctionFilter

+ (gdb) info frame-filter

+ global frame-filters:

+ Priority Enabled Name

+ 1000 Yes PrimaryFunctionFilter

+ 100 Yes Reverse

+ progspace /build/test frame-filters:

+ Priority Enabled Name

+ 100 Yes ProgspaceFilter

+ objfile /build/test frame-filters:

+ Priority Enabled Name

+ 999 No BuildProgramFilter

+`set frame-filter priority FILTER-DICTIONARY FILTER-NAME PRIORITY'

+ Set the PRIORITY of a frame filter in the dictionary matching

+ FILTER-DICTIONARY, and the frame filter name matching FILTER-NAME.

+ FILTER-DICTIONARY may be `global', `progspace' or the name of the

+ object file where the frame filter dictionary resides. PRIORITY

+ is an integer.

+`show frame-filter priority FILTER-DICTIONARY FILTER-NAME'

+ Show the PRIORITY of a frame filter in the dictionary matching

+ FILTER-DICTIONARY, and the frame filter name matching FILTER-NAME.

+ FILTER-DICTIONARY may be `global', `progspace' or the name of the

+ object file where the frame filter dictionary resides.

+ Example:

+ (gdb) info frame-filter

+ global frame-filters:

+ Priority Enabled Name

+ 1000 Yes PrimaryFunctionFilter

+ 100 Yes Reverse

+ progspace /build/test frame-filters:

+ Priority Enabled Name

+ 100 Yes ProgspaceFilter

+ objfile /build/test frame-filters:

+ Priority Enabled Name

+ 999 No BuildProgramFilter

+ (gdb) set frame-filter priority global Reverse 50

+ (gdb) info frame-filter

+ global frame-filters:

+ Priority Enabled Name

+ 1000 Yes PrimaryFunctionFilter

+ 50 Yes Reverse

+ progspace /build/test frame-filters:

+ Priority Enabled Name

+ 100 Yes ProgspaceFilter

+ objfile /build/test frame-filters:

+ Priority Enabled Name

+ 999 No BuildProgramFilter

+File: gdb.info, Node: Selection, Next: Frame Info, Prev: Frame Filter Management, Up: Stack

-8.3 Selecting a Frame

+8.4 Selecting a Frame

=====================

Most commands for examining the stack and other data in your program

@@ -5636,7 +6075,7 @@ for details.

File: gdb.info, Node: Frame Info, Prev: Selection, Up: Stack

-8.4 Information About a Frame

+8.5 Information About a Frame

=============================

There are several other commands to print information about the selected

@@ -5709,7 +6148,7 @@ execution in that frame has stopped. You can print other portions of

source files by explicit command.

If you use GDB through its GNU Emacs interface, you may prefer to

-use Emacs facilities to view source; see *Note Using GDB under GNU

+use Emacs facilities to view source; see *note Using GDB under GNU

Emacs: Emacs.

* Menu:

@@ -5729,7 +6168,7 @@ File: gdb.info, Node: List, Next: Specify Location, Up: Source

To print lines from a source file, use the `list' command (abbreviated

`l'). By default, ten lines are printed. There are several ways to

-specify what part of the file you want to print; see *Note Specify

+specify what part of the file you want to print; see *note Specify

Location::, for the full list.

Here are the forms of the `list' command most commonly used:

@@ -5755,8 +6194,10 @@ Location::, for the full list.

the `list' command. You can change this using `set listsize':

`set listsize COUNT'

+`set listsize unlimited'

Make the `list' command display COUNT source lines (unless the

- `list' argument explicitly specifies some other number).

+ `list' argument explicitly specifies some other number). Setting

+ COUNT to `unlimited' or 0 means there's no limit.

`show listsize'

Display the number of lines that `list' prints.

@@ -6025,7 +6466,7 @@ specifies how to rewrite source directories stored in the program's

debug information in case the sources were moved to a different

directory between compilation and debugging. A rule is made of two

strings, the first specifying what needs to be rewritten in the path,

-and the second specifying how it should be rewritten. In *Note set

+and the second specifying how it should be rewritten. In *note set

substitute-path::, we name these two parts FROM and TO respectively.

GDB does a simple string replacement of FROM with TO at the start of

the directory part of the source file name, and uses that result

@@ -6173,7 +6614,7 @@ line' command causes the arrow to point to the line specified. Also,

`info line LINESPEC'

Print the starting and ending addresses of the compiled code for

source line LINESPEC. You can specify source lines in any of the

- ways documented in *Note Specify Location::.

+ ways documented in *note Specify Location::.

For example, we can use `info line' to discover the location of the

object code for the first line of function `m4_changequote':

@@ -6274,6 +6715,11 @@ x86-64,

0x0000000000400289: 2e 32 00 xor %cs:(%rax),%al

End of assembler dump.

+ Addresses cannot be specified as a linespec (*note Specify

+Location::). So, for example, if you want to disassemble function `bar'

+in file `foo.c', you must type `disassemble 'foo.c'::bar' and not

+`disassemble foo.c:bar'.

Some architectures have more than one commonly-used set of

instruction mnemonics or other syntax.

@@ -6330,7 +6776,7 @@ may also print the expression using a Python-based pretty-printer

EXPR is an expression (in the source language). By default the

value of EXPR is printed in a format appropriate to its data type;

you can choose a different format by specifying `/F', where F is a

- letter specifying the format; see *Note Output Formats: Output

+ letter specifying the format; see *note Output Formats: Output

Formats.

`print'

@@ -6480,6 +6926,7 @@ argument is being invoked.

* Pretty Printing:: Python pretty printing

* Value History:: Value history

* Convenience Vars:: Convenience variables

+* Convenience Funs:: Convenience functions

* Registers:: Registers

* Floating Point Hardware:: Floating point hardware

* Vector Unit:: Vector Unit

@@ -6489,7 +6936,7 @@ argument is being invoked.

* Core File Generation:: Cause a program dump its core

* Character Sets:: Debugging programs that use a different

character set than GDB does

-* Caching Remote Data:: Data caching for remote targets

+* Caching Target Data:: Data caching for targets

* Searching Memory:: Searching memory for a sequence of bytes

@@ -6503,7 +6950,7 @@ its value. Any kind of constant, variable or operator defined by the

programming language you are using is valid in an expression in GDB.

This includes conditional expressions, function calls, casts, and

string constants. It also includes preprocessor macros, if you

-compiled your program to include this information; see *Note

+compiled your program to include this information; see *note

Compilation::.

GDB supports array constants in expressions input by the user. The

@@ -6615,455 +7062,3 @@ particular definitions of that function name:

`show multiple-symbols'

Show the current value of the `multiple-symbols' setting.

-File: gdb.info, Node: Variables, Next: Arrays, Prev: Ambiguous Expressions, Up: Data

-10.3 Program Variables

-======================

-The most common kind of expression to use is the name of a variable in

-your program.

- Variables in expressions are understood in the selected stack frame

-(*note Selecting a Frame: Selection.); they must be either:

- * global (or file-static)

-or

- * visible according to the scope rules of the programming language

- from the point of execution in that frame

-This means that in the function

- foo (a)

- int a;

- {

- bar (a);

- {

- int b = test ();

- bar (b);

- }

-you can examine and use the variable `a' whenever your program is

-executing within the function `foo', but you can only use or examine

-the variable `b' while your program is executing inside the block where

-`b' is declared.

- There is an exception: you can refer to a variable or function whose

-scope is a single source file even if the current execution point is not

-in this file. But it is possible to have more than one such variable or

-function with the same name (in different source files). If that

-happens, referring to that name has unpredictable effects. If you wish,

-you can specify a static variable in a particular function or file by

-using the colon-colon (`::') notation:

- FILE::VARIABLE

- FUNCTION::VARIABLE

-Here FILE or FUNCTION is the name of the context for the static

-VARIABLE. In the case of file names, you can use quotes to make sure

-GDB parses the file name as a single word--for example, to print a

-global value of `x' defined in `f2.c':

- (gdb) p 'f2.c'::x

- The `::' notation is normally used for referring to static

-variables, since you typically disambiguate uses of local variables in

-functions by selecting the appropriate frame and using the simple name

-of the variable. However, you may also use this notation to refer to

-local variables in frames enclosing the selected frame:

- void

- foo (int a)

- {

- if (a < 10)

- bar (a);

- else

- process (a); /* Stop here */

- }

- int

- bar (int a)

- {

- foo (a + 5);

- }

-For example, if there is a breakpoint at the commented line, here is

-what you might see when the program stops after executing the call

-`bar(0)':

- (gdb) p a

- $1 = 10

- (gdb) p bar::a

- $2 = 5

- (gdb) up 2

- #2 0x080483d0 in foo (a=5) at foobar.c:12

- (gdb) p a

- $3 = 5

- (gdb) p bar::a

- $4 = 0

- These uses of `::' are very rarely in conflict with the very similar

-use of the same notation in C++. GDB also supports use of the C++

-scope resolution operator in GDB expressions.

- _Warning:_ Occasionally, a local variable may appear to have the

- wrong value at certain points in a function--just after entry to a

- new scope, and just before exit.

- You may see this problem when you are stepping by machine

-instructions. This is because, on most machines, it takes more than

-one instruction to set up a stack frame (including local variable

-definitions); if you are stepping by machine instructions, variables

-may appear to have the wrong values until the stack frame is completely

-built. On exit, it usually also takes more than one machine

-instruction to destroy a stack frame; after you begin stepping through

-that group of instructions, local variable definitions may be gone.

- This may also happen when the compiler does significant

-optimizations. To be sure of always seeing accurate values, turn off

-all optimization when compiling.

- Another possible effect of compiler optimizations is to optimize

-unused variables out of existence, or assign variables to registers (as

-opposed to memory addresses). Depending on the support for such cases

-offered by the debug info format used by the compiler, GDB might not be

-able to display values for such local variables. If that happens, GDB

-will print a message like this:

- No symbol "foo" in current context.

- To solve such problems, either recompile without optimizations, or

-use a different debug info format, if the compiler supports several such

-formats. *Note Compilation::, for more information on choosing compiler

-options. *Note C and C++: C, for more information about debug info

-formats that are best suited to C++ programs.

- If you ask to print an object whose contents are unknown to GDB,

-e.g., because its data type is not completely specified by the debug

-information, GDB will say `<incomplete type>'. *Note incomplete type:

-Symbols, for more about this.

- If you append `@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. Entry values are normally also printed at the

-function parameter list according to *Note set print entry-values::.

- Breakpoint 1, d (i=30) at gdb.base/entry-value.c:29

- 29 i++;

- (gdb) next

- 30 e (i);

- (gdb) print i

- $1 = 31

- (gdb) print i@entry

- $2 = 30

- Strings are identified as arrays of `char' values without specified

-signedness. Arrays of either `signed char' or `unsigned char' get

-printed as arrays of 1 byte sized integers. `-fsigned-char' or

-`-funsigned-char' GCC options have no effect as GDB defines literal

-string type `"char"' as `char' without a sign. For program code

- char var0[] = "A";

- signed char var1[] = "A";

- You get during debugging

- (gdb) print var0

- $1 = "A"

- (gdb) print var1

- $2 = {65 'A', 0 '\0'}

-File: gdb.info, Node: Arrays, Next: Output Formats, Prev: Variables, Up: Data

-10.4 Artificial Arrays

-======================

-It is often useful to print out several successive objects of the same

-type in memory; a section of an array, or an array of dynamically

-determined size for which only a pointer exists in the program.

- You can do this by referring to a contiguous span of memory as an

-"artificial array", using the binary operator `@'. The left operand of

-`@' should be the first element of the desired array and be an

-individual object. The right operand should be the desired length of

-the array. The result is an array value whose elements are all of the

-type of the left argument. The first element is actually the left

-argument; the second element comes from bytes of memory immediately

-following those that hold the first element, and so on. Here is an

-example. If a program says

- int *array = (int *) malloc (len * sizeof (int));

-you can print the contents of `array' with

- p *array@len

- The left operand of `@' must reside in memory. Array values made

-with `@' in this way behave just like other arrays in terms of

-subscripting, and are coerced to pointers when used in expressions.

-Artificial arrays most often appear in expressions via the value history

-(*note Value History: Value History.), after printing one out.

- Another way to create an artificial array is to use a cast. This

-re-interprets a value as if it were an array. The value need not be in

-memory:

- (gdb) p/x (short[2])0x12345678

- $1 = {0x1234, 0x5678}

- As a convenience, if you leave the array length out (as in

-`(TYPE[])VALUE') GDB calculates the size to fill the value (as

-`sizeof(VALUE)/sizeof(TYPE)':

- (gdb) p/x (short[])0x12345678

- $2 = {0x1234, 0x5678}

- Sometimes the artificial array mechanism is not quite enough; in

-moderately complex data structures, the elements of interest may not

-actually be adjacent--for example, if you are interested in the values

-of pointers in an array. One useful work-around in this situation is

-to use a convenience variable (*note Convenience Variables: Convenience

-Vars.) as a counter in an expression that prints the first interesting

-value, and then repeat that expression via <RET>. For instance,

-suppose you have an array `dtab' of pointers to structures, and you are

-interested in the values of a field `fv' in each structure. Here is an

-example of what you might type:

- set $i = 0

- p dtab[$i++]->fv

- <RET>

- ...

-File: gdb.info, Node: Output Formats, Next: Memory, Prev: Arrays, Up: Data

-10.5 Output Formats

-===================

-By default, GDB prints a value according to its data type. Sometimes

-this is not what you want. For example, you might want to print a

-number in hex, or a pointer in decimal. Or you might want to view data

-in memory at a certain address as a character string or as an

-instruction. To do these things, specify an "output format" when you

-print a value.

- The simplest use of output formats is to say how to print a value

-already computed. This is done by starting the arguments of the

-`print' command with a slash and a format letter. The format letters

-supported are:

-`x'

- Regard the bits of the value as an integer, and print the integer

- in hexadecimal.

-`d'

- Print as integer in signed decimal.

-`u'

- Print as integer in unsigned decimal.

-`o'

- Print as integer in octal.

-`t'

- Print as integer in binary. The letter `t' stands for "two". (1)

-`a'

- Print as an address, both absolute in hexadecimal and as an offset

- from the nearest preceding symbol. You can use this format used

- to discover where (in what function) an unknown address is located:

- (gdb) p/a 0x54320

- $3 = 0x54320 <_initialize_vx+396>

- The command `info symbol 0x54320' yields similar results. *Note

- info symbol: Symbols.

-`c'

- Regard as an integer and print it as a character constant. This

- prints both the numerical value and its character representation.

- The character representation is replaced with the octal escape

- `\nnn' for characters outside the 7-bit ASCII range.

- Without this format, GDB displays `char', `unsigned char', and

- `signed char' data as character constants. Single-byte members of

- vectors are displayed as integer data.

-`f'

- Regard the bits of the value as a floating point number and print

- using typical floating point syntax.

-`s'

- Regard as a string, if possible. With this format, pointers to

- single-byte data are displayed as null-terminated strings and

- arrays of single-byte data are displayed as fixed-length strings.

- Other values are displayed in their natural types.

- Without this format, GDB displays pointers to and arrays of

- `char', `unsigned char', and `signed char' as strings.

- Single-byte members of a vector are displayed as an integer array.

-`r'

- Print using the `raw' formatting. By default, GDB will use a

- Python-based pretty-printer, if one is available (*note Pretty

- Printing::). This typically results in a higher-level display of

- the value's contents. The `r' format bypasses any Python

- pretty-printer which might exist.

- For example, to print the program counter in hex (*note

-Registers::), type

- p/x $pc

-Note that no space is required before the slash; this is because command

-names in GDB cannot contain a slash.

- To reprint the last value in the value history with a different

-format, you can use the `print' command with just a format and no

-expression. For example, `p/x' reprints the last value in hex.

- ---------- Footnotes ----------

- (1) `b' cannot be used because these format letters are also used

-with the `x' command, where `b' stands for "byte"; see *Note Examining

-Memory: Memory.

-File: gdb.info, Node: Memory, Next: Auto Display, Prev: Output Formats, Up: Data

-10.6 Examining Memory

-=====================

-You can use the command `x' (for "examine") to examine memory in any of

-several formats, independently of your program's data types.

-`x/NFU ADDR'

-`x ADDR'

-`x'

- Use the `x' command to examine memory.

- N, F, and U are all optional parameters that specify how much memory

-to display and how to format it; ADDR is an expression giving the

-address where you want to start displaying memory. If you use defaults

-for NFU, you need not type the slash `/'. Several commands set

-convenient defaults for ADDR.

-N, the repeat count

- The repeat count is a decimal integer; the default is 1. It

- specifies how much memory (counting by units U) to display.

-F, the display format

- The display format is one of the formats used by `print' (`x',

- `d', `u', `o', `t', `a', `c', `f', `s'), and in addition `i' (for

- machine instructions). The default is `x' (hexadecimal)

- initially. The default changes each time you use either `x' or

- `print'.

-U, the unit size

- The unit size is any of

- `b'

- Bytes.

- `h'

- Halfwords (two bytes).

- `w'

- Words (four bytes). This is the initial default.

- `g'

- Giant words (eight bytes).

- Each time you specify a unit size with `x', that size becomes the

- default unit the next time you use `x'. For the `i' format, the

- unit size is ignored and is normally not written. For the `s'

- format, the unit size defaults to `b', unless it is explicitly

- given. Use `x /hs' to display 16-bit char strings and `x /ws' to

- display 32-bit strings. The next use of `x /s' will again display

- 8-bit strings. Note that the results depend on the programming

- language of the current compilation unit. If the language is C,

- the `s' modifier will use the UTF-16 encoding while `w' will use

- UTF-32. The encoding is set by the programming language and cannot

- be altered.

-ADDR, starting display address

- ADDR is the address where you want GDB to begin displaying memory.

- The expression need not have a pointer value (though it may); it

- is always interpreted as an integer address of a byte of memory.

- *Note Expressions: Expressions, for more information on

- expressions. The default for ADDR is usually just after the last

- address examined--but several other commands also set the default

- address: `info breakpoints' (to the address of the last breakpoint

- listed), `info line' (to the starting address of a line), and

- `print' (if you use it to display a value from memory).

- For example, `x/3uh 0x54320' is a request to display three halfwords

-(`h') of memory, formatted as unsigned decimal integers (`u'), starting

-at address `0x54320'. `x/4xw $sp' prints the four words (`w') of

-memory above the stack pointer (here, `$sp'; *note Registers:

-Registers.) in hexadecimal (`x').

- Since the letters indicating unit sizes are all distinct from the

-letters specifying output formats, you do not have to remember whether

-unit size or format comes first; either order works. The output

-specifications `4xw' and `4wx' mean exactly the same thing. (However,

-the count N must come first; `wx4' does not work.)

- Even though the unit size U is ignored for the formats `s' and `i',

-you might still want to use a count N; for example, `3i' specifies that

-you want to see three machine instructions, including any operands.

-For convenience, especially when used with the `display' command, the

-`i' format also prints branch delay slot instructions, if any, beyond

-the count specified, which immediately follow the last instruction that

-is within the count. The command `disassemble' gives an alternative

-way of inspecting machine instructions; see *Note Source and Machine

-Code: Machine Code.

- All the defaults for the arguments to `x' are designed to make it

-easy to continue scanning memory with minimal specifications each time

-you use `x'. For example, after you have inspected three machine

-instructions with `x/3i ADDR', you can inspect the next seven with just

-`x/7'. If you use <RET> to repeat the `x' command, the repeat count N

-is used again; the other arguments default as for successive uses of

-`x'.

- When examining machine instructions, the instruction at current

-program counter is shown with a `=>' marker. For example:

- (gdb) x/5i $pc-6

- 0x804837f <main+11>: mov %esp,%ebp

- 0x8048381 <main+13>: push %ecx

- 0x8048382 <main+14>: sub $0x4,%esp

- => 0x8048385 <main+17>: movl $0x8048460,(%esp)

- 0x804838c <main+24>: call 0x80482d4 <puts@plt>

- The addresses and contents printed by the `x' command are not saved

-in the value history because there is often too much of them and they

-would get in the way. Instead, GDB makes these values available for

-subsequent use in expressions as values of the convenience variables

-`$_' and `$__'. After an `x' command, the last address examined is

-available for use in expressions in the convenience variable `$_'. The

-contents of that address, as examined, are available in the convenience

-variable `$__'.

- If the `x' command has a repeat count, the address and contents saved

-are from the last memory unit printed; this is not the same as the last

-address printed if several units were printed on the last line of

-output.

- When you are debugging a program running on a remote target machine

-(*note Remote Debugging::), you may wish to verify the program's image

-in the remote machine's memory against the executable file you

-downloaded to the target. The `compare-sections' command is provided

-for such situations.

-`compare-sections [SECTION-NAME]'

- Compare the data of a loadable section SECTION-NAME in the

- executable file of the program being debugged with the same

- section in the remote machine's memory, and report any mismatches.

- With no arguments, compares all loadable sections. This command's

- availability depends on the target's support for the `"qCRC"'

- remote request.

« no previous file with comments | « gdb/doc/gdb.info ('k') | gdb/doc/gdb.info-2 » ('j') | no next file with comments »