Subversion Repositories openrisc

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

INFO-DIR-SECTION Software development

START-INFO-DIR-ENTRY

* Gdb: (gdb).                     The GNU debugger.

END-INFO-DIR-ENTRY

   Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,

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

2010 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.1 or

any later version published by the Free Software Foundation; with the

Invariant Sections being "Free Software" and "Free Software Needs Free

Documentation", with the Front-Cover Texts being "A GNU Manual," and

with the Back-Cover Texts as in (a) below.

   (a) The FSF's Back-Cover Text is: "You are free to copy and modify

this GNU Manual.  Buying copies from GNU Press supports the FSF in

developing GNU and promoting software freedom."

   This file documents the GNU debugger GDB.

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

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

   Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,

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

2010 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.1 or

any later version published by the Free Software Foundation; with the

Invariant Sections being "Free Software" and "Free Software Needs Free

Documentation", with the Front-Cover Texts being "A GNU Manual," and

with the Back-Cover Texts as in (a) below.

   (a) The FSF's Back-Cover Text is: "You are free to copy and modify

this GNU Manual.  Buying copies from GNU Press supports the FSF in

developing GNU and promoting software freedom."

File: gdb.info,  Node: Dump/Restore Files,  Next: Core File Generation,  Prev: Memory Region Attributes,  Up: Data

10.16 Copy Between Memory and a File

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

You can use the commands `dump', `append', and `restore' to copy data

between target memory and a file.  The `dump' and `append' commands

write data to a file, and the `restore' command reads data from a file

back into the inferior's memory.  Files may be in binary, Motorola

S-record, Intel hex, or Tektronix Hex format; however, GDB can only

append to binary files.

`dump [FORMAT] memory FILENAME START_ADDR END_ADDR'

`dump [FORMAT] value FILENAME EXPR'

     Dump the contents of memory from START_ADDR to END_ADDR, or the

     value of EXPR, to FILENAME in the given format.

     The FORMAT parameter may be any one of:

    `binary'

          Raw binary form.

    `ihex'

          Intel hex format.

    `srec'

          Motorola S-record format.

    `tekhex'

          Tektronix Hex format.

     GDB uses the same definitions of these formats as the GNU binary

     utilities, like `objdump' and `objcopy'.  If FORMAT is omitted,

     GDB dumps the data in raw binary form.

`append [binary] memory FILENAME START_ADDR END_ADDR'

`append [binary] value FILENAME EXPR'

     Append the contents of memory from START_ADDR to END_ADDR, or the

     value of EXPR, to the file FILENAME, in raw binary form.  (GDB can

     only append data to files in raw binary form.)

`restore FILENAME [binary] BIAS START END'

     Restore the contents of file FILENAME into memory.  The `restore'

     command can automatically recognize any known BFD file format,

     except for raw binary.  To restore a raw binary file you must

     specify the optional keyword `binary' after the filename.

     If BIAS is non-zero, its value will be added to the addresses

     contained in the file.  Binary files always start at address zero,

     so they will be restored at address BIAS.  Other bfd files have a

     built-in location; they will be restored at offset BIAS from that

     location.

     If START and/or END are non-zero, then only data between file

     offset START and file offset END will be restored.  These offsets

     are relative to the addresses in the file, before the BIAS

     argument is applied.

File: gdb.info,  Node: Core File Generation,  Next: Character Sets,  Prev: Dump/Restore Files,  Up: Data

10.17 How to Produce a Core File from Your Program

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

A "core file" or "core dump" is a file that records the memory image of

a running process and its process status (register values etc.).  Its

primary use is post-mortem debugging of a program that crashed while it

ran outside a debugger.  A program that crashes automatically produces

a core file, unless this feature is disabled by the user.  *Note

Files::, for information on invoking GDB in the post-mortem debugging

mode.

   Occasionally, you may wish to produce a core file of the program you

are debugging in order to preserve a snapshot of its state.  GDB has a

special command for that.

`generate-core-file [FILE]'

`gcore [FILE]'

     Produce a core dump of the inferior process.  The optional argument

     FILE specifies the file name where to put the core dump.  If not

     specified, the file name defaults to `core.PID', where PID is the

     inferior process ID.

     Note that this command is implemented only for some systems (as of

     this writing, GNU/Linux, FreeBSD, Solaris, Unixware, and S390).

File: gdb.info,  Node: Character Sets,  Next: Caching Remote Data,  Prev: Core File Generation,  Up: Data

10.18 Character Sets

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

If the program you are debugging uses a different character set to

represent characters and strings than the one GDB uses itself, GDB can

automatically translate between the character sets for you.  The

character set GDB uses we call the "host character set"; the one the

inferior program uses we call the "target character set".

   For example, if you are running GDB on a GNU/Linux system, which

uses the ISO Latin 1 character set, but you are using GDB's remote

protocol (*note Remote Debugging::) to debug a program running on an

IBM mainframe, which uses the EBCDIC character set, then the host

character set is Latin-1, and the target character set is EBCDIC.  If

you give GDB the command `set target-charset EBCDIC-US', then GDB

translates between EBCDIC and Latin 1 as you print character or string

values, or use character and string literals in expressions.

   GDB has no way to automatically recognize which character set the

inferior program uses; you must tell it, using the `set target-charset'

command, described below.

   Here are the commands for controlling GDB's character set support:

`set target-charset CHARSET'

     Set the current target character set to CHARSET.  To display the

     list of supported target character sets, type

     `set target-charset '.

`set host-charset CHARSET'

     Set the current host character set to CHARSET.

     By default, GDB uses a host character set appropriate to the

     system it is running on; you can override that default using the

     `set host-charset' command.  On some systems, GDB cannot

     automatically determine the appropriate host character set.  In

     this case, GDB uses `UTF-8'.

     GDB can only use certain character sets as its host character set.

     If you type `set target-charset ', GDB will list the

     host character sets it supports.

`set charset CHARSET'

     Set the current host and target character sets to CHARSET.  As

     above, if you type `set charset ', GDB will list the

     names of the character sets that can be used for both host and

     target.

`show charset'

     Show the names of the current host and target character sets.

`show host-charset'

     Show the name of the current host character set.

`show target-charset'

     Show the name of the current target character set.

`set target-wide-charset CHARSET'

     Set the current target's wide character set to CHARSET.  This is

     the character set used by the target's `wchar_t' type.  To display

     the list of supported wide character sets, type

     `set target-wide-charset '.

`show target-wide-charset'

     Show the name of the current target's wide character set.

   Here is an example of GDB's character set support in action.  Assume

that the following source code has been placed in the file

`charset-test.c':

     #include 

     char ascii_hello[]

       = {72, 101, 108, 108, 111, 44, 32, 119,

          111, 114, 108, 100, 33, 10, 0};

     char ibm1047_hello[]

       = {200, 133, 147, 147, 150, 107, 64, 166,

          150, 153, 147, 132, 90, 37, 0};

     main ()

     {

       printf ("Hello, world!\n");

     }

   In this program, `ascii_hello' and `ibm1047_hello' are arrays

containing the string `Hello, world!' followed by a newline, encoded in

the ASCII and IBM1047 character sets.

   We compile the program, and invoke the debugger on it:

     $ gcc -g charset-test.c -o charset-test

     $ gdb -nw charset-test

     GNU gdb 2001-12-19-cvs

     Copyright 2001 Free Software Foundation, Inc.

     ...

     (gdb)

   We can use the `show charset' command to see what character sets GDB

is currently using to interpret and display characters and strings:

     (gdb) show charset

     The current host and target character set is `ISO-8859-1'.

     (gdb)

   For the sake of printing this manual, let's use ASCII as our initial

character set:

     (gdb) set charset ASCII

     (gdb) show charset

     The current host and target character set is `ASCII'.

     (gdb)

   Let's assume that ASCII is indeed the correct character set for our

host system -- in other words, let's assume that if GDB prints

characters using the ASCII character set, our terminal will display

them properly.  Since our current target character set is also ASCII,

the contents of `ascii_hello' print legibly:

     (gdb) print ascii_hello

     $1 = 0x401698 "Hello, world!\n"

     (gdb) print ascii_hello[0]

     $2 = 72 'H'

     (gdb)

   GDB uses the target character set for character and string literals

you use in expressions:

     (gdb) print '+'

     $3 = 43 '+'

     (gdb)

   The ASCII character set uses the number 43 to encode the `+'

character.

   GDB relies on the user to tell it which character set the target

program uses.  If we print `ibm1047_hello' while our target character

set is still ASCII, we get jibberish:

     (gdb) print ibm1047_hello

     $4 = 0x4016a8 "\310\205\223\223\226k@\246\226\231\223\204Z%"

     (gdb) print ibm1047_hello[0]

     $5 = 200 '\310'

     (gdb)

   If we invoke the `set target-charset' followed by , GDB

tells us the character sets it supports:

     (gdb) set target-charset

     ASCII       EBCDIC-US   IBM1047     ISO-8859-1

     (gdb) set target-charset

   We can select IBM1047 as our target character set, and examine the

program's strings again.  Now the ASCII string is wrong, but GDB

translates the contents of `ibm1047_hello' from the target character

set, IBM1047, to the host character set, ASCII, and they display

correctly:

     (gdb) set target-charset IBM1047

     (gdb) show charset

     The current host character set is `ASCII'.

     The current target character set is `IBM1047'.

     (gdb) print ascii_hello

     $6 = 0x401698 "\110\145%%?\054\040\167?\162%\144\041\012"

     (gdb) print ascii_hello[0]

     $7 = 72 '\110'

     (gdb) print ibm1047_hello

     $8 = 0x4016a8 "Hello, world!\n"

     (gdb) print ibm1047_hello[0]

     $9 = 200 'H'

     (gdb)

   As above, GDB uses the target character set for character and string

literals you use in expressions:

     (gdb) print '+'

     $10 = 78 '+'

     (gdb)

   The IBM1047 character set uses the number 78 to encode the `+'

character.

File: gdb.info,  Node: Caching Remote Data,  Next: Searching Memory,  Prev: Character Sets,  Up: Data

10.19 Caching Data of Remote Targets

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

GDB caches data exchanged between the debugger and a remote target

(*note Remote Debugging::).  Such caching generally improves

performance, because it reduces the overhead of the remote protocol by

bundling memory reads and writes into large chunks.  Unfortunately,

simply caching everything would lead to incorrect results, since GDB

does not necessarily know anything about volatile values, memory-mapped

I/O addresses, etc.  Furthermore, in non-stop mode (*note Non-Stop

Mode::) memory can be changed _while_ a gdb command is executing.

Therefore, by default, GDB only caches data known to be on the stack(1).

Other regions of memory can be explicitly marked as cacheable; see

*note Memory Region Attributes::.

`set remotecache on'

`set remotecache off'

     This option no longer does anything; it exists for compatibility

     with old scripts.

`show remotecache'

     Show the current state of the obsolete remotecache flag.

`set stack-cache on'

`set stack-cache off'

     Enable or disable caching of stack accesses.  When `ON', use

     caching.  By default, this option is `ON'.

`show stack-cache'

     Show the current state of data caching for memory accesses.

`info dcache [line]'

     Print the information about the data cache performance.  The

     information displayed includes the dcache width and depth, and for

     each cache line, its number, address, and how many times it was

     referenced.  This command is useful for debugging the data cache

     operation.

     If a line number is specified, the contents of that line will be

     printed in hex.

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

   (1) In non-stop mode, it is moderately rare for a running thread to

modify the stack of a stopped thread in a way that would interfere with

a backtrace, and caching of stack reads provides a significant speed up

of remote backtraces.

File: gdb.info,  Node: Searching Memory,  Prev: Caching Remote Data,  Up: Data

10.20 Search Memory

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

Memory can be searched for a particular sequence of bytes with the

`find' command.

`find [/SN] START_ADDR, +LEN, VAL1 [, VAL2, ...]'

`find [/SN] START_ADDR, END_ADDR, VAL1 [, VAL2, ...]'

     Search memory for the sequence of bytes specified by VAL1, VAL2,

     etc.  The search begins at address START_ADDR and continues for

     either LEN bytes or through to END_ADDR inclusive.

   S and N are optional parameters.  They may be specified in either

order, apart or together.

S, search query size

     The size of each search query value.

    `b'

          bytes

    `h'

          halfwords (two bytes)

    `w'

          words (four bytes)

    `g'

          giant words (eight bytes)

     All values are interpreted in the current language.  This means,

     for example, that if the current source language is C/C++ then

     searching for the string "hello" includes the trailing '\0'.

     If the value size is not specified, it is taken from the value's

     type in the current language.  This is useful when one wants to

     specify the search pattern as a mixture of types.  Note that this

     means, for example, that in the case of C-like languages a search

     for an untyped 0x42 will search for `(int) 0x42' which is

     typically four bytes.

N, maximum number of finds

     The maximum number of matches to print.  The default is to print

     all finds.

   You can use strings as search values.  Quote them with double-quotes

(`"').  The string value is copied into the search pattern byte by

byte, regardless of the endianness of the target and the size

specification.

   The address of each match found is printed as well as a count of the

number of matches found.

   The address of the last value found is stored in convenience variable

`$_'.  A count of the number of matches is stored in `$numfound'.

   For example, if stopped at the `printf' in this function:

     void

     hello ()

     {

       static char hello[] = "hello-hello";

       static struct { char c; short s; int i; }

         __attribute__ ((packed)) mixed

         = { 'c', 0x1234, 0x87654321 };

       printf ("%s\n", hello);

     }

you get during debugging:

     (gdb) find &hello[0], +sizeof(hello), "hello"

     0x804956d 

     1 pattern found

     (gdb) find &hello[0], +sizeof(hello), 'h', 'e', 'l', 'l', 'o'

     0x8049567 

     0x804956d 

     2 patterns found

     (gdb) find /b1 &hello[0], +sizeof(hello), 'h', 0x65, 'l'

     0x8049567 

     1 pattern found

     (gdb) find &mixed, +sizeof(mixed), (char) 'c', (short) 0x1234, (int) 0x87654321

     0x8049560 

     1 pattern found

     (gdb) print $numfound

     $1 = 1

     (gdb) print $_

     $2 = (void *) 0x8049560

File: gdb.info,  Node: Optimized Code,  Next: Macros,  Prev: Data,  Up: Top

11 Debugging Optimized Code

***************************

Almost all compilers support optimization.  With optimization disabled,

the compiler generates assembly code that corresponds directly to your

source code, in a simplistic way.  As the compiler applies more

powerful optimizations, the generated assembly code diverges from your

original source code.  With help from debugging information generated

by the compiler, GDB can map from the running program back to

constructs from your original source.

   GDB is more accurate with optimization disabled.  If you can

recompile without optimization, it is easier to follow the progress of

your program during debugging.  But, there are many cases where you may

need to debug an optimized version.

   When you debug a program compiled with `-g -O', remember that the

optimizer has rearranged your code; the debugger shows you what is

really there.  Do not be too surprised when the execution path does not

exactly match your source file!  An extreme example: if you define a

variable, but never use it, GDB never sees that variable--because the

compiler optimizes it out of existence.

   Some things do not work as well with `-g -O' as with just `-g',

particularly on machines with instruction scheduling.  If in doubt,

recompile with `-g' alone, and if this fixes the problem, please report

it to us as a bug (including a test case!).  *Note Variables::, for

more information about debugging optimized code.

* Menu:

* Inline Functions::            How GDB presents inlining

File: gdb.info,  Node: Inline Functions,  Up: Optimized Code

11.1 Inline Functions

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

"Inlining" is an optimization that inserts a copy of the function body

directly at each call site, instead of jumping to a shared routine.

GDB displays inlined functions just like non-inlined functions.  They

appear in backtraces.  You can view their arguments and local

variables, step into them with `step', skip them with `next', and

escape from them with `finish'.  You can check whether a function was

inlined by using the `info frame' command.

   For GDB to support inlined functions, the compiler must record

information about inlining in the debug information -- GCC using the

DWARF 2 format does this, and several other compilers do also.  GDB

only supports inlined functions when using DWARF 2.  Versions of GCC

before 4.1 do not emit two required attributes (`DW_AT_call_file' and

`DW_AT_call_line'); GDB does not display inlined function calls with

earlier versions of GCC.  It instead displays the arguments and local

variables of inlined functions as local variables in the caller.

   The body of an inlined function is directly included at its call

site; unlike a non-inlined function, there are no instructions devoted

to the call.  GDB still pretends that the call site and the start of

the inlined function are different instructions.  Stepping to the call

site shows the call site, and then stepping again shows the first line

of the inlined function, even though no additional instructions are

executed.

   This makes source-level debugging much clearer; you can see both the

context of the call and then the effect of the call.  Only stepping by

a single instruction using `stepi' or `nexti' does not do this; single

instruction steps always show the inlined body.

   There are some ways that GDB does not pretend that inlined function

calls are the same as normal calls:

   * You cannot set breakpoints on inlined functions.  GDB either

     reports that there is no symbol with that name, or else sets the

     breakpoint only on non-inlined copies of the function.  This

     limitation will be removed in a future version of GDB; until then,

     set a breakpoint by line number on the first line of the inlined

     function instead.

   * Setting breakpoints at the call site of an inlined function may not

     work, because the call site does not contain any code.  GDB may

     incorrectly move the breakpoint to the next line of the enclosing

     function, after the call.  This limitation will be removed in a

     future version of GDB; until then, set a breakpoint on an earlier

     line or inside the inlined function instead.

   * GDB cannot locate the return value of inlined calls after using

     the `finish' command.  This is a limitation of compiler-generated

     debugging information; after `finish', you can step to the next

     line and print a variable where your program stored the return

     value.

File: gdb.info,  Node: Macros,  Next: Tracepoints,  Prev: Optimized Code,  Up: Top

12 C Preprocessor Macros

************************

Some languages, such as C and C++, provide a way to define and invoke

"preprocessor macros" which expand into strings of tokens.  GDB can

evaluate expressions containing macro invocations, show the result of

macro expansion, and show a macro's definition, including where it was

defined.

   You may need to compile your program specially to provide GDB with

information about preprocessor macros.  Most compilers do not include

macros in their debugging information, even when you compile with the

`-g' flag.  *Note Compilation::.

   A program may define a macro at one point, remove that definition

later, and then provide a different definition after that.  Thus, at

different points in the program, a macro may have different

definitions, or have no definition at all.  If there is a current stack

frame, GDB uses the macros in scope at that frame's source code line.

Otherwise, GDB uses the macros in scope at the current listing location;

see *Note List::.

   Whenever GDB evaluates an expression, it always expands any macro

invocations present in the expression.  GDB also provides the following

commands for working with macros explicitly.

`macro expand EXPRESSION'

`macro exp EXPRESSION'

     Show the results of expanding all preprocessor macro invocations in

     EXPRESSION.  Since GDB simply expands macros, but does not parse

     the result, EXPRESSION need not be a valid expression; it can be

     any string of tokens.

`macro expand-once EXPRESSION'

`macro exp1 EXPRESSION'

     (This command is not yet implemented.)  Show the results of

     expanding those preprocessor macro invocations that appear

     explicitly in EXPRESSION.  Macro invocations appearing in that

     expansion are left unchanged.  This command allows you to see the

     effect of a particular macro more clearly, without being confused

     by further expansions.  Since GDB simply expands macros, but does

     not parse the result, EXPRESSION need not be a valid expression; it

     can be any string of tokens.

`info macro MACRO'

     Show the definition of the macro named MACRO, and describe the

     source location or compiler command-line where that definition was

     established.

`macro define MACRO REPLACEMENT-LIST'

`macro define MACRO(ARGLIST) REPLACEMENT-LIST'

     Introduce a definition for a preprocessor macro named MACRO,

     invocations of which are replaced by the tokens given in

     REPLACEMENT-LIST.  The first form of this command defines an

     "object-like" macro, which takes no arguments; the second form

     defines a "function-like" macro, which takes the arguments given in

     ARGLIST.

     A definition introduced by this command is in scope in every

     expression evaluated in GDB, until it is removed with the `macro

     undef' command, described below.  The definition overrides all

     definitions for MACRO present in the program being debugged, as

     well as any previous user-supplied definition.

`macro undef MACRO'

     Remove any user-supplied definition for the macro named MACRO.

     This command only affects definitions provided with the `macro

     define' command, described above; it cannot remove definitions

     present in the program being debugged.

`macro list'

     List all the macros defined using the `macro define' command.

   Here is a transcript showing the above commands in action.  First, we

show our source files:

     $ cat sample.c

     #include 

     #include "sample.h"

     #define M 42

     #define ADD(x) (M + x)

     main ()

     {

     #define N 28

       printf ("Hello, world!\n");

     #undef N

       printf ("We're so creative.\n");

     #define N 1729

       printf ("Goodbye, world!\n");

     }

     $ cat sample.h

     #define Q <

     $

   Now, we compile the program using the GNU C compiler, GCC.  We pass

the `-gdwarf-2' and `-g3' flags to ensure the compiler includes

information about preprocessor macros in the debugging information.

     $ gcc -gdwarf-2 -g3 sample.c -o sample

     $

   Now, we start GDB on our sample program:

     $ gdb -nw sample

     GNU gdb 2002-05-06-cvs

     Copyright 2002 Free Software Foundation, Inc.

     GDB is free software, ...

     (gdb)

   We can expand macros and examine their definitions, even when the

program is not running.  GDB uses the current listing position to

decide which macro definitions are in scope:

     (gdb) list main

     3

     4       #define M 42

     5       #define ADD(x) (M + x)

     6

     7       main ()

     8       {

     9       #define N 28

     10        printf ("Hello, world!\n");

     11      #undef N

     12        printf ("We're so creative.\n");

     (gdb) info macro ADD

     Defined at /home/jimb/gdb/macros/play/sample.c:5

     #define ADD(x) (M + x)

     (gdb) info macro Q

     Defined at /home/jimb/gdb/macros/play/sample.h:1

       included at /home/jimb/gdb/macros/play/sample.c:2

     #define Q <

     (gdb) macro expand ADD(1)

     expands to: (42 + 1)

     (gdb) macro expand-once ADD(1)

     expands to: once (M + 1)

     (gdb)

   In the example above, note that `macro expand-once' expands only the

macro invocation explicit in the original text -- the invocation of

`ADD' -- but does not expand the invocation of the macro `M', which was

introduced by `ADD'.

   Once the program is running, GDB uses the macro definitions in force

at the source line of the current stack frame:

     (gdb) break main

     Breakpoint 1 at 0x8048370: file sample.c, line 10.

     (gdb) run

     Starting program: /home/jimb/gdb/macros/play/sample

     Breakpoint 1, main () at sample.c:10

     10        printf ("Hello, world!\n");

     (gdb)

   At line 10, the definition of the macro `N' at line 9 is in force:

     (gdb) info macro N

     Defined at /home/jimb/gdb/macros/play/sample.c:9

     #define N 28

     (gdb) macro expand N Q M

     expands to: 28 < 42

     (gdb) print N Q M

     $1 = 1

     (gdb)

   As we step over directives that remove `N''s definition, and then

give it a new definition, GDB finds the definition (or lack thereof) in

force at each point:

     (gdb) next

     Hello, world!

     12        printf ("We're so creative.\n");

     (gdb) info macro N

     The symbol `N' has no definition as a C/C++ preprocessor macro

     at /home/jimb/gdb/macros/play/sample.c:12

     (gdb) next

     We're so creative.

     14        printf ("Goodbye, world!\n");

     (gdb) info macro N

     Defined at /home/jimb/gdb/macros/play/sample.c:13

     #define N 1729

     (gdb) macro expand N Q M

     expands to: 1729 < 42

     (gdb) print N Q M

     $2 = 0

     (gdb)

   In addition to source files, macros can be defined on the

compilation command line using the `-DNAME=VALUE' syntax.  For macros

defined in such a way, GDB displays the location of their definition as

line zero of the source file submitted to the compiler.

     (gdb) info macro __STDC__

     Defined at /home/jimb/gdb/macros/play/sample.c:0

     -D__STDC__=1

     (gdb)

File: gdb.info,  Node: Tracepoints,  Next: Overlays,  Prev: Macros,  Up: Top

13 Tracepoints

**************

In some applications, it is not feasible for the debugger to interrupt

the program's execution long enough for the developer to learn anything

helpful about its behavior.  If the program's correctness depends on

its real-time behavior, delays introduced by a debugger might cause the

program to change its behavior drastically, or perhaps fail, even when

the code itself is correct.  It is useful to be able to observe the

program's behavior without interrupting it.

   Using GDB's `trace' and `collect' commands, you can specify

locations in the program, called "tracepoints", and arbitrary

expressions to evaluate when those tracepoints are reached.  Later,

using the `tfind' command, you can examine the values those expressions

had when the program hit the tracepoints.  The expressions may also

denote objects in memory--structures or arrays, for example--whose

values GDB should record; while visiting a particular tracepoint, you

may inspect those objects as if they were in memory at that moment.

However, because GDB records these values without interacting with you,

it can do so quickly and unobtrusively, hopefully not disturbing the

program's behavior.

   The tracepoint facility is currently available only for remote

targets.  *Note Targets::.  In addition, your remote target must know

how to collect trace data.  This functionality is implemented in the

remote stub; however, none of the stubs distributed with GDB support

tracepoints as of this writing.  The format of the remote packets used

to implement tracepoints are described in *Note Tracepoint Packets::.

   It is also possible to get trace data from a file, in a manner

reminiscent of corefiles; you specify the filename, and use `tfind' to

search through the file.  *Note Trace Files::, for more details.

   This chapter describes the tracepoint commands and features.

* Menu:

* Set Tracepoints::

* Analyze Collected Data::

* Tracepoint Variables::

* Trace Files::

File: gdb.info,  Node: Set Tracepoints,  Next: Analyze Collected Data,  Up: Tracepoints

13.1 Commands to Set Tracepoints

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

Before running such a "trace experiment", an arbitrary number of

tracepoints can be set.  A tracepoint is actually a special type of

breakpoint (*note Set Breaks::), so you can manipulate it using

standard breakpoint commands.  For instance, as with breakpoints,

tracepoint numbers are successive integers starting from one, and many

of the commands associated with tracepoints take the tracepoint number

as their argument, to identify which tracepoint to work on.

   For each tracepoint, you can specify, in advance, some arbitrary set

of data that you want the target to collect in the trace buffer when it

hits that tracepoint.  The collected data can include registers, local

variables, or global data.  Later, you can use GDB commands to examine

the values these data had at the time the tracepoint was hit.

   Tracepoints do not support every breakpoint feature.  Conditional

expressions and ignore counts on tracepoints have no effect, and

tracepoints cannot run GDB commands when they are hit.  Tracepoints may

not be thread-specific either.

   Some targets may support "fast tracepoints", which are inserted in a

different way (such as with a jump instead of a trap), that is faster

but possibly restricted in where they may be installed.

   This section describes commands to set tracepoints and associated

conditions and actions.

* Menu:

* Create and Delete Tracepoints::

* Enable and Disable Tracepoints::

* Tracepoint Passcounts::

* Tracepoint Conditions::

* Trace State Variables::

* Tracepoint Actions::

* Listing Tracepoints::

* Starting and Stopping Trace Experiments::

File: gdb.info,  Node: Create and Delete Tracepoints,  Next: Enable and Disable Tracepoints,  Up: Set Tracepoints

13.1.1 Create and Delete Tracepoints

------------------------------------

`trace LOCATION'

     The `trace' command is very similar to the `break' command.  Its

     argument LOCATION can be a source line, a function name, or an

     address in the target program.  *Note Specify Location::.  The

     `trace' command defines a tracepoint, which is a point in the

     target program where the debugger will briefly stop, collect some

     data, and then allow the program to continue.  Setting a

     tracepoint or changing its actions doesn't take effect until the

     next `tstart' command, and once a trace experiment is running,

     further changes will not have any effect until the next trace

     experiment starts.

     Here are some examples of using the `trace' command:

          (gdb) trace foo.c:121    // a source file and line number

          (gdb) trace +2           // 2 lines forward

          (gdb) trace my_function  // first source line of function

          (gdb) trace *my_function // EXACT start address of function

          (gdb) trace *0x2117c4    // an address

     You can abbreviate `trace' as `tr'.

`trace LOCATION if COND'

     Set a tracepoint with condition COND; evaluate the expression COND

     each time the tracepoint is reached, and collect data only if the

     value is nonzero--that is, if COND evaluates as true.  *Note

     Tracepoint Conditions: Tracepoint Conditions, for more information

     on tracepoint conditions.

`ftrace LOCATION [ if COND ]'

     The `ftrace' command sets a fast tracepoint.  For targets that

     support them, fast tracepoints will use a more efficient but

     possibly less general technique to trigger data collection, such

     as a jump instruction instead of a trap, or some sort of hardware

     support.  It may not be possible to create a fast tracepoint at

     the desired location, in which case the command will exit with an

     explanatory message.

     GDB handles arguments to `ftrace' exactly as for `trace'.

     The convenience variable `$tpnum' records the tracepoint number of

     the most recently set tracepoint.

`delete tracepoint [NUM]'

     Permanently delete one or more tracepoints.  With no argument, the

     default is to delete all tracepoints.  Note that the regular

     `delete' command can remove tracepoints also.

     Examples:

          (gdb) delete trace 1 2 3 // remove three tracepoints

          (gdb) delete trace       // remove all tracepoints

     You can abbreviate this command as `del tr'.

File: gdb.info,  Node: Enable and Disable Tracepoints,  Next: Tracepoint Passcounts,  Prev: Create and Delete Tracepoints,  Up: Set Tracepoints

13.1.2 Enable and Disable Tracepoints

-------------------------------------

These commands are deprecated; they are equivalent to plain `disable'

and `enable'.

`disable tracepoint [NUM]'

     Disable tracepoint NUM, or all tracepoints if no argument NUM is

     given.  A disabled tracepoint will have no effect during the next

     trace experiment, but it is not forgotten.  You can re-enable a

     disabled tracepoint using the `enable tracepoint' command.

`enable tracepoint [NUM]'

     Enable tracepoint NUM, or all tracepoints.  The enabled

     tracepoints will become effective the next time a trace experiment

     is run.

File: gdb.info,  Node: Tracepoint Passcounts,  Next: Tracepoint Conditions,  Prev: Enable and Disable Tracepoints,  Up: Set Tracepoints

13.1.3 Tracepoint Passcounts

----------------------------

`passcount [N [NUM]]'

     Set the "passcount" of a tracepoint.  The passcount is a way to

     automatically stop a trace experiment.  If a tracepoint's