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
+software in general. We will miss him.
@end titlepage
@page
Copyright (C) 1988-2006 Free Software Foundation, Inc.
+This edition of the GDB manual is dedicated to the memory of Fred
+Fish. Fred was a long-standing contributor to GDB and to Free
+software in general. We will miss him.
+
@menu
* Summary:: Summary of @value{GDBN}
* Sample Session:: A sample @value{GDBN} session
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
@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
-a subdirectory of that directory named @file{.debug} (that is, the
-file @file{@var{execdir}/.debug/@var{debugfile}}, and
+The executable contains a @dfn{build ID}, a unique signature that is
+also present in the corresponding debug info file. (This is supported
+only on some operating systems, notably on @sc{gnu}/Linux. For more
+details about this feature, see
+@uref{http://fedoraproject.org/wiki/Releases/FeatureBuildId, the
+Fedora Project's description of the buid ID feature}.) 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
+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 signature, and @var{nnnnnnnn}
+are the rest of the signature. (Real signatures are 32 or more
+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 @dfn{debug link} that specifies the
+file @file{ls.debug}, and a @dfn{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
+A build ID is a special section of the executable file named
+@code{.note.gnu.build-id}. This section contains unique
+identification for the built files---it remains the same across
+multiple builds of the same build tree. The default algorithm SHA1
+produces 160 bits (40 hexadecimal characters) of the content. 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}.
+@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) 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
Interactively}, for the detailed description of the History library.
To issue a command to @value{GDBN} without affecting certain aspects of
-the state which is seen by users, prefix it with @samp{server }. This
+the state which is seen by users, prefix it with @samp{server }
+(@pxref{Server Prefix}). This
means that this command will not affect the command history, nor will it
affect @value{GDBN}'s notion of which command to repeat if @key{RET} is
pressed on a line by itself.
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
@item @code{-var-info-type}
@tab show the type of this variable object
@item @code{-var-info-expression}
-@tab print what this variable object represents
+@tab print parent-relative expression that this variable object represents
+@item @code{-var-info-path-expression}
+@tab print full expression that this variable object represents
@item @code{-var-show-attributes}
@tab is this variable editable? does it exist here?
@item @code{-var-evaluate-expression}
-var-info-expression @var{name}
@end smallexample
-Returns what is represented by the variable object @var{name}:
+Returns a string that is suitable for presenting this
+variable object in user interface. The string is generally
+not valid expression in the current language, and cannot be evaluated.
+
+For example, if @code{a} is an array, and variable object
+@code{A} was created for @code{a}, then we'll get this output:
@smallexample
- lang=@var{lang-spec},exp=@var{expression}
+(gdb) -var-info-expression A.1
+^done,lang="C",exp="1"
@end smallexample
@noindent
-where @var{lang-spec} is @code{@{"C" | "C++" | "Java"@}}.
+Here, the values of @code{lang} can be @code{@{"C" | "C++" | "Java"@}}.
+
+Note that the output of the @code{-var-list-children} command also
+includes those expressions, so the @code{-var-info-expression} command
+is of limited use.
+
+@subheading The @code{-var-info-path-expression} Command
+@findex -var-info-path-expression
+
+@subsubheading Synopsis
+
+@smallexample
+ -var-info-path-expression @var{name}
+@end smallexample
+
+Returns an expression that can be evaluated in the current
+context and will yield the same value that a variable object has.
+Compare this with the @code{-var-info-expression} command, which
+result can be used only for UI presentation. Typical use of
+the @code{-var-info-path-expression} command is creating a
+watchpoint from a variable object.
+
+For example, suppose @code{C} is a C@t{++} class, derived from class
+@code{Base}, and that the @code{Base} class has a member called
+@code{m_size}. Assume a variable @code{c} is has the type of
+@code{C} and a variable object @code{C} was created for variable
+@code{c}. Then, we'll get this output:
+@smallexample
+(gdb) -var-info-path-expression C.Base.public.m_size
+^done,path_expr=((Base)c).m_size)
+@end smallexample
@subheading The @code{-var-show-attributes} Command
@findex -var-show-attributes
@menu
* Annotations Overview:: What annotations are; the general syntax.
+* Server Prefix:: Issuing a command without affecting user state.
* Prompting:: Annotations marking @value{GDBN}'s need for input.
* Errors:: Annotations for error messages.
* Invalidation:: Some annotations describe things now invalid.
denotes a @samp{control-z} character) are annotations; the rest is
output from @value{GDBN}.
+@node Server Prefix
+@section The Server Prefix
+@cindex server prefix
+
+If you prefix a command with @samp{server } then it will not affect
+the command history, nor will it affect @value{GDBN}'s notion of which
+command to repeat if @key{RET} is pressed on a line by itself. This
+means that commands can be run behind a user's back by a front-end in
+a transparent manner.
+
+The server prefix does not affect the recording of values into the value
+history; to print a value without recording it into the value history,
+use the @code{output} command instead of the @code{print} command.
+
@node Prompting
@section Annotation for @value{GDBN} Input
Each byte of register data is described by two hex digits. The bytes
with the register are transmitted in target byte order. The size of
each register and their position within the @samp{g} packet are
-determined by the @value{GDBN} internal macros
-@code{DEPRECATED_REGISTER_RAW_SIZE} and @code{REGISTER_NAME} macros. The
+determined by the @value{GDBN} internal gdbarch functions
+@code{DEPRECATED_REGISTER_RAW_SIZE} and @code{gdbarch_register_name}. The
specification of several standard @samp{g} packets is specified below.
@item E @var{NN}
for an error.
@table @samp
-@item F@var{retcode},@var{errno},@var{Ctrl-C flag};@var{call-specific
-attachment}
+@item F@var{retcode},@var{errno},@var{Ctrl-C flag};@var{call-specific attachment}
@var{retcode} is the return code of the system call as hexadecimal value.
OSDN Git Service
