@c _HOST__ architectures (and you can of course get the full source,
@c with all configurations, from wherever you got this).
_if__(0)
-_0__
THIS IS THE FULL SOURCE. The full source needs to be run through m4
before either tex- or info- formatting: for example,
+_0__
m4 pretex.m4 none.m4 m680x0.m4 gdb.texinfo >gdb-680x0.texinfo
+_1__
will produce (assuming your path finds either GNU or SysV m4; Berkeley
won't do) a file suitable for formatting. See the text in "pretex.m4"
for a fuller explanation (and the macro definitions).
any "info" markup that can be generated automatically; you should first
preprocess it as above, then run it through C-u texinfo-master-menu,
before actually info-formatting it.
-_1__
_fi__(0)
@c
@syncodeindex ky cp
and target configurations.
@item
-INTERACTION: _GDBN__ now uses the GNU @code{readline} interface to read its
+INTERACTION: _GDBN__ now uses the GNU readline interface to read its
input; this provides inline editing of commands, using the familiar
Emacs or @code{vi} keymaps, and command-history support. The user interface
to _GDBN__'s control variables has been simplified and consolidated in two
@end smallexample
@node VxWorks connection,,,
-@subsubsection Connecting to a VxWorks Target
+@subsubsection Connecting to VxWorks
The _GDBN__ command @samp{target} lets you connect to a VxWorks target on the
network. To connect to a target whose host name is ``@code{tt}'', type:
@samp{target} command again.
@node VxWorks download,,,
-@subsubsection Downloading to a VxWorks Target
+@subsubsection Downloading to VxWorks
If you have connected to the VxWorks target and you want to debug an
object that has not yet been loaded, you can use the _GDBN__ @samp{load}
@item help
Used with no arguments, @samp{help} displays a short list of named
categories of commands:
-@example
+@smallexample
(_GDBP__) help
List of classes of commands:
Type "help" followed by command name for full documentation.
Command name abbreviations are allowed if unambiguous.
(_GDBP__)
-@end example
+@end smallexample
@item help @var{category}
Using one of the general help categories as an argument, you can get a
doubt, recompile with @samp{-g} alone, and if this fixes the problem,
please report it as a bug (including a test case---@pxref{_GDBN__ Bugs}).
-Older versions of the GNU C compiler, _GCC__, permitted a variant option
-@samp{-gg} for debugging information. _GDBN__ no longer supports this format;
-if your GNU C compiler has this option, do not use it.
+Older versions of the GNU C compiler permitted a variant option
+@samp{-gg} for debugging information. _GDBN__ no longer supports this
+format; if your GNU C compiler has this option, do not use it.
@ignore
@comment As far as I know, there are no cases in which _GDBN__ will
@cindex starting
@cindex running
@kindex run
-To start your program under _GDBN__, use the @samp{run} command. Except on
-VxWorks, the program must already have been specified using the
+To start your program under _GDBN__, use the @samp{run} command.
+_if__(_VXWORKS__)
+Except on VxWorks, the
+_fi__(_VXWORKS__)
+_if__(!_VXWORKS__)
+The
+_fi__(!_VXWORKS__)
+program must already have been specified using the
@samp{file} or @samp{exec-file} command, or with an argument to _GDBN__
-(@pxref{Files}).
+(@pxref{Files}).@refill
On targets that support processes, @samp{run} creates an inferior
process and makes that process run your program. On other targets,
information, which you must do @i{before} starting the program. (You
can change it after starting the program, but such changes do not affect
the program unless you start it over again.) This information may be
-divided into three categories:
+divided into four categories:
@table @asis
@item The @i{arguments.}
-You specify the arguments to give the program as the arguments of the
+You specify the arguments to give your program as the arguments of the
@samp{run} command. If a shell is available on your target, the shell
is used to pass the arguments, so that you may use normal conventions
(for example regular expression expansion or variable substitution) in
is used with the @code{SHELL} environment variable.
@item The @i{environment.}
-The program normally inherits its environment from _GDBN__, but you can
-use the _GDBN__ commands @samp{set environment} and
-@samp{unset environment} to change parts of the environment that will
-be given to the program.@refill
+Your program normally inherits its environment from _GDBN__, but you can
+use the _GDBN__ commands @samp{set environment} and @samp{unset
+environment} to change parts of the environment that will be given to
+the program.@refill
@item The @i{working directory.}
-The program inherits its working directory from _GDBN__. You can set _GDBN__'s
-working directory with the @samp{cd} command in _GDBN__.
+Your program inherits its working directory from _GDBN__. You can set
+_GDBN__'s working directory with the @samp{cd} command in _GDBN__.
+
+@item The @i{standard input and output.}
+Your program normally uses the same device for standard input and
+standard output as _GDBN__ is using. You can redirect input and output
+in the @code{run} command line, or you can use the @samp{tty} command to
+set a different device for your program.
@end table
When you issue the @samp{run} command, your program begins to execute
tells the program, when subsequently run, to assume it is being run
on behalf of the user named @samp{foo}.
-@item delete environment @var{varname}
-@itemx unset environment @var{varname}
-@kindex delete environment
+@item unset environment @var{varname}
@kindex unset environment
Remove variable @var{varname} from the environment to be passed to your
program. This is different from @samp{set env @var{varname}@ =};
-@samp{delete environment} removes the variable from the environment,
+@samp{unset environment} removes the variable from the environment,
rather than assigning it an empty value. This command can be
abbreviated @samp{d e}.
@end table
a Unix process is with the @code{ps} utility, or with the @code{jobs -l}
shell command.) In this case, you must have permission to send the
process a signal, and it must have the same effective user ID as the
-debugger.
+_GDBN__ process.
@end table
When using @samp{attach}, you should first use the @samp{file} command
to specify the program running in the process and load its symbol table.
-The first thing _GDBN__ does after arranging to debug the process is to stop
-it. You can examine and modify an attached process with all the _GDBN__
-commands that ordinarily available when you start processes with
-@samp{run}. You can insert breakpoints; you can step and continue; you
-can modify storage. If you would rather the process continue running,
-you may use the @samp{continue} command after attaching _GDBN__ to the
-process.
+The first thing _GDBN__ does after arranging to debug the specified
+process is to stop it. You can examine and modify an attached process
+with all the _GDBN__ commands that ordinarily available when you start
+processes with @samp{run}. You can insert breakpoints; you can step and
+continue; you can modify storage. If you would rather the process
+continue running, you may use the @samp{continue} command after
+attaching _GDBN__ to the process.
@kindex detach
When you have finished debugging the attached process, you can use the
Kill the child process in which your program is running under _GDBN__.
@end table
-This command is useful if you wish to debug a core dump instead. _GDBN__
-ignores any core dump file if it is actually running the program.
+This command is useful if you wish to debug a core dump instead of a
+running process. _GDBN__ ignores any core dump file while your program
+is running.
On some operating systems, you can't execute your program in another
-process while breakpoints are active inside _GDBN__. The @samp{kill}
-command is also useful in this situation, if you wish to run the program
+process while breakpoints are active inside _GDBN__. You can use the
+@samp{kill} command in this situation to permit running the program
outside the debugger.
The @samp{kill} command is also useful if you wish to recompile and
@dfn{disabled}; if disabled, it has no effect on the program until you
enable it again.
-@table @code
-@kindex info break
-@kindex $_
-@item info break
-The command @samp{info break} prints a list of all breakpoints set and not
-deleted, showing their numbers, where in the program they are, and any
-special features in use for them. Disabled breakpoints are included in the
-list, but marked as disabled. @samp{info break} with a breakpoint number
-as argument lists only that breakpoint. The convenience variable @code{$_}
-and the default examining-address for the @samp{x} command are set to the
-address of the last breakpoint listed (@pxref{Memory}).
-
-@kindex info watch
-@item info watch
-This command prints a list of watchpoints.
-
-@cindex watchpoints
-A @dfn{watchpoint} is a special breakpoint that stops your program when
-the value of an expression changes. You can use a watchpoint to stop
-execution whenever the value of an expression changes, without having to
-predict a particular place in the inferior process where this may
-happen. Aside from the different syntax in setting a watchpoint, it is
-managed exactly like any other breakpoint and is enabled, disabled, and
-deleted using exactly the same commands.
-
-Watchpoints currently execute two orders of magnitude more slowly than
-other breakpoints, but this can well be worth it to catch errors where
-you have no clue what part of your program is the culprit. Some
-processors provide special hardware to implement this feature; future
-releases of _GDBN__ will use such hardware if it is available.
-
-@end table
-
@node Set Breaks,,,
@subsection Setting Breakpoints
@kindex break
@kindex watch
Breakpoints are set with the @samp{break} command (abbreviated @samp{b}).
-Watchpoints are set with the @samp{watch} command.
You have several ways to say where the breakpoint should go.
breakpoints set with the @samp{break} command. They can be deleted,
disabled, made conditional, etc., in the standard ways.
-@kindex watch
-@item watch @var{expr}
-Set a watchpoint for an expression.
+@kindex info breakpoints
+@kindex $_
+@item info breakpoints
+The command @samp{info breakpoints} prints a list of all breakpoints set
+and not deleted, showing their numbers, where in the program they are,
+and any special features in use for them. Disabled breakpoints are
+included in the list, but marked as disabled. @samp{info break} with a
+breakpoint number as argument lists only that breakpoint. The
+convenience variable @code{$_} and the default examining-address for the
+@samp{x} command are set to the address of the last breakpoint listed
+(@pxref{Memory}).
@end table
_GDBN__ allows you to set any number of breakpoints at the same place in the
program. There is nothing silly or meaningless about this. When the
breakpoints are conditional, this is even useful (@pxref{Conditions}).
+@node Set Watchpoints,,,
+@subsection Setting Watchpoints
+@cindex watchpoints
+A @dfn{watchpoint} is a special breakpoint that stops your program when
+the value of an expression changes. You can use a watchpoint to stop
+execution whenever the value of an expression changes, without having to
+predict a particular place in the inferior process where this may
+happen. Aside from the different syntax in setting a watchpoint, it is
+managed exactly like any other breakpoint and is enabled, disabled, and
+deleted using exactly the same commands.
+
+Watchpoints currently execute two orders of magnitude more slowly than
+other breakpoints, but this can well be worth it to catch errors where
+you have no clue what part of your program is the culprit. Some
+processors provide special hardware to implement this feature; future
+releases of _GDBN__ will use such hardware if it is available.
+
+@table @code
+@kindex watch
+@item watch @var{expr}
+Set a watchpoint for an expression.
+
+@kindex info watch
+@item info watch
+This command prints a list of watchpoints.
+@end table
+
@node Exception Handling,,,
@subsection Breakpoints and Exceptions
@cindex exception handlers
and to list the exceptions the program is prepared to handle at a
given point in time.
-@cindex raise exceptions
-GNU C++ raises an exception by calling a library function named
-@code{__raise_exception} which has the following ANSI C interface:
-
-@example
- /* ADDR is where the exception identifier is stored.
- ID is the exception identifier. */
- void __raise_exception (void **addr, void *id);
-@end example
-
-@noindent
-You can make the debugger catch all exceptions @emph{before} any stack
-unwinding takes place: set a breakpoint on @code{__raise_exception}
-(@pxref{Breakpoints}). If you set a breakpoint in an exception handler
-instead, it may not be easy to find out where the exception was raised.
-
-By using a conditional breakpoint (@xref{Conditions}), you can cause
-the debugger to stop only when a specific exception is raised.
-Multiple conditional breakpoints can be used to stop the program when
-any of a number of exceptions are raised.
-
@table @code
@item catch @var{exceptions}
@kindex catch
You cannot interactively install an exception handler.
@end itemize
+@cindex raise exceptions
+Sometimes @samp{catch} is not the best way to debug exception handling:
+if you need to know exactly where an exception is raised, it's better to
+stop @emph{before} the exception handler is called, since that way you
+can see the stack before any unwinding takes place.
+
+To stop just before an exception handler is called, you need some
+knowledge of the implementation. In the case of GNU C++ exception are
+raised by calling a library function named @code{__raise_exception}
+which has the following ANSI C interface:
+
+@example
+ /* ADDR is where the exception identifier is stored.
+ ID is the exception identifier. */
+ void __raise_exception (void **addr, void *id);
+@end example
+
+@noindent
+To make the debugger catch all exceptions before any stack
+unwinding takes place, set a breakpoint on @code{__raise_exception}
+(@pxref{Breakpoints}). If you set a breakpoint in an exception handler
+instead, it may not be easy to find out where the exception was raised.
+
+With a conditional breakpoint (@xref{Conditions}) that depends on the
+value of @code{id}, you can cause the debugger to stop only when a
+specific exception is raised. Multiple conditional breakpoints can be
+used to stop the program when any of a number of exceptions are raised.
+
@node Delete Breaks,,,
@subsection Deleting Breakpoints
@end table
Save for a breakpoint set with @samp{tbreak} (@pxref{Set Breaks}),
-breakpoints that you set are enabled or disabled only when you use one
-of the commands above. (The command @samp{until} can set and delete a
-breakpoint on its own, but it will not change the state of your
-breakpoints).
+breakpoints that you set initially enabled; subsequently, they become
+disabled or enabled only when you use one of the commands above. (The
+command @samp{until} can set and delete a breakpoint of its own, but it
+will not change the state of your other breakpoints).
@node Conditions,,,
@subsection Break Conditions
Thus, the program will not stop at this breakpoint until the
@var{count}'th time it is reached.
-This command is allowed only when the program stopped due to a
-breakpoint. At other times, the argument to @samp{cont} is ignored.
+An argument to this command is meaningful only when the program stopped
+due to a breakpoint. At other times, the argument to @samp{cont} is
+ignored.
The synonym @samp{fg} is provided purely for convenience, and has
exactly the same behavior as other forms of the command.
controlled output are often useful in silent breakpoints. @xref{Output}.
For example, here is how you could use breakpoint commands to print the
-value of @code{x} at entry to @code{foo} whenever it is positive.
+value of @code{x} at entry to @code{foo} whenever @code{x} is positive.
_0__@example
break foo if x>0
@cindex stepping
@dfn{Stepping} means setting your program in motion for a limited time, so
-that control will return automatically to the debugger after one line of
+that control will return automatically to _GDBN__ after one line of
code or one machine instruction. Breakpoints are active during stepping
and the program will stop for them even if it has not gone as far as the
stepping command specifies.
@table @code
@item step
@kindex step
-Continue running the program until control reaches a different line,
-then stop it and return control to the debugger. This command is
+Continue running the program until control reaches a different source
+line, then stop it and return control to the debugger. This command is
abbreviated @samp{s}.
This command may be given when control is within a function for which
there is no debugging information. In that case, execution will proceed
until control reaches a different function, or is about to return from
-this function. An argument repeats this action.
+this function.
@item step @var{count}
Continue running as in @samp{step}, but do so @var{count} times. If a
@item next
@kindex next
-Similar to @samp{step}, but any function calls appearing within the line of
-code are executed without stopping. Execution stops when control reaches a
+Continue to the next source line in the current stack frame. Similar to
+@samp{step}, but any function calls appearing within the line of code
+are executed without stopping. Execution stops when control reaches a
different line of code at the stack level which was executing when the
@samp{next} command was given. This command is abbreviated @samp{n}.
An argument is a repeat count, as in @samp{step}.
-@samp{next} within a function without debugging information acts as does
+@samp{next} within a function that lacks debugging information acts as does
@samp{step}, but any function calls appearing within the code of the
function are executed without stopping.
@item until
@kindex until
-This command is used to avoid single stepping through a loop more than
-once. It is like the @samp{next} command, except that when @samp{until}
-encounters a jump, it automatically continues execution until the
-program counter is greater than the address of the jump.
+Continue running until a source line past the current line, in the
+current stack frame, is reached. This command is used to avoid single
+stepping through a loop more than once. It is like the @samp{next}
+command, except that when @samp{until} encounters a jump, it
+automatically continues execution until the program counter is greater
+than the address of the jump.
This means that when you reach the end of a loop after single stepping
though it, @samp{until} will cause the program to continue execution
beginning of the loop when it advances to this expression. However, it
has not really done so, not in terms of the actual machine code.
-Note that @samp{until} with no argument works by means of single
+@samp{until} with no argument works by means of single
instruction stepping, and hence is slower than @samp{until} with an
argument.
@itemx ni
@kindex nexti
@kindex ni
-Execute one machine instruction, but if it is a subroutine call,
-proceed until the subroutine returns.
+Execute one machine instruction, but if it is a function call,
+proceed until the function returns.
An argument is a repeat count, as in @samp{next}.
@end table
A typical technique for using stepping is to put a breakpoint
(@pxref{Breakpoints}) at the beginning of the function or the section of
-the program in which a problem is believed to lie, and then step through
-the suspect area, examining the variables that are interesting, until the
-problem happens.
+the program in which a problem is believed to lie, run the program until
+it stops at that breakpoint, and then step through the suspect area,
+examining the variables that are interesting, until you see the problem
+happen.
The @samp{cont} command can be used after stepping to resume execution
until the next breakpoint or signal.
just stop at the same breakpoint immediately. In fact, @samp{cont}
takes special care to prevent that from happening. You do not need
to delete the breakpoint to proceed through it after stopping at it.
-
You can, however, specify an ignore-count for the breakpoint that the
program stopped at, by means of an argument to the @samp{cont} command.
@xref{Conditions}.
beginning). The @var{keywords} say what change to make.
@end table
+@group
The keywords allowed by the @samp{handle} command can be abbreviated.
-Their full names are
+Their full names are:
@table @code
@item nostop
@item nopass
_GDBN__ should not allow the program to see this signal.
@end table
+@end group
When a signal has been set to stop the program, the program cannot see the
signal until you continue. It will see the signal then, if @samp{pass} is
going on in that frame.
@cindex frame number
-_GDBN__ assigns numbers to all existing stack frames, starting with zero for
-the innermost frame, one for the frame that called it, and so on upward.
-These numbers do not really exist in your program; they are to give you a
-way of talking about stack frames in _GDBN__ commands.
+_GDBN__ assigns numbers to all existing stack frames, starting with
+@code{0} for the innermost frame, @code{1} for the frame that called it,
+and so on upward. These numbers do not really exist in your program;
+they are assigned by _GDBN__ to give you a way of designating stack
+frames in _GDBN__ commands.
@cindex selected frame
Many _GDBN__ commands refer implicitly to one stack frame, called the
your program stops, _GDBN__ automatically selects the innermost frame.
@cindex frameless execution
-Some compilers allow functions to be compiled to run without a frame
-reserved for them on the stack. (For example, the _GCC__ option
+Some compilers allow functions to be compiled so that they operate
+without stack frames. (For example, the _GCC__ option
@samp{-fomit-frame-pointer} will generate functions without a frame.)
This is occasionally done with heavily used library functions to save
-the frame setup time. _GDBN__ has limited facilities for dealing with these
-function invocations; if the innermost function invocation has no stack
-frame, _GDBN__ will give it a virtual stack frame of 0 and correctly allow
-tracing of the function call chain. Results are undefined if a function
-invocation besides the innermost one is frameless.
+the frame setup time. _GDBN__ has limited facilities for dealing with
+these function invocations; if the innermost function invocation has no
+stack frame, _GDBN__ will give it a virtual stack frame of 0 and
+correctly allow tracing of the function call chain. Results are
+undefined if a function invocation besides the innermost one is
+frameless.
@node Backtrace,,,
@section Backtraces
@itemx bt @var{n}
Similar, but print only the innermost @var{n} frames.
-@item backtrace @var{-n}
-@itemx bt @var{-n}
+@item backtrace -@var{n}
+@itemx bt -@var{n}
Similar, but print only the outermost @var{n} frames.
@end table
The names @samp{where} and @samp{info stack} are additional aliases
for @samp{backtrace}.
-Every line in the backtrace shows the frame number and the function
+Each line in the backtrace shows the frame number and the function
name. The program counter value is also shown---unless you use
@samp{set addressprint off}.
@end example
@noindent
-The functions @code{expand_call} and @code{expand_expr} are in a file
-whose symbol details have not been fully read. Full detail is available
-for the function @code{rtx_equal_p}, which is in the file
-@file{rtlanal.c}. Its arguments, named @code{x} and @code{y}, are shown
-with their typed values.
+_GDBN__ displayed the functions @code{expand_call} and @code{expand_expr}
+with place-holders in place of their argument values and line numbers,
+because each is in a file whose symbol details have not been fully read.
+Full detail is available for the function @code{rtx_equal_p}, which is
+in the file @file{rtlanal.c}. Its arguments, named @code{x} and
+@code{y}, are shown with their typed values.
@node Selection,,,
@section Selecting a Frame
@item up @var{n}
@kindex up
-Select the frame @var{n} frames up from the frame previously selected.
-For positive numbers @var{n}, this advances toward the outermost
-frame, to higher frame numbers, to frames that have existed longer.
-@var{n} defaults to one.
+Move @var{n} frames up the stack. For positive numbers @var{n}, this
+advances toward the outermost frame, to higher frame numbers, to frames
+that have existed longer. @var{n} defaults to one.
@item down @var{n}
@kindex down
-Select the frame @var{n} frames down from the frame previously
-selected. For positive numbers @var{n}, this advances toward the
-innermost frame, to lower frame numbers, to frames that were created
-more recently. @var{n} defaults to one.
+Move @var{n} frames down the stack. For positive numbers @var{n}, this
+advances toward the innermost frame, to lower frame numbers, to frames
+that were created more recently. @var{n} defaults to one.
@end table
All of these commands end by printing some information on the frame that
source file and line number of execution in that frame, and the text of
that source line. For example:
-@example
-#3 main (argc=3, argv=??, env=??) at main.c:67
-67 read_input_file (argv[i]);
-@end example
+@smallexample
+(_GDBP__) up
+#1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc) at env.c:10
+10 read_input_file (argv[i]);
+@end smallexample
After such a printout, the @samp{list} command with no arguments will print
ten lines centered on the point of execution in the frame. @xref{List}.
@table @code
@item frame
When used without any argument, this command does not change which frame
-is selected, but still prints a brief description of the currently
+is selected, but prints a brief description of the currently
selected stack frame. It can be abbreviated @samp{f}. With an
-argument, this command is used to select a stack frame; with no
-argument, it does not change which frame is selected, but still prints
-the same kind of information.
+argument, this command is used to select a stack frame (@pxref{Selection}).
@item info frame
@kindex info frame
This command prints a verbose description of the selected stack frame,
-including the address of the frame, the addresses of the next frame in
-(called by this frame) and the next frame out (caller of this frame),
+including the address of the frame, the addresses of the next frame down
+(called by this frame) and the next frame up (caller of this frame),
the address of the frame's arguments, the program counter saved in it
(the address of execution in the caller frame), and which registers
were saved in the frame. The verbose description is useful when
@cindex catch exceptions
@cindex exception handlers
Print a list of all the exception handlers that are active in the
-current stack frame given the current value of @code{pc}. To see other
+current stack frame at the current point of execution. To see other
exception handlers, visit the associated frame (using the @samp{up},
@samp{down}, or @samp{frame} commands); then type @samp{info catch}.
@xref{Exception Handling}.
so it is equivalent to typing just @samp{list}. This is more useful
than listing the same lines again. An exception is made for an
argument of @samp{-}; that argument is preserved in repetition so that
-each repetition moves up in the file.
+each repetition moves up in the source file.
@cindex linespec
In general, the @samp{list} command expects you to supply zero, one or two
@var{address} may be any expression.
@end table
-One other command is used to map source lines to program addresses.
-
-@table @code
-@item info line @var{linenum}
-@kindex info line
-Print the starting and ending addresses of the compiled code for
-source line @var{linenum}.
-
-@kindex $_
-The default examine address for the @samp{x} command is changed to the
-starting address of the line, so that @samp{x/i} is sufficient to
-begin examining the machine code (@pxref{Memory}). Also, this address
-is saved as the value of the convenience variable @code{$_}
-(@pxref{Convenience Vars}).
-@end table
-
@node Search,,,
@section Searching Source Files
@cindex searching
Print the source path: show which directories it contains.
@end table
-Because the @samp{directory} command, when used with arguments, adds to
-the front of the source path, it can affect files that _GDBN__ has already
-found. If the source path contains directories that you do not want,
-and these directories contain misleading files with names matching your
-source files, the way to correct the situation is as follows:
+If your source path is cluttered with directories that are no longer of
+interest, _GDBN__ may sometimes cause confusion by finding the wrong
+versions of source. You can correct the situation as follows:
@enumerate
@item
in one command.
@end enumerate
+@node Machine Code,,,
+@section Source and Machine Code
+You can use the command @samp{info line} to map source lines to program
+addresses, and the command @samp{disassemble} or its synonym
+@samp{disasm} to display a range of addresses as machine instructions.
+
+@table @code
+@item info line @var{linespec}
+@kindex info line
+Print the starting and ending addresses of the compiled code for
+source line @var{linespec}.
+
+@kindex $_
+The default examine address for the @samp{x} command is changed to the
+starting address of the line, so that @samp{x/i} is sufficient to
+begin examining the machine code (@pxref{Memory}). Also, this address
+is saved as the value of the convenience variable @code{$_}
+(@pxref{Convenience Vars}).
+
+@kindex disassemble
+@kindex disasm
+@item disassemble
+@itemx disasm
+This specialized command is provided to dump a range of memory as
+machine instructions. The default memory range is the function
+surrounding the program counter of the selected frame. A single
+argument to this command is a program counter value; the function
+surrounding this value will be dumped. Two arguments (separated by one
+or more spaces) specify a range of addresses (first inclusive, second
+exclusive) to be dumped. The two spellings, @samp{disasm} and
+@samp{disassemble}, are equivalent.
+@end table
+
@node Data,,,
@chapter Examining Data
As a special exception, you can refer to a variable or function whose
scope is a single source file even if the current execution point is not
-in this file. But it is possible to have more than one such variable
-or function with the same name (if they are in different source files).
-In such a case, it is not defined which one you will get. If you wish,
-you can specify any one of them using the colon-colon construct:
+in this file. But it is possible to have more than one such variable or
+function with the same name (in different source files). In such a
+case, it is not defined which one you will get. If you wish, you can
+specify any one of them using the colon-colon construct:
@cindex colon-colon
@cindex scope
_GDBN__ normally prints all values according to their data types. Sometimes
this is not what you want. For example, you might want to print a number
in hex, or a pointer in decimal. Or you might want to view data in memory
-at a certain address as a character string or an instruction. These things
-can be done with @dfn{output formats}.
+at a certain address as a character string or an instruction. To do
+these things, specify an @dfn{output format} when you print a value.
The simplest use of output formats is to say how to print a value
already computed. This is done by starting the arguments of the
@cindex examining memory
@table @code
-@kindex disassemble
-@item disassemble
-This specialized command is provided to dump a range of memory as
-machine instructions. The default memory range is the function
-surrounding the program counter of the selected frame. A single
-argument to this command is a program counter value; the function
-surrounding this value will be dumped. Two arguments (separated by one
-or more spaces) specify a range of addresses (first inclusive, second
-exclusive) to be dumped.
-
@kindex x
@item x
The command @samp{x} (for `examine') can be used to examine memory
memory above the stack pointer in hexadecimal.
The output format in this case specifies both how big a unit of memory
-to examine and how to print the contents of that unit. It is done
+to examine and how to print the contents of that unit. This is done
with one or two of the following letters:
-These letters specify just the size of unit to examine:
+These letters specify the size of unit to examine:
@table @samp
@item b
Examine giant words (8 bytes).
@end table
-These letters specify just the way to print the contents:
+These letters specify the way to print the contents:
@table @samp
@item x
@item f
Print as floating point. This works only with sizes @samp{w} and
@samp{g}.
+@end table
+These letters specify both the unit size and the output format:
+@table @samp
@item s
-Print a null-terminated string of characters. The specified unit size
-is ignored; instead, the unit is however many bytes it takes to reach
-a null character (including the null character).
+Print a null-terminated string of characters. Any explicitly specified
+unit size is ignored; instead, the unit is however many bytes it takes
+to reach a null character (including the null character).
@item i
-Print a machine instruction in assembler syntax (or nearly). The
+Print a machine instruction in assembler syntax (or nearly). Any
specified unit size is ignored; the number of bytes in an instruction
varies depending on the type of machine, the opcode and the addressing
modes used. The command @samp{disassemble} gives an alternative way of
-inspecting machine instructions.
+inspecting machine instructions. @xref{Machine Code}.
@end table
If either the manner of printing or the size of unit fails to be specified,
When the @samp{print} command shows a value that resides in memory,
@samp{print} also sets the default address for the @samp{x} command.
@samp{info line} also sets the default for @samp{x}, to the address of
-the start of the machine code for the specified line and @samp{info
-breakpoints} sets it to the address of the last breakpoint listed.
+the start of the machine code for the specified line (@pxref{Machine
+Code}), and @samp{info breakpoints} sets it to the address of the last
+breakpoint listed (@pxref{Set Breaks}).
When you use @key{RET} to repeat an @samp{x} command, the address
specified previously (if any) is ignored, so that the repeated command
@kindex $_
@kindex $__
-The addresses and contents printed by the @samp{x} command are not put in
-the value history because there is often too much of them and they would
-get in the way. Instead, _GDBN__ makes these values available for subsequent
-use in expressions as values of the convenience variables @code{$_} and
-@code{$__}.
-
-After an @samp{x} command, the last address examined is available for use
-in expressions in the convenience variable @code{$_}. The contents of that
-address, as examined, are available in the convenience variable @code{$__}.
+The addresses and contents printed by the @samp{x} command are not put
+in the value history because there is often too much of them and they
+would get in the way. Instead, _GDBN__ makes these values available for
+subsequent use in expressions as values of the convenience variables
+@code{$_} and @code{$__}. After an @samp{x} command, the last address
+examined is available for use in expressions in the convenience variable
+@code{$_}. The contents of that address, as examined, are available in
+the convenience variable @code{$__}.
If the @samp{x} command has a repeat count, the address and contents saved
are from the last memory unit printed; this is not the same as the last
@noindent
showing item numbers, expressions and their current values.
-If the expression refers to local variables, then it does not make sense
-outside the lexical context for which it was set up. Such an expression
-is disabled when execution enters a context where one of its variables
-is not defined. For example, if you give the command
-@samp{display name} while inside a function with an argument
-@code{name}, then this argument will be displayed while the program
-continues to stop inside that function. When it stops elsewhere---where
-there is no variable @samp{name}---display is disabled. The next time
-your program stops where @samp{name} is meaningful, you can enable the
-display expression once again.
-
@table @code
@item display @var{exp}
@kindex display
number of units, add the expression @var{addr} as a memory address to
be examined each time the program stops. Examining means in effect
doing @samp{x/@var{fmt} @var{addr}}. @xref{Memory}.
+@end table
+
+For example, @samp{display/i $pc} can be helpful, to see the machine
+instruction about to be executed each time execution stops (@samp{$pc}
+is a common name for the program counter; @pxref{Registers}).
+@table @code
@item undisplay @var{dnums}@dots{}
@itemx delete display @var{dnums}@dots{}
@kindex delete display
because they refer to automatic variables not currently available.
@end table
+If a display expression refers to local variables, then it does not make
+sense outside the lexical context for which it was set up. Such an
+expression is disabled when execution enters a context where one of its
+variables is not defined. For example, if you give the command
+@samp{display name} while inside a function with an argument
+@code{name}, then this argument will be displayed while the program
+continues to stop inside that function. When it stops elsewhere---where
+there is no variable @samp{name}---display is disabled. The next time
+your program stops where @samp{name} is meaningful, you can enable the
+display expression once again.
+
@node Print Settings,,,
@section Print Settings
@end example
@noindent
-It might be useful to repeat this command many times by typing @key{RET}.
+You can print successive links in the chain by repeating this
+command---which you can do by just typing @key{RET}.
Note that the history records values, not expressions. If the value of
-@code{x} is 4 and you type this command:
+@code{x} is 4 and you type these commands:
@example
print x
@section Convenience Variables
@cindex convenience variables
-_GDBN__ provides @dfn{convenience variables} that you can use within _GDBN__ to
-hold on to a value and refer to it later. These variables exist entirely
-within _GDBN__; they are not part of your program, and setting a convenience
-variable has no effect on further execution of your program. That's why
-you can use them freely.
+_GDBN__ provides @dfn{convenience variables} that you can use within
+_GDBN__ to hold on to a value and refer to it later. These variables
+exist entirely within _GDBN__; they are not part of your program, and
+setting a convenience variable has no direct effect on further execution
+of your program. That's why you can use them freely.
Convenience variables have names starting with @samp{$}. Any name starting
with @samp{$} can be used for a convenience variable, unless it is one of
-the predefined set of register names (@pxref{Registers}).
+the predefined machine-specific register names (@pxref{Registers}).
You can save a value in a convenience variable with an assignment
expression, just as you would set a variable in your program. Example:
Convenience variables have no fixed types. You can assign a convenience
variable any type of value, including structures and arrays, even if
that variable already has a value of a different type. The convenience
-variable as an expression has whatever type its current value has.
+variable, when used as an expression, has the type of its current value.
@table @code
@item info convenience
@end table
One of the ways to use a convenience variable is as a counter to be
-incremented or a pointer to be advanced. For example:
+incremented or a pointer to be advanced. For example, to print
+a field from successive elements of an array of structures:
_0__@example
set $i = 0
@cindex registers
Machine register contents can be referred to in expressions as variables
with names starting with @samp{$}. The names of registers are different
-for each machine; use @samp{info registers} to see the names used on your
-machine. The names @code{$pc} and @code{$sp} are used on most machines for
-the program counter register and the stack pointer. Often @code{$fp} is
-used for a register that contains a pointer to the current stack frame,
-and @code{$ps} is used for a register that contains the processor
-status. These standard register names may be available on your machine
-even though the @code{info registers} command displays them with a
-different name. For example, on the SPARC, @code{info registers}
+for each machine; use @samp{info registers} to see the names used on
+your machine. The names @code{$pc} and @code{$sp} are used on most
+machines for the program counter register and the stack pointer. Often
+@code{$fp} is used for a register that contains a pointer to the current
+stack frame, and @code{$ps} is sometimes used for a register that
+contains the processor status. These standard register names may be
+available on your machine even though the @code{info registers} command
+shows other names. For example, on the SPARC, @code{info registers}
displays the processor status register as @code{$psr} but you can also
refer to it as @code{$ps}.
-_GDBN__ always considers the contents of an ordinary register as an integer
-when the register is examined in this way. Some machines have special
-registers which can hold nothing but floating point; these registers are
-considered floating point. There is no way to refer to the contents of an
-ordinary register as floating point value (although you can @emph{print}
-it as a floating point value with @samp{print/f $@var{regname}}).
+_GDBN__ always considers the contents of an ordinary register as an
+integer when the register is examined in this way. Some machines have
+special registers which can hold nothing but floating point; these
+registers are considered to have floating point values. There is no way
+to refer to the contents of an ordinary register as floating point value
+(although you can @emph{print} it as a floating point value with
+@samp{print/f $@var{regname}}).
Some registers have distinct ``raw'' and ``virtual'' data formats. This
means that the data format in which the register contents are saved by
Register values are relative to the selected stack frame
(@pxref{Selection}). This means that you get the value that the register
would contain if all stack frames farther in were exited and their saved
-registers restored. In order to see the real contents of all registers,
+registers restored. In order to see the contents of hardware registers,
you must select the innermost frame (with @samp{frame 0}).
Some registers are never saved (typically those numbered zero or one)
@item info variables
@kindex info variables
Print the names and data types of all variables that are declared
-outside of functions (i.e., except for local variables).
+outside of functions (i.e., excluding local variables).
@item info variables @var{regexp}
Print the names and data types of all variables (except for local
@end example
@noindent
-would store the value 4 into the variable @code{x}, and then print
-the value of the assignment expression (which is 4).
-
-All the assignment operators of C are supported, including the
-increment operators @samp{++} and @samp{--}, and combining
-assignments such as @samp{+=} and _0__@samp{<<=}_1__.
+would store the value 4 into the variable @code{x}, and then print the
+value of the assignment expression (which is 4). All the assignment
+operators of C are supported, including the increment operators
+@samp{++} and @samp{--}, and combining assignments such as @samp{+=} and
+_0__@samp{<<=}_1__.
@kindex set
@kindex set variable
printed and is not put in the value history (@pxref{Value History}). The
expression is evaluated only for side effects.
-Note that if the beginning of the argument string of the @samp{set} command
-appears identical to a @samp{set} subcommand, it may be necessary to use
-the @samp{set variable} command. This command is identical to @samp{set}
-except for its lack of subcommands.
+If the beginning of the argument string of the @samp{set} command
+appears identical to a @samp{set} subcommand, use the @samp{set
+variable} command instead of just @samp{set}. This command is identical
+to @samp{set} except for its lack of subcommands.
_GDBN__ allows more implicit conversions in assignments than C does; you can
freely store an integer value into a pointer variable or vice versa, and
To store values into arbitrary places in memory, use the @samp{@{@dots{}@}}
construct to generate a value of specified type at a specified address
-(@pxref{Expressions}). For example, @code{@{int@}0x83040} would refer
-to memory location 0x83040 as an integer (which implies a certain size
+(@pxref{Expressions}). For example, @code{@{int@}0x83040} refers
+to memory location @code{0x83040} as an integer (which implies a certain size
and representation in memory), and
@example
set @{int@}0x83040 = 4
@end example
-would store the value 4 into that memory location.
+@noindent
+stores the value 4 into that memory location.
@node Jumping,,,
@section Continuing at a Different Address
command.
@end table
-This command has the effect of discarding the selected stack
-frame (and all frames within it), so that control moves to the caller of
-that function. You can think of this as making the discarded frame
-return prematurely.
-
-First select the stack frame that you wish to return from
-(@pxref{Selection}). Then type the @samp{return} command. If you wish
-to specify the value to be returned, give that as an argument.
+This command abandons execution of a function. When you use
+@code{return}, _GDBN__ discards the selected stack frame (and all frames
+within it). You can think of this as making the discarded frame return
+prematurely. If you wish to specify a value to be returned, give that
+value as the argument to @code{return}.
-This pops the selected stack frame (and any other frames inside of it),
-leaving its caller as the innermost remaining frame. That frame becomes
-selected. The specified value is stored in the registers used for
-returning values of functions.
+This pops the selected stack frame (@pxref{Selection}), and any other
+frames inside of it, leaving its caller as the innermost remaining
+frame. That frame becomes selected. The specified value is stored in
+the registers used for returning values of functions.
The @samp{return} command does not resume execution; it leaves the
program stopped in the state that would exist if the function had just
-returned. Contrast this with the @samp{finish} command
-(@pxref{Stepping}), which resumes execution until the selected stack
-frame returns @emph{naturally}.
+returned. In contrast, the @samp{finish} command (@pxref{Stepping})
+resumes execution until the selected stack frame returns naturally.
@node Calling,,,
@section Calling your Program's Functions
@end table
You can use this variant of the @samp{print} command if you want to
-execute some piece of your program, but without cluttering the output
+execute a function from your program, but without cluttering the output
with @code{void} returned values. The result is printed and saved in
the value history, if it is not void.
the command arguments given when you start _GDBN__, as discussed in
@pxref{Invocation}.
-But occasionally it is necessary to change to a different file during a
+Occasionally it is necessary to change to a different file during a
_GDBN__ session. Or you may run _GDBN__ and forget to specify the files you
want to use. In these situations the _GDBN__ commands to specify new files
are useful.
@cindex executable file
@kindex file
Use @var{filename} as the program to be debugged. It is read for its
-symbols, for getting the contents of pure memory, and it is the program
+symbols and for the contents of pure memory. It is also the program
executed when you use the @samp{run} command. If you do not specify a
directory and the file is not found in _GDBN__'s working directory,
_GDBN__ will use the environment variable @code{PATH} as a list of
directories to search, just as the shell does when looking for a program
to run.
-@samp{file} with no argument makes both executable file and symbol
-table become unspecified.
+@samp{file} with no argument makes _GDBN__ discard any information it
+has on both executable file and the symbol table.
@item exec-file @var{filename}
@kindex exec-file
@end table
-While all three file-specifying commands allow both absolute and relative
-file names as arguments, _GDBN__ always converts the file name to an absolute
-one and remembers it that way.
+All file-specifying commands allow both absolute and relative file names
+as arguments. _GDBN__ always converts the file name to an absolute path
+name and remembers it that way.
@kindex sharedlibrary
@kindex share
_GDBN__ supports the SunOS shared library format. Symbols from a shared
library cannot be referenced before the shared library has been linked
-with the program. (That is to say, after one types @samp{run} and
-the function @code{main()} has been entered; or when examining core
+with the program. (That is to say, after you type @samp{run} and
+the function @code{main} has been entered; or when examining core
files.) Once the shared library has been linked in, you can use the
following commands:
Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}}
@end table
-@node Editing/History,,,
-@section Command Editing and History
+@node Editing,,,
+@section Command Editing
@cindex readline
@cindex command line editing
-@cindex history substitution
-_GDBN__ reads its input commands via the @code{readline} interface. This
+_GDBN__ reads its input commands via the @dfn{readline} interface. This
GNU library provides consistent behavior for programs which provide a
command line interface to the user. Advantages are @samp{emacs}-style
or @samp{vi}-style inline editing of commands, @samp{csh}-like history
@item show editing
Show whether command line editing is enabled.
+@node History,,,
+@section Command History
+@cindex history substitution
@cindex history file
@kindex set history file
@item set history file @var{filename}
-Set the name of the _GDBN__ command history file to @samp{filename}. This is
+Set the name of the _GDBN__ command history file to @var{filename}. This is
the file from which _GDBN__ will read an initial command history
list or to which it will write this list when it exits. This list is
accessed through history expansion or through the history
command editing characters listed below. This file defaults to the
value of the environmental variable @code{GDBHISTFILE}, or to
-@code{./.gdb_history} if this variable is not set.
+@file{./.gdb_history} if this variable is not set.
@cindex history write
@kindex set history write
@item set history write
@itemx set history write on
-Make _GDBN__ record command history in a file, whose name may be specified with the
+Record command history in a file, whose name may be specified with the
@samp{set history file} command. By default, this option is disabled.
@item set history write off
-Make _GDBN__ stop recording command history in a file.
+Stop recording command history in a file.
@cindex history size
@kindex set history size
is off by default. If you decide to enable history expansion with the
@samp{set history expansion on} command, you may sometimes need to
follow @samp{!} (when it is used as logical not, in an expression) with
-a space or a tab to prevent it from being expanded. The @code{readline}
+a space or a tab to prevent it from being expanded. The readline
history facilities will not attempt substitution on the strings
@samp{!=} and @samp{!(}, even when history expansion is enabled.
@item set history expansion off
Disable history expansion.
-The @code{readline} code comes with more complete documentation of
+The readline code comes with more complete documentation of
editing and history expansion features. Users unfamiliar with @samp{emacs}
or @samp{vi} may wish to read it.
@iftex
Commands that would ask for confirmation if used interactively proceed
without asking when used inside a user-defined command. Many _GDBN__ commands
that normally print messages to say what they are doing omit the messages
-when used in user-defined command.
+when used in a user-defined command.
@node Command Files,,,
@section Command Files
@cindex init file
@cindex @file{_GDBINIT__}
-When you start _GDBN__, it first executes commands from its @dfn{init files}.
-These are files named @file{_GDBINIT__}. _GDBN__ reads the init file (if any)
-in your home directory and then the init file (if any) in the current
-working directory. (The init files are not executed if the @samp{-nx}
-option is given.) You can also request the execution of a command file
-with the @samp{source} command:
+When you start _GDBN__, it automatically executes commands from its
+@dfn{init files}. These are files named @file{_GDBINIT__}. _GDBN__
+reads the init file (if any) in your home directory and then the init
+file (if any) in the current working directory. (The init files are not
+executed if the @samp{-nx} option is given.) You can also request the
+execution of a command file with the @samp{source} command:
@table @code
@item source @var{filename}
Commands that would ask for confirmation if used interactively proceed
without asking when used in a command file. Many _GDBN__ commands that
normally print messages to say what they are doing omit the messages
-when used in a command file.
+when called from command files.
@node Output,,,
@section Commands for Controlled Output
Your bug reports play an essential role in making _GDBN__ reliable.
Reporting a bug may help you by bringing a solution to your problem, or it
-may not. But in any case the important function of a bug report is to help
+may not. But in any case the principal function of a bug report is to help
the entire community by making the next version of _GDBN__ work better. Bug
reports are your contribution to the maintenance of _GDBN__.
In order for a bug report to serve its purpose, you must include the
-information that makes for fixing the bug.
+information that enables us to fix the bug.
@node Bug Criteria,,,
@section Have You Found a Bug?
@strong{Do not send bug reports to @samp{info-gdb}, or to
@samp{help-gdb}, or to any newsgroups.} Most users of _GDBN__ do not want to
-receive bug reports. Those that do, have asked to be on @samp{bug-gdb}.
+receive bug reports. Those that do, have arranged to receive @samp{bug-gdb}.
The mailing list @samp{bug-gdb} has a newsgroup which serves as a
repeater. The mailing list and the newsgroup carry exactly the same
fact or leave it out, state it!
Often people omit facts because they think they know what causes the
-problem and they conclude that some details don't matter. Thus, you might
+problem and assume that some details don't matter. Thus, you might
assume that the name of the variable you use in an example does not matter.
Well, probably it doesn't, but one cannot be sure. Perhaps the bug is a
stray memory reference which happens to fetch from the location where that
easiest thing for you to do, and the most helpful.
Keep in mind that the purpose of a bug report is to enable us to fix
-the bug if it is not known. It isn't very important what happens if
+the bug if it is new to us. It isn't very important what happens if
the bug is already known. Therefore, always write your bug reports on
-the assumption that the bug is not known.
+the assumption that the bug has not been reported previously.
Sometimes people give a few sketchy facts and ask, ``Does this ring a
bell?'' Those bug reports are useless, and we urge everyone to
projects / binutils-gdb.git / commitdiff