\input texinfo @c -*-texinfo-*-
-@c Copyright (C) 1988-2019 Free Software Foundation, Inc.
+@c Copyright (C) 1988--2020 Free Software Foundation, Inc.
@c
@c %**start of header
@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use
@copying
@c man begin COPYRIGHT
-Copyright @copyright{} 1988-2019 Free Software Foundation, Inc.
+Copyright @copyright{} 1988-2020 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@end ifset
Version @value{GDBVN}.
-Copyright (C) 1988-2019 Free Software Foundation, Inc.
+Copyright (C) 1988-2020 Free Software Foundation, Inc.
This edition of the GDB manual is dedicated to the memory of Fred
Fish. Fred was a long-standing contributor to GDB and to Free
command processes arbitrary expressions in any of the languages
supported by @value{GDBN}. With such commands, because raw input may
start with a leading dash that would be confused with an option or any
-of its abbreviations, e.g.@: @code{print -r} (short for @code{print
--raw} or printing negative @code{r}?), if you specify any command
+of its abbreviations, e.g.@: @code{print -p} (short for @code{print
+-pretty} or printing negative @code{p}?), if you specify any command
option, then you must use a double-dash (@code{--}) delimiter to
indicate the end of options.
@smallexample
(@value{GDBP}) print -@key{TAB}@key{TAB}
--address -max-depth -repeats -vtbl
--array -null-stop -static-members
--array-indexes -object -symbol
--elements -pretty -union
+-address -max-depth -raw-values -union
+-array -null-stop -repeats -vtbl
+-array-indexes -object -static-members
+-elements -pretty -symbol
@end smallexample
Completion will in some cases guide you with a suggestion of what kind
Set pretty formatting of structures. Related setting: @ref{set print
pretty}.
+@item -raw-values [@code{on}|@code{off}]
+Set whether to print values in raw form, bypassing any
+pretty-printers for that value. Related setting: @ref{set print
+raw-values}.
+
@item -repeats @var{number-of-repeats}|@code{unlimited}
Set threshold for repeated print elements. @code{unlimited} causes
all elements to be individually printed. Related setting: @ref{set
command option, then you must use a double dash (@code{--}) to mark
the end of option processing.
-For example, this prints the value of the @code{-r} expression:
+For example, this prints the value of the @code{-p} expression:
@smallexample
-(@value{GDBP}) print -r
+(@value{GDBP}) print -p
@end smallexample
While this repeats the last value in the value history (see below)
-with the @code{-raw} option in effect:
+with the @code{-pretty} option in effect:
@smallexample
-(@value{GDBP}) print -r --
+(@value{GDBP}) print -p --
@end smallexample
Here is an example including both on option and an expression:
@item show print pretty
Show which format @value{GDBN} is using to print structures.
+@anchor{set print raw-values}
+@item set print raw-values on
+Print values in raw form, without applying the pretty
+printers for the value.
+
+@item set print raw-values off
+Print values in pretty-printed form, if there is a pretty-printer
+for the value (@pxref{Pretty Printing}),
+otherwise print the value in raw form.
+
+The default setting is ``off''.
+
+@item show print raw-values
+Show whether to print values in raw form.
+
@item set print sevenbit-strings on
@cindex eight-bit characters in strings
@cindex octal escapes in strings
Note that for @code{bar} the entire printer can be disabled,
as can each individual subprinter.
+Printing values and frame arguments is done by default using
+the enabled pretty printers.
+
+The print option @code{-raw-values} and @value{GDBN} setting
+@code{set print raw-values} (@pxref{set print raw-values}) can be
+used to print values without applying the enabled pretty printers.
+
+Similarly, the backtrace option @code{-raw-frame-arguments} and
+@value{GDBN} setting @code{set print raw-frame-arguments}
+(@pxref{set print raw-frame-arguments}) can be used to ignore the
+enabled pretty printers when printing frame argument values.
+
@node Value History
@section Value History
the command @command{apropos -v REGEXP} uses the highlight style to
mark the documentation parts matching @var{regexp}.
+@item tui-border
+Control the styling of the TUI border. Note that, unlike other
+styling options, only the color of the border can be controlled via
+@code{set style}. This was done for compatibility reasons, as TUI
+controls to set the border's intensity predated the addition of
+general styling to @value{GDBN}. @xref{TUI Configuration}.
+
+@item tui-active-border
+Control the styling of the active TUI border; that is, the TUI window
+that has the focus.
+
@end table
@node Numbers
Define a command named @var{commandname}. If there is already a command
by that name, you are asked to confirm that you want to redefine it.
The argument @var{commandname} may be a bare command name consisting of letters,
-numbers, dashes, and underscores. It may also start with any predefined
-prefix command. For example, @samp{define target my-target} creates
+numbers, dashes, dots, and underscores. It may also start with any
+predefined or user-defined prefix command.
+For example, @samp{define target my-target} creates
a user-defined @samp{target my-target} command.
The definition of the command is made up of other @value{GDBN} command lines,
documentation of a command. Redefining the command with @code{define}
does not change the documentation.
+@kindex define-prefix
+@item define-prefix @var{commandname}
+Define or mark the command @var{commandname} as a user-defined prefix
+command. Once marked, @var{commandname} can be used as prefix command
+by the @code{define} command.
+Note that @code{define-prefix} can be used with a not yet defined
+@var{commandname}. In such a case, @var{commandname} is defined as
+an empty user-defined command.
+In case you redefine a command that was marked as a user-defined
+prefix command, the subcommands of the redefined command are kept
+(and @value{GDBN} indicates so to the user).
+
+Example:
+@example
+(gdb) define-prefix abc
+(gdb) define-prefix abc def
+(gdb) define abc def
+Type commands for definition of "abc def".
+End with a line saying just "end".
+>echo command initial def\n
+>end
+(gdb) define abc def ghi
+Type commands for definition of "abc def ghi".
+End with a line saying just "end".
+>echo command ghi\n
+>end
+(gdb) define abc def
+Keeping subcommands of prefix command "def".
+Redefine command "def"? (y or n) y
+Type commands for definition of "abc def".
+End with a line saying just "end".
+>echo command def\n
+>end
+(gdb) abc def ghi
+command ghi
+(gdb) abc def
+command def
+(gdb)
+@end example
+
@kindex dont-repeat
@cindex don't repeat command
@item dont-repeat
Set the width of tab stops to be @var{nchars} characters. This
setting affects the display of TAB characters in the source and
assembly windows.
+
+@item set tui compact-source @r{[}on@r{|}off@r{]}
+@kindex set tui compact-source
+Set whether the TUI source window is displayed in ``compact'' form.
+The default display uses more space for line numbers and starts the
+source text at the next tab stop; the compact display uses only as
+much space as is needed for the line numbers in the current file, and
+only a single space to separate the line numbers from the source.
@end table
+Note that the colors of the TUI borders can be controlled using the
+appropriate @code{set style} commands. @xref{Output Styling}.
+
@node Emacs
@chapter Using @value{GDBN} under @sc{gnu} Emacs
-symbol-info-functions [--include-nondebug]
[--type @var{type_regexp}]
[--name @var{name_regexp}]
+ [--max-results @var{limit}]
@end smallexample
@noindent
to be filtered based on either the name of the function, or the type
signature of the function.
+The option @code{--max-results} restricts the command to return no
+more than @var{limit} results. If exactly @var{limit} results are
+returned then there might be additional results available if a higher
+limit is used.
+
@subsubheading @value{GDBN} Command
The corresponding @value{GDBN} command is @samp{info functions}.
@end group
@end smallexample
+@subheading The @code{-symbol-info-module-functions} Command
+@findex -symbol-info-module-functions
+@anchor{-symbol-info-module-functions}
+
+@subsubheading Synopsis
+
+@smallexample
+ -symbol-info-module-functions [--module @var{module_regexp}]
+ [--name @var{name_regexp}]
+ [--type @var{type_regexp}]
+@end smallexample
+
+@noindent
+Return a list containing the names of all known functions within all
+know Fortran modules. The functions are grouped by source file and
+containing module, and shown with the line number on which each
+function is defined.
+
+The option @code{--module} only returns results for modules matching
+@var{module_regexp}. The option @code{--name} only returns functions
+whose name matches @var{name_regexp}, and @code{--type} only returns
+functions whose type matches @var{type_regexp}.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{info module functions}.
+
+@subsubheading Example
+
+@smallexample
+@group
+(gdb)
+-symbol-info-module-functions
+^done,symbols=
+ [@{module="mod1",
+ files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
+ symbols=[@{line="21",name="mod1::check_all",type="void (void)",
+ description="void mod1::check_all(void);"@}]@}]@},
+ @{module="mod2",
+ files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
+ symbols=[@{line="30",name="mod2::check_var_i",type="void (void)",
+ description="void mod2::check_var_i(void);"@}]@}]@},
+ @{module="mod3",
+ files=[@{filename="/projec/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
+ fullname="/projec/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
+ symbols=[@{line="21",name="mod3::check_all",type="void (void)",
+ description="void mod3::check_all(void);"@},
+ @{line="27",name="mod3::check_mod2",type="void (void)",
+ description="void mod3::check_mod2(void);"@}]@}]@},
+ @{module="modmany",
+ files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
+ symbols=[@{line="35",name="modmany::check_some",type="void (void)",
+ description="void modmany::check_some(void);"@}]@}]@},
+ @{module="moduse",
+ files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
+ symbols=[@{line="44",name="moduse::check_all",type="void (void)",
+ description="void moduse::check_all(void);"@},
+ @{line="49",name="moduse::check_var_x",type="void (void)",
+ description="void moduse::check_var_x(void);"@}]@}]@}]
+@end group
+@end smallexample
+
+@subheading The @code{-symbol-info-module-variables} Command
+@findex -symbol-info-module-variables
+@anchor{-symbol-info-module-variables}
+
+@subsubheading Synopsis
+
+@smallexample
+ -symbol-info-module-variables [--module @var{module_regexp}]
+ [--name @var{name_regexp}]
+ [--type @var{type_regexp}]
+@end smallexample
+
+@noindent
+Return a list containing the names of all known variables within all
+know Fortran modules. The variables are grouped by source file and
+containing module, and shown with the line number on which each
+variable is defined.
+
+The option @code{--module} only returns results for modules matching
+@var{module_regexp}. The option @code{--name} only returns variables
+whose name matches @var{name_regexp}, and @code{--type} only returns
+variables whose type matches @var{type_regexp}.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{info module variables}.
+
+@subsubheading Example
+
+@smallexample
+@group
+(gdb)
+-symbol-info-module-variables
+^done,symbols=
+ [@{module="mod1",
+ files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
+ symbols=[@{line="18",name="mod1::var_const",type="integer(kind=4)",
+ description="integer(kind=4) mod1::var_const;"@},
+ @{line="17",name="mod1::var_i",type="integer(kind=4)",
+ description="integer(kind=4) mod1::var_i;"@}]@}]@},
+ @{module="mod2",
+ files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
+ symbols=[@{line="28",name="mod2::var_i",type="integer(kind=4)",
+ description="integer(kind=4) mod2::var_i;"@}]@}]@},
+ @{module="mod3",
+ files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
+ symbols=[@{line="18",name="mod3::mod1",type="integer(kind=4)",
+ description="integer(kind=4) mod3::mod1;"@},
+ @{line="17",name="mod3::mod2",type="integer(kind=4)",
+ description="integer(kind=4) mod3::mod2;"@},
+ @{line="19",name="mod3::var_i",type="integer(kind=4)",
+ description="integer(kind=4) mod3::var_i;"@}]@}]@},
+ @{module="modmany",
+ files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
+ symbols=[@{line="33",name="modmany::var_a",type="integer(kind=4)",
+ description="integer(kind=4) modmany::var_a;"@},
+ @{line="33",name="modmany::var_b",type="integer(kind=4)",
+ description="integer(kind=4) modmany::var_b;"@},
+ @{line="33",name="modmany::var_c",type="integer(kind=4)",
+ description="integer(kind=4) modmany::var_c;"@},
+ @{line="33",name="modmany::var_i",type="integer(kind=4)",
+ description="integer(kind=4) modmany::var_i;"@}]@}]@},
+ @{module="moduse",
+ files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
+ symbols=[@{line="42",name="moduse::var_x",type="integer(kind=4)",
+ description="integer(kind=4) moduse::var_x;"@},
+ @{line="42",name="moduse::var_y",type="integer(kind=4)",
+ description="integer(kind=4) moduse::var_y;"@}]@}]@}]
+@end group
+@end smallexample
+
+@subheading The @code{-symbol-info-modules} Command
+@findex -symbol-info-modules
+@anchor{-symbol-info-modules}
+
+@subsubheading Synopsis
+
+@smallexample
+ -symbol-info-modules [--name @var{name_regexp}]
+ [--max-results @var{limit}]
+
+@end smallexample
+
+@noindent
+Return a list containing the names of all known Fortran modules. The
+modules are grouped by source file, and shown with the line number on
+which each modules is defined.
+
+The option @code{--name} allows the modules returned to be filtered
+based the name of the module.
+
+The option @code{--max-results} restricts the command to return no
+more than @var{limit} results. If exactly @var{limit} results are
+returned then there might be additional results available if a higher
+limit is used.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{info modules}.
+
+@subsubheading Example
+@smallexample
+@group
+(gdb)
+-symbol-info-modules
+^done,symbols=
+ @{debug=
+ [@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
+ symbols=[@{line="16",name="mod1"@},
+ @{line="22",name="mod2"@}]@},
+ @{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
+ symbols=[@{line="16",name="mod3"@},
+ @{line="22",name="modmany"@},
+ @{line="26",name="moduse"@}]@}]@}
+@end group
+@group
+(gdb)
+-symbol-info-modules --name mod[123]
+^done,symbols=
+ @{debug=
+ [@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
+ symbols=[@{line="16",name="mod1"@},
+ @{line="22",name="mod2"@}]@},
+ @{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
+ symbols=[@{line="16",name="mod3"@}]@}]@}
+@end group
+@end smallexample
+
@subheading The @code{-symbol-info-types} Command
@findex -symbol-info-types
@anchor{-symbol-info-types}
@smallexample
-symbol-info-types [--name @var{name_regexp}]
+ [--max-results @var{limit}]
+
@end smallexample
@noindent
The option @code{--name} allows the list of types returned to be
filtered by name.
+The option @code{--max-results} restricts the command to return no
+more than @var{limit} results. If exactly @var{limit} results are
+returned then there might be additional results available if a higher
+limit is used.
+
@subsubheading @value{GDBN} Command
The corresponding @value{GDBN} command is @samp{info types}.
-symbol-info-variables [--include-nondebug]
[--type @var{type_regexp}]
[--name @var{name_regexp}]
+ [--max-results @var{limit}]
+
@end smallexample
@noindent
to be filtered based on either the name of the variable, or the type
of the variable.
+The option @code{--max-results} restricts the command to return no
+more than @var{limit} results. If exactly @var{limit} results are
+returned then there might be additional results available if a higher
+limit is used.
+
@subsubheading @value{GDBN} Command
The corresponding @value{GDBN} command is @samp{info variables}.
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
+(@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
projects / deliverable / binutils-gdb.git / blobdiff