gdb.texinfo

早期freebsd实现

You can also start with both an executable program and a core file
specified:

@example
_GDBP__ @var{program} @var{core}
@end example

You can, instead, specify a process ID as a second argument, if you want
to debug a running process:

@example
_GDBP__ @var{program} 1234
@end example

@noindent
would attach _GDBN__ to process @code{1234} (unless you also have a file
named @file{1234}; _GDBN__ does check for a core file first).

Taking advantage of the second command-line argument requires a fairly
complete operating system; when you use _GDBN__ as a remote debugger
attached to a bare board, there may not be any notion of ``process'',
and there is often no way to get a core dump.
_fi__(!_BARE__)

@noindent
You can further control how _GDBN__ starts up by using command-line
options.  _GDBN__ itself can remind you of the options available.

@noindent
Type

@example
_GDBP__ -help
@end example

@noindent
to display all available options and briefly describe their use
(@samp{_GDBP__ -h} is a shorter equivalent).

All options and command line arguments you give are processed
in sequential order.  The order makes a difference when the
@samp{-x} option is used.

@menu
_if__(!_GENERIC__)
_include__(gdbinv-m.m4)_dnl__
_fi__(!_GENERIC__)
* File Options::                Choosing Files
* Mode Options::                Choosing Modes
@end menu

_if__(!_GENERIC__)
_include__(gdbinv-s.m4)
_fi__(!_GENERIC__)

@node File Options
@subsection Choosing Files

_if__(!_BARE__)
When _GDBN__ starts, it reads any arguments other than options as
specifying an executable file and core file (or process ID).  This is
the same as if the arguments were specified by the @samp{-se} and
@samp{-c} options respectively.  (_GDBN__ reads the first argument
that does not have an associated option flag as equivalent to the
@samp{-se} option followed by that argument; and the second argument
that does not have an associated option flag, if any, as equivalent to
the @samp{-c} option followed by that argument.)
_fi__(!_BARE__)
_if__(_BARE__)
When _GDBN__ starts, it reads any argument other than options as
specifying an executable file.  This is the same as if the argument was
specified by the @samp{-se} option.
_fi__(_BARE__)

Many options have both long and short forms; both are shown in the
following list.  _GDBN__ also recognizes the long forms if you truncate
them, so long as enough of the option is present to be unambiguous.
(If you prefer, you can flag option arguments with @samp{--} rather
than @samp{-}, though we illustrate the more usual convention.)

@table @code
@item -symbols=@var{file}
@itemx -s @var{file}
Read symbol table from file @var{file}.

@item -exec=@var{file}
@itemx -e @var{file}
Use file @var{file} as the executable file to execute when
appropriate, and for examining pure data in conjunction with a core
dump.

@item -se=@var{file}
Read symbol table from file @var{file} and use it as the executable
file.

_if__(!_BARE__)
@item -core=@var{file}
@itemx -c @var{file}
Use file @var{file} as a core dump to examine.
_fi__(!_BARE__)

@item -command=@var{file}
@itemx -x @var{file}
Execute _GDBN__ commands from file @var{file}.  @xref{Command Files}.

@item -directory=@var{directory}
@itemx -d @var{directory}
Add @var{directory} to the path to search for source files.

_if__(!_BARE__)
@item -m
@itemx -mapped
@emph{Warning: this option depends on operating system facilities that are not
supported on all systems.}@*
If memory-mapped files are available on your system through the @code{mmap}
system call, you can use this option 
to have _GDBN__ write the symbols from your
program into a reusable file in the current directory.  If the program you are debugging is
called @file{/tmp/fred}, the mapped symbol file will be @file{./fred.syms}.
Future _GDBN__ debugging sessions will notice the presence of this file,
and will quickly map in symbol information from it, rather than reading
the symbol table from the executable program.

The @file{.syms} file is specific to the host machine on which _GDBN__ is run.
It holds an exact image of _GDBN__'s internal symbol table.  It cannot be
shared across multiple host platforms.
_fi__(!_BARE__)

@item -r
@itemx -readnow
Read each symbol file's entire symbol table immediately, rather than
the default, which is to read it incrementally as it is needed.
This makes startup slower, but makes future operations faster.
@end table

_if__(!_BARE__)
The @code{-mapped} and @code{-readnow} options are typically combined in order to
build a @file{.syms} file that contains complete symbol information.
A simple GDB invocation to do nothing but build a @file{.syms} file for future
use is:

@example
	gdb -batch -nx -mapped -readnow programname
@end example
_fi__(!_BARE__)

@node Mode Options
@subsection Choosing Modes

You can run _GDBN__ in various alternative modes---for example, in
batch mode or quiet mode.

@table @code
@item -nx
@itemx -n
Do not execute commands from any @file{_GDBINIT__} initialization files.
Normally, the commands in these files are executed after all the
command options and arguments have been processed.
@xref{Command Files}.

@item -quiet
@itemx -q
``Quiet''.  Do not print the introductory and copyright messages.  These
messages are also suppressed in batch mode.

@item -batch
Run in batch mode.  Exit with status @code{0} after processing all the command
files specified with @samp{-x} (and @file{_GDBINIT__}, if not inhibited).
Exit with nonzero status if an error occurs in executing the _GDBN__
commands in the command files.

Batch mode may be useful for running _GDBN__ as a filter, for example to
download and run a program on another computer; in order to make this
more useful, the message

@example
Program exited normally.
@end example

@noindent
(which is ordinarily issued whenever a program running under _GDBN__ control
terminates) is not issued when running in batch mode.

@item -cd=@var{directory}
Run _GDBN__ using @var{directory} as its working directory,
instead of the current directory.

_if__(_LUCID__)
@item -context @var{authentication}
When the Energize programming system starts up _GDBN__, it uses this
option to trigger an alternate mode of interaction.
@var{authentication} is a pair of numeric codes that identify _GDBN__
as a client in the Energize environment.  Avoid this option when you run
_GDBN__ directly from the command line.  See @ref{Energize,,Using
_GDBN__ with Energize} for more discussion of using _GDBN__ with Energize.
_fi__(_LUCID__)

@item -fullname
@itemx -f
Emacs sets this option when it runs _GDBN__ as a subprocess.  It tells _GDBN__
to output the full file name and line number in a standard,
recognizable fashion each time a stack frame is displayed (which
includes each time your program stops).  This recognizable format looks
like two @samp{\032} characters, followed by the file name, line number
and character position separated by colons, and a newline.  The
Emacs-to-_GDBN__ interface program uses the two @samp{\032} characters as
a signal to display the source code for the frame.

_if__(_GENERIC__ || !_H8__)
@item -b @var{bps}
Set the line speed (baud rate or bits per second) of any serial
interface used by _GDBN__ for remote debugging.

@item -tty=@var{device}
Run using @var{device} for your program's standard input and output.
@c FIXME: kingdon thinks there is more to -tty.  Investigate.
_fi__(_GENERIC__ || !_H8__)
@end table

@node Leaving _GDBN__
@section Leaving _GDBN__
@cindex exiting _GDBN__

@table @code
@item quit
@kindex quit
@kindex q
To exit _GDBN__, use the @code{quit} command (abbreviated @code{q}), or type
an end-of-file character (usually @kbd{C-d}).
@end table

@cindex interrupt
An interrupt (often @kbd{C-c}) will not exit from _GDBN__, but rather
will terminate the action of any _GDBN__ command that is in progress and
return to _GDBN__ command level.  It is safe to type the interrupt
character at any time because _GDBN__ does not allow it to take effect
until a time when it is safe.

_if__(!_BARE__)
If you have been using _GDBN__ to control an attached process or device, you
can release it with the @code{detach} command; @pxref{Attach,
,Debugging an Already-Running Process}..
_fi__(!_BARE__)

_if__(!_BARE__)
@node Shell Commands
@section Shell Commands

If you need to execute occasional shell commands during your
debugging session, there is no need to leave or suspend _GDBN__; you can
just use the @code{shell} command.

@table @code
@item shell @var{command string}
@kindex shell
@cindex shell escape
Directs _GDBN__ to invoke an inferior shell to execute @var{command
string}.  If it exists, the environment variable @code{SHELL} is used
for the name of the shell to run.  Otherwise _GDBN__ uses
@code{/bin/sh}.
@end table

The utility @code{make} is often needed in development environments.
You do not have to use the @code{shell} command for this purpose in _GDBN__:

@table @code
@item make @var{make-args}
@kindex make
@cindex calling make
Causes _GDBN__ to execute an inferior @code{make} program with the specified
arguments.  This is equivalent to @samp{shell make @var{make-args}}.
@end table
_fi__(!_BARE__)

@node Commands
@chapter _GDBN__ Commands

You can abbreviate a _GDBN__ command to the first few letters of the command
name, if that abbreviation is unambiguous; and you can repeat certain
_GDBN__ commands by typing just @key{RET}.  You can also use the @key{TAB}
key to get _GDBN__ to fill out the rest of a word in a command (or to
show you the alternatives available, if there's more than one possibility).

@menu
* Command Syntax::              Command Syntax
* Completion::                  Command Completion
* Help::                        Getting Help
@end menu

@node Command Syntax
@section Command Syntax

A _GDBN__ command is a single line of input.  There is no limit on how long
it can be.  It starts with a command name, which is followed by arguments
whose meaning depends on the command name.  For example, the command
@code{step} accepts an argument which is the number of times to step,
as in @samp{step 5}.  You can also use the @code{step} command with
no arguments.  Some command names do not allow any arguments.

@cindex abbreviation
_GDBN__ command names may always be truncated if that abbreviation is
unambiguous.  Other possible command abbreviations are listed in the
documentation for individual commands.  In some cases, even ambiguous
abbreviations are allowed; for example, @code{s} is specially defined as
equivalent to @code{step} even though there are other commands whose
names start with @code{s}.  You can test abbreviations by using them as
arguments to the @code{help} command.

@cindex repeating commands
@kindex RET
A blank line as input to _GDBN__ (typing just @key{RET}) means to
repeat the previous command. Certain commands (for example, @code{run})
will not repeat this way; these are commands for which unintentional
repetition might cause trouble and which you are unlikely to want to
repeat.

The @code{list} and @code{x} commands, when you repeat them with
@key{RET}, construct new arguments rather than repeating
exactly as typed.  This permits easy scanning of source or memory.

_GDBN__ can also use @key{RET} in another way: to partition lengthy
output, in a way similar to the common utility @code{more}
(@pxref{Screen Size}).  Since it is easy to press one @key{RET} too many
in this situation, _GDBN__ disables command repetition after any command
that generates this sort of display.

@kindex #
@cindex comment
A line of input starting with @kbd{#} is a comment; it does nothing.
This is useful mainly in command files (@pxref{Command Files}).

@node Completion
@section Command Completion

@cindex completion
@cindex word completion
_GDBN__ can fill in the rest of a word in a command for you, if there's
only one possibility; it can also show you what the valid possibilities
are for the next word in a command, at any time.  This works for _GDBN__
commands, _GDBN__ subcommands, and the names of symbols in your program.

Press the @key{TAB} key whenever you want _GDBN__ to fill out the rest
of a word.  If there's only one possibility, _GDBN__ will fill in the
word, and wait for you to finish the command (or press @key{RET} to
enter it).  For example, if you type

@c FIXME "@key" doesn't distinguish its argument sufficiently to permit
@c complete accuracy in these examples; space introduced for clarity.
@c If texinfo enhancements make it unnecessary, it would be nice to
@c replace " @key" by "@key" in the following...
@example
(_GDBP__) info bre @key{TAB}
@end example

@noindent
_GDBN__ fills in the rest of the word @samp{breakpoints}, since that's
the only @code{info} subcommand beginning with @samp{bre}:

@example
(_GDBP__) info breakpoints
@end example