@end itemize
You can use @value{GDBN} to debug programs written in C and C@t{++}.
-For more information, see @ref{Support,,Supported languages}.
+For more information, see @ref{Supported languages,,Supported languages}.
For more information, see @ref{C,,C and C++}.
@cindex Modula-2
@node Logging output
@section Logging output
@cindex logging @value{GDBN} output
+@cindex save @value{GDBN} output to a file
You may want to save the output of @value{GDBN} commands to a file.
There are several commands to control @value{GDBN}'s logging.
Enable logging.
@item set logging off
Disable logging.
+@cindex logging file name
@item set logging file @var{file}
Change the name of the current logfile. The default logfile is @file{gdb.txt}.
@item set logging overwrite [on|off]
@table @code
@kindex show version
-@cindex version number
+@cindex @value{GDBN} version number
@item show version
Show what version of @value{GDBN} is running. You should include this
information in @value{GDBN} bug-reports. If multiple versions of
@kindex show copying
@kindex info copying
+@cindex display @value{GDBN} copyright
@item show copying
@itemx info copying
Display information about permission for copying @value{GDBN}.
@samp{Switching to} depends on your system's conventions for identifying
threads.
+@kindex thread apply
@item thread apply [@var{threadno}] [@var{all}] @var{args}
The @code{thread apply} command allows you to apply a command to one or
more threads. Specify the numbers of the threads that you want affected
@item set follow-fork-mode @var{mode}
Set the debugger response to a program call of @code{fork} or
@code{vfork}. A call to @code{fork} or @code{vfork} creates a new
-process. The @var{mode} can be:
+process. The @var{mode} argument can be:
@table @code
@item parent
@end table
+@kindex show follow-fork-mode
@item show follow-fork-mode
Display the current debugger response to a @code{fork} or @code{vfork} call.
@end table
@value{GDBN} will reject this command if more than two are used. Delete
or disable unused hardware breakpoints before setting new ones
(@pxref{Disabling, ,Disabling}). @xref{Conditions, ,Break conditions}.
-@xref{set remote hardware-breakpoint-limit}.
+For remote targets, you can restrict the number of hardware
+breakpoints @value{GDBN} will use, see @ref{set remote
+hardware-breakpoint-limit}.
@kindex thbreak
@code{can-use-hw-watchpoints} to zero will still use the hardware
mechanism of watching expressiion values.)
+@table @code
+@item set can-use-hw-watchpoints
+@kindex set can-use-hw-watchpoints
+Set whether or not to use hardware watchpoints.
+
+@item show can-use-hw-watchpoints
+@kindex show can-use-hw-watchpoints
+Show the current mode of using hardware watchpoints.
+@end table
+
+For remote targets, you can restrict the number of hardware
+watchpoints @value{GDBN} will use, see @ref{set remote
+hardware-breakpoint-limit}.
+
When you issue the @code{watch} command, @value{GDBN} reports
@smallexample
Causes the @code{step} command to step over any functions which contains no
debug information. This is the default.
+@item show step-mode
+Show whether @value{GDBN} will stop in or step over functions without
+source line debug information.
+
@kindex finish
@item finish
Continue running until just after function in the selected stack frame
@table @code
@item set scheduler-locking @var{mode}
+@cindex scheduler locking mode
+@cindex lock scheduler
Set the scheduler locking mode. If it is @code{off}, then there is no
locking and any thread may run at any time. If @code{on}, then only the
current thread may run when the inferior is resumed. The @code{step}
Print lines just before the lines last printed.
@end table
+@cindex @code{list}, how many lines to display
By default, @value{GDBN} prints ten source lines with any of these forms of
the @code{list} command. You can change this using @code{set listsize}:
can set @var{instruction-set} to either @code{intel} or @code{att}.
The default is @code{att}, the AT&T flavor used by default by Unix
assemblers for x86-based targets.
+
+@kindex show disassembly-flavor
+@item show disassembly-flavor
+Show the current setting of the disassembly flavor.
@end table
@table @code
@item set print symbol-filename on
-@cindex closest symbol and offset for an address
+@cindex source file and line of a symbol
+@cindex symbol, source file and line
Tell @value{GDBN} to print the source file name and line number of a
symbol in the symbolic form of an address.
@item set print elements @var{number-of-elements}
@cindex number of array elements to print
+@cindex limit on number of printed array elements
Set a limit on how many elements of an array @value{GDBN} will print.
If @value{GDBN} is printing a large array, it stops printing after it has
printed the number of elements set by the @code{set print elements} command.
Display the number of elements of a large array that @value{GDBN} will print.
If the number is 0, then the printing is unlimited.
+@item set print repeats
+@cindex repeated array elements
+Set the threshold for suppressing display of repeated array
+elelments. When the number of consecutive identical elements of an
+array exceeds the threshold, @value{GDBN} prints the string
+@code{"<repeats @var{n} times>"}, where @var{n} is the number of
+identical repetitions, instead of displaying the identical elements
+themselves. Setting the threshold to zero will cause all elements to
+be individually printed. The default threshold is 10.
+
+@item show print repeats
+Display the current threshold for printing repeated identical
+elements.
+
@item set print null-stop
@cindex @sc{null} elements in arrays
Cause @value{GDBN} to stop printing the characters of an array when the first
contain only short strings.
The default is off.
+@item show print null-stop
+Show whether @value{GDBN} stops printing an array on the first
+@sc{null} character.
+
@item set print pretty on
+@cindex print structures in indented form
+@cindex indentation in structure display
Cause @value{GDBN} to print structures in an indented format with one member
per line, like this:
@item set print union on
@cindex unions in structures, printing
-Tell @value{GDBN} to print unions which are contained in structures. This
-is the default setting.
+Tell @value{GDBN} to print unions which are contained in structures
+and other unions. This is the default setting.
@item set print union off
-Tell @value{GDBN} not to print unions which are contained in structures.
+Tell @value{GDBN} not to print unions which are contained in
+structures and other unions. @value{GDBN} will print @code{"@{...@}"}
+instead.
@item show print union
Ask @value{GDBN} whether or not it will print unions which are contained in
-structures.
+structures and other unions.
For example, given the declarations
@smallexample
$1 = @{it = Tree, form = @{...@}@}
@end smallexample
+
+@noindent
+@code{set print union} affects programs written in C-like languages
+and in Pascal.
@end table
@need 1000
@item set print object
@itemx set print object on
@cindex derived type of an object, printing
+@cindex display derived types
When displaying a pointer to an object, identify the @emph{actual}
(derived) type of the object rather than the @emph{declared} type, using
the virtual function table.
Do not print static members when displaying a C@t{++} object.
@item show print static-members
-Show whether C@t{++} static members are printed, or not.
+Show whether C@t{++} static members are printed or not.
+
+@item set print pascal_static-members
+@itemx set print pascal_static-members on
+@cindex static members of Pacal objects
+@cindex Pacal objects, static members display
+Print static members when displaying a Pascal object. The default is on.
+
+@item set print pascal_static-members off
+Do not print static members when displaying a Pascal object.
+
+@item show print pascal_static-members
+Show whether Pascal static members are printed or not.
@c These don't work with HP ANSI C++ yet.
@item set print vtbl
@itemx set print vtbl on
@cindex pretty print C@t{++} virtual function tables
+@cindex virtual functions (C@t{++}) display
+@cindex VTBL display
Pretty print C@t{++} virtual function tables. The default is off.
(The @code{vtbl} commands do not work on programs compiled with the HP
ANSI C@t{++} compiler (@code{aCC}).)
@section Value history
@cindex value history
+@cindex history of values printed by @value{GDBN}
Values printed by the @code{print} command are saved in the @value{GDBN}
@dfn{value history}. This allows you to refer to them in other expressions.
Values are kept until the symbol table is re-read or discarded
@section Convenience variables
@cindex convenience variables
+@cindex user-defined variables
@value{GDBN} provides @dfn{convenience variables} that you can use within
@value{GDBN} to hold on to a value and refer to it later. These variables
exist entirely within @value{GDBN}; they are not part of your program, and
@table @code
@kindex show convenience
+@cindex show all user variables
@item show convenience
Print a list of convenience variables used so far, and their values.
Abbreviated @code{show conv}.
hardware, operating system, and process. Each value's purpose is
identified by an integer tag; the meanings are well-known but system-specific.
Depending on the configuration and operating system facilities,
-@value{GDBN} may be able to show you this information.
+@value{GDBN} may be able to show you this information. For remote
+targets, this functionality may further depend on the remote stub's
+support of the @samp{qPart:auxv:read} packet, see @ref{Remote
+configuration, auxiliary vector}.
@table @code
@kindex info auxv
* Setting:: Switching between source languages
* Show:: Displaying the language
* Checks:: Type and range checks
-* Support:: Supported languages
+* Supported languages:: Supported languages
* Unsupported languages:: Unsupported languages
@end menu
The following commands help you find out which language is the
working language, and also what language source files were written in.
-@kindex show language
@table @code
@item show language
+@kindex show language
Display the current working language. This is the
language you can use with commands such as @code{print} to
build and compute expressions that may involve variables in your program.
not in the standard list. You can then set the extension associated
with a language explicitly:
-@kindex set extension-language
-@kindex info extensions
@table @code
@item set extension-language @var{ext} @var{language}
+@kindex set extension-language
Tell @value{GDBN} that source files with extension @var{ext} are to be
assumed as written in the source language @var{language}.
@item info extensions
+@kindex info extensions
List all the filename extensions and the associated languages.
@end table
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{Support, ,Supported languages},
-for the default settings of supported languages.
+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.
@menu
* Type Checking:: An overview of type checking
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{Support, ,Supported languages}, for further
+operators. @xref{Supported languages, ,Supported languages}, for further
details on specific languages.
@value{GDBN} provides some additional commands for controlling the type checker:
@table @code
@item set check type auto
Set type checking on or off based on the current working language.
-@xref{Support, ,Supported languages}, for the default settings for
+@xref{Supported languages, ,Supported languages}, for the default settings for
each language.
@item set check type on
@end smallexample
This, too, is specific to individual languages, and in some cases
-specific to individual compilers or machines. @xref{Support, ,
+specific to individual compilers or machines. @xref{Supported languages, ,
Supported languages}, for further details on specific languages.
@value{GDBN} provides some additional commands for controlling the range checker:
@table @code
@item set check range auto
Set range checking on or off based on the current working language.
-@xref{Support, ,Supported languages}, for the default settings for
+@xref{Supported languages, ,Supported languages}, for the default settings for
each language.
@item set check range on
being set automatically by @value{GDBN}.
@end table
-@node Support
+@node Supported languages
@section Supported languages
-@value{GDBN} supports C, C@t{++}, Objective-C, Fortran, Java, assembly, Modula-2, and Ada.
+@value{GDBN} supports C, C@t{++}, Objective-C, Fortran, Java, Pascal,
+assembly, Modula-2, and Ada.
@c This is false ...
Some @value{GDBN} features may be used in expressions regardless of the
language you use: the @value{GDBN} @code{@@} and @code{::} operators,
* C:: C and C@t{++}
* Objective-C:: Objective-C
* Fortran:: Fortran
+* Pascal:: Pascal
* Modula-2:: Modula-2
* Ada:: Ada
@end menu
searches for a function whose signature @emph{exactly} matches the
argument types.
+@kindex show overload-resolution
+@item show overload-resolution
+Show the current setting of overload resolution.
+
@item @r{Overloaded symbol names}
You can specify a particular definition of an overloaded symbol, using
the same notation that is used to declare such symbols in C@t{++}: type
change that with the @samp{set case-insensitive} command, see
@ref{Symbols}, for the details.
+@node Pascal
+@subsection Pascal
+
+@cindex Pascal support in @value{GDBN}, limitations
+Debugging Pascal programs which use sets, subranges, file variables, or
+nested functions does not currently work. @value{GDBN} does not support
+entering expressions, printing values, or similar features using Pascal
+syntax.
+
+The Pascal-specific command @code{set print pascal_static-members}
+controls whether static members of Pascal objects are displayed.
+@xref{Print Settings, pascal_static-members}.
+
@node Modula-2
@subsection Modula-2
matches for all languages except for Fortran, for which the default is
case-insensitive matches.
-@kindex show case-insensitive
-@item show case-insensitive
+@kindex show case-sensitive
+@item show case-sensitive
This command shows the current setting of case sensitivity for symbols
lookups.
@kindex info symbol
@cindex symbol from address
+@cindex closest symbol and offset for an address
@item info symbol @var{addr}
Print the name of a symbol which is stored at the address @var{addr}.
If no symbol is stored exactly at @var{addr}, @value{GDBN} prints the
Show the current @code{on} or @code{off} setting.
@end table
+@cindex opaque data types
@kindex set opaque-type-resolution
@item set opaque-type-resolution on
Tell @value{GDBN} to resolve opaque types. An opaque type is a type
@c @group
@node Signaling
@section Giving your program a signal
+@cindex deliver a signal to a program
@table @code
@kindex signal
@cindex calling functions
@cindex inferior functions, calling
@item print @var{expr}
-Evaluate the expression @var{expr} and displaying the resuling value.
+Evaluate the expression @var{expr} and display the resuling value.
@var{expr} may include calls to functions in the program being
debugged.
value history.
@end table
+It is possible for the function you call via the @code{print} or
+@code{call} command to generate a signal (e.g., if there's a bug in
+the function, or if you passed it incorrect arguments). What happens
+in that case is controlled by the @code{set unwindonsignal} command.
+
+@table @code
+@item set unwindonsignal
+@kindex set unwindonsignal
+@cindex unwind stack in called functions
+@cindex call dummy stack unwinding
+Set unwinding of the stack if a signal is received while in a function
+that @value{GDBN} called in the program being debugged. If set to on,
+@value{GDBN} unwinds the stack it created for the call and restores
+the context to what it was before the call. If set to off (the
+default), @value{GDBN} stops in the frame where the signal was
+received.
+
+@item show unwindonsignal
+@kindex show unwindonsignal
+Show the current setting of stack unwinding in the functions called by
+@value{GDBN}.
+@end table
+
@cindex weak alias functions
Sometimes, a function you wish to call is actually a @dfn{weak alias}
for another function. In such case, @value{GDBN} might not pick up
@end table
@end table
@kindex set trust-readonly-sections
+@cindex read-only sections
@item set trust-readonly-sections on
Tell @value{GDBN} that readonly sections in your object file
really are read-only (i.e.@: that their contents will not change).
Tell @value{GDBN} not to trust readonly sections. This means that
the contents of the section might change while the program is running,
and must therefore be fetched from the target when needed.
+
+@item show trust-readonly-sections
+Show the current setting of trusting readonly sections.
@end table
All file-specifying commands allow both absolute and relative file names
name and remembers it that way.
@cindex shared libraries
-@value{GDBN} supports GNU/Linux, MS-Windows, HP-UX, SunOS, SVr4, Irix
-5, and IBM RS/6000 shared libraries.
+@value{GDBN} supports GNU/Linux, MS-Windows, HP-UX, SunOS, SVr4, Irix,
+and IBM RS/6000 AIX shared libraries.
@value{GDBN} automatically loads symbol definitions from shared libraries
when you use the @code{run} command, or when you examine a core file.
@item show architecture
Show the current target architecture.
+
+@item set processor
+@itemx processor
+@kindex set processor
+@kindex show processor
+These are alias commands for, respectively, @code{set architecture}
+and @code{show architecture}.
@end table
@menu
@cindex serial line, @code{target remote}
If you're using a serial line, you may want to give @value{GDBN} the
@w{@samp{--baud}} option, or use the @code{set remotebaud} command
-before the @code{target} command.
+(@pxref{Remote configuration, set remotebaud}) before the
+@code{target} command.
After that, use @code{target remote} to establish communications with
the target machine. Its argument specifies how to communicate---either
@node Remote configuration
@section Remote configuration
-The following configuration options are available when debugging remote
-programs:
+@kindex set remote
+@kindex show remote
+This section documents the configuration options available when
+debugging remote programs. For the options related to the File I/O
+extensions of the remote protocol, see @ref{The system call,
+system-call-allowed}.
@table @code
-@kindex set remote hardware-watchpoint-limit
-@kindex set remote hardware-breakpoint-limit
+@item set remoteaddresssize @var{bits}
+@cindex adress size for remote targets
+@cindex bits in remote address
+Set the maximum size of address in a memory packet to the specified
+number of bits. @value{GDBN} will mask off the address bits above
+that number, when it passes addresses to the remote target. The
+default value is the number of bits in the target's address.
+
+@item show remoteaddresssize
+Show the current value of remote address size in bits.
+
+@item set remotebaud @var{n}
+@cindex baud rate for remote targets
+Set the baud rate for the remote serial I/O to @var{n} baud. The
+value is used to set the speed of the serial port used for debugging
+remote targets.
+
+@item show remotebaud
+Show the current speed of the remote connection.
+
+@item set remotebreak
+@cindex interrupt remote programs
+@cindex BREAK signal instead of Ctrl-C
+If set to on, @value{GDBN} sends a @code{BREAK} signal to the remote
+when you press the @key{Ctrl-C} key to interrupt the program running
+on the remote. If set to off, @value{GDBN} sends the @samp{Strl-C}
+character instead. The default is off, since most remote systems
+expect to see @samp{Ctrl-C} as the interrupt signal.
+
+@item show remotebreak
+Show whether @value{GDBN} sends @code{BREAK} or @samp{Ctrl-C} to
+interrupt the remote program.
+
+@item set remotedebug
+@cindex debug remote protocol
+@cindex remote protocol debugging
+@cindex display remote packets
+Control the debugging of the remote protocol. When enabled, each
+packet sent to or received from the remote target is displayed. The
+defaults is off.
+
+@item show remotedebug
+Show the current setting of the remote protocol debugging.
+
+@item set remotedevice @var{device}
+@cindex serial port name
+Set the name of the serial port through which to communicate to the
+remote target to @var{device}. This is the device used by
+@value{GDBN} to open the serial communications line to the remote
+target. There's no default, so you must set a valid port name for the
+remote serial communications to work. (Some varieties of the
+@code{target} command accept the port name as part of their
+arguments.)
+
+@item show remotedevice
+Show the current name of the serial port.
+
+@item set remotelogbase @var{base}
+Set the base (a.k.a.@: radix) of logging serial protocol
+communications to @var{base}. Supported values of @var{base} are:
+@code{ascii}, @code{octal}, and @code{hex}. The default is
+@code{ascii}.
+
+@item show remotelogbase
+Show the current setting of the radix for logging remote serial
+protocol.
+
+@item set remotelogfile @var{file}
+@cindex record serial communications on file
+Record remote serial communications on the named @var{file}. The
+default is not to record at all.
+
+@item show remotelogfile.
+Show the current setting of the file name on which to record the
+serial communications.
+
+@item set remotetimeout @var{num}
+@cindex timeout for serial communications
+@cindex remote timeout
+Set the timeout limit to wait for the remote target to respond to
+@var{num} seconds. The default is 2 seconds.
+
+@item show remotetimeout
+Show the current number of seconds to wait for the remote target
+responses.
+
+@cindex limit hardware breakpoints and watchpoints
+@cindex remote target, limit break- and watchpoints
@anchor{set remote hardware-watchpoint-limit}
@anchor{set remote hardware-breakpoint-limit}
@item set remote hardware-watchpoint-limit @var{limit}
@itemx set remote hardware-breakpoint-limit @var{limit}
Restrict @value{GDBN} to using @var{limit} remote hardware breakpoint or
watchpoints. A limit of -1, the default, is treated as unlimited.
+
+@item set remote fetch-register-packet
+@itemx set remote set-register-packet
+@itemx set remote P-packet
+@itemx set remote p-packet
+@cindex P-packet
+@cindex fetch registers from remote targets
+@cindex set registers in remote targets
+Determine whether @value{GDBN} can set and fetch registers from the
+remote target using the @samp{P} packets. The default depends on the
+remote stub's support of the @samp{P} packets (@value{GDBN} queries
+the stub when this packet is first required).
+
+@item show remote fetch-register-packet
+@itemx show remote set-register-packet
+@itemx show remote P-packet
+@itemx show remote p-packet
+Show the current setting of using the @samp{P} packets for setting and
+fetching registers from the remote target.
+
+@cindex binary downloads
+@cindex X-packet
+@item set remote binary-download-packet
+@itemx set remote X-packet
+Determine whether @value{GDBN} sends downloads in binary mode using
+the @samp{X} packets. The default is on.
+
+@item show remote binary-download-packet
+@itemx show remote X-packet
+Show the current setting of using the @samp{X} packets for binary
+downloads.
+
+@item set remote read-aux-vector-packet
+@cindex auxiliary vector of remote target
+@cindex @code{auxv}, and remote targets
+Set the use of the remote protocol's @samp{qPart:auxv:read} (target
+auxiliary vector read) request. This request is used to fetch the
+remote target's @dfn{auxiliary vector}, see @ref{Auxiliary Vector}.
+The default setting depends on the remote stub's support of this
+request (@value{GDBN} queries the stub when this request is first
+required). @xref{General Query Packets, qPart}, for more information
+about this request.
+
+@item show remote read-aux-vector-packet
+Show the current setting of use of the @samp{qPart:auxv:read} request.
+
+@item set remote symbol-lookup-packet
+@cindex remote symbol lookup request
+Set the use of the remote protocol's @samp{qSymbol} (target symbol
+lookup) request. This request is used to communicate symbol
+information to the remote target, e.g., whenever a new shared library
+is loaded by the remote (@pxref{Files, shared libraries}). The
+default setting depends on the remote stub's support of this request
+(@value{GDBN} queries the stub when this request is first required).
+@xref{General Query Packets, qSymbol}, for more information about this
+request.
+
+@item show remote symbol-lookup-packet
+Show the current setting of use of the @samp{qSymbol} request.
+
+@item set remote verbose-resume-packet
+@cindex resume remote target
+@cindex signal thread, and remote targets
+@cindex single-step thread, and remote targets
+@cindex thread-specific operations on remote targets
+Set the use of the remote protocol's @samp{vCont} (descriptive resume)
+request. This request is used to resume specific threads in the
+remote target, and to single-step or signal them. The default setting
+depends on the remote stub's support of this request (@value{GDBN}
+queries the stub when this request is first required). This setting
+affects debugging of multithreaded programs: if @samp{vCont} cannot be
+used, @value{GDBN} might be unable to single-step a specific thread,
+especially under @code{set scheduler-locking off}; it is also
+impossible to pause a specific thread. @xref{Packets, vCont}, for
+more details.
+
+@item show remote verbose-resume-packet
+Show the current setting of use of the @samp{vCont} request
+
+@item set remote software-breakpoint-packet
+@itemx set remote hardware-breakpoint-packet
+@itemx set remote write-watchpoint-packet
+@itemx set remote read-watchpoint-packet
+@itemx set remote access-watchpoint-packet
+@itemx set remote Z-packet
+@cindex Z-packet
+@cindex remote hardware breakpoints and watchpoints
+These commands enable or disable the use of @samp{Z} packets for
+setting breakpoints and watchpoints in the remote target. The default
+depends on the remote stub's support of the @samp{Z} packets
+(@value{GDBN} queries the stub when each packet is first required).
+The command @code{set remote Z-packet}, kept for back-compatibility,
+turns on or off all the features that require the use of @samp{Z}
+packets.
+
+@item show remote software-breakpoint-packet
+@itemx show remote hardware-breakpoint-packet
+@itemx show remote write-watchpoint-packet
+@itemx show remote read-watchpoint-packet
+@itemx show remote access-watchpoint-packet
+@itemx show remote Z-packet
+Show the current setting of @samp{Z} packets usage.
@end table
@node remote stub
begins with a dollar sign, @value{GDBN} searches for a user or system
name first, before it searches for a convenience variable.
+
@node BSD libkvm Interface
@subsection BSD libkvm Interface
@kindex target hms@r{, and serial protocol}
Now that serial communications are set up, and the development board is
-connected, you can start up @value{GDBN}. Call @code{@value{GDBP}} with
+connected, you can start up @value{GDBN}. Call @code{@value{GDBN}} with
the name of your program as the argument. @code{@value{GDBN}} prompts
you, as usual, with the prompt @samp{(@value{GDBP})}. Use two special
commands to begin your debugging session: @samp{target hms} to specify
@value{GDBN} also supports these special commands for MIPS targets:
@table @code
-@item set processor @var{args}
-@itemx show processor
-@kindex set processor @var{args}
-@kindex show processor
-Use the @code{set processor} command to set the type of MIPS
-processor when you want to access processor-type-specific registers.
-For example, @code{set processor @var{r3041}} tells @value{GDBN}
-to use the CPU registers appropriate for the 3041 chip.
-Use the @code{show processor} command to see what MIPS processor @value{GDBN}
-is using. Use the @code{info reg} command to see what registers
-@value{GDBN} is using.
-
@item set mipsfpu double
@itemx set mipsfpu single
@itemx set mipsfpu none
As usual, you can inquire about the @code{mipsfpu} variable with
@samp{show mipsfpu}.
-@item set remotedebug @var{n}
-@itemx show remotedebug
-@kindex set remotedebug@r{, MIPS protocol}
-@kindex show remotedebug@r{, MIPS protocol}
-@cindex @code{remotedebug}, MIPS protocol
-@cindex MIPS @code{remotedebug} protocol
-@c FIXME! For this to be useful, you must know something about the MIPS
-@c FIXME...protocol. Where is it described?
-You can see some debugging information about communications with the board
-by setting the @code{remotedebug} variable. If you set it to @code{1} using
-@samp{set remotedebug 1}, every packet is displayed. If you set it
-to @code{2}, every character is displayed. You can check the current value
-at any time with the command @samp{show remotedebug}.
-
@item set timeout @var{seconds}
@itemx set retransmit-timeout @var{seconds}
@itemx show timeout
all uses of @value{GDBN} with the architecture, both native and cross.
@menu
+* i386::
* A29K::
* Alpha::
* MIPS::
@end menu
+@node i386
+@subsection x86 Architecture-specific issues.
+
+@table @code
+@item set struct-convention @var{mode}
+@kindex set struct-convention
+@cindex struct return convention
+@cindex struct/union returned in registers
+Set the convention used by the inferior to return @code{struct}s and
+@code{union}s from functions to @var{mode}. Possible values of
+@var{mode} are @code{"pcc"}, @code{"reg"}, and @code{"default"} (the
+default). @code{"default"} or @code{"pcc"} means that @code{struct}s
+are returned on the stack, while @code{"reg"} means that a
+@code{struct} or a @code{union} whose size is 1, 2, 4, or 8 bytes will
+be returned in a register.
+
+@item show struct-convention
+@kindex show struct-convention
+Show the current setting of the convention to return @code{struct}s
+from functions.
+@end table
+
@node A29K
@subsection A29K
@file{./.gdb_history} (@file{./_gdb_history} on MS-DOS) if this variable
is not set.
-@cindex history save
-@kindex set history
+@cindex save command history
+@kindex set history save
@item set history save
@itemx set history save on
Record command history in a file, whose name may be specified with the
Stop recording command history in a file.
@cindex history size
+@kindex set history size
@item set history size @var{size}
Set the number of commands which @value{GDBN} keeps in its history list.
This defaults to the value of the environment variable
@end table
@table @code
-@kindex shows
+@kindex show commands
+@cindex show last commands
+@cindex display command history
@item show commands
Display the last ten commands in the command history.
Likewise, you can specify @samp{set width 0} to prevent @value{GDBN}
from wrapping its output.
+
+@item set pagination on
+@itemx set pagination off
+@kindex set pagination
+Turn the output pagination on or off; the default is on. Turning
+pagination off is the alternative to @code{set height 0}.
+
+@item show pagination
+@kindex show pagination
+Show the current pagination mode.
@end table
@node Numbers
example, any of
@smallexample
-set radix 012
-set radix 10.
-set radix 0xa
+set input-radix 012
+set input-radix 10.
+set input-radix 0xa
@end smallexample
@noindent
-sets the base to decimal. On the other hand, @samp{set radix 10}
-leaves the radix unchanged no matter what it was.
+sets the input base to decimal. On the other hand, @samp{set input-radix 10}
+leaves the input radix unchanged, no matter what it was.
@kindex set output-radix
@item set output-radix @var{base}
@kindex show output-radix
@item show output-radix
Display the current default base for numeric display.
+
+@item set radix @r{[}@var{base}@r{]}
+@itemx show radix
+@kindex set radix
+@kindex show radix
+These commands set and show the default base for both input and output
+of numbers. @code{set radix} sets the radix of input and output to
+the same base; without an argument, it resets the radix back to its
+default value of 10.
+
@end table
@node ABI
@item set coerce-float-to-double off
Arguments of type @code{float} will be passed directly to unprototyped
functions.
+
+@kindex show coerce-float-to-double
+@item show coerce-float-to-double
+Show the current setting of promoting @code{float} to @code{double}.
@end table
@kindex set cp-abi
@node Messages/Warnings
@section Optional warnings and messages
+@cindex verbose operation
+@cindex optional warnings
By default, @value{GDBN} is silent about its inner workings. If you are
running on a slow machine, you may want to use the @code{set verbose}
command. This makes @value{GDBN} tell you when it does a lengthy
not its documentation). If no @var{commandname} is given, display the
definitions for all user-defined commands.
+@cindex infinite recusrion in user-defined commands
@kindex show max-user-call-depth
@kindex set max-user-call-depth
@item show max-user-call-depth
@item set annotate @var{level}
The @value{GDB} command @code{set annotate} sets the level of
annotations to the specified @var{level}.
+
+@item show annotate
+@kindex show annotate
+Show the current annotation level.
@end table
This chapter describes level 3 annotations.
@end table
+The following command is useful for non-interactive invocations of
+@value{GDBN}, such as in the test suite.
+
+@table @code
+@item set watchdog @var{nsec}
+@kindex set watchdog
+@cindex watchdog timer
+@cindex timeout for commands
+Set the maximum number of seconds @value{GDBN} will wait for the
+target operation to finish. If this time expires, @value{GDBN}
+reports and error and the command is aborted.
+
+@item show watchdog
+Show the current setting of the target wait timeout.
+@end table
@node Remote Protocol
@appendix @value{GDBN} Remote Serial Protocol
The following table provides a complete list of all currently defined
@var{command}s and their corresponding response @var{data}.
+@xref{File-I/O remote protocol extension}, for details about the File
+I/O extension of the remote protocol.
@table @r
@node General Query Packets
@section General Query Packets
+@cindex remote query requests
The following set and query packets have already been defined.
@table @r
@item @code{q}@code{C} --- current thread
-
+@cindex current thread, remote request
+@cindex @code{qC} packet
Return the current thread id.
Reply:
@end table
@item @code{q}@code{fThreadInfo} -- all thread ids
-
+@cindex list active threads, remote request
+@cindex @code{qfThreadInfo} packet
@code{q}@code{sThreadInfo}
Obtain a list of active thread ids from the target (OS). Since there
with @code{l} (lower-case el, for @code{'last'}).
@item @code{q}@code{ThreadExtraInfo}@code{,}@var{id} --- extra thread info
-
+@cindex thread attributes info, remote request
+@cindex @code{qThreadExtraInfo} packet
Where @var{id} is a thread-id in big-endian hex. Obtain a printable
string description of a thread's attributes from the target OS. This
string may contain anything that the target OS thinks is interesting for
@end table
@item @code{q}@code{CRC:}@var{addr}@code{,}@var{length} --- compute CRC of memory block
-
+@cindex CRC of memory block, remote request
+@cindex @code{qCRC} packet
Reply:
@table @samp
@item @code{E}@var{NN}
@end table
@item @code{q}@code{Offsets} --- query sect offs
-
+@cindex section offsets, remote request
+@cindex @code{qOffsets} packet
Get section offsets that the target used when re-locating the downloaded
image. @emph{Note: while a @code{Bss} offset is included in the
response, @value{GDBN} ignores this and instead applies the @code{Data}
@end table
@item @code{q}@code{P}@var{mode}@var{threadid} --- thread info request
-
+@cindex thread information, remote request
+@cindex @code{qP} packet
Returns information on @var{threadid}. Where: @var{mode} is a hex
encoded 32 bit mode; @var{threadid} is a hex encoded 64 bit thread ID.
See @code{remote.c:remote_unpack_thread_info_response()}.
@item @code{q}@code{Rcmd,}@var{command} --- remote command
-
+@cindex execute remote command, remote request
+@cindex @code{qRcmd} packet
@var{command} (hex encoded) is passed to the local interpreter for
execution. Invalid commands should be reported using the output string.
Before the final result packet, the target may also respond with a
@item @samp{}
When @samp{q}@samp{Rcmd} is not recognized.
@end table
-
+z
@item @code{qSymbol::} --- symbol lookup
-
+@cindex symbol lookup, remote request
+@cindex @code{qSymbol} packet
Notify the target that @value{GDBN} is prepared to serve symbol lookup
requests. Accept requests from the target for the values of symbols.
@end table
@item @code{qPart}:@var{object}:@code{read}:@var{annex}:@var{offset},@var{length} --- read special data
-
+@cindex read special object, remote request
+@cindex @code{qPart} packet
Read uninterpreted bytes from the target's special data area
identified by the keyword @code{object}.
Request @var{length} bytes starting at @var{offset} bytes into the data.
@table @asis
@item @code{qPart}:@code{auxv}:@code{read}::@var{offset},@var{length}
-Access the target's @dfn{auxiliary vector}. @xref{Auxiliary Vector}.
+Access the target's @dfn{auxiliary vector}. @xref{Auxiliary Vector},
+and see @ref{Remote configuration, read-aux-vector-packet}.
Note @var{annex} must be empty.
@end table
@end table
@item @code{qPart}:@var{object}:@code{write}:@var{annex}:@var{offset}:@var{data@dots{}}
-
+@cindex write data into object, remote request
Write uninterpreted bytes into the target's special data area
identified by the keyword @code{object},
starting at @var{offset} bytes into the data.
the stub must respond with an empty packet.
@item @code{qGetTLSAddr}:@var{thread-id},@var{offset},@var{lm} --- get thread local storage address
-
+@cindex get thread-local storage address, remote request
+@cindex @code{qGetTLSAddr} packet
Fetch the address associated with thread local storage specified
by @var{thread-id}, @var{offset}, and @var{lm}.
@subsection File-I/O Overview
@cindex file-i/o overview
-The File I/O remote protocol extension (short: File-I/O) allows the
-target to use the hosts file system and console I/O when calling various
+The @dfn{File I/O remote protocol extension} (short: File-I/O) allows the
+target to use the host's file system and console I/O when calling various
system calls. System calls on the target system are translated into a
remote protocol packet to the host system which then performs the needed
actions and returns with an adequate response packet to the target system.
This simulates file system operations even on targets that lack file systems.
The protocol is defined host- and target-system independent. It uses
-it's own independent representation of datatypes and values. Both,
+its own independent representation of datatypes and values. Both,
@value{GDBN} and the target's @value{GDBN} stub are responsible for
translating the system dependent values into the unified protocol values
when data is transmitted.
@cindex isatty call, file-i/o protocol
A special case in this protocol is the library call @code{isatty} which
-is implemented as it's own call inside of this protocol. It returns
+is implemented as its own call inside of this protocol. It returns
1 to the target if the file descriptor given as parameter is attached
to the @value{GDBN} console, 0 otherwise. Implementing through system calls
would require implementing @code{ioctl} and would be more complex than
@cindex system call, file-i/o protocol
The other special case in this protocol is the @code{system} call which
-is implemented as it's own call, too. @value{GDBN} is taking over the full
+is implemented as its own call, too. @value{GDBN} is taking over the full
task of calling the necessary host calls to perform the @code{system}
call. The return value of @code{system} is simplified before it's returned
to the target. Basically, the only signal transmitted back is @code{EINTR}
in case the user pressed @kbd{Ctrl-C}. Otherwise the return value consists
entirely of the exit status of the called command.
-Due to security concerns, the @code{system} call is refused to be called
-by @value{GDBN} by default. The user has to allow this call explicitly by
-entering
+Due to security concerns, the @code{system} call is by default refused
+by @value{GDBN}. The user has to allow this call explicitly with the
+@kbd{set remote system-call-allowed 1} command.
-@table @samp
-@kindex set remote system-call-allowed 1
-@item @code{set remote system-call-allowed 1}
-@end table
-
-Disabling the @code{system} call is done by
-
-@table @samp
-@kindex set remote system-call-allowed 0
-@item @code{set remote system-call-allowed 0}
-@end table
-
-The current setting is shown by typing
+@table @code
+@item set remote system-call-allowed
+@kindex set remote system-call-allowed
+Control whether to allow the @code{system} calls in the File I/O
+protocol for the remote target. The default is zero (disabled).
-@table @samp
+@item show remote system-call-allowed
@kindex show remote system-call-allowed
-@item @code{show remote system-call-allowed}
+Show the current setting of system calls for the remote File I/O
+protocol.
@end table
@node List of supported calls
projects / deliverable / binutils-gdb.git / commitdiff
