Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below.
-(a) The Free Software Foundation's Back-Cover Text is: ``You have
-freedom to copy and modify this GNU Manual, like GNU software. Copies
-published by the Free Software Foundation raise funds for GNU
-development.''
+(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.''
@end ifinfo
@titlepage
Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below.
-(a) The Free Software Foundation's Back-Cover Text is: ``You have
-freedom to copy and modify this GNU Manual, like GNU software. Copies
-published by the Free Software Foundation raise funds for GNU
-development.''
+(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.''
@page
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
Whether the breakpoint is marked to be disabled or deleted when hit.
@item Enabled or Disabled
Enabled breakpoints are marked with @samp{y}. @samp{n} marks breakpoints
-that are not enabled.
+that are not enabled. An optional @samp{(p)} suffix marks pending
+breakpoints --- breakpoints for which address is either not yet
+resolved, pending load of a shared library, or for which address was
+in a shared library that was since unloaded. Such breakpoint won't
+fire until a shared library that has the symbol or line referred by
+breakpoint is loaded. See below for details.
@item Address
-Where the breakpoint is in your program, as a memory address. If the
-breakpoint is pending (see below for details) on a future load of a shared library, the address
-will be listed as @samp{<PENDING>}.
+Where the breakpoint is in your program, as a memory address. For a
+pending breakpoint whose address is not yet known, this field will
+contain @samp{<PENDING>}. A breakpoint with several locations will
+have @samp{<MULTIPLE>} in this field --- see below for details.
@item What
Where the breakpoint is in the source for your program, as a file and
line number. For a pending breakpoint, the original string passed to
the breakpoints are conditional, this is even useful
(@pxref{Conditions, ,Break Conditions}).
+It is possible that a breakpoint corresponds to several locations
+in your program. Examples of this situation are:
+
+@itemize @bullet
+
+@item
+For a C@t{++} constructor, the @value{NGCC} compiler generates several
+instances of the function body, used in different cases.
+
+@item
+For a C@t{++} template function, a given line in the function can
+correspond to any number of instantiations.
+
+@item
+For an inlined function, a given source line can correspond to
+several places where that function is inlined.
+
+@end itemize
+
+In all those cases, @value{GDBN} will insert a breakpoint at all
+the relevant locations.
+
+A breakpoint with multiple locations is displayed in the
+breakpoint table using several rows --- one header row, followed
+by one row for each breakpoint location. The header row
+has @samp{<MULTIPLE>} in the address column. The rows for
+individual locations contain the actual addresses for locations,
+and say what functions those locations are in. The number
+column for a location has number in the format
+@var{breakpoint-number}.@var{location-number}.
+
+For example:
+@smallexample
+Num Type Disp Enb Address What
+1 breakpoint keep y <MULTIPLE>
+ stop only if i==1
+ breakpoint already hit 1 time
+1.1 y 0x080486a2 in void foo<int>() at t.cc:8
+1.2 y 0x080486ca in void foo<double>() at t.cc:8
+@end smallexample
+
+Each location can be individually enabled or disabled by passing
+@var{breakpoint-number}.@var{location-number} as argument to the
+@code{enable} and @code{disable} commands.
+
@cindex pending breakpoints
-If a specified breakpoint location cannot be found, it may be due to the fact
-that the location is in a shared library that is yet to be loaded. In such
-a case, you may want @value{GDBN} to create a special breakpoint (known as
-a @dfn{pending breakpoint}) that
-attempts to resolve itself in the future when an appropriate shared library
-gets loaded.
-
-Pending breakpoints are useful to set at the start of your
-@value{GDBN} session for locations that you know will be dynamically loaded
-later by the program being debugged. When shared libraries are loaded,
-a check is made to see if the load resolves any pending breakpoint locations.
-If a pending breakpoint location gets resolved,
-a regular breakpoint is created and the original pending breakpoint is removed.
-
-@value{GDBN} provides some additional commands for controlling pending
-breakpoint support:
+It's quite common to have a breakpoint inside a shared library.
+The shared library may be loaded and unloaded explicitly,
+and possibly repeatedly, as the program is executed. To support
+this use case, @value{GDBN} updates breakpoint locations whenever
+any shared library is loaded or unloaded. Typically, you would
+set a breakpoint in a shared library at the beginning of your
+debugging session, when the library is not loaded, and when the
+symbols from the library are not available. When you try to set
+breakpoint, @value{GDBN} will ask you if you want to set
+a so called @dfn{pending breakpoint} --- breakpoint whose address
+is not yet resolved.
+
+After the program is run, whenever a new shared library is loaded,
+@value{GDBN} reevaluates all the breakpoints. When a newly loaded
+shared library contains the symbol or line referred to by some
+pending breakpoint, that breakpoint is resolved and becomes an
+ordinary breakpoint. When a library is unloaded, all breakpoints
+that refer to its symbols or source lines become pending again.
+
+This logic works for breakpoints with multiple locations, too. For
+example, if you have a breakpoint in a C@t{++} template function, and
+a newly loaded shared library has an instantiation of that template,
+a new location is added to the list of locations for the breakpoint.
+
+Except for having unresolved address, pending breakpoints do not
+differ from regular breakpoints. You can set conditions or commands,
+enable and disable them and perform other breakpoint operations.
+
+@value{GDBN} provides some additional commands for controlling what
+happens when the @samp{break} command cannot resolve breakpoint
+address specification to an address:
@kindex set breakpoint pending
@kindex show breakpoint pending
Show the current behavior setting for creating pending breakpoints.
@end table
-@cindex operations allowed on pending breakpoints
-Normal breakpoint operations apply to pending breakpoints as well. You may
-specify a condition for a pending breakpoint and/or commands to run when the
-breakpoint is reached. You can also enable or disable
-the pending breakpoint. When you specify a condition for a pending breakpoint,
-the parsing of the condition will be deferred until the point where the
-pending breakpoint location is resolved. Disabling a pending breakpoint
-tells @value{GDBN} to not attempt to resolve the breakpoint on any subsequent
-shared library load. When a pending breakpoint is re-enabled,
-@value{GDBN} checks to see if the location is already resolved.
-This is done because any number of shared library loads could have
-occurred since the time the breakpoint was disabled and one or more
-of these loads could resolve the location.
+The settings above only affect the @code{break} command and its
+variants. Once breakpoint is set, it will be automatically updated
+as shared libraries are loaded and unloaded.
@cindex automatic hardware breakpoints
For some targets, @value{GDBN} can automatically decide if hardware or
breakpoint address is read-only or read-write. This applies to
breakpoints set with the @code{break} command as well as to internal
breakpoints set by commands like @code{next} and @code{finish}. For
-breakpoints set with @code{hbreak}, @value{GDBN} will always use hardware
+breakpoints set with @code{hbreak}, @value{GDBN} will always use hardware
breakpoints.
You can control this automatic behaviour with the following commands::
way of doing that would be to set a code breakpoint at the entry to the
@code{main} function and when it breaks, set all the watchpoints.
-@quotation
@cindex watchpoints and threads
@cindex threads and watchpoints
-@emph{Warning:} In multi-thread programs, watchpoints have only limited
-usefulness. With the current watchpoint implementation, @value{GDBN}
-can only watch the value of an expression @emph{in a single thread}. If
-you are confident that the expression can only change due to the current
-thread's activity (and if you are also confident that no other thread
-can become current), then you can use watchpoints as usual. However,
-@value{GDBN} may not notice when a non-current thread's activity changes
-the expression.
-
-@c FIXME: this is almost identical to the previous paragraph.
-@emph{HP-UX Warning:} In multi-thread programs, software watchpoints
+In multi-threaded programs, watchpoints will detect changes to the
+watched expression from every thread.
+
+@quotation
+@emph{Warning:} In multi-threaded programs, software watchpoints
have only limited usefulness. If @value{GDBN} creates a software
watchpoint, it can only watch the value of an expression @emph{in a
single thread}. If you are confident that the expression can only
character representation is replaced with the octal escape @samp{\nnn}
for characters outside the 7-bit @sc{ascii} range.
+Without this format, @value{GDBN} displays @code{char},
+@w{@code{unsigned char}}, and @w{@code{signed char}} data as character
+constants. Single-byte members of vectors are displayed as integer
+data.
+
@item f
Regard the bits of the value as a floating point number and print
using typical floating point syntax.
+
+@item s
+@cindex printing strings
+@cindex printing byte arrays
+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, @value{GDBN} displays pointers to and arrays of
+@code{char}, @w{@code{unsigned char}}, and @w{@code{signed char}} as
+strings. Single-byte members of a vector are displayed as an integer
+array.
@end table
For example, to print the program counter in hex (@pxref{Registers}), type
@item @var{f}, the display format
The display format is one of the formats used by @code{print}
(@samp{x}, @samp{d}, @samp{u}, @samp{o}, @samp{t}, @samp{a}, @samp{c},
-@samp{f}), and in addition @samp{s} (for null-terminated strings) and
-@samp{i} (for machine instructions). The default is @samp{x}
-(hexadecimal) initially. The default changes each time you use either
-@code{x} or @code{print}.
+@samp{f}, @samp{s}), and in addition @samp{i} (for machine instructions).
+The default is @samp{x} (hexadecimal) initially. The default changes
+each time you use either @code{x} or @code{print}.
@item @var{u}, the unit size
The unit size is any of
This display shows item numbers, expressions and their current values. As with
displays you request manually using @code{x} or @code{print}, you can
specify the output format you prefer; in fact, @code{display} decides
-whether to use @code{print} or @code{x} depending on how elaborate your
-format specification is---it uses @code{x} if you specify a unit size,
-or one of the two formats (@samp{i} and @samp{s}) that are only
-supported by @code{x}; otherwise it uses @code{print}.
+whether to use @code{print} or @code{x} depending your format
+specification---it uses @code{x} if you specify either the @samp{i}
+or @samp{s} format, or a unit size; otherwise it uses @code{print}.
@table @code
@kindex display
to such memory. The checks are only performed if there's at least one
memory range defined. If @code{off} is specified, make @value{GDBN}
treat the memory not explicitly described by the memory ranges as RAM.
-The default value is @code{off}.
+The default value is @code{on}.
@kindex show mem inaccessible-by-default
@item show mem inaccessible-by-default
Show the current handling of accesses to unknown memory.
@cindex @file{.debug} subdirectories
@cindex debugging information directory, global
@cindex global debugging information directory
+@cindex build ID, and separate debugging files
+@cindex @file{.build-id} directory
@value{GDBN} allows you to put a program's debugging information in a
file separate from the executable itself, in a way that allows
@value{GDBN} to find and load the debugging information automatically.
-Since debugging information can be very large --- sometimes larger
-than the executable code itself --- some systems distribute debugging
+Since debugging information can be very large---sometimes larger
+than the executable code itself---some systems distribute debugging
information for their executables in separate files, which users can
install only when they need to debug a problem.
-If an executable's debugging information has been extracted to a
-separate file, the executable should contain a @dfn{debug link} giving
-the name of the debugging information file (with no directory
-components), and a checksum of its contents. (The exact form of a
-debug link is described below.) If the full name of the directory
-containing the executable is @var{execdir}, and the executable has a
-debug link that specifies the name @var{debugfile}, then @value{GDBN}
-will automatically search for the debugging information file in three
-places:
+@value{GDBN} supports two ways of specifying the separate debug info
+file:
@itemize @bullet
@item
-the directory containing the executable file (that is, it will look
-for a file named @file{@var{execdir}/@var{debugfile}},
+The executable contains a @dfn{debug link} that specifies the name of
+the separate debug info file. The separate debug file's name is
+usually @file{@var{executable}.debug}, where @var{executable} is the
+name of the corresponding executable file without leading directories
+(e.g., @file{ls.debug} for @file{/usr/bin/ls}). In addition, the
+debug link specifies a CRC32 checksum for the debug file, which
+@value{GDBN} uses to validate that the executable and the debug file
+came from the same build.
+
+@item
+The executable contains a @dfn{build ID}, a unique bit string that is
+also present in the corresponding debug info file. (This is supported
+only on some operating systems, notably those which use the ELF format
+for binary files and the @sc{gnu} Binutils.) For more details about
+this feature, see the description of the @option{--build-id}
+command-line option in @ref{Options, , Command Line Options, ld.info,
+The GNU Linker}. The debug info file's name is not specified
+explicitly by the build ID, but can be computed from the build ID, see
+below.
+@end itemize
+
+Depending on the way the debug info file is specified, @value{GDBN}
+uses two different methods of looking for the debug file:
+
+@itemize @bullet
@item
-a subdirectory of that directory named @file{.debug} (that is, the
-file @file{@var{execdir}/.debug/@var{debugfile}}, and
+For the ``debug link'' method, @value{GDBN} looks up the named file in
+the directory of the executable file, then in a subdirectory of that
+directory named @file{.debug}, and finally under the global debug
+directory, in a subdirectory whose name is identical to the leading
+directories of the executable's absolute file name.
+
@item
-a subdirectory of the global debug file directory that includes the
-executable's full path, and the name from the link (that is, the file
-@file{@var{globaldebugdir}/@var{execdir}/@var{debugfile}}, where
-@var{globaldebugdir} is the global debug file directory, and
-@var{execdir} has been turned into a relative path).
+For the ``build ID'' method, @value{GDBN} looks in the
+@file{.build-id} subdirectory of the global debug directory for a file
+named @file{@var{nn}/@var{nnnnnnnn}.debug}, where @var{nn} are the
+first 2 hex characters of the build ID bit string, and @var{nnnnnnnn}
+are the rest of the bit string. (Real build ID strings are 32 or more
+hex characters, not 10.)
@end itemize
-@noindent
-@value{GDBN} checks under each of these names for a debugging
-information file whose checksum matches that given in the link, and
-reads the debugging information from the first one it finds.
-
-So, for example, if you ask @value{GDBN} to debug @file{/usr/bin/ls},
-which has a link containing the name @file{ls.debug}, and the global
-debug directory is @file{/usr/lib/debug}, then @value{GDBN} will look
-for debug information in @file{/usr/bin/ls.debug},
-@file{/usr/bin/.debug/ls.debug}, and
+
+So, for example, suppose you ask @value{GDBN} to debug
+@file{/usr/bin/ls}, which has a debug link that specifies the
+file @file{ls.debug}, and a build ID whose value in hex is
+@code{abcdef1234}. If the global debug directory is
+@file{/usr/lib/debug}, then @value{GDBN} will look for the following
+debug information files, in the indicated order:
+
+@itemize @minus
+@item
+@file{/usr/lib/debug/.build-id/ab/cdef1234.debug}
+@item
+@file{/usr/bin/ls.debug}
+@item
+@file{/usr/bin/.debug/ls.debug}
+@item
@file{/usr/lib/debug/usr/bin/ls.debug}.
+@end itemize
You can set the global debugging info directory's name, and view the
name @value{GDBN} is currently using.
@end table
@cindex @code{.gnu_debuglink} sections
-@cindex debug links
+@cindex debug link sections
A debug link is a special section of the executable file named
@code{.gnu_debuglink}. The section must contain:
contain a section named @code{.gnu_debuglink} with the contents
described above.
+@cindex @code{.note.gnu.build-id} sections
+@cindex build ID sections
+The build ID is a special section in the executable file (and in other
+ELF binary files that @value{GDBN} may consider). This section is
+often named @code{.note.gnu.build-id}, but that name is not mandatory.
+It contains unique identification for the built files---the ID remains
+the same across multiple builds of the same build tree. The default
+algorithm SHA1 produces 160 bits (40 hexadecimal characters) of the
+content for the build ID string. The same section with an identical
+value is present in the original built binary with symbols, in its
+stripped variant, and in the separate debugging information file.
+
The debugging information file itself should be an ordinary
executable, containing a full set of linker symbols, sections, and
debugging information. The sections of the debugging information file
-should have the same names, addresses and sizes as the original file,
-but they need not contain any data --- much like a @code{.bss} section
+should have the same names, addresses, and sizes as the original file,
+but they need not contain any data---much like a @code{.bss} section
in an ordinary executable.
-As of December 2002, there is no standard GNU utility to produce
-separated executable / debugging information file pairs. Ulrich
-Drepper's @file{elfutils} package, starting with version 0.53,
-contains a version of the @code{strip} command such that the command
-@kbd{strip foo -f foo.debug} removes the debugging information from
-the executable file @file{foo}, places it in the file
-@file{foo.debug}, and leaves behind a debug link in @file{foo}.
+The @sc{gnu} binary utilities (Binutils) package includes the
+@samp{objcopy} utility that can produce
+the separated executable / debugging information file pairs using the
+following commands:
+
+@smallexample
+@kbd{objcopy --only-keep-debug foo foo.debug}
+@kbd{strip -g foo}
+@end smallexample
+
+@noindent
+These commands remove the debugging
+information from the executable file @file{foo} and place it in the file
+@file{foo.debug}. You can use the first, second or both methods to link the
+two files:
+
+@itemize @bullet
+@item
+The debug link method needs the following additional command to also leave
+behind a debug link in @file{foo}:
+
+@smallexample
+@kbd{objcopy --add-gnu-debuglink=foo.debug foo}
+@end smallexample
+
+Ulrich Drepper's @file{elfutils} package, starting with version 0.53, contains
+a version of the @code{strip} command such that the command @kbd{strip foo -f
+foo.debug} has the same functionality as the two @code{objcopy} commands and
+the @code{ln -s} command above, together.
+
+@item
+Build ID gets embedded into the main executable using @code{ld --build-id} or
+the @value{NGCC} counterpart @code{gcc -Wl,--build-id}. Build ID support plus
+compatibility fixes for debug files separation are present in @sc{gnu} binary
+utilities (Binutils) package since version 2.18.
+@end itemize
+
+@noindent
-Since there are many different ways to compute CRC's (different
-polynomials, reversals, byte ordering, etc.), the simplest way to
-describe the CRC used in @code{.gnu_debuglink} sections is to give the
-complete code for a function that computes it:
+Since there are many different ways to compute CRC's for the debug
+link (different polynomials, reversals, byte ordering, etc.), the
+simplest way to describe the CRC used in @code{.gnu_debuglink}
+sections is to give the complete code for a function that computes it:
@kindex gnu_debuglink_crc32
@smallexample
@}
@end smallexample
+@noindent
+This computation does not apply to the ``build ID'' method.
+
@node Symbol Errors
@section Errors Reading Symbol Files
Formats}, for more information.
@kindex printf
-@item printf @var{string}, @var{expressions}@dots{}
-Print the values of the @var{expressions} under the control of
-@var{string}. The @var{expressions} are separated by commas and may be
-either numbers or pointers. Their values are printed as specified by
-@var{string}, exactly as if your program were to execute the C
-subroutine
-@c FIXME: the above implies that at least all ANSI C formats are
-@c supported, but it isn't true: %E and %G don't work (or so it seems).
-@c Either this is a bug, or the manual should document what formats are
-@c supported.
+@item printf @var{template}, @var{expressions}@dots{}
+Print the values of one or more @var{expressions} under the control of
+the string @var{template}. To print several values, make
+@var{expressions} be a comma-separated list of individual expressions,
+which may be either numbers or pointers. Their values are printed as
+specified by @var{template}, exactly as a C program would do by
+executing the code below:
@smallexample
-printf (@var{string}, @var{expressions}@dots{});
+printf (@var{template}, @var{expressions}@dots{});
@end smallexample
+As in @code{C} @code{printf}, ordinary characters in @var{template}
+are printed verbatim, while @dfn{conversion specification} introduced
+by the @samp{%} character cause subsequent @var{expressions} to be
+evaluated, their values converted and formatted according to type and
+style information encoded in the conversion specifications, and then
+printed.
+
For example, you can print two values in hex like this:
@smallexample
printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
@end smallexample
-The only backslash-escape sequences that you can use in the format
-string are the simple ones that consist of backslash followed by a
-letter.
+@code{printf} supports all the standard @code{C} conversion
+specifications, including the flags and modifiers between the @samp{%}
+character and the conversion letter, with the following exceptions:
+
+@itemize @bullet
+@item
+The argument-ordering modifiers, such as @samp{2$}, are not supported.
+
+@item
+The modifier @samp{*} is not supported for specifying precision or
+width.
+
+@item
+The @samp{'} flag (for separation of digits into groups according to
+@code{LC_NUMERIC'}) is not supported.
+
+@item
+The type modifiers @samp{hh}, @samp{j}, @samp{t}, and @samp{z} are not
+supported.
+
+@item
+The conversion letter @samp{n} (as in @samp{%n}) is not supported.
+
+@item
+The conversion letters @samp{a} and @samp{A} are not supported.
+@end itemize
+
+@noindent
+Note that the @samp{ll} type modifier is supported only if the
+underlying @code{C} implementation used to build @value{GDBN} supports
+the @code{long long int} type, and the @samp{L} type modifier is
+supported only if @code{long double} type is available.
+
+As in @code{C}, @code{printf} supports simple backslash-escape
+sequences, such as @code{\n}, @samp{\t}, @samp{\\}, @samp{\"},
+@samp{\a}, and @samp{\f}, that consist of backslash followed by a
+single character. Octal and hexadecimal escape sequences are not
+supported.
@end table
@node Interpreters
(gdb)
@end smallexample
+@subheading The @code{-list-features} Command
+@findex -list-features
+
+Returns a list of particular features of the MI protocol that
+this version of gdb implements. A feature can be a command,
+or a new field in an output of some command, or even an
+important bugfix. While a frontend can sometimes detect presence
+of a feature at runtime, it is easier to perform detection at debugger
+startup.
+
+The command returns a list of strings, with each string naming an
+available feature. Each returned string is just a name, it does not
+have any internal structure. The list of possible feature names
+is given below.
+
+Example output:
+
+@smallexample
+(gdb) -list-features
+^done,result=["feature1","feature2"]
+@end smallexample
+
+The current list of features is:
+
+@itemize @minus
+@item
+@samp{frozen-varobjs}---indicates presence of the
+@code{-var-set-frozen} command, as well as possible presense of the
+@code{frozen} field in the output of @code{-varobj-create}.
+@end itemize
+
@subheading The @code{-interpreter-exec} Command
@findex -interpreter-exec
Print the entire architecture configuration. The optional argument
@var{file} names the file where the output goes.
+@kindex maint print c-tdesc
+@item maint print c-tdesc
+Print the current target description (@pxref{Target Descriptions}) as
+a C source file. The created source file can be used in @value{GDBN}
+when an XML parser is not available to parse the description.
+
@kindex maint print dummy-frames
@item maint print dummy-frames
Prints the contents of @value{GDBN}'s internal dummy-frame stack.
projects / deliverable / binutils-gdb.git / blobdiff