\input texinfo @c -*-texinfo-*-
@c Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,
-@c 1999, 2000, 2001, 2002, 2003, 2004
+@c 1999, 2000, 2001, 2002, 2003, 2004, 2005
@c Free Software Foundation, Inc.
@c
@c %**start of header
Version @value{GDBVN}.
Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,@*
- 1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc.
+ 1999, 2000, 2001, 2002, 2003, 2004, 2005@*
+ 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.1 or
@vskip 0pt plus 1filll
Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995,
-1996, 1998, 1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc.
+1996, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005
+Free Software Foundation, Inc.
@sp 2
Published by the Free Software Foundation @*
59 Temple Place - Suite 330, @*
This is the @value{EDITION} Edition, for @value{GDBN} Version
@value{GDBVN}.
-Copyright (C) 1988-2004 Free Software Foundation, Inc.
+Copyright (C) 1988-2005 Free Software Foundation, Inc.
@menu
* Summary:: Summary of @value{GDBN}
@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
Set the line speed (baud rate or bits per second) of any serial
interface used by @value{GDBN} for remote debugging.
+@item -l @var{timeout}
+@cindex @code{-l}
+Set the timeout (in seconds) of any communication used by @value{GDBN}
+for remote debugging.
+
@item -tty @var{device}
@itemx -t @var{device}
@cindex @code{--tty}
@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]
@kindex apropos
@item apropos @var{args}
-The @code{apropos @var{args}} command searches through all of the @value{GDBN}
+The @code{apropos} command searches through all of the @value{GDBN}
commands, and their documentation, for the regular expression specified in
@var{args}. It prints out all matches found. For example:
@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
@value{GDBN}.
@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}.
@kindex show warranty
+@kindex info warranty
@item show warranty
+@itemx info warranty
Display the @sc{gnu} ``NO WARRANTY'' statement, or a warranty,
if your version of @value{GDBN} comes with one.
breakpoint at the beginning of the main procedure and then invoking
the @samp{run} command.
-Some programs contain an elaboration phase where some startup code is
-executed before the main program is called. This depends on the
-languages used to write your program. In C@t{++} for instance,
+@cindex elaboration phase
+Some programs contain an @dfn{elaboration} phase where some startup code is
+executed before the main procedure is called. This depends on the
+languages used to write your program. In C@t{++}, for instance,
constructors for static and global objects are executed before
@code{main} is called. It is therefore possible that the debugger stops
before reaching the main procedure. However, the temporary breakpoint
@table @code
@kindex cd
+@cindex change working directory
@item cd @var{directory}
Set the @value{GDBN} working directory to @var{directory}.
This command attaches to a running process---one that was started
outside @value{GDBN}. (@code{info files} shows your active
targets.) The command takes as argument a process ID. The usual way to
-find out the process-id of a Unix process is with the @code{ps} utility,
+find out the @var{process-id} of a Unix process is with the @code{ps} utility,
or with the @samp{jobs -l} shell command.
@code{attach} does not repeat if you press @key{RET} a second time after
program. @value{GDBN} displays for each thread (in this order):
@enumerate
-@item the thread number assigned by @value{GDBN}
+@item
+the thread number assigned by @value{GDBN}
-@item the target system's thread identifier (@var{systag})
+@item
+the target system's thread identifier (@var{systag})
-@item the current stack frame summary for that thread
+@item
+the current stack frame summary for that thread
@end enumerate
@noindent
@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
should stop by line number, function name or exact address in the
program.
-In HP-UX, SunOS 4.x, SVR4, and Alpha OSF/1 configurations, you can set
-breakpoints in shared libraries before the executable is run. There is
-a minor limitation on HP-UX systems: you must wait until the executable
-is run in order to set breakpoints in shared library routines that are
-not called directly by the program (for example, routines that are
-arguments in a @code{pthread_create} call).
+On some systems, you can set breakpoints in shared libraries before
+the executable is run. There is a minor limitation on HP-UX systems:
+you must wait until the executable is run in order to set breakpoints
+in shared library routines that are not called directly by the program
+(for example, routines that are arguments in a @code{pthread_create}
+call).
@cindex watchpoints
@cindex memory tracing
have this support. The main purpose of this is EPROM/ROM code
debugging, so you can set a breakpoint at an instruction without
changing the instruction. This can be used with the new trap-generation
-provided by SPARClite DSU and some x86-based targets. These targets
+provided by SPARClite DSU and most x86-based targets. These targets
will generate traps when a program accesses some data or instruction
address that is assigned to the debug registers. However the hardware
breakpoint registers can take a limited number of breakpoints. For
@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
@subsection Setting watchpoints
@cindex setting watchpoints
-@cindex software watchpoints
-@cindex hardware watchpoints
You can use a watchpoint to stop execution whenever the value of an
expression changes, without having to predict a particular place where
this may happen.
+@cindex software watchpoints
+@cindex hardware watchpoints
Depending on your system, watchpoints may be implemented in software or
hardware. @value{GDBN} does software watchpointing by single-stepping your
program and testing the variable's value each time, which is hundreds of
catch errors where you have no clue what part of your program is the
culprit.)
-On some systems, such as HP-UX, @sc{gnu}/Linux and some other x86-based targets,
-@value{GDBN} includes support for
-hardware watchpoints, which do not slow down the running of your
-program.
+On some systems, such as HP-UX, @sc{gnu}/Linux and most other
+x86-based targets, @value{GDBN} includes support for hardware
+watchpoints, which do not slow down the running of your program.
@table @code
@kindex watch
@kindex rwatch
@item rwatch @var{expr}
-Set a watchpoint that will break when watch @var{expr} is read by the program.
+Set a watchpoint that will break when the value of @var{expr} is read
+by the program.
@kindex awatch
@item awatch @var{expr}
-Set a watchpoint that will break when @var{expr} is either read or written into
-by the program.
+Set a watchpoint that will break when @var{expr} is either read from
+or written into by the program.
@kindex info watchpoints
@item info watchpoints
This command prints a list of watchpoints, breakpoints, and catchpoints;
-it is the same as @code{info break}.
+it is the same as @code{info break} (@pxref{Set Breaks}).
@end table
@value{GDBN} sets a @dfn{hardware watchpoint} if possible. Hardware
value at the exact instruction where the change occurs. If @value{GDBN}
cannot set a hardware watchpoint, it sets a software watchpoint, which
executes more slowly and reports the change in value at the next
-statement, not the instruction, after the change occurs.
+@emph{statement}, not the instruction, after the change occurs.
+
+@vindex can-use-hw-watchpoints
+@cindex use only software watchpoints
+You can force @value{GDBN} to use only software watchpoints with the
+@kbd{set can-use-hw-watchpoints 0} command. With this variable set to
+zero, @value{GDBN} will never try to use hardware watchpoints, even if
+the underlying system supports them. (Note that hardware-assisted
+watchpoints that were set @emph{before} setting
+@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
@item clear @var{function}
@itemx clear @var{filename}:@var{function}
-Delete any breakpoints set at entry to the function @var{function}.
+Delete any breakpoints set at entry to the named @var{function}.
@item clear @var{linenum}
@itemx clear @var{filename}:@var{linenum}
-Delete any breakpoints set at or within the code of the specified line.
+Delete any breakpoints set at or within the code of the specified
+@var{linenum} of the specified @var{filename}.
@cindex delete breakpoints
@kindex delete
@item enable @r{[}breakpoints@r{]} delete @var{range}@dots{}
Enable the specified breakpoints to work once, then die. @value{GDBN}
deletes any of these breakpoints as soon as your program stops there.
+Breakpoints set by the @code{tbreak} command start out in this state.
@end table
@c FIXME: I think the following ``Except for [...] @code{tbreak}'' is
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
@kindex until
@kindex u @r{(@code{until})}
+@cindex run until specified location
@item until
@itemx u
Continue running until a source line past the current line, in the
@kindex advance @var{location}
@itemx advance @var{location}
-Continue running the program up to the given location. An argument is
-required, anything of the same form as arguments for the @code{break}
+Continue running the program up to the given @var{location}. An argument is
+required, which should be of the same form as arguments for the @code{break}
command. Execution will also stop upon exit from the current stack
frame. This command is similar to @code{until}, but @code{advance} will
not skip over recursive function calls, and the target location doesn't
@table @code
@kindex info signals
+@kindex info handle
@item info signals
@itemx info handle
Print a table of all the kinds of signals and how @value{GDBN} has been told to
@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}
@node Backtrace
@section Backtraces
-@cindex backtraces
-@cindex tracebacks
-@cindex stack traces
+@cindex traceback
+@cindex call stack traces
A backtrace is a summary of how your program got where it is. It shows one
line per frame, for many frames, starting with the currently executing
frame (frame zero), followed by its caller (frame one), and on up the
value, indicating that your program has stopped at the beginning of the
code for line @code{993} of @code{builtin.c}.
+@cindex backtrace beyond @code{main} function
+@cindex program entry point
+@cindex startup code, and backtrace
Most programs have a standard user entry point---a place where system
libraries and startup code transition into user code. For C this is
@code{main}. When @value{GDBN} finds the entry function in a backtrace
@kindex show backtrace
Display the current user entry point backtrace policy.
+@item set backtrace past-entry
+@itemx set backtrace past-entry on
+Backtraces will continue past the internal entry point of an application.
+This entry point is encoded by the linker when the application is built,
+and is likely before the user entry point @code{main} (or equivalent) is called.
+
+@item set backtrace past-entry off
+Backtraces will stop when they encouter the internal entry point of an
+application. This is the default.
+
+@item show backtrace past-entry
+Display the current internal entry point backtrace policy.
+
@item set backtrace limit @var{n}
@itemx set backtrace limit 0
@cindex backtrace limit
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}:
@node Search
@section Searching source files
@cindex searching source files
-@kindex reverse-search
There are two commands for searching through the current source file for a
regular expression.
synonym @samp{search @var{regexp}} or abbreviate the command name as
@code{fo}.
+@kindex reverse-search
@item reverse-search @var{regexp}
The command @samp{reverse-search @var{regexp}} checks each line, starting
with the one before the last line listed and going backward, for a match
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
* Registers:: Registers
* Floating Point Hardware:: Floating point hardware
* Vector Unit:: Vector Unit
-* Auxiliary Vector:: Auxiliary data provided by operating system
+* OS Information:: Auxiliary data provided by operating system
* Memory Region Attributes:: Memory region attributes
* Dump/Restore Files:: Copy between memory and a file
+* Core File Generation:: Cause a program dump its core
* Character Sets:: Debugging programs that use a different
character set than GDB does
+* Caching Remote Data:: Data caching for remote targets
@end menu
@node Expressions
are from the last memory unit printed; this is not the same as the last
address printed if several units were printed on the last line of output.
+@cindex remote memory comparison
+@cindex verify remote memory image
+When you are debugging a program running on a remote target machine
+(@pxref{Remote}), you may wish to verify the program's image in the
+remote machine's memory against the executable file you downloaded to
+the target. The @code{compare-sections} command is provided for such
+situations.
+
+@table @code
+@kindex compare-sections
+@item compare-sections @r{[}@var{section-name}@r{]}
+Compare the data of a loadable section @var{section-name} in the
+executable file of the program being debugged with the same section in
+the remote machine's memory, and report any mismatches. With no
+arguments, compares all loadable sections. This command's
+availability depends on the target's support for the @code{"qCRC"}
+remote request.
+@end table
+
@node Auto Display
@section Automatic display
@cindex automatic display
@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
@cindex C@t{++} symbol decoding style
@cindex symbol decoding style, C@t{++}
+@kindex set demangle-style
@item set demangle-style @var{style}
Choose among several encoding schemes used by different compilers to
represent C@t{++} names. The choices for @var{style} are currently:
@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}.
layout vary depending on the hardware.
@end table
-@node Auxiliary Vector
-@section Operating system auxiliary vector
+@node OS Information
+@section Operating system auxiliary information
+@cindex OS information
+
+@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
startup. This is akin to the arguments and environment that you
specify for a program, but contains a system-dependent variety of
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
an unrecognized tag.
@end table
+
@node Memory Region Attributes
@section Memory region attributes
@cindex memory region attributes
@table @code
@kindex mem
@item mem @var{lower} @var{upper} @var{attributes}@dots{}
-Define memory region bounded by @var{lower} and @var{upper} with
-attributes @var{attributes}@dots{}. Note that @var{upper} == 0 is a
-special case: it is treated as the the target's maximum memory address.
+Define a memory region bounded by @var{lower} and @var{upper} with
+attributes @var{attributes}@dots{}, and add it to the list of regions
+monitored by @value{GDBN}. Note that @var{upper} == 0 is a special
+case: it is treated as the the target's maximum memory address.
(0xffff on 16 bit targets, 0xffffffff on 32 bit targets, etc.)
@kindex delete mem
@item delete mem @var{nums}@dots{}
-Remove memory regions @var{nums}@dots{}.
+Remove memory regions @var{nums}@dots{} from the list of regions
+monitored by @value{GDBN}.
@kindex disable mem
@item disable mem @var{nums}@dots{}
-Disable memory regions @var{nums}@dots{}.
+Disable monitoring of memory regions @var{nums}@dots{}.
A disabled memory region is not forgotten.
It may be enabled again later.
@kindex enable mem
@item enable mem @var{nums}@dots{}
-Enable memory regions @var{nums}@dots{}.
+Enable monitoring of memory regions @var{nums}@dots{}.
@kindex info mem
@item info mem
Print a table of all defined memory regions, with the following columns
-for each region.
+for each region:
@table @emph
@item Memory Region Number
@item append @r{[}binary@r{]} memory @var{filename} @var{start_addr} @var{end_addr}
@itemx append @r{[}binary@r{]} value @var{filename} @var{expr}
Append the contents of memory from @var{start_addr} to @var{end_addr},
-or the value of @var{expr}, to @var{filename}, in raw binary form.
+or the value of @var{expr}, to the file @var{filename}, in raw binary form.
(@value{GDBN} can only append data to files in raw binary form.)
@kindex restore
@end table
+@node Core File Generation
+@section How to Produce a Core File from Your Program
+@cindex dump core from inferior
+
+A @dfn{core file} or @dfn{core dump} is a file that records the memory
+image of a running process and its process status (register values
+etc.). Its primary use is post-mortem debugging of a program that
+crashed while it ran outside a debugger. A program that crashes
+automatically produces a core file, unless this feature is disabled by
+the user. @xref{Files}, for information on invoking @value{GDBN} in
+the post-mortem debugging mode.
+
+Occasionally, you may wish to produce a core file of the program you
+are debugging in order to preserve a snapshot of its state.
+@value{GDBN} has a special command for that.
+
+@table @code
+@kindex gcore
+@kindex generate-core-file
+@item generate-core-file [@var{file}]
+@itemx gcore [@var{file}]
+Produce a core dump of the inferior process. The optional argument
+@var{file} specifies the file name where to put the core dump. If not
+specified, the file name defaults to @file{core.@var{pid}}, where
+@var{pid} is the inferior process ID.
+
+Note that this command is implemented only for some systems (as of
+this writing, @sc{gnu}/Linux, FreeBSD, Solaris, Unixware, and S390).
+@end table
+
@node Character Sets
@section Character Sets
@cindex character sets
The @sc{ibm1047} character set uses the number 78 to encode the @samp{+}
character.
+@node Caching Remote Data
+@section Caching Data of Remote Targets
+@cindex caching data of remote targets
+
+@value{GDBN} can cache data exchanged between the debugger and a
+remote target (@pxref{Remote}). Such caching generally improves
+performance, because it reduces the overhead of the remote protocol by
+bundling memory reads and writes into large chunks. Unfortunately,
+@value{GDBN} does not currently know anything about volatile
+registers, and thus data caching will produce incorrect results when
+volatile registers are in use.
+
+@table @code
+@kindex set remotecache
+@item set remotecache on
+@itemx set remotecache off
+Set caching state for remote targets. When @code{ON}, use data
+caching. By default, this option is @code{OFF}.
+
+@kindex show remotecache
+@item show remotecache
+Show the current state of data caching for remote targets.
+
+@kindex info dcache
+@item info dcache
+Print the information about the data cache performance. The
+information displayed includes: the dcache width and depth; and for
+each cache line, how many times it was referenced, and its data and
+state (dirty, bad, ok, etc.). This command is useful for debugging
+the data cache operation.
+@end table
+
@node Macros
@chapter C Preprocessor Macros
not parse the result, @var{expression} need not be a valid expression;
it can be any string of tokens.
+@kindex macro exp1
@item macro expand-once @var{expression}
@itemx macro exp1 @var{expression}
@cindex expand macro once
above; it cannot remove definitions present in the program being
debugged.
+@kindex macro list
+@item macro list
+@i{(This command is not yet implemented.)} List all the macros
+defined using the @code{macro define} command.
@end table
@cindex macros, example of debugging with
@table @code
@kindex info tracepoints
+@kindex info tp
@cindex information about tracepoints
@item info tracepoints @r{[}@var{num}@r{]}
Display information about the tracepoint @var{num}. If you don't specify
This command takes no arguments. It ends the trace experiment, and
stops collecting data.
-@strong{Note:} a trace experiment and data collection may stop
+@strong{Note}: a trace experiment and data collection may stop
automatically if any tracepoint's passcount is reached
(@pxref{Tracepoint Passcounts}), or if the trace buffer becomes full.
* 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}
-Set source files with extension @var{.ext} to be assumed to be in
-the source language @var{language}.
+@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,
@menu
* 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
@cindex Objective-C
This section provides information about some commands and command
-options that are useful for debugging Objective-C code.
+options that are useful for debugging Objective-C code. See also
+@ref{Symbols, info classes}, and @ref{Symbols, info selectors}, for a
+few more commands specific to Objective-C support.
@menu
* Method Names in Commands::
@node The Print Command with Objective-C
@subsubsection The Print Command With Objective-C
+@cindex Objective-C, print objects
@kindex print-object
@kindex po @r{(@code{print-object})}
with certain Objective-C libraries that have a particular hook
function, @code{_NSPrintForDebugger}, defined.
-@node Modula-2, Ada, Objective-C, Support
+@node Fortran
+@subsection Fortran
+@cindex Fortran-specific support in @value{GDBN}
+
+@table @code
+@cindex @code{COMMON} blocks, Fortran
+@kindex info common
+@item info common @r{[}@var{common-name}@r{]}
+This command prints the values contained in the Fortran @code{COMMON}
+block whose name is @var{common-name}. With no argument, the names of
+all @code{COMMON} blocks visible at current program location are
+printed.
+@end table
+
+Fortran symbols are usually case-insensitive, so @value{GDBN} by
+default uses case-insensitive matches for Fortran symbols. You can
+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
@cindex Modula-2, @value{GDBN} support
looks up the value of @code{x} in the scope of the file @file{foo.c}.
@table @code
+@cindex case-insensitive symbol names
+@cindex case sensitivity in symbol names
+@kindex set case-sensitive
+@item set case-sensitive on
+@itemx set case-sensitive off
+@itemx set case-sensitive auto
+Normally, when @value{GDBN} looks up symbols, it matches their names
+with case sensitivity determined by the current source language.
+Occasionally, you may wish to control that. The command @code{set
+case-sensitive} lets you do that by specifying @code{on} for
+case-sensitive matches or @code{off} for case-insensitive ones. If
+you specify @code{auto}, case sensitivity is reset to the default
+suitable for the source language. The default is case-sensitive
+matches for all languages except for Fortran, for which the default is
+case-insensitive matches.
+
+@kindex show case-sensitive
+@item show case-sensitive
+This command shows the current setting of case sensitivity for symbols
+lookups.
+
@kindex info address
@cindex address of a symbol
@item info address @var{symbol}
@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
@kindex info types
@item info types @var{regexp}
@itemx info types
-Print a brief description of all types whose names match @var{regexp}
-(or all types in your program, if you supply no argument). Each
-complete typename is matched as though it were a complete line; thus,
-@samp{i type value} gives information on all types in your program whose
-names include the string @code{value}, but @samp{i type ^value$} gives
-information only on types whose complete name is @code{value}.
+Print a brief description of all types whose names match the regular
+expression @var{regexp} (or all types in your program, if you supply
+no argument). Each complete typename is matched as though it were a
+complete line; thus, @samp{i type value} gives information on all
+types in your program whose names include the string @code{value}, but
+@samp{i type ^value$} gives information only on types whose complete
+name is @code{value}.
This command differs from @code{ptype} in two ways: first, like
@code{whatis}, it does not print a detailed description; second, it
@kindex info scope
@cindex local variables
-@item info scope @var{addr}
+@item info scope @var{location}
List all the variables local to a particular scope. This command
-accepts a location---a function name, a source line, or an address
-preceded by a @samp{*}, and prints all the variables local to the
-scope defined by that location. For example:
+accepts a @var{location} argument---a function name, a source line, or
+an address preceded by a @samp{*}, and prints all the variables local
+to the scope defined by that location. For example:
@smallexample
(@value{GDBP}) @b{info scope command_line_handler}
@var{regexp}.
@kindex info classes
+@cindex Objective-C, classes and selectors
@item info classes
@itemx info classes @var{regexp}
Display all Objective-C classes in your program, or
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
@node Calling
@section Calling program functions
+@table @code
@cindex calling functions
+@cindex inferior functions, calling
+@item print @var{expr}
+Evaluate the expression @var{expr} and display the resuling value.
+@var{expr} may include calls to functions in the program being
+debugged.
+
@kindex call
-@table @code
@item call @var{expr}
Evaluate the expression @var{expr} without displaying @code{void}
returned values.
-@end table
You can use this variant of the @code{print} command if you want to
-execute a function from your program, but without cluttering the output
-with @code{void} returned values. If the result is not void, it
-is printed and saved in the value history.
+execute a function from your program that does not return anything
+(a.k.a.@: @dfn{a void function}), but without cluttering the output
+with @code{void} returned values that @value{GDBN} will otherwise
+print. If the result is not void, it is printed and saved in the
+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
+the type information, including the types of the function arguments,
+which causes @value{GDBN} to call the inferior function incorrectly.
+As a result, the called function will function erroneously and may
+even crash. A solution to that is to use the name of the aliased
+function instead.
@node Patching
@section Patching programs
@var{filename}. If so, @value{GDBN} maps in the symbol table from
@file{@var{filename}.syms}, starting up more quickly. See the
descriptions of the file options @samp{-mapped} and @samp{-readnow}
-(available on the command line, and with the commands @code{file},
-@code{symbol-file}, or @code{add-symbol-file}, described below),
-for more information.
+(available on the command line, see @ref{File Options, , -readnow},
+and with the commands @code{file}, @code{symbol-file}, or
+@code{add-symbol-file}, described below), for more information.
@item file
@code{file} with no argument makes @value{GDBN} discard any information it
@c files.
@kindex core-file
-@item core-file @r{[} @var{filename} @r{]}
+@item core-file @r{[}@var{filename}@r{]}
@itemx core
Specify the whereabouts of a core dump file to be used as the ``contents
of memory''. Traditionally, core files contain only some parts of the
the @code{symbol-file} command, to change how @value{GDBN} manages the symbol
table information for @var{filename}.
-@kindex add-shared-symbol-file
-@item add-shared-symbol-file
-The @code{add-shared-symbol-file} command can be used only under Harris' CXUX
-operating system for the Motorola 88k. @value{GDBN} automatically looks for
-shared libraries, however if @value{GDBN} does not find yours, you can run
-@code{add-shared-symbol-file}. It takes no arguments.
+@kindex add-shared-symbol-files
+@kindex assf
+@item add-shared-symbol-files @var{library-file}
+@itemx assf @var{library-file}
+The @code{add-shared-symbol-files} command can currently be used only
+in the Cygwin build of @value{GDBN} on MS-Windows OS, where it is an
+alias for the @code{dll-symbols} command (@pxref{Cygwin Native}).
+@value{GDBN} automatically looks for shared libraries, however if
+@value{GDBN} does not find yours, you can invoke
+@code{add-shared-symbol-files}. It takes one argument: the shared
+library's file name. @code{assf} is a shorthand alias for
+@code{add-shared-symbol-files}.
@kindex section
-@item section
-The @code{section} command changes the base address of section SECTION of
-the exec file to ADDR. This can be used if the exec file does not contain
-section addresses, (such as in the a.out format), or when the addresses
-specified in the file itself are wrong. Each section must be changed
-separately. The @code{info files} command, described below, lists all
-the sections and their addresses.
+@item section @var{section} @var{addr}
+The @code{section} command changes the base address of the named
+@var{section} of the exec file to @var{addr}. This can be used if the
+exec file does not contain section addresses, (such as in the
+@code{a.out} format), or when the addresses specified in the file
+itself are wrong. Each section must be changed separately. The
+@code{info files} command, described below, lists all the sections and
+their addresses.
@kindex info files
@kindex info target
@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 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.
is @code{off}, symbols must be loaded manually, using the
@code{sharedlibrary} command. The default value is @code{on}.
+@cindex memory used for symbol tables
+If your program uses lots of shared libraries with debug info that
+takes large amounts of memory, you can decrease the @value{GDBN}
+memory footprint by preventing it from automatically loading the
+symbols from shared libraries. To that end, type @kbd{set
+auto-solib-add off} before running the inferior, then load each
+library whose debug symbols you do need with @kbd{sharedlibrary
+@var{regexp}}, where @var{regexp} is a regular expresion that matches
+the libraries whose symbols you want to be loaded.
+
@kindex show auto-solib-add
@item show auto-solib-add
Display the current autoloading mode.
Display the current autoloading size threshold, in megabytes.
@end table
+Sometimes you may wish that @value{GDBN} stops and gives you control
+when any of shared library events happen. Use the @code{set
+stop-on-solib-events} command for this:
+
+@table @code
+@item set stop-on-solib-events
+@kindex set stop-on-solib-events
+This command controls whether @value{GDBN} should give you control
+when the dynamic linker notifies it about some shared library event.
+The most common event of interest is loading or unloading of a new
+shared library.
+
+@item show stop-on-solib-events
+@kindex show stop-on-solib-events
+Show whether @value{GDBN} stops and gives you control when shared
+library events happen.
+@end table
+
Shared libraries are also supported in many cross or remote debugging
configurations. A copy of the target's libraries need to be present on the
host system; they need to be the same as the target libraries, although the
@chapter Specifying a Debugging Target
@cindex debugging target
-@kindex target
-
A @dfn{target} is the execution environment occupied by your program.
Often, @value{GDBN} runs in the same host environment as your program;
command to specify one of the target types configured for @value{GDBN}
(@pxref{Target Commands, ,Commands for managing targets}).
+@cindex target architecture
+It is possible to build @value{GDBN} for several different @dfn{target
+architectures}. When @value{GDBN} is built like that, you can choose
+one of the available architectures with the @kbd{set architecture}
+command.
+
+@table @code
+@kindex set architecture
+@kindex show architecture
+@item set architecture @var{arch}
+This command sets the current target architecture to @var{arch}. The
+value of @var{arch} can be @code{"auto"}, in addition to one of the
+supported architectures.
+
+@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
* Active Targets:: Active targets
* Target Commands:: Commands for managing targets
Different targets are available on different configurations of @value{GDBN};
your configuration may have more or fewer targets.
-Many remote targets require you to download the executable's code
-once you've successfully established a connection.
+Many remote targets require you to download the executable's code once
+you've successfully established a connection. You may wish to control
+various aspects of this process, such as the size of the data chunks
+used by @value{GDBN} to download program parts to the remote target.
+
+@table @code
+@kindex set download-write-size
+@item set download-write-size @var{size}
+Set the write size used when downloading a program. Only used when
+downloading a program onto a remote target. Specify zero or a
+negative value to disable blocked writes. The actual size of each
+transfer is also limited by the size of the target packet and the
+memory cache.
+
+@kindex show download-write-size
+@item show download-write-size
+@kindex show download-write-size
+Show the current value of the write size.
+
+@item set hash
+@kindex set hash@r{, for remote monitors}
+@cindex hash mark while downloading
+This command controls whether a hash mark @samp{#} is displayed while
+downloading a file to the remote monitor. If on, a hash mark is
+displayed after each S-record is successfully downloaded to the
+monitor.
+
+@item show hash
+@kindex show hash@r{, for remote monitors}
+Show the current status of displaying the hash mark.
+
+@item set debug monitor
+@kindex set debug monitor
+@cindex display remote monitor communications
+Enable or disable display of communications messages between
+@value{GDBN} and the remote monitor.
+
+@item show debug monitor
+@kindex show debug monitor
+Show the current status of displaying communications between
+@value{GDBN} and the remote monitor.
+@end table
@table @code
@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
(this instance or another one) to connect and continue debugging. After
the @code{disconnect} command, @value{GDBN} is again free to connect to
another target.
+
+@cindex send command to remote monitor
+@kindex monitor
+@item monitor @var{cmd}
+This command allows you to send commands directly to the remote
+monitor.
@end table
@node Server
@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{OS Information,
+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
* SVR4 Process Information:: SVR4 process information
* DJGPP Native:: Features specific to the DJGPP port
* Cygwin Native:: Features specific to the Cygwin port
+* Hurd Native:: Features specific to @sc{gnu} Hurd
+* Neutrino:: Features specific to QNX Neutrino
@end menu
@node HP-UX
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
@table @code
@kindex kvm
@item kvm pcb
-Set current context from pcb address.
+Set current context from the @dfn{Process Control Block} (PCB) address.
@item kvm proc
Set current context from proc address. This command isn't available on
Report on the process IDs related to your program: its own process ID,
the ID of its parent, the process group ID, and the session ID.
@end ignore
+
+@item set procfs-trace
+@kindex set procfs-trace
+@cindex @code{procfs} API calls
+This command enables and disables tracing of @code{procfs} API calls.
+
+@item show procfs-trace
+@kindex show procfs-trace
+Show the current state of @code{procfs} API call tracing.
+
+@item set procfs-file @var{file}
+@kindex set procfs-file
+Tell @value{GDBN} to write @code{procfs} API trace to the named
+@var{file}. @value{GDBN} appends the trace info to the previous
+contents of the file. The default is to display the trace on the
+standard output.
+
+@item show procfs-file
+@kindex show procfs-file
+Show the file to which @code{procfs} API trace is written.
+
+@item proc-trace-entry
+@itemx proc-trace-exit
+@itemx proc-untrace-entry
+@itemx proc-untrace-exit
+@kindex proc-trace-entry
+@kindex proc-trace-exit
+@kindex proc-untrace-entry
+@kindex proc-untrace-exit
+These commands enable and disable tracing of entries into and exits
+from the @code{syscall} interface.
+
+@item info pidlist
+@kindex info pidlist
+@cindex process list, QNX Neutrino
+For QNX Neutrino only, this command displays the list of all the
+processes and all the threads within each process.
+
+@item info meminfo
+@kindex info meminfo
+@cindex mapinfo list, QNX Neutrino
+For QNX Neutrino only, this command displays the list of all mapinfos.
@end table
@node DJGPP Native
This command is supported only with some DPMI servers.
@end table
+In addition to native debugging, the DJGPP port supports remote
+debugging via a serial data link. The following commands are specific
+to remote serial debugging in the DJGPP port of @value{GDBN}.
+
+@table @code
+@kindex set com1base
+@kindex set com1irq
+@kindex set com2base
+@kindex set com2irq
+@kindex set com3base
+@kindex set com3irq
+@kindex set com4base
+@kindex set com4irq
+@item set com1base @var{addr}
+This command sets the base I/O port address of the @file{COM1} serial
+port.
+
+@item set com1irq @var{irq}
+This command sets the @dfn{Interrupt Request} (@code{IRQ}) line to use
+for the @file{COM1} serial port.
+
+There are similar commands @samp{set com2base}, @samp{set com3irq},
+etc.@: for setting the port address and the @code{IRQ} lines for the
+other 3 COM ports.
+
+@kindex show com1base
+@kindex show com1irq
+@kindex show com2base
+@kindex show com2irq
+@kindex show com3base
+@kindex show com3irq
+@kindex show com4base
+@kindex show com4irq
+The related commands @samp{show com1base}, @samp{show com1irq} etc.@:
+display the current settings of the base address and the @code{IRQ}
+lines used by the COM ports.
+@end table
+
+
@node Cygwin Native
@subsection Features for Debugging MS Windows PE executables
@cindex MS Windows debugging
break point within a shared DLL like @file{kernel32.dll} is completely
safe.
+@node Hurd Native
+@subsection Commands specific to @sc{gnu} Hurd systems
+@cindex @sc{gnu} Hurd debugging
+
+This subsection describes @value{GDBN} commands specific to the
+@sc{gnu} Hurd native debugging.
+
+@table @code
+@item set signals
+@itemx set sigs
+@kindex set signals@r{, Hurd command}
+@kindex set sigs@r{, Hurd command}
+This command toggles the state of inferior signal interception by
+@value{GDBN}. Mach exceptions, such as breakpoint traps, are not
+affected by this command. @code{sigs} is a shorthand alias for
+@code{signals}.
+
+@item show signals
+@itemx show sigs
+@kindex show signals@r{, Hurd command}
+@kindex show sigs@r{, Hurd command}
+Show the current state of intercepting inferior's signals.
+
+@item set signal-thread
+@itemx set sigthread
+@kindex set signal-thread
+@kindex set sigthread
+This command tells @value{GDBN} which thread is the @code{libc} signal
+thread. That thread is run when a signal is delivered to a running
+process. @code{set sigthread} is the shorthand alias of @code{set
+signal-thread}.
+
+@item show signal-thread
+@itemx show sigthread
+@kindex show signal-thread
+@kindex show sigthread
+These two commands show which thread will run when the inferior is
+delivered a signal.
+
+@item set stopped
+@kindex set stopped@r{, Hurd command}
+This commands tells @value{GDBN} that the inferior process is stopped,
+as with the @code{SIGSTOP} signal. The stopped process can be
+continued by delivering a signal to it.
+
+@item show stopped
+@kindex show stopped@r{, Hurd command}
+This command shows whether @value{GDBN} thinks the debuggee is
+stopped.
+
+@item set exceptions
+@kindex set exceptions@r{, Hurd command}
+Use this command to turn off trapping of exceptions in the inferior.
+When exception trapping is off, neither breakpoints nor
+single-stepping will work. To restore the default, set exception
+trapping on.
+
+@item show exceptions
+@kindex show exceptions@r{, Hurd command}
+Show the current state of trapping exceptions in the inferior.
+
+@item set task pause
+@kindex set task@r{, Hurd commands}
+@cindex task attributes (@sc{gnu} Hurd)
+@cindex pause current task (@sc{gnu} Hurd)
+This command toggles task suspension when @value{GDBN} has control.
+Setting it to on takes effect immediately, and the task is suspended
+whenever @value{GDBN} gets control. Setting it to off will take
+effect the next time the inferior is continued. If this option is set
+to off, you can use @code{set thread default pause on} or @code{set
+thread pause on} (see below) to pause individual threads.
+
+@item show task pause
+@kindex show task@r{, Hurd commands}
+Show the current state of task suspension.
+
+@item set task detach-suspend-count
+@cindex task suspend count
+@cindex detach from task, @sc{gnu} Hurd
+This command sets the suspend count the task will be left with when
+@value{GDBN} detaches from it.
+
+@item show task detach-suspend-count
+Show the suspend count the task will be left with when detaching.
+
+@item set task exception-port
+@itemx set task excp
+@cindex task exception port, @sc{gnu} Hurd
+This command sets the task exception port to which @value{GDBN} will
+forward exceptions. The argument should be the value of the @dfn{send
+rights} of the task. @code{set task excp} is a shorthand alias.
+
+@item set noninvasive
+@cindex noninvasive task options
+This command switches @value{GDBN} to a mode that is the least
+invasive as far as interfering with the inferior is concerned. This
+is the same as using @code{set task pause}, @code{set exceptions}, and
+@code{set signals} to values opposite to the defaults.
+
+@item info send-rights
+@itemx info receive-rights
+@itemx info port-rights
+@itemx info port-sets
+@itemx info dead-names
+@itemx info ports
+@itemx info psets
+@cindex send rights, @sc{gnu} Hurd
+@cindex receive rights, @sc{gnu} Hurd
+@cindex port rights, @sc{gnu} Hurd
+@cindex port sets, @sc{gnu} Hurd
+@cindex dead names, @sc{gnu} Hurd
+These commands display information about, respectively, send rights,
+receive rights, port rights, port sets, and dead names of a task.
+There are also shorthand aliases: @code{info ports} for @code{info
+port-rights} and @code{info psets} for @code{info port-sets}.
+
+@item set thread pause
+@kindex set thread@r{, Hurd command}
+@cindex thread properties, @sc{gnu} Hurd
+@cindex pause current thread (@sc{gnu} Hurd)
+This command toggles current thread suspension when @value{GDBN} has
+control. Setting it to on takes effect immediately, and the current
+thread is suspended whenever @value{GDBN} gets control. Setting it to
+off will take effect the next time the inferior is continued.
+Normally, this command has no effect, since when @value{GDBN} has
+control, the whole task is suspended. However, if you used @code{set
+task pause off} (see above), this command comes in handy to suspend
+only the current thread.
+
+@item show thread pause
+@kindex show thread@r{, Hurd command}
+This command shows the state of current thread suspension.
+
+@item set thread run
+This comamnd sets whether the current thread is allowed to run.
+
+@item show thread run
+Show whether the current thread is allowed to run.
+
+@item set thread detach-suspend-count
+@cindex thread suspend count, @sc{gnu} Hurd
+@cindex detach from thread, @sc{gnu} Hurd
+This command sets the suspend count @value{GDBN} will leave on a
+thread when detaching. This number is relative to the suspend count
+found by @value{GDBN} when it notices the thread; use @code{set thread
+takeover-suspend-count} to force it to an absolute value.
+
+@item show thread detach-suspend-count
+Show the suspend count @value{GDBN} will leave on the thread when
+detaching.
+
+@item set thread exception-port
+@itemx set thread excp
+Set the thread exception port to which to forward exceptions. This
+overrides the port set by @code{set task exception-port} (see above).
+@code{set thread excp} is the shorthand alias.
+
+@item set thread takeover-suspend-count
+Normally, @value{GDBN}'s thread suspend counts are relative to the
+value @value{GDBN} finds when it notices each thread. This command
+changes the suspend counts to be absolute instead.
+
+@item set thread default
+@itemx show thread default
+@cindex thread default settings, @sc{gnu} Hurd
+Each of the above @code{set thread} commands has a @code{set thread
+default} counterpart (e.g., @code{set thread default pause}, @code{set
+thread default exception-port}, etc.). The @code{thread default}
+variety of commands sets the default thread properties for all
+threads; you can then change the properties of individual threads with
+the non-default commands.
+@end table
+
+
+@node Neutrino
+@subsection QNX Neutrino
+@cindex QNX Neutrino
+
+@value{GDBN} provides the following commands specific to the QNX
+Neutrino target:
+
+@table @code
+@item set debug nto-debug
+@kindex set debug nto-debug
+When set to on, enables debugging messages specific to the QNX
+Neutrino support.
+
+@item show debug nto-debug
+@kindex show debug nto-debug
+Show the current state of QNX Neutrino messages.
+@end table
+
+
@node Embedded OS
@section Embedded Operating Systems
* Sparclite:: Fujitsu Sparclite
* ST2000:: Tandem ST2000
* Z8000:: Zilog Z8000
+* AVR:: Atmel AVR
+* CRIS:: CRIS
+* Super-H:: Renesas Super-H
@end menu
@node ARM
@end table
+@value{GDBN} provides the following ARM-specific commands:
+
+@table @code
+@item set arm disassembler
+@kindex set arm
+This commands selects from a list of disassembly styles. The
+@code{"std"} style is the standard style.
+
+@item show arm disassembler
+@kindex show arm
+Show the current disassembly style.
+
+@item set arm apcs32
+@cindex ARM 32-bit mode
+This command toggles ARM operation mode between 32-bit and 26-bit.
+
+@item show arm apcs32
+Display the current usage of the ARM 32-bit mode.
+
+@item set arm fpu @var{fputype}
+This command sets the ARM floating-point unit (FPU) type. The
+argument @var{fputype} can be one of these:
+
+@table @code
+@item auto
+Determine the FPU type by querying the OS ABI.
+@item softfpa
+Software FPU, with mixed-endian doubles on little-endian ARM
+processors.
+@item fpa
+GCC-compiled FPA co-processor.
+@item softvfp
+Software FPU with pure-endian doubles.
+@item vfp
+VFP co-processor.
+@end table
+
+@item show arm fpu
+Show the current type of the FPU.
+
+@item set arm abi
+This command forces @value{GDBN} to use the specified ABI.
+
+@item show arm abi
+Show the currently used ABI.
+
+@item set debug arm
+Toggle whether to display ARM-specific debugging messages from the ARM
+target support subsystem.
+
+@item show debug arm
+Show whether ARM-specific debugging messages are enabled.
+@end table
+
+
@node H8/300
@subsection Renesas H8/300
@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
@subsection Renesas M32R/D
@table @code
-
@kindex target m32r
@item target m32r @var{dev}
Renesas M32R/D ROM monitor.
@kindex target m32rsdi
@item target m32rsdi @var{dev}
Renesas M32R SDI server, connected via parallel port to the board.
+@end table
+
+The following @value{GDBN} commands are specific to the M32R monitor:
+
+@table @code
+@item set download-path @var{path}
+@kindex set download-path
+@cindex find downloadable @sc{srec} files (M32R)
+Set the default path for finding donwloadable @sc{srec} files.
+
+@item show download-path
+@kindex show download-path
+Show the default path for downloadable @sc{srec} files.
+
+@item set board-address @var{addr}
+@kindex set board-address
+@cindex M32-EVA target board address
+Set the IP address for the M32R-EVA target board.
+
+@item show board-address
+@kindex show board-address
+Show the current IP address of the target board.
+
+@item set server-address @var{addr}
+@kindex set server-address
+@cindex download server address (M32R)
+Set the IP address for the download server, which is the @value{GDBN}'s
+host machine.
+
+@item show server-address
+@kindex show server-address
+Display the IP address of the download server.
+@item upload @r{[}@var{file}@r{]}
+@kindex upload@r{, M32R}
+Upload the specified @sc{srec} @var{file} via the monitor's Ethernet
+upload capability. If no @var{file} argument is given, the current
+executable file is uploaded.
+
+@item tload @r{[}@var{file}@r{]}
+@kindex tload@r{, M32R}
+Test the @code{upload} command.
@end table
@node M68K
@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
+@itemx set mipsfpu auto
@itemx show mipsfpu
@kindex set mipsfpu
@kindex show mipsfpu
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
conditional breakpoint that suspends only after at least 5000
simulated clock ticks.
+@node AVR
+@subsection Atmel AVR
+@cindex AVR
+
+When configured for debugging the Atmel AVR, @value{GDBN} supports the
+following AVR-specific commands:
+
+@table @code
+@item info io_registers
+@kindex info io_registers@r{, AVR}
+@cindex I/O registers (Atmel AVR)
+This command displays information about the AVR I/O registers. For
+each register, @value{GDBN} prints its number and value.
+@end table
+
+@node CRIS
+@subsection CRIS
+@cindex CRIS
+
+When configured for debugging CRIS, @value{GDBN} provides the
+following CRIS-specific commands:
+
+@table @code
+@item set cris-version @var{ver}
+@cindex CRIS version
+Set the current CRIS version to @var{ver}. The CRIS version affects
+register names and sizes. This command is useful in case
+autodetection of the CRIS version fails.
+
+@item show cris-version
+Show the current CRIS version.
+
+@item set cris-dwarf2-cfi
+@cindex DWARF-2 CFI and CRIS
+Set the usage of DWARF-2 CFI for CRIS debugging. The default is off
+if using @code{gcc-cris} whose version is below @code{R59}, otherwise
+on.
+
+@item show cris-dwarf2-cfi
+Show the current state of using DWARF-2 CFI.
+@end table
+
+@node Super-H
+@subsection Renesas Super-H
+@cindex Super-H
+
+For the Renesas Super-H processor, @value{GDBN} provides these
+commands:
+
+@table @code
+@item regs
+@kindex regs@r{, Super-H}
+Show the values of all Super-H registers.
+@end table
+
+
@node Architectures
@section Architectures
all uses of @value{GDBN} with the architecture, both native and cross.
@menu
+* i386::
* A29K::
* Alpha::
* MIPS::
+* HPPA:: HP PA architecture
@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
search for the beginning of a function. A value of @var{0} (the
default) means there is no limit. However, except for @var{0}, the
larger the limit the more bytes @code{heuristic-fence-post} must search
-and therefore the longer it takes to run.
+and therefore the longer it takes to run. You should only need to use
+this command when debugging a stripped executable.
@item show heuristic-fence-post
Display the current limit.
These commands are available @emph{only} when @value{GDBN} is configured
for debugging programs on Alpha or MIPS processors.
+Several MIPS-specific commands are available when debugging MIPS
+programs:
+
+@table @code
+@item set mips saved-gpreg-size @var{size}
+@kindex set mips saved-gpreg-size
+@cindex MIPS GP register size on stack
+Set the size of MIPS general-purpose registers saved on the stack.
+The argument @var{size} can be one of the following:
+
+@table @samp
+@item 32
+32-bit GP registers
+@item 64
+64-bit GP registers
+@item auto
+Use the target's default setting or autodetect the saved size from the
+information contained in the executable. This is the default
+@end table
+
+@item show mips saved-gpreg-size
+@kindex show mips saved-gpreg-size
+Show the current size of MIPS GP registers on the stack.
+
+@item set mips stack-arg-size @var{size}
+@kindex set mips stack-arg-size
+@cindex MIPS stack space for arguments
+Set the amount of stack space reserved for arguments to functions.
+The argument can be one of @code{"32"}, @code{"64"} or @code{"auto"}
+(the default).
+
+@item set mips abi @var{arg}
+@kindex set mips abi
+@cindex set ABI for MIPS
+Tell @value{GDBN} which MIPS ABI is used by the inferior. Possible
+values of @var{arg} are:
+
+@table @samp
+@item auto
+The default ABI associated with the current binary (this is the
+default).
+@item o32
+@item o64
+@item n32
+@item n64
+@item eabi32
+@item eabi64
+@item auto
+@end table
+
+@item show mips abi
+@kindex show mips abi
+Show the MIPS ABI used by @value{GDBN} to debug the inferior.
+
+@item set mipsfpu
+@itemx show mipsfpu
+@xref{MIPS Embedded, set mipsfpu}.
+
+@item set mips mask-address @var{arg}
+@kindex set mips mask-address
+@cindex MIPS addresses, masking
+This command determines whether the most-significant 32 bits of 64-bit
+MIPS addresses are masked off. The argument @var{arg} can be
+@samp{on}, @samp{off}, or @samp{auto}. The latter is the default
+setting, which lets @value{GDBN} determine the correct value.
+
+@item show mips mask-address
+@kindex show mips mask-address
+Show whether the upper 32 bits of MIPS addresses are masked off or
+not.
+
+@item set remote-mips64-transfers-32bit-regs
+@kindex set remote-mips64-transfers-32bit-regs
+This command controls compatibility with 64-bit MIPS targets that
+transfer data in 32-bit quantities. If you have an old MIPS 64 target
+that transfers 32 bits for some registers, like @sc{sr} and @sc{fsr},
+and 64 bits for other registers, set this option to @samp{on}.
+
+@item show remote-mips64-transfers-32bit-regs
+@kindex show remote-mips64-transfers-32bit-regs
+Show the current setting of compatibility with older MIPS 64 targets.
+
+@item set debug mips
+@kindex set debug mips
+This command turns on and off debugging messages for the MIPS-specific
+target code in @value{GDBN}.
+
+@item show debug mips
+@kindex show debug mips
+Show the current setting of MIPS debugging messages.
+@end table
+
+
+@node HPPA
+@subsection HPPA
+@cindex HPPA support
+
+When @value{GDBN} is debugging te HP PA architecture, it provides the
+following special commands:
+
+@table @code
+@item set debug hppa
+@kindex set debug hppa
+THis command determines whether HPPA architecture specific debugging
+messages are to be displayed.
+
+@item show debug hppa
+Show whether HPPA debugging messages are displayed.
+
+@item maint print unwind @var{address}
+@kindex maint print unwind@r{, HPPA}
+This command displays the contents of the unwind table entry at the
+given @var{address}.
+
+@end table
+
@node Controlling GDB
@chapter Controlling @value{GDBN}
@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
@end table
@cindex float promotion
-@kindex set coerce-float-to-double
Generally, the way that an argument of type @code{float} is passed to a
function depends on whether the function is prototyped. For a prototyped
as prototyped, it consults @kbd{set coerce-float-to-double}.
@table @code
+@kindex set coerce-float-to-double
@item set coerce-float-to-double
@itemx set coerce-float-to-double on
Arguments of type @code{float} will be promoted to @code{double} when passed
@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
@section Optional messages about internal happenings
@cindex optional debugging messages
+@value{GDBN} has commands that enable optional debugging messages from
+various @value{GDBN} subsystems; normally these commands are of
+interest to @value{GDBN} maintainers, or when reporting a bug. This
+section documents those commands.
+
@table @code
+@kindex set exec-done-display
+@item set exec-done-display
+Turns on or off the notification of asynchronous commands'
+completion. When on, @value{GDBN} will print a message when an
+asynchronous command finishes its execution. The default is off.
+@kindex show exec-done-display
+@item show exec-done-display
+Displays the current setting of asynchronous command completion
+notification.
@kindex set debug
@cindex gdbarch debugging info
+@cindex architecture debugging info
@item set debug arch
-Turns on or off display of gdbarch debugging info. The default is off
+Turns on or off display of gdbarch debugging info. The default is off
@kindex show debug
@item show debug arch
Displays the current state of displaying gdbarch debugging info.
+@item set debug aix-thread
+@cindex AIX threads
+Display debugging messages about inner workings of the AIX thread
+module.
+@item show debug aix-thread
+Show the current state of AIX thread debugging info display.
@item set debug event
@cindex event debugging info
-Turns on or off display of @value{GDBN} event debugging info. The
+Turns on or off display of @value{GDBN} event debugging info. The
default is off.
@item show debug event
Displays the current state of displaying @value{GDBN} event debugging
info.
@item set debug expression
@cindex expression debugging info
-Turns on or off display of @value{GDBN} expression debugging info. The
-default is off.
+Turns on or off display of debugging info about @value{GDBN}
+expression parsing. The default is off.
@item show debug expression
-Displays the current state of displaying @value{GDBN} expression
-debugging info.
+Displays the current state of displaying debugging info about
+@value{GDBN} expression parsing.
@item set debug frame
@cindex frame debugging info
Turns on or off display of @value{GDBN} frame debugging info. The
@item show debug frame
Displays the current state of displaying @value{GDBN} frame debugging
info.
+@item set debug infrun
+@cindex inferior debugging info
+Turns on or off display of @value{GDBN} debugging info for running the inferior.
+The default is off. @file{infrun.c} contains GDB's runtime state machine used
+for implementing operations such as single-stepping the inferior.
+@item show debug infrun
+Displays the current state of @value{GDBN} inferior debugging.
+@item set debug lin-lwp
+@cindex @sc{gnu}/Linux LWP debug messages
+@cindex Linux lightweight processes
+Turns on or off debugging messages from the Linux LWP debug support.
+@item show debug lin-lwp
+Show the current state of Linux LWP debugging messages.
@item set debug observer
@cindex observer debugging info
Turns on or off display of @value{GDBN} observer debugging. This
@kindex if
@kindex else
@item if
+@itemx else
Takes a single argument, which is an expression to evaluate.
It is followed by a series of commands that are executed
only if the expression is true (nonzero).
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
pre-execution hooks, for the same command.
It is valid for a hook to call the command which it hooks. If this
-occurs, the hook is not re-executed, thereby avoiding infinte recursion.
+occurs, the hook is not re-executed, thereby avoiding infinite recursion.
@c It would be nice if hookpost could be passed a parameter indicating
@c if the command it hooks executed properly or not. FIXME!
subprocess of @sc{gnu} Emacs, level 3 is the maximum annotation suitable
for programs that control @value{GDBN}, and level 2 annotations have
been made obsolete (@pxref{Limitations, , Limitations of the Annotation
-Interface, annotate, GDB's Obsolete Annotations}). This chapter
-describes level 3 annotations.
+Interface, annotate, GDB's Obsolete Annotations}).
+
+@table @code
+@kindex set annotate
+@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.
A simple example of starting up @value{GDBN} with annotations is:
@cindex internal commands
In addition to commands intended for @value{GDBN} users, @value{GDBN}
-includes a number of commands intended for @value{GDBN} developers.
-These commands are provided here for reference.
+includes a number of commands intended for @value{GDBN} developers,
+that are not documented elsewhere in this manual. These commands are
+provided here for reference. (For commands that turn on debugging
+messages, see @ref{Debugging Output}.)
@table @code
+@kindex maint agent
+@item maint agent @var{expression}
+Translate the given @var{expression} into remote agent bytecodes.
+This command is useful for debugging the Agent Expression mechanism
+(@pxref{Agent Expressions}).
+
@kindex maint info breakpoints
@item @anchor{maint info breakpoints}maint info breakpoints
Using the same format as @samp{info breakpoints}, display both the
@end table
+@kindex maint check-symtabs
+@item maint check-symtabs
+Check the consistency of psymtabs and symtabs.
+
+@kindex maint cplus first_component
+@item maint cplus first_component @var{name}
+Print the first C@t{++} class/namespace component of @var{name}.
+
+@kindex maint cplus namespace
+@item maint cplus namespace
+Print the list of possible C@t{++} namespaces.
+
+@kindex maint demangle
+@item maint demangle @var{name}
+Demangle a C@t{++} or Objective-C manled @var{name}.
+
+@kindex maint deprecate
+@kindex maint undeprecate
+@cindex deprecated commands
+@item maint deprecate @var{command} @r{[}@var{replacement}@r{]}
+@itemx maint undeprecate @var{command}
+Deprecate or undeprecate the named @var{command}. Deprecated commands
+cause @value{GDBN} to issue a warning when you use them. The optional
+argument @var{replacement} says which newer command should be used in
+favor of the deprecated one; if it is given, @value{GDBN} will mention
+the replacement as part of the warning.
+
+@kindex maint dump-me
+@item maint dump-me
+@cindex @code{SIGQUIT} signal, dump core of @value{GDBN}
+Cause a fatal signal in the debugger and force it to dump its core.
+This is supported only on systems which support aborting a program
+with the @code{SIGQUIT} signal.
+
@kindex maint internal-error
@kindex maint internal-warning
-@item maint internal-error
-@itemx maint internal-warning
+@item maint internal-error @r{[}@var{message-text}@r{]}
+@itemx maint internal-warning @r{[}@var{message-text}@r{]}
Cause @value{GDBN} to call the internal function @code{internal_error}
or @code{internal_warning} and hence behave as though an internal error
or internal warning has been detected. In addition to reporting the
either quit @value{GDBN} or create a core file of the current
@value{GDBN} session.
+These commands take an optional parameter @var{message-text} that is
+used as the text of the error or warning message.
+
+Here's an example of using @code{indernal-error}:
+
@smallexample
(@value{GDBP}) @kbd{maint internal-error testing, 1, 2}
@dots{}/maint.c:121: internal-error: testing, 1, 2
(@value{GDBP})
@end smallexample
-Takes an optional parameter that is used as the text of the error or
-warning message.
+@kindex maint packet
+@item maint packet @var{text}
+If @value{GDBN} is talking to an inferior via the serial protocol,
+then this command sends the string @var{text} to the inferior, and
+displays the response packet. @value{GDBN} supplies the initial
+@samp{$} character, the terminating @samp{#} character, and the
+checksum.
+
+@kindex maint print architecture
+@item maint print architecture @r{[}@var{file}@r{]}
+Print the entire architecture configuration. The optional argument
+@var{file} names the file where the output goes.
@kindex maint print dummy-frames
@item maint print dummy-frames
-
Prints the contents of @value{GDBN}'s internal dummy-frame stack.
@smallexample
@kindex maint print raw-registers
@kindex maint print cooked-registers
@kindex maint print register-groups
-@item maint print registers
-@itemx maint print raw-registers
-@itemx maint print cooked-registers
-@itemx maint print register-groups
+@item maint print registers @r{[}@var{file}@r{]}
+@itemx maint print raw-registers @r{[}@var{file}@r{]}
+@itemx maint print cooked-registers @r{[}@var{file}@r{]}
+@itemx maint print register-groups @r{[}@var{file}@r{]}
Print @value{GDBN}'s internal register data structures.
The command @code{maint print raw-registers} includes the contents of
register is a member of. @xref{Registers,, Registers, gdbint,
@value{GDBN} Internals}.
-Takes an optional file parameter.
+These commands take an optional parameter, a file name to which to
+write the information.
@kindex maint print reggroups
-@item maint print reggroups
-Print @value{GDBN}'s internal register group data structures.
+@item maint print reggroups @r{[}@var{file}@r{]}
+Print @value{GDBN}'s internal register group data structures. The
+optional argument @var{file} tells to what file to write the
+information.
-Takes an optional file parameter.
+The register groups info looks like this:
@smallexample
(@value{GDBP}) @kbd{maint print reggroups}
restore internal
@end smallexample
+@kindex flushregs
+@item flushregs
+This command forces @value{GDBN} to flush its internal register cache.
+
+@kindex maint print objfiles
+@cindex info for known object files
+@item maint print objfiles
+Print a dump of all known object files. For each object file, this
+command prints its name, address in memory, and all of its psymtabs
+and symtabs.
+
+@kindex maint print statistics
+@cindex bcache statistics
+@item maint print statistics
+This command prints, for each object file in the program, various data
+about that object file followed by the byte cache (@dfn{bcache})
+statistics for the object file. The objfile data includes the number
+of minimal, partical, full, and stabs symbols, the number of types
+defined by the objfile, the number of as yet unexpanded psym tables,
+the number of line tables and string tables, and the amount of memory
+used by the various tables. The bcache statistics include the counts,
+sizes, and counts of duplicates of all and unique objects, max,
+average, and median entry size, total memory used and its overhead and
+savings, and various measures of the hash table size and chain
+lengths.
+
+@kindex maint print type
+@cindex type chain of a data type
+@item maint print type @var{expr}
+Print the type chain for a type specified by @var{expr}. The argument
+can be either a type name or a symbol. If it is a symbol, the type of
+that symbol is described. The type chain produced by this command is
+a recursive definition of the data type as stored in @value{GDBN}'s
+data structures, including its flags and contained types.
+
+@kindex maint set dwarf2 max-cache-age
+@kindex maint show dwarf2 max-cache-age
+@item maint set dwarf2 max-cache-age
+@itemx maint show dwarf2 max-cache-age
+Control the DWARF 2 compilation unit cache.
+
+@cindex DWARF 2 compilation units cache
+In object files with inter-compilation-unit references, such as those
+produced by the GCC option @samp{-feliminate-dwarf2-dups}, the DWARF 2
+reader needs to frequently refer to previously read compilation units.
+This setting controls how long a compilation unit will remain in the
+cache if it is not referenced. A higher limit means that cached
+compilation units will be stored in memory longer, and more total
+memory will be used. Setting it to zero disables caching, which will
+slow down @value{GDBN} startup, but reduce memory consumption.
+
@kindex maint set profile
@kindex maint show profile
@cindex profiling GDB
Configuring with @samp{--enable-profiling} arranges for @value{GDBN} to be
compiled with the @samp{-pg} compiler option.
-@kindex maint set dwarf2 max-cache-age
-@kindex maint show dwarf2 max-cache-age
-@item maint set dwarf2 max-cache-age
-@itemx maint show dwarf2 max-cache-age
-Control the DWARF 2 compilation unit cache.
+@kindex maint show-debug-regs
+@cindex x86 hardware debug registers
+@item maint show-debug-regs
+Control whether to show variables that mirror the x86 hardware debug
+registers. Use @code{ON} to enable, @code{OFF} to disable. If
+enabled, the debug registers values are shown when GDB inserts or
+removes a hardware breakpoint or watchpoint, and when the inferior
+triggers a hardware-assisted breakpoint or watchpoint.
+
+@kindex maint space
+@cindex memory used by commands
+@item maint space
+Control whether to display memory usage for each command. If set to a
+nonzero value, @value{GDBN} will display how much memory each command
+took, following the command's own output. This can also be requested
+by invoking @value{GDBN} with the @option{--statistics} command-line
+switch (@pxref{Mode Options}).
+
+@kindex maint time
+@cindex time of command execution
+@item maint time
+Control whether to display the execution time for each command. If
+set to a nonzero value, @value{GDBN} will display how much time it
+took to execute each command, following the command's own output.
+This can also be requested by invoking @value{GDBN} with the
+@option{--statistics} command-line switch (@pxref{Mode Options}).
+
+@kindex maint translate-address
+@item maint translate-address @r{[}@var{section}@r{]} @var{addr}
+Find the symbol stored at the location specified by the address
+@var{addr} and an optional section name @var{section}. If found,
+@value{GDBN} prints the name of the closest symbol and an offset from
+the symbol's location to the specified address. This is similar to
+the @code{info address} command (@pxref{Symbols}), except that this
+command also allows to find symbols in other sections.
+
+@end table
+
+The following command is useful for non-interactive invocations of
+@value{GDBN}, such as in the test suite.
-In object files with inter-compilation-unit references, such as those
-produced by the GCC option @samp{-feliminate-dwarf2-dups}, the DWARF 2
-reader needs to frequently refer to previously read compilation units.
-This setting controls how long a compilation unit will remain in the cache
-if it is not referenced. Setting it to zero disables caching, which will
-slow down @value{GDBN} startup but reduce memory consumption.
+@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
@var{addr} is address, @var{length} is number of bytes, @var{XX@dots{}}
is binary data. The characters @code{$}, @code{#}, and @code{0x7d} are
-escaped using @code{0x7d}.
+escaped using @code{0x7d}, and then XORed with @code{0x20}.
+For example, @code{0x7d} would be transmitted as @code{0x7d 0x5d}.
Reply:
@table @samp
@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:
@table @samp
@item @code{QC}@var{pid}
-Where @var{pid} is a HEX encoded 16 bit process id.
+Where @var{pid} is an unsigned hexidecimal process id.
@item *
Any other reply implies the old pid.
@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
@end table
In response to each query, the target will reply with a list of one or
-more thread ids, in big-endian hex, separated by commas. @value{GDBN}
-will respond to each reply with a request for more thread ids (using the
-@code{qs} form of the query), until the target responds with @code{l}
-(lower-case el, for @code{'last'}).
+more thread ids, in big-endian unsigned hex, separated by commas.
+@value{GDBN} will respond to each reply with a request for more thread
+ids (using the @code{qs} form of the query), until the target responds
+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}.
-Note @var{annex} must be empty.
+Access the target's @dfn{auxiliary vector}. @xref{OS Information,
+auxiliary vector}, and see @ref{Remote configuration,
+read-aux-vector-packet}. Note @var{annex} must be empty.
@end table
Reply:
@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.
not recognize the @var{object} keyword, or its support for
@var{object} does not recognize the @var{operation} keyword,
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}.
+
+@var{thread-id} is the (big endian, hex encoded) thread id associated with the
+thread for which to fetch the TLS address.
+
+@var{offset} is the (big endian, hex encoded) offset associated with the
+thread local variable. (This offset is obtained from the debug
+information associated with the variable.)
+
+@var{lm} is the (big endian, hex encoded) OS/ABI specific encoding of the
+the load module associated with the thread local storage. For example,
+a @sc{gnu}/Linux system will pass the link map address of the shared
+object associated with the thread local storage under consideration.
+Other operating environments may choose to represent the load module
+differently, so the precise meaning of this parameter will vary.
+
+Reply:
+@table @asis
+@item @var{XX@dots{}}
+Hex encoded (big endian) bytes representing the address of the thread
+local storage requested.
+
+@item @code{E}@var{nn} (where @var{nn} are hex digits)
+An error occurred.
+
+@item @code{""} (empty)
+An empty reply indicates that @code{qGetTLSAddr} is not supported by the stub.
+@end table
+
@end table
@node Register Packet Format
@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 / blobdiff