@itemx -n
@cindex @code{--nx}
@cindex @code{-n}
-Do not execute commands found in any initialization files. Normally,
-@value{GDBN} executes the commands in these files after all the command
-options and arguments have been processed. @xref{Command Files,,Command
-Files}.
+Do not execute commands found in any initialization file.
+There are three init files, loaded in the following order:
+
+@table @code
+@item @file{system.gdbinit}
+This is the system-wide init file.
+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{~/.gdbinit}
+This is the init file in your home directory.
+It is loaded next, after @file{system.gdbinit}, and before
+command options have been processed.
+@item @file{./.gdbinit}
+This is the init file in the current directory.
+It is loaded last, after command line options other than @code{-x} and
+@code{-ex} have been processed. Command line options @code{-x} and
+@code{-ex} are processed last, after @file{./.gdbinit} has been loaded.
+@end table
+
+For further documentation on startup processing, @xref{Startup}.
+For documentation on how to write command files,
+@xref{Command Files,,Command Files}.
+
+@anchor{-nh}
+@item -nh
+@cindex @code{--nh}
+Do not execute commands found in @file{~/.gdbinit}, the init file
+in your home directory.
+@xref{Startup}.
@item -quiet
@itemx -silent
The @value{GDBN} init files are normally called @file{.gdbinit}.
The DJGPP port of @value{GDBN} uses the name @file{gdb.ini}, due to
the limitations of file names imposed by DOS filesystems. The Windows
-ports of @value{GDBN} use the standard name, but if they find a
-@file{gdb.ini} file, they warn you about that and suggest to rename
-the file to the standard name.
+port of @value{GDBN} uses the standard name, but if it finds a
+@file{gdb.ini} file in your home directory, it warns you about that
+and suggests to rename the file to the standard name.
@node Quitting GDB
@table @code
@kindex cd
@cindex change working directory
-@item cd @var{directory}
-Set the @value{GDBN} working directory to @var{directory}.
+@item cd @r{[}@var{directory}@r{]}
+Set the @value{GDBN} working directory to @var{directory}. If not
+given, @var{directory} uses @file{'~'}.
@kindex pwd
@item pwd
@item set listsize @var{count}
Make the @code{list} command display @var{count} source lines (unless
the @code{list} argument explicitly specifies some other number).
+Setting @var{count} to -1 means there's no limit and 0 means suppress
+display of source lines.
@kindex show listsize
@item show listsize
@table @code
@kindex search
@kindex forward-search
+@kindex fo @r{(@code{forward-search})}
@item forward-search @var{regexp}
@itemx search @var{regexp}
The command @samp{forward-search @var{regexp}} checks each line,
* Pretty Printing:: Python pretty printing
* Value History:: Value history
* Convenience Vars:: Convenience variables
+* Convenience Funs:: Convenience functions
* Registers:: Registers
* Floating Point Hardware:: Floating point hardware
* Vector Unit:: Vector Unit
@table @code
@item auto
Allow @value{GDBN} to choose a decoding style by inspecting your program.
+This is the default.
@item gnu
Decode based on the @sc{gnu} C@t{++} compiler (@code{g++}) encoding algorithm.
-This is the default.
@item hp
Decode based on the HP ANSI C@t{++} (@code{aCC}) encoding algorithm.
@table @code
@kindex show convenience
-@cindex show all user variables
+@cindex show all user variables and functions
@item show convenience
-Print a list of convenience variables used so far, and their values.
+Print a list of convenience variables used so far, and their values,
+as well as a list of the convenience functions.
Abbreviated @code{show conv}.
@kindex init-if-undefined
begins with a dollar sign, @value{GDBN} searches for a user or system
name first, before it searches for a convenience variable.
+@node Convenience Funs
+@section Convenience Functions
+
@cindex convenience functions
@value{GDBN} also supplies some @dfn{convenience functions}. These
have a syntax similar to convenience variables. A convenience
however, a convenience function is implemented internally to
@value{GDBN}.
+These functions require @value{GDBN} to be configured with
+@code{Python} support.
+
+@table @code
+
+@item $_memeq(@var{buf1}, @var{buf2}, @var{length})
+@findex $_memeq@r{, convenience function}
+Returns one if the @var{length} bytes at the addresses given by
+@var{buf1} and @var{buf2} are equal.
+Otherwise it returns zero.
+
+@item $_regex(@var{str}, @var{regex})
+@findex $_regex@r{, convenience function}
+Returns one if the string @var{str} matches the regular expression
+@var{regex}. Otherwise it returns zero.
+The syntax of the regular expression is that specified by @code{Python}'s
+regular expression support.
+
+@item $_streq(@var{str1}, @var{str2})
+@findex $_streq@r{, convenience function}
+Returns one if the strings @var{str1} and @var{str2} are equal.
+Otherwise it returns zero.
+
+@item $_strlen(@var{str})
+@findex $_strlen@r{, convenience function}
+Returns the length of string @var{str}.
+
+@end table
+
+@value{GDBN} provides the ability to list and get help on
+convenience functions.
+
@table @code
@item help function
@kindex help function
@value{GDBN} provides interfaces to useful OS facilities that can help
you debug your program.
-@cindex @code{ptrace} system call
-@cindex @code{struct user} contents
-When @value{GDBN} runs on a @dfn{Posix system} (such as GNU or Unix
-machines), it interfaces with the inferior via the @code{ptrace}
-system call. The operating system creates a special sata structure,
-called @code{struct user}, for this interface. You can use the
-command @code{info udot} to display the contents of this data
-structure.
-
-@table @code
-@item info udot
-@kindex info udot
-Display the contents of the @code{struct user} maintained by the OS
-kernel for the program being debugged. @value{GDBN} displays the
-contents of @code{struct user} as a list of hex numbers, similar to
-the @code{examine} command.
-@end table
-
@cindex auxiliary vector
@cindex vector, auxiliary
Some operating systems supply an @dfn{auxiliary vector} to programs at
@node Checks
@section Type and Range Checking
-@quotation
-@emph{Warning:} In this release, the @value{GDBN} commands for type and range
-checking are included, but they do not yet have any effect. This
-section documents the intended facilities.
-@end quotation
-@c FIXME remove warning when type/range code added
-
Some languages are designed to guard you against making seemingly common
errors through a series of compile- and run-time checks. These include
-checking the type of arguments to functions and operators, and making
+checking the type of arguments to functions and operators and making
sure mathematical overflows are caught at run time. Checks such as
these help to ensure a program's correctness once it has been compiled
-by eliminating type mismatches, and providing active checks for range
+by eliminating type mismatches and providing active checks for range
errors when your program is running.
-@value{GDBN} can check for conditions like the above if you wish.
-Although @value{GDBN} does not check the statements in your program,
-it can check expressions entered directly into @value{GDBN} for
-evaluation via the @code{print} command, for example. As with the
-working language, @value{GDBN} can also decide whether or not to check
-automatically based on your program's source language.
-@xref{Supported Languages, ,Supported Languages}, for the default
-settings of supported languages.
+By default @value{GDBN} checks for these errors according to the
+rules of the current source language. Although @value{GDBN} does not check
+the statements in your program, it can check expressions entered directly
+into @value{GDBN} for evaluation via the @code{print} command, for example.
@menu
* Type Checking:: An overview of type checking
@node Type Checking
@subsection An Overview of Type Checking
-Some languages, such as Modula-2, are strongly typed, meaning that the
+Some languages, such as C and C@t{++}, are strongly typed, meaning that the
arguments to operators and functions have to be of the correct type,
otherwise an error occurs. These checks prevent type mismatch
errors from ever causing any run-time problems. For example,
@smallexample
-1 + 2 @result{} 3
+int klass::my_method(char *b) @{ return b ? 1 : 2; @}
+
+(@value{GDBP}) print obj.my_method (0)
+$1 = 2
@exdent but
-@error{} 1 + 2.3
+(@value{GDBP}) print obj.my_method (0x1234)
+Cannot resolve method klass::my_method to any overloaded instance
@end smallexample
-The second example fails because the @code{CARDINAL} 1 is not
-type-compatible with the @code{REAL} 2.3.
+The second example fails because in C@t{++} the integer constant
+@samp{0x1234} is not type-compatible with the pointer parameter type.
-For the expressions you use in @value{GDBN} commands, you can tell the
-@value{GDBN} type checker to skip checking;
+For the expressions you use in @value{GDBN} commands, you can tell
+@value{GDBN} to not enforce strict type checking or
to treat any mismatches as errors and abandon the expression;
-or to only issue warnings when type mismatches occur,
-but evaluate the expression anyway. When you choose the last of
-these, @value{GDBN} evaluates expressions like the second example above, but
-also issues a warning.
+When type checking is disabled, @value{GDBN} successfully evaluates
+expressions like the second example above.
-Even if you turn type checking off, there may be other reasons
+Even if type checking is off, there may be other reasons
related to type that prevent @value{GDBN} from evaluating an expression.
For instance, @value{GDBN} does not know how to add an @code{int} and
a @code{struct foo}. These particular type errors have nothing to do
-with the language in use, and usually arise from expressions, such as
-the one described above, which make little sense to evaluate anyway.
+with the language in use and usually arise from expressions which make
+little sense to evaluate anyway.
-Each language defines to what degree it is strict about type. For
-instance, both Modula-2 and C require the arguments to arithmetical
-operators to be numbers. In C, enumerated types and pointers can be
-represented as numbers, so that they are valid arguments to mathematical
-operators. @xref{Supported Languages, ,Supported Languages}, for further
-details on specific languages.
-
-@value{GDBN} provides some additional commands for controlling the type checker:
+@value{GDBN} provides some additional commands for controlling type checking:
@kindex set check type
@kindex show check type
@table @code
-@item set check type auto
-Set type checking on or off based on the current working language.
-@xref{Supported Languages, ,Supported Languages}, for the default settings for
-each language.
-
@item set check type on
@itemx set check type off
-Set type checking on or off, overriding the default setting for the
-current working language. Issue a warning if the setting does not
-match the language default. If any type mismatches occur in
+Set strict type checking on or off. If any type mismatches occur in
evaluating an expression while type checking is on, @value{GDBN} prints a
message and aborts evaluation of the expression.
-@item set check type warn
-Cause the type checker to issue warnings, but to always attempt to
-evaluate the expression. Evaluating the expression may still
-be impossible for other reasons. For example, @value{GDBN} cannot add
-numbers and structures.
-
-@item show type
-Show the current setting of the type checker, and whether or not @value{GDBN}
-is setting it automatically.
+@item show check type
+Show the current setting of type checking and whether @value{GDBN}
+is enforcing strict type checking rules.
@end table
@cindex range checking
@cindex C and C@t{++} defaults
-If you allow @value{GDBN} to set type and range checking automatically, they
-both default to @code{off} whenever the working language changes to
+If you allow @value{GDBN} to set range checking automatically, it
+defaults to @code{off} whenever the working language changes to
C or C@t{++}. This happens regardless of whether you or @value{GDBN}
selects the working language.
@xref{Automatically, ,Having @value{GDBN} Infer the Source Language},
for further details.
-@c Type checking is (a) primarily motivated by Modula-2, and (b)
-@c unimplemented. If (b) changes, it might make sense to let this node
-@c appear even if Mod-2 does not, but meanwhile ignore it. roland 16jul93.
-
@node C Checks
@subsubsection C and C@t{++} Type and Range Checks
@cindex C and C@t{++} checks
-By default, when @value{GDBN} parses C or C@t{++} expressions, type checking
-is not used. However, if you turn type checking on, @value{GDBN}
-considers two variables type equivalent if:
-
-@itemize @bullet
-@item
-The two variables are structured and have the same structure, union, or
-enumerated tag.
-
-@item
-The two variables have the same type name, or types that have been
-declared equivalent through @code{typedef}.
-
-@ignore
-@c leaving this out because neither J Gilmore nor R Pesch understand it.
-@c FIXME--beers?
-@item
-The two @code{struct}, @code{union}, or @code{enum} variables are
-declared in the same declaration. (Note: this may not be true for all C
-compilers.)
-@end ignore
-@end itemize
+By default, when @value{GDBN} parses C or C@t{++} expressions, strict type
+checking is used. However, if you turn type checking off, @value{GDBN}
+will allow certain non-standard conversions, such as promoting integer
+constants to pointers.
Range checking, if turned on, is done on mathematical operations. Array
indices are not checked, since they are often used to index a pointer
This command shows the current setting of case sensitivity for symbols
lookups.
+@kindex set print type methods
+@item set print type methods
+@itemx set print type methods on
+@itemx set print type methods off
+Normally, when @value{GDBN} prints a class, it displays any methods
+declared in that class. You can control this behavior either by
+passing the appropriate flag to @code{ptype}, or using @command{set
+print type methods}. Specifying @code{on} will cause @value{GDBN} to
+display the methods; this is the default. Specifying @code{off} will
+cause @value{GDBN} to omit the methods.
+
+@kindex show print type methods
+@item show print type methods
+This command shows the current setting of method display when printing
+classes.
+
+@kindex set print type typedefs
+@item set print type typedefs
+@itemx set print type typedefs on
+@itemx set print type typedefs off
+
+Normally, when @value{GDBN} prints a class, it displays any typedefs
+defined in that class. You can control this behavior either by
+passing the appropriate flag to @code{ptype}, or using @command{set
+print type typedefs}. Specifying @code{on} will cause @value{GDBN} to
+display the typedef definitions; this is the default. Specifying
+@code{off} will cause @value{GDBN} to omit the typedef definitions.
+Note that this controls whether the typedef definition itself is
+printed, not whether typedef names are substituted when printing other
+types.
+
+@kindex show print type typedefs
+@item show print type typedefs
+This command shows the current setting of typedef display when
+printing classes.
+
@kindex info address
@cindex address of a symbol
@item info address @var{symbol}
@end smallexample
@kindex whatis
-@item whatis [@var{arg}]
+@item whatis[/@var{flags}] [@var{arg}]
Print the data type of @var{arg}, which can be either an expression
or a name of a data type. With no argument, print the data type of
@code{$}, the last value in the value history.
@var{class-name}}, @samp{struct @var{struct-tag}}, @samp{union
@var{union-tag}} or @samp{enum @var{enum-tag}}.
+@var{flags} can be used to modify how the type is displayed.
+Available flags are:
+
+@table @code
+@item r
+Display in ``raw'' form. Normally, @value{GDBN} substitutes template
+parameters and typedefs defined in a class when printing the class'
+members. The @code{/r} flag disables this.
+
+@item m
+Do not print methods defined in the class.
+
+@item M
+Print methods defined in the class. This is the default, but the flag
+exists in case you change the default with @command{set print type methods}.
+
+@item t
+Do not print typedefs defined in the class. Note that this controls
+whether the typedef definition itself is printed, not whether typedef
+names are substituted when printing other types.
+
+@item T
+Print typedefs defined in the class. This is the default, but the flag
+exists in case you change the default with @command{set print type typedefs}.
+@end table
+
@kindex ptype
-@item ptype [@var{arg}]
+@item ptype[/@var{flags}] [@var{arg}]
@code{ptype} accepts the same arguments as @code{whatis}, but prints a
detailed description of the type, instead of just the name of the type.
@xref{Expressions, ,Expressions}.
@code{whatis}, it does not print a detailed description; second, it
lists all source files where a type is defined.
+@kindex info type-printers
+@item info type-printers
+Versions of @value{GDBN} that ship with Python scripting enabled may
+have ``type printers'' available. When using @command{ptype} or
+@command{whatis}, these printers are consulted when the name of a type
+is needed. @xref{Type Printing API}, for more information on writing
+type printers.
+
+@code{info type-printers} displays all the available type printers.
+
+@kindex enable type-printer
+@kindex disable type-printer
+@item enable type-printer @var{name}@dots{}
+@item disable type-printer @var{name}@dots{}
+These commands can be used to enable or disable type printers.
+
@kindex info scope
@cindex local variables
@item info scope @var{location}
@table @code
@kindex jump
+@kindex j @r{(@code{jump})}
@item jump @var{linespec}
+@itemx j @var{linespec}
@itemx jump @var{location}
+@itemx j @var{location}
Resume execution at line @var{linespec} or at address given by
@var{location}. Execution stops again immediately if there is a
breakpoint there. @xref{Specify Location}, for a description of the
Alternatively, if @var{signal} is zero, continue execution without
giving a signal. This is useful when your program stopped on account of
-a signal and would ordinary see the signal when resumed with the
+a signal and would ordinarily see the signal when resumed with the
@code{continue} command; @samp{signal 0} causes it to resume without a
signal.
@menu
* Files:: Commands to specify files
* Separate Debug Files:: Debugging information in separate files
+* MiniDebugInfo:: Debugging information in a special section
* Index Files:: Index files speed up GDB
* Symbol Errors:: Errors reading symbol files
* Data Files:: GDB data files
@noindent
This computation does not apply to the ``build ID'' method.
+@node MiniDebugInfo
+@section Debugging information in a special section
+@cindex separate debug sections
+@cindex @samp{.gnu_debugdata} section
+
+Some systems ship pre-built executables and libraries that have a
+special @samp{.gnu_debugdata} section. This feature is called
+@dfn{MiniDebugInfo}. This section holds an LZMA-compressed object and
+is used to supply extra symbols for backtraces.
+
+The intent of this section is to provide extra minimal debugging
+information for use in simple backtraces. It is not intended to be a
+replacement for full separate debugging information (@pxref{Separate
+Debug Files}). The example below shows the intended use; however,
+@value{GDBN} does not currently put restrictions on what sort of
+debugging information might be included in the section.
+
+@value{GDBN} has support for this extension. If the section exists,
+then it is used provided that no other source of debugging information
+can be found, and that @value{GDBN} was configured with LZMA support.
+
+This section can be easily created using @command{objcopy} and other
+standard utilities:
+
+@smallexample
+# Extract the dynamic symbols from the main binary, there is no need
+# to also have these in the normal symbol table
+nm -D @var{binary} --format=posix --defined-only \
+ | awk '@{ print $1 @}' | sort > dynsyms
+
+# Extract all the text (i.e. function) symbols from the debuginfo .
+nm @var{binary} --format=posix --defined-only \
+ | awk '@{ if ($2 == "T" || $2 == "t") print $1 @}' \
+ | sort > funcsyms
+
+# Keep all the function symbols not already in the dynamic symbol
+# table.
+comm -13 dynsyms funcsyms > keep_symbols
+
+# Copy the full debuginfo, keeping only a minimal set of symbols and
+# removing some unnecessary sections.
+objcopy -S --remove-section .gdb_index --remove-section .comment \
+ --keep-symbols=keep_symbols @var{binary} mini_debuginfo
+
+# Inject the compressed data into the .gnu_debugdata section of the
+# original binary.
+xz mini_debuginfo
+objcopy --add-section .gnu_debugdata=mini_debuginfo.xz @var{binary}
+@end smallexample
@node Index Files
@section Index Files Speed Up @value{GDBN}
@anchor{set remote hardware-watchpoint-limit}
@anchor{set remote hardware-breakpoint-limit}
@item set remote hardware-watchpoint-limit @var{limit}
-@kindex set remote hardware-watchpoint-limit
@itemx set remote hardware-breakpoint-limit @var{limit}
-@kindex set remote hardware-breakpoint-limit
Restrict @value{GDBN} to using @var{limit} remote hardware breakpoint or
watchpoints. A limit of -1, the default, is treated as unlimited.
commands:
@table @code
-@item regs
-@kindex regs@r{, Super-H}
-This command is deprecated, and @code{info all-registers} should be
-used instead.
-
-Show the values of all Super-H registers.
-
@item set sh calling-convention @var{convention}
@kindex set sh calling-convention
Set the calling-convention used when calling functions from @value{GDBN}.
@cindex python commands
@cindex commands to access python
-@value{GDBN} provides one command for accessing the Python interpreter,
+@value{GDBN} provides two commands for accessing the Python interpreter,
and one related setting:
@table @code
+@kindex python-interactive
+@kindex pi
+@item python-interactive @r{[}@var{command}@r{]}
+@itemx pi @r{[}@var{command}@r{]}
+Without an argument, the @code{python-interactive} command can be used
+to start an interactive Python prompt. To return to @value{GDBN},
+type the @code{EOF} character (e.g., @kbd{Ctrl-D} on an empty prompt).
+
+Alternatively, a single-line Python command can be given as an
+argument and evaluated. If the command is an expression, the result
+will be printed; otherwise, nothing will be printed. For example:
+
+@smallexample
+(@value{GDBP}) python-interactive 2 + 3
+5
+@end smallexample
+
@kindex python
-@item python @r{[}@var{code}@r{]}
+@kindex py
+@item python @r{[}@var{command}@r{]}
+@itemx py @r{[}@var{command}@r{]}
The @code{python} command can be used to evaluate Python code.
If given an argument, the @code{python} command will evaluate the
* Pretty Printing API:: Pretty-printing values.
* Selecting Pretty-Printers:: How GDB chooses a pretty-printer.
* Writing a Pretty-Printer:: Writing a Pretty-Printer.
+* Type Printing API:: Pretty-printing types.
* Inferiors In Python:: Python representation of inferiors (processes)
* Events In Python:: Listening for events from @value{GDBN}.
* Threads In Python:: Accessing inferior threads from Python.
must not be negative, but the bounds can be.
@end defun
+@defun Type.vector (@var{n1} @r{[}, @var{n2}@r{]})
+Return a new @code{gdb.Type} object which represents a vector of this
+type. If one argument is given, it is the inclusive upper bound of
+the vector; in this case the lower bound is zero. If two arguments are
+given, the first argument is the lower bound of the vector, and the
+second argument is the upper bound of the vector. A vector's length
+must not be negative, but the bounds can be.
+
+The difference between an @code{array} and a @code{vector} is that
+arrays behave like in C: when used in expressions they decay to a pointer
+to the first element whereas vectors are treated as first class values.
+@end defun
+
@defun Type.const ()
Return a new @code{gdb.Type} object which represents a
@code{const}-qualified variant of this type.
@findex TYPE_CODE_BITSTRING
@findex gdb.TYPE_CODE_BITSTRING
@item gdb.TYPE_CODE_BITSTRING
-A string of bits.
+A string of bits. It is deprecated.
@findex TYPE_CODE_ERROR
@findex gdb.TYPE_CODE_ERROR
bar
@end smallexample
+@node Type Printing API
+@subsubsection Type Printing API
+@cindex type printing API for Python
+
+@value{GDBN} provides a way for Python code to customize type display.
+This is mainly useful for substituting canonical typedef names for
+types.
+
+@cindex type printer
+A @dfn{type printer} is just a Python object conforming to a certain
+protocol. A simple base class implementing the protocol is provided;
+see @ref{gdb.types}. A type printer must supply at least:
+
+@defivar type_printer enabled
+A boolean which is True if the printer is enabled, and False
+otherwise. This is manipulated by the @code{enable type-printer}
+and @code{disable type-printer} commands.
+@end defivar
+
+@defivar type_printer name
+The name of the type printer. This must be a string. This is used by
+the @code{enable type-printer} and @code{disable type-printer}
+commands.
+@end defivar
+
+@defmethod type_printer instantiate (self)
+This is called by @value{GDBN} at the start of type-printing. It is
+only called if the type printer is enabled. This method must return a
+new object that supplies a @code{recognize} method, as described below.
+@end defmethod
+
+
+When displaying a type, say via the @code{ptype} command, @value{GDBN}
+will compute a list of type recognizers. This is done by iterating
+first over the per-objfile type printers (@pxref{Objfiles In Python}),
+followed by the per-progspace type printers (@pxref{Progspaces In
+Python}), and finally the global type printers.
+
+@value{GDBN} will call the @code{instantiate} method of each enabled
+type printer. If this method returns @code{None}, then the result is
+ignored; otherwise, it is appended to the list of recognizers.
+
+Then, when @value{GDBN} is going to display a type name, it iterates
+over the list of recognizers. For each one, it calls the recognition
+function, stopping if the function returns a non-@code{None} value.
+The recognition function is defined as:
+
+@defmethod type_recognizer recognize (self, type)
+If @var{type} is not recognized, return @code{None}. Otherwise,
+return a string which is to be printed as the name of @var{type}.
+@var{type} will be an instance of @code{gdb.Type} (@pxref{Types In
+Python}).
+@end defmethod
+
+@value{GDBN} uses this two-pass approach so that type printers can
+efficiently cache information without holding on to it too long. For
+example, it can be convenient to look up type information in a type
+printer and hold it for a recognizer's lifetime; if a single pass were
+done then type printers would have to make use of the event system in
+order to avoid holding information that could become stale as the
+inferior changed.
+
@node Inferiors In Python
@subsubsection Inferiors In Python
@cindex inferiors in Python
Python code is read into @value{GDBN}, you may need to import the
@code{gdb} module explicitly.
+Now you can use the function in an expression:
+
+@smallexample
+(gdb) print $greet("Bob")
+$1 = "Hello, Bob!"
+@end smallexample
+
@node Progspaces In Python
@subsubsection Program Spaces In Python
information.
@end defvar
+@defvar Progspace.type_printers
+The @code{type_printers} attribute is a list of type printer objects.
+@xref{Type Printing API}, for more information.
+@end defvar
+
@node Objfiles In Python
@subsubsection Objfiles In Python
information.
@end defvar
+@defvar Objfile.type_printers
+The @code{type_printers} attribute is a list of type printer objects.
+@xref{Type Printing API}, for more information.
+@end defvar
+
A @code{gdb.Objfile} object has the following methods:
@defun Objfile.is_valid ()
Note that loading of this script file also requires accordingly configured
@code{auto-load safe-path} (@pxref{Auto-loading safe path}).
+For object files using @file{.exe} suffix @value{GDBN} tries to load first the
+scripts normally according to its @file{.exe} filename. But if no scripts are
+found @value{GDBN} also tries script filenames matching the object file without
+its @file{.exe} suffix. This @file{.exe} stripping is case insensitive and it
+is attempted on any platform. This makes the script filenames compatible
+between Unix and MS-Windows hosts.
+
@table @code
@anchor{set auto-load scripts-directory}
@kindex set auto-load scripts-directory
@cindex gdb.types
This module provides a collection of utilities for working with
-@code{gdb.Types} objects.
+@code{gdb.Type} objects.
@table @code
@item get_basic_type (@var{type})
@{['a', 'b0', 'b1']@}
@end smallexample
+@item get_type_recognizers ()
+Return a list of the enabled type recognizers for the current context.
+This is called by @value{GDBN} during the type-printing process
+(@pxref{Type Printing API}).
+
+@item apply_type_recognizers (recognizers, type_obj)
+Apply the type recognizers, @var{recognizers}, to the type object
+@var{type_obj}. If any recognizer returns a string, return that
+string. Otherwise, return @code{None}. This is called by
+@value{GDBN} during the type-printing process (@pxref{Type Printing
+API}).
+
+@item register_type_printer (locus, printer)
+This is a convenience function to register a type printer.
+@var{printer} is the type printer to register. It must implement the
+type printer protocol. @var{locus} is either a @code{gdb.Objfile}, in
+which case the printer is registered with that objfile; a
+@code{gdb.Progspace}, in which case the printer is registered with
+that progspace; or @code{None}, in which case the printer is
+registered globally.
+
+@item TypePrinter
+This is a base class that implements the type printer protocol. Type
+printers are encouraged, but not required, to derive from this class.
+It defines a constructor:
+
+@defmethod TypePrinter __init__ (self, name)
+Initialize the type printer with the given name. The new printer
+starts in the enabled state.
+@end defmethod
+
@end table
@node gdb.prompt
absent, it means the library was unloaded in the context of all present
thread groups.
+@item =traceframe-changed,num=@var{tfnum},tracepoint=@var{tpnum}
+@itemx =traceframe-changed,end
+Reports that the trace frame was changed and its new number is
+@var{tfnum}. The number of the tracepoint associated with this trace
+frame is @var{tpnum}.
+
+@item =tsv-created,name=@var{name},value=@var{value}
+Reports that the new trace state variable @var{name} is created with
+value @var{value}.
+
+@item =tsv-deleted,name=@var{name}
+@itemx =tsv-deleted
+Reports that the trace state variable @var{name} is deleted or all
+trace state variables are deleted.
+
@item =breakpoint-created,bkpt=@{...@}
@itemx =breakpoint-modified,bkpt=@{...@}
@itemx =breakpoint-deleted,id=@var{number}
Note that if a breakpoint is emitted in the result record of a
command, then it will not also be emitted in an async record.
+@item =record-started,thread-group="@var{id}"
+@itemx =record-stopped,thread-group="@var{id}"
+Execution log recording was either started or stopped on an
+inferior. The @var{id} is the @value{GDBN} identifier of the thread
+group corresponding to the affected inferior.
+
+@item =cmd-param-changed,param=@var{param},value=@var{value}
+Reports that a parameter of the command @code{set @var{param}} is
+changed to @var{value}. In the multi-word @code{set} command,
+the @var{param} is the whole parameter list to @code{set} command.
+For example, In command @code{set check type on}, @var{param}
+is @code{check type} and @var{value} is @code{on}.
+
+@item =memory-changed,thread-group=@var{id},addr=@var{addr},len=@var{len}[,type="code"]
+Reports that bytes from @var{addr} to @var{data} + @var{len} were
+written in an inferior. The @var{id} is the identifier of the
+thread group corresponding to the affected inferior. The optional
+@code{type="code"} part is reported if the memory written to holds
+executable code.
@end table
@node GDB/MI Frame Information
@subsubheading Result
-The output for each instruction is composed of four fields:
+The result of the @code{-data-disassemble} command will be a list named
+@samp{asm_insns}, the contents of this list depend on the @var{mode}
+used with the @code{-data-disassemble} command.
-@itemize @bullet
-@item Address
-@item Func-name
-@item Offset
-@item Instruction
-@end itemize
+For modes 0 and 2 the @samp{asm_insns} list contains tuples with the
+following fields:
+
+@table @code
+@item address
+The address at which this instruction was disassembled.
+
+@item func-name
+The name of the function this instruction is within.
+
+@item offset
+The decimal offset in bytes from the start of @samp{func-name}.
+
+@item inst
+The text disassembly for this @samp{address}.
+
+@item opcodes
+This field is only present for mode 2. This contains the raw opcode
+bytes for the @samp{inst} field.
+
+@end table
+
+For modes 1 and 3 the @samp{asm_insns} list contains tuples named
+@samp{src_and_asm_line}, each of which has the following fields:
+
+@table @code
+@item line
+The line number within @samp{file}.
+
+@item file
+The file name from the compilation unit. This might be an absolute
+file name or a relative file name depending on the compile command
+used.
-Note that whatever included in the instruction field, is not manipulated
-directly by @sc{gdb/mi}, i.e., it is not possible to adjust its format.
+@item fullname
+This field is optional. If it is present it will contain an absolute
+file name of @samp{file}. If this field is not present then
+@value{GDBN} was unable to determine the absolute file name.
+
+@item line_asm_insn
+This is a list of tuples containing the disassembly for @samp{line} in
+@samp{file}. The fields of each tuple are the same as for
+@code{-data-disassemble} in @var{mode} 0 and 2, so @samp{address},
+@samp{func-name}, @samp{offset}, @samp{inst}, and optionally
+@samp{opcodes}.
+
+@end table
+
+Note that whatever included in the @samp{inst} field, is not
+manipulated directly by @sc{gdb/mi}, i.e., it is not possible to
+adjust its format.
@subsubheading @value{GDBN} Command
-There's no direct mapping from this command to the CLI.
+The corresponding @value{GDBN} command is @samp{disassemble}.
@subsubheading Example
-data-disassemble -f basics.c -l 32 -n 3 -- 1
^done,asm_insns=[
src_and_asm_line=@{line="31",
-file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
- testsuite/gdb.mi/basics.c",line_asm_insn=[
-@{address="0x000107bc",func-name="main",offset="0",
-inst="save %sp, -112, %sp"@}]@},
+file="../../../src/gdb/testsuite/gdb.mi/basics.c",
+fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c",
+line_asm_insn=[@{address="0x000107bc",
+func-name="main",offset="0",inst="save %sp, -112, %sp"@}]@},
src_and_asm_line=@{line="32",
-file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
- testsuite/gdb.mi/basics.c",line_asm_insn=[
-@{address="0x000107c0",func-name="main",offset="4",
-inst="mov 2, %o0"@},
+file="../../../src/gdb/testsuite/gdb.mi/basics.c",
+fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c",
+line_asm_insn=[@{address="0x000107c0",
+func-name="main",offset="4",inst="mov 2, %o0"@},
@{address="0x000107c4",func-name="main",offset="8",
inst="sethi %hi(0x11800), %o2"@}]@}]
(gdb)
@smallexample
-data-write-memory-bytes @var{address} @var{contents}
+ -data-write-memory-bytes @var{address} @var{contents} @r{[}@var{count}@r{]}
@end smallexample
@noindent
@item @var{contents}
The hex-encoded bytes to write.
+@item @var{count}
+Optional argument indicating the number of bytes to be written. If @var{count}
+is greater than @var{contents}' length, @value{GDBN} will repeatedly
+write @var{contents} until it fills @var{count} bytes.
+
@end table
@subsubheading @value{GDBN} Command
(gdb)
@end smallexample
+@smallexample
+(gdb)
+-data-write-memory-bytes &a "aabbccdd" 16e
+^done
+(gdb)
+@end smallexample
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Tracepoint Commands
wherever @value{GDBN} is installed.
@end itemize
+If the configured location of the system-wide init file (as given by the
+@option{--with-system-gdbinit} option at configure time) is in the
+data-directory (as specified by @option{--with-gdb-datadir} at configure
+time) or in one of its subdirectories, then @value{GDBN} will look for the
+system-wide init file in the directory specified by the
+@option{--data-directory} command-line option.
+Note that the system-wide init file is only read once, during @value{GDBN}
+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.
+
@node Maintenance Commands
@appendix Maintenance Commands
@cindex maintenance commands
@table @samp
@item QAgent:1
-@item QAgent:0
+@itemx QAgent:0
Turn on or off the agent as a helper to perform some debugging operations
delegated from @value{GDBN} (@pxref{Control Agent}).
Reply: see @code{remote.c:remote_unpack_thread_info_response()}.
@item QNonStop:1
-@item QNonStop:0
+@itemx QNonStop:0
@cindex non-stop mode, remote request
@cindex @samp{QNonStop} packet
@anchor{QNonStop}
@end table
@item qTBuffer
-@item QTBuffer
-@item QTDisconnected
+@itemx QTBuffer
+@itemx QTDisconnected
@itemx QTDP
@itemx QTDPsrc
@itemx QTDV
packets.)
@item QTNotes
-@item qTP
-@item QTSave
-@item qTsP
-@item qTsV
+@itemx qTP
+@itemx QTSave
+@itemx qTsP
+@itemx qTsV
@itemx QTStart
@itemx QTStop
@itemx QTEnable
projects / binutils.git / blobdiff