gdb.texinfo

早期freebsd实现

@noindent
You can either press @key{RET} at this point, to run the @code{info
breakpoints} command, or backspace and enter something else, if
@samp{breakpoints} doesn't look like the command you expected.  (If you
were sure you wanted @code{info breakpoints} in the first place, you
might as well just type @key{RET} immediately after @samp{info bre},
to exploit command abbreviations rather than command completion).

If there is more than one possibility for the next word when you press
@key{TAB}, _GDBN__ will sound a bell.  You can either supply more
characters and try again, or just press @key{TAB} a second time, and
_GDBN__ will display all the possible completions for that word.  For
example, you might want to set a breakpoint on a subroutine whose name
begins with @samp{make_}, but when you type @kbd{b make_@key{TAB}} _GDBN__
just sounds the bell.  Typing @key{TAB} again will display all the
function names in your program that begin with those characters, for
example:

@example
(_GDBP__) b make_ @key{TAB}
@exdent _GDBN__ sounds bell; press @key{TAB} again, to see:
make_a_section_from_file     make_environ               
make_abs_section             make_function_type         
make_blockvector             make_pointer_type          
make_cleanup                 make_reference_type        
make_command                 make_symbol_completion_list
(GDBP__) b make_
@end example

@noindent
After displaying the available possibilities, _GDBN__ copies your
partial input (@samp{b make_} in the example) so you can finish the
command.

If you just want to see the list of alternatives in the first place, you
can press @kbd{M-?} rather than pressing @key{TAB} twice. @kbd{M-?}
means @kbd{@key{META} ?}.  You can type this
_if__(_GENERIC__||!_DOSHOST__)
either by holding down a
key designated as the @key{META} shift on your keyboard (if there is
one) while typing @kbd{?}, or
_fi__(_GENERIC__||!_DOSHOST__)
as @key{ESC} followed by @kbd{?}.

@cindex quotes in commands
@cindex completion of quoted strings
Sometimes the string you need, while logically a ``word'', may contain
parentheses or other characters that _GDBN__ normally excludes from its
notion of a word.  To permit word completion to work in this situation,
you may enclose words in @code{'} (single quote marks) in _GDBN__ commands.

The most likely situation where you might need this is in typing the
name of a C++ function.  This is because C++ allows function overloading
(multiple definitions of the same function, distinguished by argument
type).  For example, when you want to set a breakpoint you may need to
distinguish whether you mean the version of @code{name} that takes an
@code{int} parameter, @code{name(int)}, or the version that takes a
@code{float} parameter, @code{name(float)}.  To use the word-completion
facilities in this situation, type a single quote @code{'} at the
beginning of the function name.  This alerts _GDBN__ that it may need to
consider more information than usual when you press @key{TAB} or
@kbd{M-?} to request word completion:

@example
(_GDBP__) b 'bubble( @key{M-?}
bubble(double,double)    bubble(int,int)
(_GDBP__) b 'bubble(
@end example

In some cases, _GDBN__ can tell that completing a name will require
quotes.  When this happens, _GDBN__ will insert the quote for you (while
completing as much as it can) if you do not type the quote in the first
place:

@example
(_GDBP__) b bub @key{TAB}
@exdent _GDBN__ alters your input line to the following, and rings a bell:
(_GDBP__) b 'bubble(
@end example

@noindent
In general, _GDBN__ can tell that a quote is needed (and inserts it) if
you have not yet started typing the argument list when you ask for
completion on an overloaded symbol.


@node Help
@section Getting Help
@cindex online documentation
@kindex help

You can always ask _GDBN__ itself for information on its commands, using the
command @code{help}.

@table @code
@item help
@itemx h
@kindex h
You can use @code{help} (abbreviated @code{h}) with no arguments to
display a short list of named classes of commands:

@smallexample
(_GDBP__) help
List of classes of commands:

running -- Running the program
stack -- Examining the stack
data -- Examining data
breakpoints -- Making program stop at certain points
files -- Specifying and examining files
status -- Status inquiries
support -- Support facilities
user-defined -- User-defined commands
aliases -- Aliases of other commands
obscure -- Obscure features

Type "help" followed by a class name for a list of 
commands in that class.
Type "help" followed by command name for full 
documentation.
Command name abbreviations are allowed if unambiguous.
(_GDBP__)
@end smallexample

@item help @var{class}
Using one of the general help classes as an argument, you can get a
list of the individual commands in that class.  For example, here is the
help display for the class @code{status}:

@smallexample
(_GDBP__) help status
Status inquiries.

List of commands:

show -- Generic command for showing things set with "set"
info -- Generic command for printing status

Type "help" followed by command name for full 
documentation.
Command name abbreviations are allowed if unambiguous.
(_GDBP__)
@end smallexample

@item help @var{command}
With a command name as @code{help} argument, _GDBN__ will display a
short paragraph on how to use that command.
@end table

In addition to @code{help}, you can use the _GDBN__ commands @code{info}
and @code{show} to inquire about the state of your program, or the state
of _GDBN__ itself.  Each command supports many topics of inquiry; this
manual introduces each of them in the appropriate context.  The listings
under @code{info} and under @code{show} in the Index point to
all the sub-commands.  @xref{Index}.

@c @group
@table @code
@item info
@kindex info
@kindex i
This command (abbreviated @code{i}) is for describing the state of your
program; for example, it can list the arguments given to your program
(@code{info args}), the registers currently in use (@code{info
registers}), or the breakpoints you have set (@code{info breakpoints}).
You can get a complete list of the @code{info} sub-commands with
@w{@code{help info}}.

@kindex show
@item show
In contrast, @code{show} is for describing the state of _GDBN__ itself.
You can change most of the things you can @code{show}, by using the
related command @code{set}; for example, you can control what number
system is used for displays with @code{set radix}, or simply inquire
which is currently in use with @code{show radix}.

@kindex info set
To display all the settable parameters and their current
values, you can use @code{show} with no arguments; you may also use
@code{info set}.  Both commands produce the same display.
@c FIXME: "info set" violates the rule that "info" is for state of
@c FIXME...program.  Ck w/ GNU: "info set" to be called something else,
@c FIXME...or change desc of rule---eg "state of prog and debugging session"?
@end table
@c @end group

Here are three miscellaneous @code{show} subcommands, all of which are
exceptional in lacking corresponding @code{set} commands:

@table @code
@kindex show version
@cindex version number
@item show version
Show what version of _GDBN__ is running.  You should include this
information in _GDBN__ bug-reports.  If multiple versions of _GDBN__ are in
use at your site, you may occasionally want to make sure what version
of _GDBN__ you are running; as _GDBN__ evolves, new commands are introduced,
and old ones may wither away.  The version number is also announced
when you start _GDBN__ with no arguments.

@kindex show copying
@item show copying
Display information about permission for copying _GDBN__.

@kindex show warranty
@item show warranty
Display the GNU ``NO WARRANTY'' statement.
@end table

@node Running
@chapter Running Programs Under _GDBN__

To debug a program, you must run it under _GDBN__.

@menu
* Compilation::                 Compiling for Debugging
* Starting::                    Starting your Program
_if__(!_BARE__)
* Arguments::                   Your Program's Arguments
* Environment::                 Your Program's Environment
* Working Directory::           Your Program's Working Directory
* Input/Output::                Your Program's Input and Output
* Attach::                      Debugging an Already-Running Process
* Kill Process::                Killing the Child Process
* Process Information::         Additional Process Information
_fi__(!_BARE__)
@end menu

@node Compilation
@section Compiling for Debugging

In order to debug a program effectively, you need to generate
debugging information when you compile it.  This debugging information
is stored in the object file; it describes the data type of each
variable or function and the correspondence between source line numbers
and addresses in the executable code.

To request debugging information, specify the @samp{-g} option when you run
the compiler.

Many C compilers are unable to handle the @samp{-g} and @samp{-O}
options together.  Using those compilers, you cannot generate optimized
executables containing debugging information.

_GCC__, the GNU C compiler, supports @samp{-g} with or without
@samp{-O}, making it possible to debug optimized code.  We recommend
that you @emph{always} use @samp{-g} whenever you compile a program.
You may think your program is correct, but there is no sense in pushing
your luck.

@cindex optimized code, debugging
@cindex debugging optimized code
When you debug a program compiled with @samp{-g -O}, remember that the
optimizer is rearranging your code; the debugger will show you what's
really there.  Don't be too surprised when the execution path doesn't
exactly match your source file!  An extreme example: if you define a
variable, but never use it, _GDBN__ will never see that
variable---because the compiler optimizes it out of existence.

Some things do not work as well with @samp{-g -O} as with just
@samp{-g}, particularly on machines with instruction scheduling.  If in
doubt, recompile with @samp{-g} alone, and if this fixes the problem,
please report it as a bug (including a test case!).

Older versions of the GNU C compiler permitted a variant option
@w{@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
@comment produce strange output in this case.  (but no promises).
If your program includes archives made with the @code{ar} program, and
if the object files used as input to @code{ar} were compiled without the
@samp{-g} option and have names longer than 15 characters, _GDBN__ will get
confused reading your program's symbol table.  No error message will be
given, but _GDBN__ may behave strangely.  The reason for this problem is a
deficiency in the Unix archive file format, which cannot represent file
names longer than 15 characters.

To avoid this problem, compile the archive members with the @samp{-g}
option or use shorter file names.  Alternatively, use a version of GNU
@code{ar} dated more recently than August 1989.
@end ignore

@node Starting
@section Starting your Program
@cindex starting
@cindex running

@table @code
@item run
@itemx r
@kindex run
Use the @code{run} command to start your program under _GDBN__.  You must
first specify the program name
_if__(_VXWORKS__)
(except on VxWorks)
_fi__(_VXWORKS__)
with an argument to
_GDBN__ (@pxref{Invocation, ,Getting In and Out of _GDBN__}), or by using the
@code{file} or @code{exec-file} command (@pxref{Files, ,Commands to
Specify Files}).

@end table

_if__(!_BARE__)
If you are running your program in an execution environment that
supports processes, @code{run} creates an inferior process and makes
that process run your program.  (In environments without processes,
@code{run} jumps to the start of your program.)

The execution of a program is affected by certain information it
receives from its superior.  _GDBN__ provides ways to specify this
information, which you must do @emph{before} starting your program.  (You
can change it after starting your program, but such changes will only affect
your program the next time you start it.)  This information may be
divided into four categories:

@table @asis
@item The @emph{arguments.}
Specify the arguments to give your program as the arguments of the
@code{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
(such as wildcard expansion or variable substitution) in describing
the arguments.  In Unix systems, you can control which shell is used
with the @code{SHELL} environment variable. @xref{Arguments, ,Your
Program's Arguments}.

@item The @emph{environment.}
Your program normally inherits its environment from _GDBN__, but you can
use the _GDBN__ commands @code{set environment} and @code{unset
environment} to change parts of the environment that will be given to
your program.  @xref{Environment, ,Your Program's Environment}.

@item The @emph{working directory.}
Your program inherits its working directory from _GDBN__.  You can set
_GDBN__'s working directory with the @code{cd} command in _GDBN__.
@xref{Working Directory, ,Your Program's Working Directory}.

@item The @emph{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 @code{tty} command to
set a different device for your program.
@xref{Input/Output, ,Your Program's Input and Output}.

@cindex pipes
@emph{Warning:} While input and output redirection work, you cannot use
pipes to pass the output of the program you are debugging to another
program; if you attempt this, _GDBN__ is likely to wind up debugging the
wrong program.
@end table
_fi__(!_BARE__)

When you issue the @code{run} command, your program begins to execute
immediately.  @xref{Stopping, ,Stopping and Continuing}, for discussion
of how to arrange for your program to stop.  Once your program has
stopped, you may calls functions in your program, using the @code{print}
or @code{call} commands.  @xref{Data, ,Examining Data}.