X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=gdb%2Fdoc%2Fgdb.texinfo;h=8002429b599358e113ad6131bf18a16ded616bfa;hb=1cd470df207d45a647e161d8580f15783a74e786;hp=945b68d3dde28746d72a1c86a20445aa6436c65f;hpb=169081d0534030ce80a8be7487d765c830aebcec;p=deliverable%2Fbinutils-gdb.git diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 945b68d3dd..8002429b59 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -990,6 +990,22 @@ also be interleaved with @samp{-command} as required. -x setbreakpoints -ex 'run' a.out @end smallexample +@item -init-command @var{file} +@itemx -ix @var{file} +@cindex @code{--init-command} +@cindex @code{-ix} +Execute commands from file @var{file} before loading gdbinit files or the +inferior. +@xref{Startup}. + +@item -init-eval-command @var{command} +@itemx -iex @var{command} +@cindex @code{--init-eval-command} +@cindex @code{-iex} +Execute a single @value{GDBN} command before loading gdbinit files or the +inferior. +@xref{Startup}. + @item -directory @var{directory} @itemx -d @var{directory} @cindex @code{--directory} @@ -1221,6 +1237,13 @@ memory usage after it completes each command and returns to the prompt. This option causes @value{GDBN} to print its version number and no-warranty blurb, and exit. +@item -use-deprecated-index-sections +@cindex @code{--use-deprecated-index-sections} +This option causes @value{GDBN} to read and use deprecated +@samp{.gdb_index} sections from symbol files. This can speed up +startup, but may result in some functionality being lost. +@xref{Index Section Format}. + @end table @node Startup @@ -1234,6 +1257,13 @@ Here's the description of what @value{GDBN} does during session startup: Sets up the command interpreter as specified by the command line (@pxref{Mode Options, interpreter}). +@item +Executes commands and command files specified by the @samp{-iex} and +@samp{-ix} options in their specified order. Usually you should use the +@samp{-ex} and @samp{-x} options instead, but this way you can apply +settings before @value{GDBN} init files get executed and before inferior +gets loaded. + @item @cindex init file Reads the system-wide @dfn{init file} (if @option{--with-system-gdbinit} was @@ -1268,14 +1298,11 @@ If you wish to disable the auto-loading during startup, you must do something like the following: @smallexample -$ gdb -ex "set auto-load-scripts off" -ex "file myprogram" +$ gdb -iex "set auto-load-scripts off" myprogram @end smallexample -The following does not work because the auto-loading is turned off too late: - -@smallexample -$ gdb -ex "set auto-load-scripts off" myprogram -@end smallexample +Option @samp{-ex} does not work because the auto-loading is then turned +off too late. @item Executes commands and command files specified by the @samp{-ex} and @@ -1700,7 +1727,7 @@ commands, and their documentation, for the regular expression specified in @var{args}. It prints out all matches found. For example: @smallexample -apropos reload +apropos alias @end smallexample @noindent @@ -1708,10 +1735,11 @@ results in: @smallexample @c @group -set symbol-reloading -- Set dynamic symbol table reloading - multiple times in one run -show symbol-reloading -- Show dynamic symbol table reloading - multiple times in one run +alias -- Define a new command that is an alias of an existing command +aliases -- Aliases of other commands +d -- Delete some breakpoints or auto-display expressions +del -- Delete some breakpoints or auto-display expressions +delete -- Delete some breakpoints or auto-display expressions @c @end group @end smallexample @@ -9888,14 +9916,6 @@ There are some ways that @value{GDBN} does not pretend that inlined function calls are the same as normal calls: @itemize @bullet -@item -You cannot set breakpoints on inlined functions. @value{GDBN} -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 @value{GDBN}; until then, -set a breakpoint by line number on the first line of the inlined -function instead. - @item Setting breakpoints at the call site of an inlined function may not work, because the call site does not contain any code. @value{GDBN} @@ -12787,6 +12807,12 @@ Print inheritance relationships as well as other information for type @var{typename}. @xref{Symbols, ,Examining the Symbol Table}. +@item info vtbl @var{expression}. +The @code{info vtbl} command can be used to display the virtual +method tables of the object computed by @var{expression}. This shows +one entry per virtual table; there may be multiple virtual tables when +multiple inheritance is in use. + @cindex C@t{++} symbol display @item set print demangle @itemx show print demangle @@ -14721,33 +14747,6 @@ from the @code{ptype} command can be overwhelming and hard to use. The which match the regular-expression @var{regexp}. @end ignore -@cindex reloading symbols -Some systems allow individual object files that make up your program to -be replaced without stopping and restarting your program. For example, -in VxWorks you can simply recompile a defective object file and keep on -running. If you are running on one of these systems, you can allow -@value{GDBN} to reload the symbols for automatically relinked modules: - -@table @code -@kindex set symbol-reloading -@item set symbol-reloading on -Replace symbol definitions for the corresponding source file when an -object file with a particular name is seen again. - -@item set symbol-reloading off -Do not replace symbol definitions when encountering object files of the -same name more than once. This is the default state; if you are not -running on a system that permits automatic relinking of modules, you -should leave @code{symbol-reloading} off, since otherwise @value{GDBN} -may discard symbols when linking large programs, that may contain -several modules (from different directories or libraries) with the same -name. - -@kindex show symbol-reloading -@item show symbol-reloading -Show the current @code{on} or @code{off} setting. -@end table - @cindex opaque data types @kindex set opaque-type-resolution @item set opaque-type-resolution on @@ -17514,6 +17513,10 @@ are: @tab @code{QPassSignals} @tab @code{handle @var{signal}} +@item @code{program-signals} +@tab @code{QProgramSignals} +@tab @code{handle @var{signal}} + @item @code{hostio-close-packet} @tab @code{vFile:close} @tab @code{remote get}, @code{remote put} @@ -22133,6 +22136,79 @@ bar = foo.dereference () The result @code{bar} will be a @code{gdb.Value} object holding the value pointed to by @code{foo}. + +A similar function @code{Value.referenced_value} exists which also +returns @code{gdb.Value} objects corresonding to the values pointed to +by pointer values (and additionally, values referenced by reference +values). However, the behavior of @code{Value.dereference} +differs from @code{Value.referenced_value} by the fact that the +behavior of @code{Value.dereference} is identical to applying the C +unary operator @code{*} on a given value. For example, consider a +reference to a pointer @code{ptrref}, declared in your C@t{++} program +as + +@smallexample +typedef int *intptr; +... +int val = 10; +intptr ptr = &val; +intptr &ptrref = ptr; +@end smallexample + +Though @code{ptrref} is a reference value, one can apply the method +@code{Value.dereference} to the @code{gdb.Value} object corresponding +to it and obtain a @code{gdb.Value} which is identical to that +corresponding to @code{val}. However, if you apply the method +@code{Value.referenced_value}, the result would be a @code{gdb.Value} +object identical to that corresponding to @code{ptr}. + +@smallexample +py_ptrref = gdb.parse_and_eval ("ptrref") +py_val = py_ptrref.dereference () +py_ptr = py_ptrref.referenced_value () +@end smallexample + +The @code{gdb.Value} object @code{py_val} is identical to that +corresponding to @code{val}, and @code{py_ptr} is identical to that +corresponding to @code{ptr}. In general, @code{Value.dereference} can +be applied whenever the C unary operator @code{*} can be applied +to the corresponding C value. For those cases where applying both +@code{Value.dereference} and @code{Value.referenced_value} is allowed, +the results obtained need not be identical (as we have seen in the above +example). The results are however identical when applied on +@code{gdb.Value} objects corresponding to pointers (@code{gdb.Value} +objects with type code @code{TYPE_CODE_PTR}) in a C/C@t{++} program. +@end defun + +@defun Value.referenced_value () +For pointer or reference data types, this method returns a new +@code{gdb.Value} object corresponding to the value referenced by the +pointer/reference value. For pointer data types, +@code{Value.dereference} and @code{Value.referenced_value} produce +identical results. The difference between these methods is that +@code{Value.dereference} cannot get the values referenced by reference +values. For example, consider a reference to an @code{int}, declared +in your C@t{++} program as + +@smallexample +int val = 10; +int &ref = val; +@end smallexample + +@noindent +then applying @code{Value.dereference} to the @code{gdb.Value} object +corresponding to @code{ref} will result in an error, while applying +@code{Value.referenced_value} will result in a @code{gdb.Value} object +identical to that corresponding to @code{val}. + +@smallexample +py_ref = gdb.parse_and_eval ("ref") +er_ref = py_ref.dereference () # Results in error +py_val = py_ref.referenced_value () # Returns the referenced value +@end smallexample + +The @code{gdb.Value} object @code{py_val} is identical to that +corresponding to @code{val}. @end defun @defun Value.dynamic_cast (type) @@ -24638,13 +24714,9 @@ writable. When a new object file is read (for example, due to the @code{file} command, or because the inferior has loaded a shared library), @value{GDBN} will look for Python support scripts in several ways: -@file{@var{objfile}-gdb.py} and @code{.debug_gdb_scripts} section. - -@menu -* objfile-gdb.py file:: The @file{@var{objfile}-gdb.py} file -* .debug_gdb_scripts section:: The @code{.debug_gdb_scripts} section -* Which flavor to choose?:: -@end menu +@file{@var{objfile}-gdb.py} (@pxref{objfile-gdb.py file}) +and @code{.debug_gdb_scripts} section +(@pxref{dotdebug_gdb_scripts section}). The auto-loading feature is useful for supplying application-specific debugging commands and scripts. @@ -24668,7 +24740,7 @@ Print the list of all scripts that @value{GDBN} auto-loaded. Also printed is the list of scripts that were mentioned in the @code{.debug_gdb_scripts} section and were not found -(@pxref{.debug_gdb_scripts section}). +(@pxref{dotdebug_gdb_scripts section}). This is useful because their names are not printed when @value{GDBN} tries to load them and fails. There may be many of them, and printing an error message for each one is problematic. @@ -24691,6 +24763,12 @@ When reading an auto-loaded file, @value{GDBN} sets the function (@pxref{Objfiles In Python}). This can be useful for registering objfile-specific pretty-printers. +@menu +* objfile-gdb.py file:: The @file{@var{objfile}-gdb.py} file +* dotdebug_gdb_scripts section:: The @code{.debug_gdb_scripts} section +* Which flavor to choose?:: +@end menu + @node objfile-gdb.py file @subsubsection The @file{@var{objfile}-gdb.py} file @cindex @file{@var{objfile}-gdb.py} @@ -24719,7 +24797,7 @@ is the object file's real name, as described above. So your @file{-gdb.py} file should be careful to avoid errors if it is evaluated more than once. -@node .debug_gdb_scripts section +@node dotdebug_gdb_scripts section @subsubsection The @code{.debug_gdb_scripts} section @cindex @code{.debug_gdb_scripts} section @@ -29304,6 +29382,12 @@ This is only present if the varobj is still valid. If the type changed, then this will be the string @samp{true}; otherwise it will be @samp{false}. +When a varobj's type changes, its children are also likely to have +become incorrect. Therefore, the varobj's children are automatically +deleted when this attribute is @samp{true}. Also, the varobj's update +range, when set using the @code{-var-set-update-range} command, is +unset. + @item new_type If the varobj's type changed, then this field will be present and will hold the new type. @@ -33399,7 +33483,7 @@ If @var{regexp} is specified, only print scripts loaded by object files matching @var{regexp}. For each script, this command prints its name as specified in the objfile, and the full path if known. -@xref{.debug_gdb_scripts section}. +@xref{dotdebug_gdb_scripts section}. @kindex maint print statistics @cindex bcache statistics @@ -34974,6 +35058,48 @@ command (@pxref{Remote Configuration, set remote pass-signals}). This packet is not probed by default; the remote stub must request it, by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). +@item QProgramSignals: @var{signal} @r{[};@var{signal}@r{]}@dots{} +@cindex signals the inferior may see, remote request +@cindex @samp{QProgramSignals} packet +@anchor{QProgramSignals} +Each listed @var{signal} may be delivered to the inferior process. +Others should be silently discarded. + +In some cases, the remote stub may need to decide whether to deliver a +signal to the program or not without @value{GDBN} involvement. One +example of that is while detaching --- the program's threads may have +stopped for signals that haven't yet had a chance of being reported to +@value{GDBN}, and so the remote stub can use the signal list specified +by this packet to know whether to deliver or ignore those pending +signals. + +This does not influence whether to deliver a signal as requested by a +resumption packet (@pxref{vCont packet}). + +Signals are numbered identically to continue packets and stop replies +(@pxref{Stop Reply Packets}). Each @var{signal} list item should be +strictly greater than the previous item. Multiple +@samp{QProgramSignals} packets do not combine; any earlier +@samp{QProgramSignals} list is completely replaced by the new list. + +Reply: +@table @samp +@item OK +The request succeeded. + +@item E @var{nn} +An error occurred. @var{nn} are hex digits. + +@item +An empty reply indicates that @samp{QProgramSignals} is not supported +by the stub. +@end table + +Use of this packet is controlled by the @code{set remote program-signals} +command (@pxref{Remote Configuration, set remote program-signals}). +This packet is not probed by default; the remote stub must request it, +by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). + @item qRcmd,@var{command} @cindex execute remote command, remote request @cindex @samp{qRcmd} packet @@ -38930,8 +39056,11 @@ unless otherwise noted: @enumerate @item -The version number, currently 5. Versions 1, 2 and 3 are obsolete. -Version 4 differs by its hashing function. +The version number, currently 6. Versions 1, 2 and 3 are obsolete. +Version 4 uses a different hashing function from versions 5 and 6. +Version 6 includes symbols for inlined functions, whereas versions +4 and 5 do not. @value{GDBN} will only read version 4 and 5 indices +if the @code{--use-deprecated-index-sections} option is used. @item The offset, from the start of the file, of the CU list. @@ -39006,7 +39135,7 @@ index version: @item Version 4 The formula is @code{r = r * 67 + c - 113}. -@item Version 5 +@item Versions 5 and 6 The formula is @code{r = r * 67 + tolower (c) - 113}. @end table