X-Git-Url: http://drtracing.org/?a=blobdiff_plain;ds=sidebyside;f=gdb%2Fdoc%2Fgdb.texinfo;h=50c299e480d0723b81d97cc888500117829576f7;hb=f8eba3c61629b3c03ac1f33853eab4d8507adb9c;hp=0aa90eb49584fa7ef699f130c170617aadbcbab0;hpb=a7fc3f37d47e196365f04fea7e1f17b4d56b83e4;p=deliverable%2Fbinutils-gdb.git diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 0aa90eb495..50c299e480 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -1347,9 +1347,12 @@ just use the @code{shell} command. @table @code @kindex shell +@kindex ! @cindex shell escape -@item shell @var{command string} -Invoke a standard shell to execute @var{command string}. +@item shell @var{command-string} +@itemx !@var{command-string} +Invoke a standard shell to execute @var{command-string}. +Note that no space is needed between @code{!} and @var{command-string}. If it exists, the environment variable @code{SHELL} determines which shell to run. Otherwise @value{GDBN} uses the default shell (@file{/bin/sh} on Unix systems, @file{COMMAND.COM} on MS-DOS, etc.). @@ -1873,14 +1876,18 @@ format; if your @sc{gnu} C compiler has this option, do not use it. @value{GDBN} knows about preprocessor macros and can show you their expansion (@pxref{Macros}). Most compilers do not include information about preprocessor macros in the debugging information if you specify -the @option{-g} flag alone, because this information is rather large. -Version 3.1 and later of @value{NGCC}, the @sc{gnu} C compiler, -provides macro information if you specify the options -@option{-gdwarf-2} and @option{-g3}; the former option requests -debugging information in the Dwarf 2 format, and the latter requests -``extra information''. In the future, we hope to find more compact -ways to represent macro information, so that it can be included with -@option{-g} alone. +the @option{-g} flag alone. Version 3.1 and later of @value{NGCC}, +the @sc{gnu} C compiler, provides macro information if you are using +the DWARF debugging format, and specify the option @option{-g3}. + +@xref{Debugging Options,,Options for Debugging Your Program or GCC, +gcc.info, Using the @sc{gnu} Compiler Collection (GCC)}, for more +information on @value{NGCC} options affecting debug information. + +You will have the best debugging experience if you use the latest +version of the DWARF debugging format that your compiler supports. +DWARF is currently the most expressive and best supported debugging +format in @value{GDBN}. @need 2000 @node Starting @@ -3216,6 +3223,8 @@ running or not, what process it is, and why it stopped. @menu * Breakpoints:: Breakpoints, watchpoints, and catchpoints * Continuing and Stepping:: Resuming execution +* Skipping Over Functions and Files:: + Skipping over functions and files * Signals:: Signals * Thread Stops:: Stopping and starting multi-thread programs @end menu @@ -3512,6 +3521,9 @@ It is possible that a breakpoint corresponds to several locations in your program. Examples of this situation are: @itemize @bullet +@item +Multiple functions in the program may have the same name. + @item For a C@t{++} constructor, the @value{NGCC} compiler generates several instances of the function body, used in different cases. @@ -3526,11 +3538,7 @@ several places where that function is inlined. @end itemize In all those cases, @value{GDBN} will insert a breakpoint at all -the relevant locations@footnote{ -As of this writing, multiple-location breakpoints work only if there's -line number information for all the locations. This means that they -will generally not work in system libraries, unless you have debug -info with line numbers for them.}. +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 @@ -4854,6 +4862,111 @@ proceed until the function returns. An argument is a repeat count, as in @code{next}. @end table +@node Skipping Over Functions and Files +@section Skipping Over Functions and Files +@cindex skipping over functions and files + +The program you are debugging may contain some functions which are +uninteresting to debug. The @code{skip} comand lets you tell @value{GDBN} to +skip a function or all functions in a file when stepping. + +For example, consider the following C function: + +@smallexample +101 int func() +102 @{ +103 foo(boring()); +104 bar(boring()); +105 @} +@end smallexample + +@noindent +Suppose you wish to step into the functions @code{foo} and @code{bar}, but you +are not interested in stepping through @code{boring}. If you run @code{step} +at line 103, you'll enter @code{boring()}, but if you run @code{next}, you'll +step over both @code{foo} and @code{boring}! + +One solution is to @code{step} into @code{boring} and use the @code{finish} +command to immediately exit it. But this can become tedious if @code{boring} +is called from many places. + +A more flexible solution is to execute @kbd{skip boring}. This instructs +@value{GDBN} never to step into @code{boring}. Now when you execute +@code{step} at line 103, you'll step over @code{boring} and directly into +@code{foo}. + +You can also instruct @value{GDBN} to skip all functions in a file, with, for +example, @code{skip file boring.c}. + +@table @code +@kindex skip function +@item skip @r{[}@var{linespec}@r{]} +@itemx skip function @r{[}@var{linespec}@r{]} +After running this command, the function named by @var{linespec} or the +function containing the line named by @var{linespec} will be skipped over when +stepping. @xref{Specify Location}. + +If you do not specify @var{linespec}, the function you're currently debugging +will be skipped. + +(If you have a function called @code{file} that you want to skip, use +@kbd{skip function file}.) + +@kindex skip file +@item skip file @r{[}@var{filename}@r{]} +After running this command, any function whose source lives in @var{filename} +will be skipped over when stepping. + +If you do not specify @var{filename}, functions whose source lives in the file +you're currently debugging will be skipped. +@end table + +Skips can be listed, deleted, disabled, and enabled, much like breakpoints. +These are the commands for managing your list of skips: + +@table @code +@kindex info skip +@item info skip @r{[}@var{range}@r{]} +Print details about the specified skip(s). If @var{range} is not specified, +print a table with details about all functions and files marked for skipping. +@code{info skip} prints the following information about each skip: + +@table @emph +@item Identifier +A number identifying this skip. +@item Type +The type of this skip, either @samp{function} or @samp{file}. +@item Enabled or Disabled +Enabled skips are marked with @samp{y}. Disabled skips are marked with @samp{n}. +@item Address +For function skips, this column indicates the address in memory of the function +being skipped. If you've set a function skip on a function which has not yet +been loaded, this field will contain @samp{}. Once a shared library +which has the function is loaded, @code{info skip} will show the function's +address here. +@item What +For file skips, this field contains the filename being skipped. For functions +skips, this field contains the function name and its line number in the file +where it is defined. +@end table + +@kindex skip delete +@item skip delete @r{[}@var{range}@r{]} +Delete the specified skip(s). If @var{range} is not specified, delete all +skips. + +@kindex skip enable +@item skip enable @r{[}@var{range}@r{]} +Enable the specified skip(s). If @var{range} is not specified, enable all +skips. + +@kindex skip disable +@item skip disable @r{[}@var{range}@r{]} +Disable the specified skip(s). If @var{range} is not specified, disable all +skips. + +@end table + @node Signals @section Signals @cindex signals @@ -7262,15 +7375,9 @@ 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. For example, @value{NGCC}, the @sc{gnu} C/C@t{++} compiler, -usually supports the @option{-gstabs+} option. @option{-gstabs+} -produces debug info in a format that is superior to formats such as -COFF. You may be able to use DWARF 2 (@option{-gdwarf-2}), which is also -an effective form for debug info. @xref{Debugging Options,,Options -for Debugging Your Program or GCC, gcc.info, Using the @sc{gnu} -Compiler Collection (GCC)}. -@xref{C, ,C and C@t{++}}, for more information about debug info formats -that are best suited to C@t{++} programs. +formats. @xref{Compilation}, for more information on choosing compiler +options. @xref{C, ,C and C@t{++}}, for more information about debug +info formats that are best suited to C@t{++} programs. If you ask to print an object whose contents are unknown to @value{GDBN}, e.g., because its data type is not completely specified @@ -8265,7 +8372,10 @@ Display the encoding style currently in use for decoding C@t{++} symbols. @cindex display derived types When displaying a pointer to an object, identify the @emph{actual} (derived) type of the object rather than the @emph{declared} type, using -the virtual function table. +the virtual function table. Note that the virtual function table is +required---this feature can only work for objects that have run-time +type identification; a single virtual method in the object's declared +type is sufficient. @item set print object off Display only the declared type of objects, without reference to the @@ -9903,9 +10013,12 @@ can be any string of tokens. @cindex macro definition, showing @cindex definition of a macro, showing @cindex macros, from debug info -@item info macro @var{macro} -Show the current definition of the named @var{macro}, and describe the -source location or compiler command-line where that definition was established. +@item info macro [-a|-all] [--] @var{macro} +Show the current definition or all definitions of the named @var{macro}, +and describe the source location or compiler command-line where that +definition was established. The optional double dash is to signify the end of +argument processing and the beginning of @var{macro} for non C-like macros where +the macro may begin with a hyphen. @kindex info macros @item info macros @var{linespec} @@ -9913,12 +10026,6 @@ Show all macro definitions that are in effect at the location specified by @var{linespec}, and describe the source location or compiler command-line where those definitions were established. -@kindex info definitions -@item info definitions @var{macro} -Show all definitions of the named @var{macro} that are defined in the current -compilation unit, and describe the source location or compiler command-line -where those definitions were established. - @kindex macro define @cindex user-defined macros @cindex defining macros interactively @@ -9976,9 +10083,12 @@ $ cat sample.h $ @end smallexample -Now, we compile the program using the @sc{gnu} C compiler, @value{NGCC}. -We pass the @option{-gdwarf-2} and @option{-g3} flags to ensure the -compiler includes information about preprocessor macros in the debugging +Now, we compile the program using the @sc{gnu} C compiler, +@value{NGCC}. We pass the @option{-gdwarf-2}@footnote{This is the +minimum. Recent versions of @value{NGCC} support @option{-gdwarf-3} +and @option{-gdwarf-4}; we recommend always choosing the most recent +version of DWARF.} @emph{and} @option{-g3} flags to ensure the compiler +includes information about preprocessor macros in the debugging information. @smallexample @@ -10223,9 +10333,21 @@ an address in the target program. @xref{Specify Location}. The @code{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 @code{tstart} +changing its actions takes effect immediately if the remote stub +supports the @samp{InstallInTrace} feature (@pxref{install tracepoint +in tracing}). +If remote stub doesn't support the @samp{InstallInTrace} feature, all +these changes don't take effect until the next @code{tstart} command, and once a trace experiment is running, further changes will -not have any effect until the next trace experiment starts. +not have any effect until the next trace experiment starts. In addition, +@value{GDBN} supports @dfn{pending tracepoints}---tracepoints whose +address is not yet resolved. (This is similar to pending breakpoints.) +Pending tracepoints are not downloaded to the target and not installed +until they are resolved. The resolution of pending tracepoints requires +@value{GDBN} support---when debugging with the remote target, and +@value{GDBN} disconnects from the remote stub (@pxref{disconnected +tracing}), pending tracepoints can not be resolved (and downloaded to +the remote stub) while @value{GDBN} is disconnected. Here are some examples of using the @code{trace} command: @@ -10266,6 +10388,23 @@ message. @value{GDBN} handles arguments to @code{ftrace} exactly as for @code{trace}. +On 32-bit x86-architecture systems, fast tracepoints normally need to +be placed at an instruction that is 5 bytes or longer, but can be +placed at 4-byte instructions if the low 64K of memory of the target +program is available to install trampolines. Some Unix-type systems, +such as @sc{gnu}/Linux, exclude low addresses from the program's +address space; but for instance with the Linux kernel it is possible +to let @value{GDBN} use this area by doing a @command{sysctl} command +to set the @code{mmap_min_addr} kernel parameter, as in + +@example +sudo sysctl -w vm.mmap_min_addr=32768 +@end example + +@noindent +which sets the low address to 32K, which leaves plenty of room for +trampolines. The minimum address should be set to a page boundary. + @item strace @var{location} [ if @var{cond} ] @cindex set static tracepoint @cindex static tracepoints, setting @@ -10561,7 +10700,7 @@ end @end smallexample @kindex collect @r{(tracepoints)} -@item collect @var{expr1}, @var{expr2}, @dots{} +@item collect@r{[}/@var{mods}@r{]} @var{expr1}, @var{expr2}, @dots{} Collect values of the given expressions when the tracepoint is hit. This command accepts a comma-separated list of any valid expressions. In addition to global, static, or local variables, the following @@ -10607,6 +10746,15 @@ You can give several consecutive @code{collect} commands, each one with a single argument, or one @code{collect} command with several arguments separated by commas; the effect is the same. +The optional @var{mods} changes the usual handling of the arguments. +@code{s} requests that pointers to chars be handled as strings, in +particular collecting the contents of the memory being pointed at, up +to the first zero. The upper bound is by default the value of the +@code{print elements} variable; if @code{s} is followed by a decimal +number, that is the upper bound instead. So for instance +@samp{collect/s25 mystr} collects as many as 25 characters at +@samp{mystr}. + The command @code{info scope} (@pxref{Symbols, info scope}) is particularly useful for figuring out what data to collect. @@ -10753,20 +10901,27 @@ Cnt ID Enb Address What @subsection Starting and Stopping Trace Experiments @table @code -@kindex tstart +@kindex tstart [ @var{notes} ] @cindex start a new trace experiment @cindex collected data discarded @item tstart -This command takes no arguments. It starts the trace experiment, and -begins collecting data. This has the side effect of discarding all -the data collected in the trace buffer during the previous trace -experiment. - -@kindex tstop +This command starts the trace experiment, and begins collecting data. +It has the side effect of discarding all the data collected in the +trace buffer during the previous trace experiment. If any arguments +are supplied, they are taken as a note and stored with the trace +experiment's state. The notes may be arbitrary text, and are +especially useful with disconnected tracing in a multi-user context; +the notes can explain what the trace is doing, supply user contact +information, and so forth. + +@kindex tstop [ @var{notes} ] @cindex stop a running trace experiment @item tstop -This command takes no arguments. It ends the trace experiment, and -stops collecting data. +This command stops the trace experiment. If any arguments are +supplied, they are recorded with the experiment as a note. This is +useful if you are stopping a trace started by someone else, for +instance if the trace is interfering with the system's behavior and +needs to be stopped quickly. @strong{Note}: a trace experiment and data collection may stop automatically if any tracepoint's passcount is reached @@ -10870,6 +11025,33 @@ for instance if you are looking at frames from a trace file. @end table +@table @code +@item set trace-user @var{text} +@kindex set trace-user + +@item show trace-user +@kindex show trace-user + +@item set trace-notes @var{text} +@kindex set trace-notes +Set the trace run's notes. + +@item show trace-notes +@kindex show trace-notes +Show the trace run's notes. + +@item set trace-stop-notes @var{text} +@kindex set trace-stop-notes +Set the trace run's stop notes. The handling of the note is as for +@code{tstop} arguments; the set command is convenient way to fix a +stop note that is mistaken or incomplete. + +@item show trace-stop-notes +@kindex show trace-stop-notes +Show the trace run's stop notes. + +@end table + @node Tracepoint Restrictions @subsection Tracepoint Restrictions @@ -12057,13 +12239,6 @@ effectively, you must compile your C@t{++} programs with a supported C@t{++} compiler, such as @sc{gnu} @code{g++}, or the HP ANSI C@t{++} compiler (@code{aCC}). -For best results when using @sc{gnu} C@t{++}, use the DWARF 2 debugging -format; if it doesn't work on your system, try the stabs+ debugging -format. You can select those formats explicitly with the @code{g++} -command-line options @option{-gdwarf-2} and @option{-gstabs+}. -@xref{Debugging Options,,Options for Debugging Your Program or GCC, -gcc.info, Using the @sc{gnu} Compiler Collection (GCC)}. - @menu * C Operators:: C and C@t{++} operators * C Constants:: C and C@t{++} constants @@ -12273,6 +12448,11 @@ of the character's ordinal value; or of the form @samp{\@var{x}}, where @samp{@var{x}} is a predefined special character---for example, @samp{\n} for newline. +Wide character constants can be written by prefixing a character +constant with @samp{L}, as in C. For example, @samp{L'x'} is the wide +form of @samp{x}. The target wide character set is used when +computing the value of this constant (@pxref{Character Sets}). + @item String constants are a sequence of character constants surrounded by double quotes (@code{"}). Any valid character constant (as described @@ -12280,6 +12460,10 @@ above) may appear. Double quotes within the string must be preceded by a backslash, so for instance @samp{"a\"b'c"} is a string of five characters. +Wide string constants can be written by prefixing a string constant +with @samp{L}, as in C. The target wide character set is used when +computing the value of this constant (@pxref{Character Sets}). + @item Pointer constants are an integral value. You can also write pointers to constants using the C operator @samp{&}. @@ -12302,16 +12486,14 @@ and @samp{@{&"hi", &"there", &"fred"@}} is a three-element array of pointers. @cindex debug formats and C@t{++} @cindex @value{NGCC} and C@t{++} @quotation -@emph{Warning:} @value{GDBN} can only debug C@t{++} code if you use the -proper compiler and the proper debug format. Currently, @value{GDBN} -works best when debugging C@t{++} code that is compiled with -@value{NGCC} 2.95.3 or with @value{NGCC} 3.1 or newer, using the options -@option{-gdwarf-2} or @option{-gstabs+}. DWARF 2 is preferred over -stabs+. Most configurations of @value{NGCC} emit either DWARF 2 or -stabs+ as their default debug format, so you usually don't need to -specify a debug format explicitly. Other compilers and/or debug formats -are likely to work badly or not at all when using @value{GDBN} to debug -C@t{++} code. +@emph{Warning:} @value{GDBN} can only debug C@t{++} code if you use +the proper compiler and the proper debug format. Currently, +@value{GDBN} works best when debugging C@t{++} code that is compiled +with the most recent version of @value{NGCC} possible. The DWARF +debugging format is preferred; @value{NGCC} defaults to this on most +popular platforms. Other compilers and/or debug formats are likely to +work badly or not at all when using @value{GDBN} to debug C@t{++} +code. @xref{Compilation}. @end quotation @enumerate @@ -12330,7 +12512,8 @@ count = aml->GetOriginal(x, y) While a member function is active (in the selected stack frame), your expressions have the same namespace available as the member function; that is, @value{GDBN} allows implicit references to the class instance -pointer @code{this} following the same rules as C@t{++}. +pointer @code{this} following the same rules as C@t{++}. @code{using} +declarations in the current scope are also respected by @value{GDBN}. @cindex call overloaded functions @cindex overloaded functions, calling @@ -12382,12 +12565,11 @@ necessary, for example in an expression like @samp{@var{scope1}::@var{scope2}::@var{name}}. @value{GDBN} also allows resolving name scope by reference to source files, in both C and C@t{++} debugging (@pxref{Variables, ,Program Variables}). -@end enumerate -In addition, when used with HP's C@t{++} compiler, @value{GDBN} supports -calling virtual functions correctly, printing out virtual bases of -objects, calling functions in a base subobject, casting objects, and -invoking user-defined operators. +@item +@value{GDBN} performs argument-dependent lookup, following the C@t{++} +specification. +@end enumerate @node C Defaults @subsubsection C and C@t{++} Defaults @@ -15564,6 +15746,33 @@ This is the default. @end table @end table +@cindex file name canonicalization +@cindex base name differences +When processing file names provided by the user, @value{GDBN} +frequently needs to compare them to the file names recorded in the +program's debug info. Normally, @value{GDBN} compares just the +@dfn{base names} of the files as strings, which is reasonably fast +even for very large programs. (The base name of a file is the last +portion of its name, after stripping all the leading directories.) +This shortcut in comparison is based upon the assumption that files +cannot have more than one base name. This is usually true, but +references to files that use symlinks or similar filesystem +facilities violate that assumption. If your program records files +using such facilities, or if you provide file names to @value{GDBN} +using symlinks etc., you can set @code{basenames-may-differ} to +@code{true} to instruct @value{GDBN} to completely canonicalize each +pair of file names it needs to compare. This will make file-name +comparisons accurate, but at a price of a significant slowdown. + +@table @code +@item set basenames-may-differ +@kindex set basenames-may-differ +Set whether a source file may have multiple base names. + +@item show basenames-may-differ +@kindex show basenames-may-differ +Show whether a source file may have multiple base names. +@end table @node Separate Debug Files @section Debugging Information in Separate Files @@ -17200,6 +17409,10 @@ are: @tab @code{qXfer:traceframe-info:read} @tab Traceframe info +@item @code{install-in-trace} +@tab @code{InstallInTrace} +@tab Install tracepoint in tracing + @item @code{disable-randomization} @tab @code{QDisableRandomization} @tab @code{set disable-randomization} @@ -19724,7 +19937,6 @@ default). @item n64 @item eabi32 @item eabi64 -@item auto @end table @item show mips abi @@ -21681,6 +21893,21 @@ that includes @acronym{RTTI} for the object in question. Otherwise, it will just return the static type of the value as in @kbd{ptype foo} (@pxref{Symbols, ptype}). @end defvar + +@defvar Value.is_lazy +The value of this read-only boolean attribute is @code{True} if this +@code{gdb.Value} has not yet been fetched from the inferior. +@value{GDBN} does not fetch values until necessary, for efficiency. +For example: + +@smallexample +myval = gdb.parse_and_eval ('somevar') +@end smallexample + +The value of @code{somevar} is not fetched at this time. It will be +fetched when the value is needed, or when the @code{fetch_lazy} +method is invoked. +@end defvar @end table The following methods are provided: @@ -21814,6 +22041,19 @@ fetched and encoded to the length of characters specified. If the @var{length} argument is not provided, the string will be fetched and encoded until a null of appropriate width is found. @end defun + +@defun Value.fetch_lazy () +If the @code{gdb.Value} object is currently a lazy value +(@code{gdb.Value.is_lazy} is @code{True}), then the value is +fetched from the inferior. Any errors that occur in the process +will produce a Python exception. + +If the @code{gdb.Value} object is not a lazy value, this method +has no effect. + +This method does not return a value. +@end defun + @end table @node Types In Python @@ -22350,7 +22590,7 @@ this code might appear in @code{gdb.libstdcxx.v6}: @smallexample def register_printers(objfile): - objfile.pretty_printers.add(str_lookup_function) + objfile.pretty_printers.append(str_lookup_function) @end smallexample @noindent @@ -22752,7 +22992,7 @@ You can implement new @value{GDBN} CLI commands in Python. A CLI command is implemented using an instance of the @code{gdb.Command} class, most commonly using a subclass. -@defun Command.__init__ (name, @var{command_class} @r{[}, var{completer_class} @r{[}, var{prefix}@r{]]}) +@defun Command.__init__ (name, @var{command_class} @r{[}, @var{completer_class} @r{[}, @var{prefix}@r{]]}) The object initializer for @code{Command} registers the new command with @value{GDBN}. This initializer is normally invoked from the subclass' own @code{__init__} method. @@ -23445,6 +23685,19 @@ stack corruption. @item gdb.FRAME_UNWIND_NO_SAVED_PC The frame unwinder did not find any saved PC, but we needed one to unwind further. + +@item gdb.FRAME_UNWIND_FIRST_ERROR +Any stop reason greater or equal to this value indicates some kind +of error. This special value facilitates writing code that tests +for errors in unwinding in a way that will work correctly even if +the list of the other values is modified in future @value{GDBN} +versions. Using it, you could write: +@smallexample +reason = gdb.selected_frame().unwind_stop_reason () +reason_str = gdb.frame_stop_reason_string (reason) +if reason >= gdb.FRAME_UNWIND_FIRST_ERROR: + print "An error occured: %s" % reason_str +@end smallexample @end table @end defun @@ -23549,6 +23802,27 @@ attribute is not writable. The block containing this block. If this parent block does not exist, this attribute holds @code{None}. This attribute is not writable. @end defvar + +@defvar Block.global_block +The global block associated with this block. This attribute is not +writable. +@end defvar + +@defvar Block.static_block +The static block associated with this block. This attribute is not +writable. +@end defvar + +@defvar Block.is_global +@code{True} if the @code{gdb.Block} object is a global block, +@code{False} if not. This attribute is not +writable. +@end defvar + +@defvar Block.is_static +@code{True} if the @code{gdb.Block} object is a static block, +@code{False} if not. This attribute is not writable. +@end defvar @end table @node Symbols In Python @@ -24375,6 +24649,35 @@ Return @code{True} if @var{type}, assumed to be a type with fields @item make_enum_dict (@var{enum_type}) Return a Python @code{dictionary} type produced from @var{enum_type}. + +@item deep_items (@var{type}) +Returns a Python iterator similar to the standard +@code{gdb.Type.iteritems} method, except that the iterator returned +by @code{deep_items} will recursively traverse anonymous struct or +union fields. For example: + +@smallexample +struct A +@{ + int a; + union @{ + int b0; + int b1; + @}; +@}; +@end smallexample + +@noindent +Then in @value{GDBN}: +@smallexample +(@value{GDBP}) python import gdb.types +(@value{GDBP}) python struct_a = gdb.lookup_type("struct A") +(@value{GDBP}) python print struct_a.keys () +@{['a', '']@} +(@value{GDBP}) python print [k for k,v in gdb.types.deep_items(struct_a)] +@{['a', 'b0', 'b1']@} +@end smallexample + @end table @node gdb.prompt @@ -25868,6 +26171,25 @@ The inferior exited. The inferior exited normally. @item signal-received A signal was received by the inferior. +@item solib-event +The inferior has stopped due to a library being loaded or unloaded. +This can only happen when @code{stop-on-solib-events} (@pxref{Files}) +is set. +@item fork +The inferior has forked. This is reported when @code{catch fork} +(@pxref{Set Catchpoints}) has been used. +@item vfork +The inferior has vforked. This is reported in when @code{catch vfork} +(@pxref{Set Catchpoints}) has been used. +@item syscall-entry +The inferior entered a system call. This is reported when @code{catch +syscall} (@pxref{Set Catchpoints}) has been used. +@item syscall-entry +The inferior returned from a system call. This is reported when +@code{catch syscall} (@pxref{Set Catchpoints}) has been used. +@item exec +The inferior called @code{exec}. This is reported when @code{catch exec} +(@pxref{Set Catchpoints}) has been used. @end table The @var{id} field identifies the thread that directly caused the stop @@ -31505,6 +31827,7 @@ out about additional code. * Declarations:: Relevant C struct declarations * Registering Code:: Steps to register code * Unregistering Code:: Steps to unregister code +* Custom Debug Info:: Emit debug information in a custom format @end menu @node Declarations @@ -31601,6 +31924,121 @@ Set @code{action_flag} to @code{JIT_UNREGISTER} and call If the JIT frees or recompiles code without unregistering it, then @value{GDBN} and the JIT will leak the memory used for the associated symbol files. +@node Custom Debug Info +@section Custom Debug Info +@cindex custom JIT debug info +@cindex JIT debug info reader + +Generating debug information in platform-native file formats (like ELF +or COFF) may be an overkill for JIT compilers; especially if all the +debug info is used for is displaying a meaningful backtrace. The +issue can be resolved by having the JIT writers decide on a debug info +format and also provide a reader that parses the debug info generated +by the JIT compiler. This section gives a brief overview on writing +such a parser. More specific details can be found in the source file +@file{gdb/jit-reader.in}, which is also installed as a header at +@file{@var{includedir}/gdb/jit-reader.h} for easy inclusion. + +The reader is implemented as a shared object (so this functionality is +not available on platforms which don't allow loading shared objects at +runtime). Two @value{GDBN} commands, @code{jit-reader-load} and +@code{jit-reader-unload} are provided, to be used to load and unload +the readers from a preconfigured directory. Once loaded, the shared +object is used the parse the debug information emitted by the JIT +compiler. + +@menu +* Using JIT Debug Info Readers:: How to use supplied readers correctly +* Writing JIT Debug Info Readers:: Creating a debug-info reader +@end menu + +@node Using JIT Debug Info Readers +@subsection Using JIT Debug Info Readers +@kindex jit-reader-load +@kindex jit-reader-unload + +Readers can be loaded and unloaded using the @code{jit-reader-load} +and @code{jit-reader-unload} commands. + +@table @code +@item jit-reader-load @var{reader-name} +Load the JIT reader named @var{reader-name}. On a UNIX system, this +will usually load @file{@var{libdir}/gdb/@var{reader-name}}, where +@var{libdir} is the system library directory, usually +@file{/usr/local/lib}. Only one reader can be active at a time; +trying to load a second reader when one is already loaded will result +in @value{GDBN} reporting an error. A new JIT reader can be loaded by +first unloading the current one using @code{jit-reader-load} and then +invoking @code{jit-reader-load}. + +@item jit-reader-unload +Unload the currently loaded JIT reader. + +@end table + +@node Writing JIT Debug Info Readers +@subsection Writing JIT Debug Info Readers +@cindex writing JIT debug info readers + +As mentioned, a reader is essentially a shared object conforming to a +certain ABI. This ABI is described in @file{jit-reader.h}. + +@file{jit-reader.h} defines the structures, macros and functions +required to write a reader. It is installed (along with +@value{GDBN}), in @file{@var{includedir}/gdb} where @var{includedir} is +the system include directory. + +Readers need to be released under a GPL compatible license. A reader +can be declared as released under such a license by placing the macro +@code{GDB_DECLARE_GPL_COMPATIBLE_READER} in a source file. + +The entry point for readers is the symbol @code{gdb_init_reader}, +which is expected to be a function with the prototype + +@findex gdb_init_reader +@smallexample +extern struct gdb_reader_funcs *gdb_init_reader (void); +@end smallexample + +@cindex @code{struct gdb_reader_funcs} + +@code{struct gdb_reader_funcs} contains a set of pointers to callback +functions. These functions are executed to read the debug info +generated by the JIT compiler (@code{read}), to unwind stack frames +(@code{unwind}) and to create canonical frame IDs +(@code{get_Frame_id}). It also has a callback that is called when the +reader is being unloaded (@code{destroy}). The struct looks like this + +@smallexample +struct gdb_reader_funcs +@{ + /* Must be set to GDB_READER_INTERFACE_VERSION. */ + int reader_version; + + /* For use by the reader. */ + void *priv_data; + + gdb_read_debug_info *read; + gdb_unwind_frame *unwind; + gdb_get_frame_id *get_frame_id; + gdb_destroy_reader *destroy; +@}; +@end smallexample + +@cindex @code{struct gdb_symbol_callbacks} +@cindex @code{struct gdb_unwind_callbacks} + +The callbacks are provided with another set of callbacks by +@value{GDBN} to do their job. For @code{read}, these callbacks are +passed in a @code{struct gdb_symbol_callbacks} and for @code{unwind} +and @code{get_frame_id}, in a @code{struct gdb_unwind_callbacks}. +@code{struct gdb_symbol_callbacks} has callbacks to create new object +files and new symbol tables inside those object files. @code{struct +gdb_unwind_callbacks} has callbacks to read registers off the current +frame and to write out the values of the registers in the previous +frame. Both have a callback (@code{target_read}) to read bytes off the +target's address space. + @node GDB Bugs @chapter Reporting Bugs in @value{GDBN} @cindex bugs in @value{GDBN} @@ -32009,7 +32447,8 @@ Remote protocol memory maps (@pxref{Memory Map Format}) @item Target descriptions (@pxref{Target Descriptions}) @item -Remote shared library lists (@pxref{Library List Format}) +Remote shared library lists (@xref{Library List Format}, +or alternatively @pxref{Library List Format for SVR4 Targets}) @item MS-Windows shared libraries (@pxref{Shared Libraries}) @item @@ -32784,13 +33223,16 @@ switch (@pxref{Mode Options}). @kindex maint time @cindex time of command execution @item maint time -Control whether to display the execution time for each command. If -set to a nonzero value, @value{GDBN} will display how much time it +Control whether to display the execution time of @value{GDBN} for each command. +If set to a nonzero value, @value{GDBN} will display how much time it took to execute each command, following the command's own output. -The time is not printed for the commands that run the target, since -there's no mechanism currently to compute how much time was spend -by @value{GDBN} and how much time was spend by the program been debugged. -it's not possibly currently +Both CPU time and wallclock time are printed. +Printing both is useful when trying to determine whether the cost is +CPU or, e.g., disk/network, latency. +Note that the CPU time printed is for @value{GDBN} only, it does not include +the execution time of the inferior because there's no mechanism currently +to compute how much time was spent by @value{GDBN} and how much time was +spent by the program been debugged. This can also be requested by invoking @value{GDBN} with the @option{--statistics} command-line switch (@pxref{Mode Options}). @@ -32843,6 +33285,7 @@ Show the current setting of the target wait timeout. * Examples:: * File-I/O Remote Protocol Extension:: * Library List Format:: +* Library List Format for SVR4 Targets:: * Memory Map Format:: * Thread List Format:: * Traceframe Info Format:: @@ -34511,6 +34954,11 @@ These are the currently defined stub features and their properties: @tab @samp{-} @tab No +@item @samp{tracenz} +@tab No +@tab @samp{-} +@tab No + @end multitable These are the currently defined stub features, in more detail: @@ -34539,6 +34987,10 @@ The remote stub understands the @samp{qXfer:features:read} packet The remote stub understands the @samp{qXfer:libraries:read} packet (@pxref{qXfer library list read}). +@item qXfer:libraries-svr4:read +The remote stub understands the @samp{qXfer:libraries-svr4:read} packet +(@pxref{qXfer svr4 library list read}). + @item qXfer:memory-map:read The remote stub understands the @samp{qXfer:memory-map:read} packet (@pxref{qXfer memory map read}). @@ -34630,11 +35082,20 @@ The remote stub understands the @samp{QDisableRandomization} packet. @cindex static tracepoints, in remote protocol The remote stub supports static tracepoints. +@item InstallInTrace +@anchor{install tracepoint in tracing} +The remote stub supports installing tracepoint in tracing. + @item EnableDisableTracepoints The remote stub supports the @samp{QTEnable} (@pxref{QTEnable}) and @samp{QTDisable} (@pxref{QTDisable}) packets that allow tracepoints to be enabled and disabled while a trace experiment is running. +@item tracenz +@cindex string tracing, in remote protocol +The remote stub supports the @samp{tracenz} bytecode for collecting strings. +See @ref{Bytecode Descriptions} for details about the bytecode. + @end table @item qSymbol:: @@ -34683,6 +35144,8 @@ encoded). @value{GDBN} will continue to supply the values of symbols @itemx qTfP @itemx qTfV @itemx QTFrame +@itemx qTMinFTPILen + @xref{Tracepoint Packets}. @item qThreadExtraInfo,@var{thread-id} @@ -34710,6 +35173,8 @@ the command by a @samp{,}, not a @samp{:}, contrary to the naming conventions above. Please don't use this packet as a model for new packets.) +@item QTNotes +@item qTP @item QTSave @item qTsP @item qTsV @@ -34771,6 +35236,18 @@ the operating system manages the list of loaded libraries. This packet is not probed by default; the remote stub must request it, by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). +@item qXfer:libraries-svr4:read:@var{annex}:@var{offset},@var{length} +@anchor{qXfer svr4 library list read} +Access the target's list of loaded libraries when the target is an SVR4 +platform. @xref{Library List Format for SVR4 Targets}. The annex part +of the generic @samp{qXfer} packet must be empty (@pxref{qXfer read}). + +This packet is optional for better performance on SVR4 targets. +@value{GDBN} uses memory read packets to read the SVR4 library list otherwise. + +This packet is not probed by default; the remote stub must request it, +by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). + @item qXfer:memory-map:read::@var{offset},@var{length} @anchor{qXfer memory map read} Access the target's @dfn{memory-map}. @xref{Memory Map Format}. The @@ -35206,6 +35683,30 @@ numbers. Like @samp{QTFrame:range:@var{start}:@var{end}}, but select the first frame @emph{outside} the given range of addresses (exclusive). +@item qTMinFTPILen +This packet requests the minimum length of instruction at which a fast +tracepoint (@pxref{Set Tracepoints}) may be placed. For instance, on +the 32-bit x86 architecture, it is possible to use a 4-byte jump, but +it depends on the target system being able to create trampolines in +the first 64K of memory, which might or might not be possible for that +system. So the reply to this packet will be 4 if it is able to +arrange for that. + +Replies: + +@table @samp +@item 0 +The minimum instruction length is currently unknown. +@item @var{length} +The minimum instruction length is @var{length}, where @var{length} is greater +or equal to 1. @var{length} is a hexadecimal number. A reply of 1 means +that a fast tracepoint may be placed on any instruction regardless of size. +@item E +An error has occurred. +@item +An empty reply indicates that the request is not supported by the stub. +@end table + @item QTStart Begin the tracepoint experiment. Begin collecting data from tracepoint hits in the trace frame buffer. This packet supports the @@ -35268,8 +35769,11 @@ explanations as one of the optional fields: @item tnotrun:0 No trace has been run yet. -@item tstop:0 -The trace was stopped by a user-originated stop command. +@item tstop[:@var{text}]:0 +The trace was stopped by a user-originated stop command. The optional +@var{text} field is a user-supplied string supplied as part of the +stop command (for instance, an explanation of why the trace was +stopped manually). It is hex-encoded. @item tfull:0 The trace stopped because the trace buffer filled up. @@ -35325,6 +35829,22 @@ that the trace run will stop. @end table +@item qTP:@var{tp}:@var{addr} +@cindex tracepoint status, remote request +@cindex @samp{qTP} packet +Ask the stub for the current state of tracepoint number @var{tp} at +address @var{addr}. + +Replies: +@table @samp +@item V@var{hits}:@var{usage} +The tracepoint has been hit @var{hits} times so far during the trace +run, and accounts for @var{usage} in the trace buffer. Note that +@code{while-stepping} steps are not counted as separate hits, but the +steps' space consumption is added into the usage number. + +@end table + @item qTV:@var{var} @cindex trace state variable value, remote request @cindex @samp{qTV} packet @@ -35418,6 +35938,11 @@ available. This packet directs the target to use a circular trace buffer if @var{value} is 1, or a linear buffer if the value is 0. +@item QTNotes:@r{[}@var{type}:@var{text}@r{]}@r{[};@var{type}:@var{text}@r{]}@dots{} +This packet adds optional textual notes to the trace run. Allowable +types include @code{user}, @code{notes}, and @code{tstop}, the +@var{text} fields are arbitrary strings, hex-encoded. + @end table @subsection Relocate instruction reply packet @@ -37034,6 +37559,68 @@ In addition, segments and section descriptors cannot be mixed within a single library element, and you must supply at least one segment or section for each library. +@node Library List Format for SVR4 Targets +@section Library List Format for SVR4 Targets +@cindex library list format, remote protocol + +On SVR4 platforms @value{GDBN} can use the symbol table of a dynamic loader +(e.g.@: @file{ld.so}) and normal memory operations to maintain a list of +shared libraries. Still a special library list provided by this packet is +more efficient for the @value{GDBN} remote protocol. + +The @samp{qXfer:libraries-svr4:read} packet returns an XML document which lists +loaded libraries and their SVR4 linker parameters. For each library on SVR4 +target, the following parameters are reported: + +@itemize @minus +@item +@code{name}, the absolute file name from the @code{l_name} field of +@code{struct link_map}. +@item +@code{lm} with address of @code{struct link_map} used for TLS +(Thread Local Storage) access. +@item +@code{l_addr}, the displacement as read from the field @code{l_addr} of +@code{struct link_map}. For prelinked libraries this is not an absolute +memory address. It is a displacement of absolute memory address against +address the file was prelinked to during the library load. +@item +@code{l_ld}, which is memory address of the @code{PT_DYNAMIC} segment +@end itemize + +Additionally the single @code{main-lm} attribute specifies address of +@code{struct link_map} used for the main executable. This parameter is used +for TLS access and its presence is optional. + +@value{GDBN} must be linked with the Expat library to support XML +SVR4 library lists. @xref{Expat}. + +A simple memory map, with two loaded libraries (which do not use prelink), +looks like this: + +@smallexample + + + + +@end smallexample + +The format of an SVR4 library list is described by this DTD: + +@smallexample + + + + + + + + + +@end smallexample + @node Memory Map Format @section Memory Map Format @cindex memory map format