X-Git-Url: http://drtracing.org/?a=blobdiff_plain;f=gdb%2Fdoc%2Fgdb.texinfo;h=70e4be1524402a02a82cadce92fdae2076fb9bce;hb=165f8965d770708f1dee623e308374ac108e6578;hp=9a0320e5d8f826e3381424808f5c118186440981;hpb=30056ea04ae3ecd828e2a06e12e6f174ae6659c9;p=deliverable%2Fbinutils-gdb.git diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 9a0320e5d8..70e4be1524 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -874,16 +874,17 @@ specified: @value{GDBP} @var{program} @var{core} @end smallexample -You can, instead, specify a process ID as a second argument, if you want -to debug a running process: +You can, instead, specify a process ID as a second argument or use option +@code{-p}, if you want to debug a running process: @smallexample @value{GDBP} @var{program} 1234 +@value{GDBP} -p 1234 @end smallexample @noindent -would attach @value{GDBN} to process @code{1234} (unless you also have a file -named @file{1234}; @value{GDBN} does check for a core file first). +would attach @value{GDBN} to process @code{1234}. With option @option{-p} you +can omit the @var{program} filename. Taking advantage of the second command-line argument requires a fairly complete operating system; when you use @value{GDBN} as a remote @@ -1082,6 +1083,16 @@ Its location is specified with the @code{--with-system-gdbinit} configure option (@pxref{System-wide configuration}). It is loaded first when @value{GDBN} starts, before command line options have been processed. +@item @file{system.gdbinit.d} +This is the system-wide init directory. +Its location is specified with the @code{--with-system-gdbinit-dir} +configure option (@pxref{System-wide configuration}). +Files in this directory are loaded in alphabetical order immediately after +system.gdbinit (if enabled) when @value{GDBN} starts, before command line +options have been processed. Files need to have a recognized scripting +language extension (@file{.py}/@file{.scm}) or be named with a @file{.gdb} +extension to be interpreted as regular @value{GDBN} commands. @value{GDBN} +will not recurse into any subdirectories of this directory. @item @file{~/.gdbinit} This is the init file in your home directory. It is loaded next, after @file{system.gdbinit}, and before @@ -1314,8 +1325,11 @@ Sets up the command interpreter as specified by the command line @cindex init file Reads the system-wide @dfn{init file} (if @option{--with-system-gdbinit} was used when building @value{GDBN}; @pxref{System-wide configuration, - ,System-wide configuration and settings}) and executes all the commands in -that file. + ,System-wide configuration and settings}) and the files in the system-wide +gdbinit directory (if @option{--with-system-gdbinit-dir} was used) and executes +all the commands in those files. The files need to be named with a @file{.gdb} +extension to be interpreted as @value{GDBN} commands, or they can be written +in a supported scripting language with an appropriate file extension. @anchor{Home Directory Init File} @item @@ -1560,6 +1574,7 @@ show you the alternatives available, if there is more than one possibility). @menu * Command Syntax:: How to give commands to @value{GDBN} +* Command Settings:: How to change default behavior of commands * Completion:: Command completion * Command Options:: Command options * Help:: How to ask @value{GDBN} for help @@ -1616,6 +1631,98 @@ commands. This command accepts the current line, like @key{RET}, and then fetches the next line relative to the current line from the history for editing. + +@node Command Settings +@section Command Settings +@cindex default behavior of commands, changing +@cindex default settings, changing + +Many commands change their behavior according to command-specific +variables or settings. These settings can be changed with the +@code{set} subcommands. For example, the @code{print} command +(@pxref{Data, ,Examining Data}) prints arrays differently depending on +settings changeable with the commands @code{set print elements +NUMBER-OF-ELEMENTS} and @code{set print array-indexes}, among others. + +You can change these settings to your preference in the gdbinit files +loaded at @value{GDBN} startup. @xref{Startup}. + +The settings can also be changed interactively during the debugging +session. For example, to change the limit of array elements to print, +you can do the following: +@smallexample +(@value{GDBN}) set print elements 10 +(@value{GDBN}) print some_array +$1 = @{0, 10, 20, 30, 40, 50, 60, 70, 80, 90...@} +@end smallexample + +The above @code{set print elements 10} command changes the number of +elements to print from the default of 200 to 10. If you only intend +this limit of 10 to be used for printing @code{some_array}, then you +must restore the limit back to 200, with @code{set print elements +200}. + +Some commands allow overriding settings with command options. For +example, the @code{print} command supports a number of options that +allow overriding relevant global print settings as set by @code{set +print} subcommands. @xref{print options}. The example above could be +rewritten as: +@smallexample +(@value{GDBN}) print -elements 10 -- some_array +$1 = @{0, 10, 20, 30, 40, 50, 60, 70, 80, 90...@} +@end smallexample + +Alternatively, you can use the @code{with} command to change a setting +temporarily, for the duration of a command invocation. + +@table @code +@kindex with command +@kindex w @r{(@code{with})} +@cindex settings +@cindex temporarily change settings +@item with @var{setting} [@var{value}] [-- @var{command}] +@itemx w @var{setting} [@var{value}] [-- @var{command}] +Temporarily set @var{setting} to @var{value} for the duration of +@var{command}. + +@var{setting} is any setting you can change with the @code{set} +subcommands. @var{value} is the value to assign to @code{setting} +while running @code{command}. + +If no @var{command} is provided, the last command executed is +repeated. + +If a @var{command} is provided, it must be preceded by a double dash +(@code{--}) separator. This is required because some settings accept +free-form arguments, such as expressions or filenames. + +For example, the command +@smallexample +(@value{GDBN}) with print array on -- print some_array +@end smallexample +@noindent +is equivalent to the following 3 commands: +@smallexample +(@value{GDBN}) set print array on +(@value{GDBN}) print some_array +(@value{GDBN}) set print array off +@end smallexample + +The @code{with} command is particularly useful when you want to +override a setting while running user-defined commands, or commands +defined in Python or Guile. @xref{Extending GDB,, Extending GDB}. + +@smallexample +(@value{GDBN}) with print pretty on -- my_complex_command +@end smallexample + +To change several settings for the same command, you can nest +@code{with} commands. For example, @code{with language ada -- with +print elements 10} temporarily changes the language to Ada and sets a +limit of 10 elements to print for arrays and strings. + +@end table + @node Completion @section Command Completion @@ -4694,9 +4801,16 @@ called @code{Constraint_Error} is defined in package @code{Pck}, then the command to use to catch such exceptions is @kbd{catch exception Pck.Constraint_Error}. +@vindex $_ada_exception@r{, convenience variable} +The convenience variable @code{$_ada_exception} holds the address of +the exception being thrown. This can be useful when setting a +condition for such a catchpoint. + @item exception unhandled @kindex catch exception unhandled -An exception that was raised but is not handled by the program. +An exception that was raised but is not handled by the program. The +convenience variable @code{$_ada_exception} is set as for @code{catch +exception}. @item handlers @r{[}@var{name}@r{]} @kindex catch handlers @@ -4718,9 +4832,13 @@ user-defined one. For instance, assuming an exception called command to use to catch such exceptions handling is @kbd{catch handlers Pck.Constraint_Error}. +The convenience variable @code{$_ada_exception} is set as for +@code{catch exception}. + @item assert @kindex catch assert -A failed Ada assertion. +A failed Ada assertion. Note that the convenience variable +@code{$_ada_exception} is @emph{not} set by this catchpoint. @item exec @kindex catch exec @@ -7712,6 +7830,10 @@ Related setting: @ref{set print frame-arguments}. @item -raw-frame-arguments [@code{on}|@code{off}] Set whether to print frame arguments in raw form. Related setting: @ref{set print raw-frame-arguments}. + +@item -frame-info @code{auto}|@code{source-line}|@code{location}|@code{source-and-location}|@code{location-and-address}|@code{short-location} +Set printing of frame information. +Related setting: @ref{set print frame-info}. @end table The optional @var{qualifier} is maintained for backward compatibility. @@ -7776,6 +7898,8 @@ The value of parameter @code{data} in frame 1 has been replaced by only if it is a scalar (integer, pointer, enumeration, etc). See command @kbd{set print frame-arguments} in @ref{Print Settings} for more details on how to configure the way function parameter values are printed. +The command @kbd{set print frame-info} (@pxref{Print Settings}) controls +what frame information is printed. @cindex optimized out, in backtrace @cindex function call arguments, optimized out @@ -8854,11 +8978,21 @@ it tries all the directories in the list, in the order they are present in the list, until it finds a file with the desired name. For example, suppose an executable references the file -@file{/usr/src/foo-1.0/lib/foo.c}, and our source path is -@file{/mnt/cross}. The file is first looked up literally; if this -fails, @file{/mnt/cross/usr/src/foo-1.0/lib/foo.c} is tried; if this -fails, @file{/mnt/cross/foo.c} is opened; if this fails, an error -message is printed. @value{GDBN} does not look up the parts of the +@file{/usr/src/foo-1.0/lib/foo.c}, does not record a compilation +directory, and the @dfn{source path} is @file{/mnt/cross}. +@value{GDBN} would look for the source file in the following +locations: + +@enumerate + +@item @file{/usr/src/foo-1.0/lib/foo.c} +@item @file{/mnt/cross/usr/src/foo-1.0/lib/foo.c} +@item @file{/mnt/cross/foo.c} + +@end enumerate + +If the source file is not present at any of the above locations then +an error is printed. @value{GDBN} does not look up the parts of the source file name, such as @file{/mnt/cross/src/foo-1.0/lib/foo.c}. Likewise, the subdirectories of the source path are not searched: if the source path is @file{/mnt/cross}, and the binary refers to @@ -8866,11 +9000,91 @@ the source path is @file{/mnt/cross}, and the binary refers to @file{/mnt/cross/usr/src/foo-1.0/lib}. Plain file names, relative file names with leading directories, file -names containing dots, etc.@: are all treated as described above; for -instance, if the source path is @file{/mnt/cross}, and the source file -is recorded as @file{../lib/foo.c}, @value{GDBN} would first try -@file{../lib/foo.c}, then @file{/mnt/cross/../lib/foo.c}, and after -that---@file{/mnt/cross/foo.c}. +names containing dots, etc.@: are all treated as described above, +except that non-absolute file names are not looked up literally. If +the @dfn{source path} is @file{/mnt/cross}, the source file is +recorded as @file{../lib/foo.c}, and no compilation directory is +recorded, then @value{GDBN} will search in the following locations: + +@enumerate + +@item @file{/mnt/cross/../lib/foo.c} +@item @file{/mnt/cross/foo.c} + +@end enumerate + +@kindex cdir +@kindex cwd +@vindex $cdir@r{, convenience variable} +@vindex $cwd@r{, convenience variable} +@cindex compilation directory +@cindex current directory +@cindex working directory +@cindex directory, current +@cindex directory, compilation +The @dfn{source path} will always include two special entries +@samp{$cdir} and @samp{$cwd}, these refer to the compilation directory +(if one is recorded) and the current working directory respectively. + +@samp{$cdir} causes @value{GDBN} to search within the compilation +directory, if one is recorded in the debug information. If no +compilation directory is recorded in the debug information then +@samp{$cdir} is ignored. + +@samp{$cwd} is not the same as @samp{.}---the former tracks the +current working directory as it changes during your @value{GDBN} +session, while the latter is immediately expanded to the current +directory at the time you add an entry to the source path. + +If a compilation directory is recorded in the debug information, and +@value{GDBN} has not found the source file after the first search +using @dfn{source path}, then @value{GDBN} will combine the +compilation directory and the filename, and then search for the source +file again using the @dfn{source path}. + +For example, if the executable records the source file as +@file{/usr/src/foo-1.0/lib/foo.c}, the compilation directory is +recorded as @file{/project/build}, and the @dfn{source path} is +@file{/mnt/cross:$cdir:$cwd} while the current working directory of +the @value{GDBN} session is @file{/home/user}, then @value{GDBN} will +search for the source file in the following loctions: + +@enumerate + +@item @file{/usr/src/foo-1.0/lib/foo.c} +@item @file{/mnt/cross/usr/src/foo-1.0/lib/foo.c} +@item @file{/project/build/usr/src/foo-1.0/lib/foo.c} +@item @file{/home/user/usr/src/foo-1.0/lib/foo.c} +@item @file{/mnt/cross/project/build/usr/src/foo-1.0/lib/foo.c} +@item @file{/project/build/project/build/usr/src/foo-1.0/lib/foo.c} +@item @file{/home/user/project/build/usr/src/foo-1.0/lib/foo.c} +@item @file{/mnt/cross/foo.c} +@item @file{/project/build/foo.c} +@item @file{/home/user/foo.c} + +@end enumerate + +If the file name in the previous example had been recorded in the +executable as a relative path rather than an absolute path, then the +first look up would not have occurred, but all of the remaining steps +would be similar. + +When searching for source files on MS-DOS and MS-Windows, where +absolute paths start with a drive letter (e.g. +@file{C:/project/foo.c}), @value{GDBN} will remove the drive letter +from the file name before appending it to a search directory from +@dfn{source path}; for instance if the executable references the +source file @file{C:/project/foo.c} and @dfn{source path} is set to +@file{D:/mnt/cross}, then @value{GDBN} will search in the following +locations for the source file: + +@enumerate + +@item @file{C:/project/foo.c} +@item @file{D:/mnt/cross/project/foo.c} +@item @file{D:/mnt/cross/foo.c} + +@end enumerate Note that the executable search path is @emph{not} used to locate the source files. @@ -8881,8 +9095,8 @@ each line is in the file. @kindex directory @kindex dir -When you start @value{GDBN}, its source path includes only @samp{cdir} -and @samp{cwd}, in that order. +When you start @value{GDBN}, its source path includes only @samp{$cdir} +and @samp{$cwd}, in that order. To add other directories, use the @code{directory} command. The search path is used to find both program source files and @value{GDBN} @@ -8958,21 +9172,12 @@ part of absolute file names) or whitespace. You may specify a directory that is already in the source path; this moves it forward, so @value{GDBN} searches it sooner. -@kindex cdir -@kindex cwd -@vindex $cdir@r{, convenience variable} -@vindex $cwd@r{, convenience variable} -@cindex compilation directory -@cindex current directory -@cindex working directory -@cindex directory, current -@cindex directory, compilation -You can use the string @samp{$cdir} to refer to the compilation -directory (if one is recorded), and @samp{$cwd} to refer to the current -working directory. @samp{$cwd} is not the same as @samp{.}---the former -tracks the current working directory as it changes during your @value{GDBN} -session, while the latter is immediately expanded to the current -directory at the time you add an entry to the source path. +The special strings @samp{$cdir} (to refer to the compilation +directory, if one is recorded), and @samp{$cwd} (to refer to the +current working directory) can also be included in the list of +directories @var{dirname}. Though these will already be in the source +path they will be moved forward in the list so @value{GDBN} searches +them sooner. @item directory Reset the source path to its default value (@samp{$cdir:$cwd} on Unix systems). This requires confirmation. @@ -10722,7 +10927,7 @@ If the number is 0, then the printing is unlimited. @cindex printing frame argument values @cindex print all frame argument values @cindex print frame argument values for scalars only -@cindex do not print frame argument values +@cindex do not print frame arguments This command allows to control how the values of arguments are printed when the debugger prints a frame (@pxref{Frames}). The possible values are: @@ -10750,6 +10955,17 @@ is replaced by @code{@dots{}}. In this case, the example above now becomes: #1 0x08048361 in call_me (i=@dots{}, s=@dots{}, ss=@dots{}, u=@dots{}, e=@dots{}) at frame-args.c:23 @end smallexample + +@item presence +Only the presence of arguments is indicated by @code{@dots{}}. +The @code{@dots{}} are not printed for function without any arguments. +None of the argument names and values are printed. +In this case, the example above now becomes: + +@smallexample +#1 0x08048361 in call_me (@dots{}) at frame-args.c:23 +@end smallexample + @end table By default, only scalar arguments are printed. This command can be used @@ -10760,8 +10976,8 @@ information printed in each frame, making the backtrace more readable. Also, it improves performance when displaying Ada frames, because the computation of large arguments can sometimes be CPU-intensive, especially in large applications. Setting @code{print frame-arguments} -to @code{scalars} (the default) or @code{none} avoids this computation, -thus speeding up the display of each Ada frame. +to @code{scalars} (the default), @code{none} or @code{presence} avoids +this computation, thus speeding up the display of each Ada frame. @item show print frame-arguments Show how the value of arguments should be displayed when printing a frame. @@ -10894,6 +11110,46 @@ entry resolution see @ref{set debug entry-values}. Show the method being used for printing of frame argument values at function entry. +@anchor{set print frame-info} +@item set print frame-info @var{value} +@kindex set print frame-info +@cindex printing frame information +@cindex frame information, printing +This command allows to control the information printed when +the debugger prints a frame. See @ref{Frames}, @ref{Backtrace}, +for a general explanation about frames and frame information. +Note that some other settings (such as @code{set print frame-arguments} +and @code{set print address}) are also influencing if and how some frame +information is displayed. In particular, the frame program counter is never +printed if @code{set print address} is off. + +The possible values for @code{set print frame-info} are: +@table @code +@item short-location +Print the frame level, the program counter (if not at the +beginning of the location source line), the function, the function +arguments. +@item location +Same as @code{short-location} but also print the source file and source line +number. +@item location-and-address +Same as @code{location} but print the program counter even if located at the +beginning of the location source line. +@item source-line +Print the program counter (if not at the beginning of the location +source line), the line number and the source line. +@item source-and-location +Print what @code{location} and @code{source-line} are printing. +@item auto +The information printed for a frame is decided automatically +by the @value{GDBN} command that prints a frame. +For example, @code{frame} prints the information printed by +@code{source-and-location} while @code{stepi} will switch between +@code{source-line} and @code{source-and-location} depending on the program +counter. +The default value is @code{auto}. +@end table + @anchor{set print repeats} @item set print repeats @var{number-of-repeats} @itemx set print repeats unlimited @@ -11591,6 +11847,11 @@ The program has exited The variable @code{$_exception} is set to the exception object being thrown at an exception-related catchpoint. @xref{Set Catchpoints}. +@item $_ada_exception +The variable @code{$_ada_exception} is set to the address of the +exception being caught or thrown at an Ada exception-related +catchpoint. @xref{Set Catchpoints}. + @item $_probe_argc @itemx $_probe_arg0@dots{}$_probe_arg11 Arguments to a static probe. @xref{Static Probe Points}. @@ -11726,9 +11987,98 @@ $3 = void $4 = 1 @end smallexample +@item $_gdb_setting_str (@var{setting}) +@findex $_gdb_setting_str@r{, convenience function} +Return the value of the @value{GDBN} @var{setting} as a string. +@var{setting} is any setting that can be used in a @code{set} or +@code{show} command (@pxref{Controlling GDB}). + +@smallexample +(@value{GDBP}) show print frame-arguments +Printing of non-scalar frame arguments is "scalars". +(@value{GDBP}) p $_gdb_setting_str("print frame-arguments") +$1 = "scalars" +(@value{GDBP}) p $_gdb_setting_str("height") +$2 = "30" +(@value{GDBP}) +@end smallexample + +@item $_gdb_setting (@var{setting}) +@findex $_gdb_setting@r{, convenience function} +Return the value of the @value{GDBN} @var{setting}. +The type of the returned value depends on the setting. + +The value type for boolean and auto boolean settings is @code{int}. +The boolean values @code{off} and @code{on} are converted to +the integer values @code{0} and @code{1}. The value @code{auto} is +converted to the value @code{-1}. + +The value type for integer settings is either @code{unsigned int} +or @code{int}, depending on the setting. + +Some integer settings accept an @code{unlimited} value. +Depending on the setting, the @code{set} command also accepts +the value @code{0} or the value @code{@minus{}1} as a synonym for +@code{unlimited}. +For example, @code{set height unlimited} is equivalent to +@code{set height 0}. + +Some other settings that accept the @code{unlimited} value +use the value @code{0} to literally mean zero. +For example, @code{set history size 0} indicates to not +record any @value{GDBN} commands in the command history. +For such settings, @code{@minus{}1} is the synonym +for @code{unlimited}. + +See the documentation of the corresponding @code{set} command for +the numerical value equivalent to @code{unlimited}. + +The @code{$_gdb_setting} function converts the unlimited value +to a @code{0} or a @code{@minus{}1} value according to what the +@code{set} command uses. + +@smallexample +@group +(@value{GDBP}) p $_gdb_setting_str("height") +$1 = "30" +(@value{GDBP}) p $_gdb_setting("height") +$2 = 30 +(@value{GDBP}) set height unlimited +(@value{GDBP}) p $_gdb_setting_str("height") +$3 = "unlimited" +(@value{GDBP}) p $_gdb_setting("height") +$4 = 0 +@end group +@group +(@value{GDBP}) p $_gdb_setting_str("history size") +$5 = "unlimited" +(@value{GDBP}) p $_gdb_setting("history size") +$6 = -1 +(@value{GDBP}) p $_gdb_setting_str("disassemble-next-line") +$7 = "auto" +(@value{GDBP}) p $_gdb_setting("disassemble-next-line") +$8 = -1 +(@value{GDBP}) +@end group +@end smallexample + +Other setting types (enum, filename, optional filename, string, string noescape) +are returned as string values. + + +@item $_gdb_maint_setting_str (@var{setting}) +@findex $_gdb_maint_setting_str@r{, convenience function} +Like the @code{$_gdb_setting_str} function, but works with +@code{maintenance set} variables. + +@item $_gdb_maint_setting (@var{setting}) +@findex $_gdb_maint_setting@r{, convenience function} +Like the @code{$_gdb_setting} function, but works with +@code{maintenance set} variables. + @end table -These functions require @value{GDBN} to be configured with +The following functions require @value{GDBN} to be configured with @code{Python} support. @table @code @@ -16322,6 +16672,10 @@ The access component operator. Normally used to access elements in derived types. Also suitable for unions. As unions aren't part of regular Fortran, this can only happen when accessing a register that uses a gdbarch-defined union type. +@item :: +The scope operator. Normally used to access variables in modules or +to set breakpoints on subroutines nested in modules or in other +subroutines (internal subroutines). @end table @node Fortran Defaults @@ -17600,10 +17954,10 @@ the following example: * 2 807c468 1 15 Runnable task_1 (@value{GDBP}) info task 2 Ada Task: 0x807c468 -Name: task_1 +Name: "task_1" Thread: 0 LWP: 0x1fac -Parent: 1 (main_task) +Parent: 1 ("main_task") Base Priority: 15 State: Runnable @end smallexample @@ -17611,7 +17965,7 @@ State: Runnable @item task @kindex task@r{ (Ada)} @cindex current Ada task ID -This command prints the ID of the current task. +This command prints the ID and name of the current task. @smallexample @iftex @@ -17620,9 +17974,9 @@ This command prints the ID of the current task. (@value{GDBP}) info tasks ID TID P-ID Pri State Name 1 8077870 0 15 Child Activation Wait main_task -* 2 807c458 1 15 Runnable t +* 2 807c458 1 15 Runnable some_task (@value{GDBP}) task -[Current task is 2] +[Current task is 2 "some_task"] @end smallexample @item task @var{taskno} @@ -17638,9 +17992,9 @@ from the current task to the given task. (@value{GDBP}) info tasks ID TID P-ID Pri State Name 1 8077870 0 15 Child Activation Wait main_task -* 2 807c458 1 15 Runnable t +* 2 807c458 1 15 Runnable some_task (@value{GDBP}) task 1 -[Switching to task 1] +[Switching to task 1 "main_task"] #0 0x8067726 in pthread_cond_wait () (@value{GDBP}) bt #0 0x8067726 in pthread_cond_wait () @@ -18334,8 +18688,7 @@ information. Inspecting the type of a (global) variable for which of such variables. @kindex info types -@item info types @var{regexp} -@itemx info types +@item info types [-q] [@var{regexp}] Print a brief description of all types whose names match the regular expression @var{regexp} (or all types in your program, if you supply no argument). Each complete typename is matched as though it were a @@ -18355,6 +18708,11 @@ This command differs from @code{ptype} in two ways: first, like @code{whatis}, it does not print a detailed description; second, it lists all source files and line numbers where a type is defined. +The output from @samp{into types} is proceeded with a header line +describing what types are being listed. The optional flag @samp{-q}, +which stands for @samp{quiet}, disables printing this header +information. + @kindex info type-printers @item info type-printers Versions of @value{GDBN} that ship with Python scripting enabled may @@ -18428,8 +18786,18 @@ Print the names of all source files in your program for which there is debugging information, organized into two lists: files whose symbols have already been read, and files whose symbols will be read when needed. +@item info sources [-dirname | -basename] [--] [@var{regexp}] +Like @samp{info sources}, but only print the names of the files +matching the provided @var{regexp}. +By default, the @var{regexp} is used to match anywhere in the filename. +If @code{-dirname}, only files having a dirname matching @var{regexp} are shown. +If @code{-basename}, only files having a basename matching @var{regexp} +are shown. +The matching is case-sensitive, except on operating systems that +have case-insensitive filesystem (e.g., MS-Windows). + @kindex info functions -@item info functions [-q] +@item info functions [-q] [-n] Print the names and data types of all defined functions. Similarly to @samp{info types}, this command groups its output by source files and annotates each function definition with its source line @@ -18442,11 +18810,16 @@ to print the function name and type according to the language of the function, other values mean to use the manually specified language (see @ref{Manually, ,Set Language Manually}). +The @samp{-n} flag excludes @dfn{non-debugging symbols} from the +results. A non-debugging symbol is a symbol that comes from the +executable's symbol table, not from the debug information (for +example, DWARF) associated with the executable. + The optional flag @samp{-q}, which stands for @samp{quiet}, disables printing header information and messages explaining why no functions have been printed. -@item info functions [-q] [-t @var{type_regexp}] [@var{regexp}] +@item info functions [-q] [-n] [-t @var{type_regexp}] [@var{regexp}] Like @samp{info functions}, but only print the names and data types of the functions selected with the provided regexp(s). @@ -18476,7 +18849,7 @@ is printed only if its name matches @var{regexp} and its type matches @kindex info variables -@item info variables [-q] +@item info variables [-q] [-n] Print the names and data types of all variables that are defined outside of functions (i.e.@: excluding local variables). The printed variables are grouped by source files and annotated with @@ -18489,11 +18862,13 @@ to print the variable name and type according to the language of the variable, other values mean to use the manually specified language (see @ref{Manually, ,Set Language Manually}). +The @samp{-n} flag excludes non-debugging symbols from the results. + The optional flag @samp{-q}, which stands for @samp{quiet}, disables printing header information and messages explaining why no variables have been printed. -@item info variables [-q] [-t @var{type_regexp}] [@var{regexp}] +@item info variables [-q] [-n] [-t @var{type_regexp}] [@var{regexp}] Like @kbd{info variables}, but only print the variables selected with the provided regexp(s). @@ -18511,6 +18886,35 @@ If both @var{regexp} and @var{type_regexp} are provided, an argument is printed only if its name matches @var{regexp} and its type matches @var{type_regexp}. +@kindex info modules +@cindex modules +@item info modules @r{[}-q@r{]} @r{[}@var{regexp}@r{]} +List all Fortran modules in the program, or all modules matching the +optional regular expression @var{regexp}. + +The optional flag @samp{-q}, which stands for @samp{quiet}, disables +printing header information and messages explaining why no modules +have been printed. + +@kindex info module +@cindex Fortran modules, information about +@cindex functions and variables by Fortran module +@cindex module functions and variables +@item info module functions @r{[}-q@r{]} @r{[}-m @var{module-regexp}@r{]} @r{[}-t @var{type-regexp}@r{]} @r{[}@var{regexp}@r{]} +@itemx info module variables @r{[}-q@r{]} @r{[}-m @var{module-regexp}@r{]} @r{[}-t @var{type-regexp}@r{]} @r{[}@var{regexp}@r{]} +List all functions or variables within all Fortran modules. The set +of functions or variables listed can be limited by providing some or +all of the optional regular expressions. If @var{module-regexp} is +provided, then only Fortran modules matching @var{module-regexp} will +be searched. Only functions or variables whose type matches the +optional regular expression @var{type-regexp} will be listed. And +only functions or variables whose name matches the optional regular +expression @var{regexp} will be listed. + +The optional flag @samp{-q}, which stands for @samp{quiet}, disables +printing header information and messages explaining why no functions +or variables have been printed. + @kindex info classes @cindex Objective-C, classes and selectors @item info classes @@ -20764,8 +21168,8 @@ $ gdb -iex "set use-deprecated-index-sections on" @end smallexample There are currently some limitation on indices. They only work when -for DWARF debugging information, not stabs. And, they do not -currently work for programs using Ada. +using DWARF debugging information, not stabs. And, only the +@code{-dwarf-5} index works for programs using Ada. @subsection Automatic symbol index cache @@ -22310,14 +22714,6 @@ are: @tab @code{qXfer:sdata:read} @tab @code{print $_sdata} -@item @code{read-spu-object} -@tab @code{qXfer:spu:read} -@tab @code{info spu} - -@item @code{write-spu-object} -@tab @code{qXfer:spu:write} -@tab @code{info spu} - @item @code{read-siginfo-object} @tab @code{qXfer:siginfo:read} @tab @code{print $_siginfo} @@ -24185,7 +24581,6 @@ all uses of @value{GDBN} with the architecture, both native and cross. * Alpha:: * MIPS:: * HPPA:: HP PA architecture -* SPU:: Cell Broadband Engine SPU architecture * PowerPC:: * Nios II:: * Sparc64:: @@ -24225,6 +24620,15 @@ but the lengths of the @code{z} and @code{p} registers will not change. This is a known limitation of @value{GDBN} and does not affect the execution of the target process. +@subsubsection AArch64 Pointer Authentication. +@cindex AArch64 Pointer Authentication. + +When @value{GDBN} is debugging the AArch64 architecture, and the program is +using the v8.3-A feature Pointer Authentication (PAC), then whenever the link +register @code{$lr} is pointing to an PAC function its value will be masked. +When GDB prints a backtrace, any addresses that required unmasking will be +postfixed with the marker [PAC]. When using the MI, this is printed as part +of the @code{addr_flags} field. @node i386 @subsection x86 Architecture-specific Issues @@ -24491,69 +24895,6 @@ given @var{address}. @end table -@node SPU -@subsection Cell Broadband Engine SPU architecture -@cindex Cell Broadband Engine -@cindex SPU - -When @value{GDBN} is debugging the Cell Broadband Engine SPU architecture, -it provides the following special commands: - -@table @code -@item info spu event -@kindex info spu -Display SPU event facility status. Shows current event mask -and pending event status. - -@item info spu signal -Display SPU signal notification facility status. Shows pending -signal-control word and signal notification mode of both signal -notification channels. - -@item info spu mailbox -Display SPU mailbox facility status. Shows all pending entries, -in order of processing, in each of the SPU Write Outbound, -SPU Write Outbound Interrupt, and SPU Read Inbound mailboxes. - -@item info spu dma -Display MFC DMA status. Shows all pending commands in the MFC -DMA queue. For each entry, opcode, tag, class IDs, effective -and local store addresses and transfer size are shown. - -@item info spu proxydma -Display MFC Proxy-DMA status. Shows all pending commands in the MFC -Proxy-DMA queue. For each entry, opcode, tag, class IDs, effective -and local store addresses and transfer size are shown. - -@end table - -When @value{GDBN} is debugging a combined PowerPC/SPU application -on the Cell Broadband Engine, it provides in addition the following -special commands: - -@table @code -@item set spu stop-on-load @var{arg} -@kindex set spu -Set whether to stop for new SPE threads. When set to @code{on}, @value{GDBN} -will give control to the user when a new SPE thread enters its @code{main} -function. The default is @code{off}. - -@item show spu stop-on-load -@kindex show spu -Show whether to stop for new SPE threads. - -@item set spu auto-flush-cache @var{arg} -Set whether to automatically flush the software-managed cache. When set to -@code{on}, @value{GDBN} will automatically cause the SPE software-managed -cache to be flushed whenever SPE execution stops. This provides a consistent -view of PowerPC memory that is accessed via the cache. If an application -does not use the software-managed cache, this option has no effect. - -@item show spu auto-flush-cache -Show whether to automatically flush the software-managed cache. - -@end table - @node PowerPC @subsection PowerPC @cindex PowerPC architecture @@ -24794,6 +25135,10 @@ for more details about the Readline interface. Users unfamiliar with @sc{gnu} Emacs or @code{vi} are encouraged to read that chapter. +@cindex Readline application name +@value{GDBN} sets the Readline application name to @samp{gdb}. This +is useful for conditions in @file{.inputrc}. + @node Command History @section Command History @cindex command history @@ -26069,6 +26414,13 @@ Display the current value of the @code{script-extension} option. @end table +@ifset SYSTEM_GDBINIT_DIR +This setting is not used for files in the system-wide gdbinit directory. +Files in that directory must have an extension matching their language, +or have a @file{.gdb} extension to be interpreted as regular @value{GDBN} +commands. @xref{Startup}. +@end ifset + @node Sequences @section Canned Sequences of Commands @@ -27396,6 +27748,10 @@ with the TUI SingleKey mode. Once the command is entered the TUI SingleKey mode is restored. The only way to permanently leave this mode is by typing @kbd{q} or @kbd{C-x s}. +@cindex SingleKey keymap name +If @value{GDBN} was built with Readline 8.0 or later, the TUI +SingleKey keymap will be named @samp{SingleKey}. This can be used in +@file{.inputrc} to add additional bindings to this keymap. @node TUI Commands @section TUI-specific Commands @@ -27416,7 +27772,7 @@ possible or desirable to enable curses window management. @item tui enable @kindex tui enable Activate TUI mode. The last active TUI window layout will be used if -TUI mode has prevsiouly been used in the current debugging session, +TUI mode has previously been used in the current debugging session, otherwise a default layout is used. @item tui disable @@ -28752,6 +29108,11 @@ breakpoint; or the string @samp{}, for a breakpoint with multiple locations. This field will not be present if no address can be determined. For example, a watchpoint does not have an address. +@item addr_flags +Optional field containing any flags related to the address. These flags are +architecture-dependent; see @ref{Architectures} for their meaning for a +particular CPU. + @item func If known, the function in which the breakpoint appears. If not known, this field is not present. @@ -28852,6 +29213,11 @@ Note that this is not the same as the field @code{enable}. @item addr The address of this location as an hexidecimal number. +@item addr_flags +Optional field containing any flags related to the address. These flags are +architecture-dependent; see @ref{Architectures} for their meaning for a +particular CPU. + @item func If known, the function in which the location appears. If not known, this field is not present. @@ -28904,6 +29270,11 @@ be absent if @value{GDBN} is unable to determine the function name. @item addr The code address for the frame. This field is always present. +@item addr_flags +Optional field containing any flags related to the address. These flags are +architecture-dependent; see @ref{Architectures} for their meaning for a +particular CPU. + @item file The name of the source files that correspond to the frame's code address. This field may be absent. @@ -30026,9 +30397,9 @@ and @samp{tcatch throw} (@pxref{Set Catchpoints}). @smallexample -catch-throw -r exception_type -^done,bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", - addr="0x00000000004006c0",what="exception throw", - catch-type="throw",thread-groups=["i1"], +^done,bkpt=@{number="1",type="catchpoint",disp="keep",enabled="y", + what="exception throw",catch-type="throw", + thread-groups=["i1"], regexp="exception_type",times="0"@} (gdb) -exec-run @@ -30070,9 +30441,9 @@ and @samp{tcatch rethrow} (@pxref{Set Catchpoints}). @smallexample -catch-rethrow -r exception_type -^done,bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", - addr="0x00000000004006c0",what="exception rethrow", - catch-type="rethrow",thread-groups=["i1"], +^done,bkpt=@{number="1",type="catchpoint",disp="keep",enabled="y", + what="exception rethrow",catch-type="rethrow", + thread-groups=["i1"], regexp="exception_type",times="0"@} (gdb) -exec-run @@ -30114,9 +30485,9 @@ and @samp{tcatch catch} (@pxref{Set Catchpoints}). @smallexample -catch-catch -r exception_type -^done,bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", - addr="0x00000000004006c0",what="exception catch", - catch-type="catch",thread-groups=["i1"], +^done,bkpt=@{number="1",type="catchpoint",disp="keep",enabled="y", + what="exception catch",catch-type="catch", + thread-groups=["i1"], regexp="exception_type",times="0"@} (gdb) -exec-run @@ -36732,7 +37103,8 @@ details. @item --with-system-readline Use the readline library installed on the host, rather than the -library supplied as part of @value{GDBN}. +library supplied as part of @value{GDBN}. Readline 7 or newer is +required; this is enforced by the build system. @item --with-system-zlib Use the zlib library installed on the host, rather than the library @@ -36820,6 +37192,14 @@ directory under the configured prefix, and @value{GDBN} is moved to another location after being built, the location of the system-wide init file will be adjusted accordingly. +@item --with-system-gdbinit-dir=@var{directory} +Configure @value{GDBN} to automatically load init files from a +system-wide directory. @var{directory} should be an absolute directory +name. If @var{directory} is in a directory under the configured +prefix, and @value{GDBN} is moved to another location after being +built, the location of the system-wide init directory will be +adjusted accordingly. + @item --enable-build-warnings When building the @value{GDBN} sources, ask the compiler to warn about any code which looks even vaguely suspicious. It passes many @@ -36845,24 +37225,28 @@ was first introduced in GCC 4.9. @section System-wide configuration and settings @cindex system-wide init file -@value{GDBN} can be configured to have a system-wide init file; -this file will be read and executed at startup (@pxref{Startup, , What -@value{GDBN} does during startup}). +@value{GDBN} can be configured to have a system-wide init file and a +system-wide init file directory; this file and files in that directory +(if they have a recognized file extension) will be read and executed at +startup (@pxref{Startup, , What @value{GDBN} does during startup}). -Here is the corresponding configure option: +Here are the corresponding configure options: @table @code @item --with-system-gdbinit=@var{file} Specify that the default location of the system-wide init file is @var{file}. +@item --with-system-gdbinit-dir=@var{directory} +Specify that the default location of the system-wide init file directory +is @var{directory}. @end table If @value{GDBN} has been configured with the option @option{--prefix=$prefix}, -it may be subject to relocation. Two possible cases: +they may be subject to relocation. Two possible cases: @itemize @bullet @item -If the default location of this init file contains @file{$prefix}, +If the default location of this init file/directory contains @file{$prefix}, it will be subject to relocation. Suppose that the configure options are @option{--prefix=$prefix --with-system-gdbinit=$prefix/etc/gdbinit}; if @value{GDBN} is moved from @file{$prefix} to @file{$install}, the system @@ -36888,6 +37272,14 @@ initialization. If the data-directory is changed after @value{GDBN} has started with the @code{set data-directory} command, the file will not be reread. +This applies similarly to the system-wide directory specified in +@option{--with-system-gdbinit-dir}. + +Any supported scripting language can be used for these init files, as long +as the file extension matches the scripting language. To be interpreted +as regular @value{GDBN} commands, the files needs to have a @file{.gdb} +extension. + @menu * System-wide Configuration Scripts:: Installed System-wide Configuration Scripts @end menu @@ -37626,12 +38018,20 @@ Shows the result of completing the @code{maint test-options} subcommands. This is used by the testsuite to validate completion support in the command options framework. -@kindex maint test-settings -@item maint test-settings set @var{kind} -@itemx maint test-settings show @var{kind} +@kindex maint set test-settings +@kindex maint show test-settings +@item maint set test-settings @var{kind} +@itemx maint show test-settings @var{kind} These are representative commands for each @var{kind} of setting type @value{GDBN} supports. They are used by the testsuite for exercising the settings infrastructure. + +@kindex maint with +@item maint with @var{setting} [@var{value}] [-- @var{command}] +Like the @code{with} command, but works with @code{maintenance set} +variables. This is used by the testsuite to exercise the @code{with} +command's infrastructure. + @end table The following command is useful for non-interactive invocations of @@ -39816,16 +40216,6 @@ These are the currently defined stub features and their properties: @tab @samp{-} @tab Yes -@item @samp{qXfer:spu:read} -@tab No -@tab @samp{-} -@tab Yes - -@item @samp{qXfer:spu:write} -@tab No -@tab @samp{-} -@tab Yes - @item @samp{qXfer:siginfo:read} @tab No @tab @samp{-} @@ -40058,14 +40448,6 @@ The remote stub understands the @samp{qXfer:memory-map:read} packet The remote stub understands the @samp{qXfer:sdata:read} packet (@pxref{qXfer sdata read}). -@item qXfer:spu:read -The remote stub understands the @samp{qXfer:spu:read} packet -(@pxref{qXfer spu read}). - -@item qXfer:spu:write -The remote stub understands the @samp{qXfer:spu:write} packet -(@pxref{qXfer spu write}). - @item qXfer:siginfo:read The remote stub understands the @samp{qXfer:siginfo:read} packet (@pxref{qXfer siginfo read}). @@ -40511,18 +40893,6 @@ This packet is not probed by default; the remote stub must request it, by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). -@item qXfer:spu:read:@var{annex}:@var{offset},@var{length} -@anchor{qXfer spu read} -Read contents of an @code{spufs} file on the target system. The -annex specifies which file to read; it must be of the form -@file{@var{id}/@var{name}}, where @var{id} specifies an SPU context ID -in the target process, and @var{name} identifes the @code{spufs} file -in that context to be accessed. - -This packet is not probed by default; the remote stub must request it, -by supplying an appropriate @samp{qSupported} response -(@pxref{qSupported}). - @item qXfer:threads:read::@var{offset},@var{length} @anchor{qXfer threads read} Access the list of threads on target. @xref{Thread List Format}. The @@ -40608,17 +40978,6 @@ empty (@pxref{qXfer write}). This packet is not probed by default; the remote stub must request it, by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). - -@item qXfer:spu:write:@var{annex}:@var{offset}:@var{data}@dots{} -@anchor{qXfer spu write} -Write @var{data} to an @code{spufs} file on the target system. The -annex specifies which file to write; it must be of the form -@file{@var{id}/@var{name}}, where @var{id} specifies an SPU context ID -in the target process, and @var{name} identifes the @code{spufs} file -in that context to be accessed. - -This packet is not probed by default; the remote stub must request it, -by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). @end table @item qXfer:@var{object}:@var{operation}:@dots{} @@ -43886,6 +44245,7 @@ registers using the capitalization used in the description. * OpenRISC 1000 Features:: * PowerPC Features:: * RISC-V Features:: +* RX Features:: * S/390 and System z Features:: * Sparc Features:: * TIC6x Features:: @@ -44316,6 +44676,15 @@ target has floating point hardware, but can be moved into the csr feature if the target has the floating point control registers, but no other floating point hardware. +@node RX Features +@subsection RX Features +@cindex target descriptions, RX Features + +The @samp{org.gnu.gdb.rx.core} feature is required for RX +targets. It should contain the registers @samp{r0} through +@samp{r15}, @samp{usp}, @samp{isp}, @samp{psw}, @samp{pc}, @samp{intb}, +@samp{bpsw}, @samp{bpc}, @samp{fintv}, @samp{fpsw}, and @samp{acc}. + @node S/390 and System z Features @subsection S/390 and System z Features @cindex target descriptions, S/390 features @@ -44863,8 +45232,8 @@ You can also start with both an executable program and a core file specified: gdb program core @end smallexample -You can, instead, specify a process ID as a second argument, if you want -to debug a running process: +You can, instead, specify a process ID as a second argument or use option +@code{-p}, if you want to debug a running process: @smallexample gdb program 1234 @@ -44872,9 +45241,8 @@ gdb -p 1234 @end smallexample @noindent -would attach @value{GDBN} to process @code{1234} (unless you also have a file -named @file{1234}; @value{GDBN} does check for a core file first). -With option @option{-p} you can omit the @var{program} filename. +would attach @value{GDBN} to process @code{1234}. With option @option{-p} you +can omit the @var{program} filename. Here are some of the most frequently needed @value{GDBN} commands: @@ -45401,6 +45769,10 @@ Richard M. Stallman and Roland H. Pesch, July 1991. @value{SYSTEM_GDBINIT} @end ifset +@ifset SYSTEM_GDBINIT_DIR +@value{SYSTEM_GDBINIT_DIR}/* +@end ifset + ~/.gdbinit ./.gdbinit @@ -45442,6 +45814,20 @@ See more in the @value{GDBN} manual in node @code{System-wide configuration} -- shell command @code{info -f gdb -n 'System-wide configuration'}. @end ifset +@ifset SYSTEM_GDBINIT_DIR +@item @value{SYSTEM_GDBINIT_DIR} +@end ifset +@ifclear SYSTEM_GDBINIT_DIR +@item (not enabled with @code{--with-system-gdbinit-dir} during compilation) +@end ifclear +System-wide initialization directory. All files in this directory are +executed on startup unless user specified @value{GDBN} option @code{-nx} or +@code{-n}, as long as they have a recognized file extension. +See more in +@ifset man +the @value{GDBN} manual in node @code{System-wide configuration} +-- shell command @code{info -f gdb -n 'System-wide configuration'}. +@end ifset @ifclear man @ref{System-wide configuration}. @end ifclear