   This file documents the GNU debugger GDB.

   This is the Fifth Edition, April 1998, of `Debugging with GDB: the
GNU Source-Level Debugger' for GDB Version .

   Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
1997, 1998 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the entire resulting derived work is distributed under the terms
of a permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.

Readline Arguments
------------------

   You can pass numeric arguments to Readline commands.  Sometimes the
argument acts as a repeat count, other times it is the sign of the
argument that is significant.  If you pass a negative argument to a
command which normally acts in a forward direction, that command will
act in a backward direction.  For example, to kill text back to the
start of the line, you might type <M-> <C-k>.

   The general way to pass numeric arguments to a command is to type
meta digits before the command.  If the first `digit' you type is a
minus sign (<->), then the sign of the argument will be negative.  Once
you have typed one meta digit to get the argument started, you can type
the remainder of the digits, and then the command.  For example, to give
the <C-d> command an argument of 10, you could type <M-1 0 C-d>.

Readline Init File
==================

   Although the Readline library comes with a set of GNU Emacs-like
keybindings, it is possible that you would like to use a different set
of keybindings.  You can customize programs that use Readline by putting
commands in an "init" file in your home directory.  The name of this
file is `~/.inputrc'.

   When a program which uses the Readline library starts up, the
`~/.inputrc' file is read, and the keybindings are set.

   In addition, the <C-x C-r> command re-reads this init file, thus
incorporating any changes that you might have made to it.

Readline Init Syntax
--------------------

   There are only four constructs allowed in the `~/.inputrc' file:

Variable Settings
     You can change the state of a few variables in Readline.  You do
     this by using the `set' command within the init file.  Here is how
     you would specify that you wish to use `vi' line editing commands:

          set editing-mode vi

     Right now, there are only a few variables which can be set; so few
     in fact, that we just iterate them here:

    `editing-mode'
          The `editing-mode' variable controls which editing mode you
          are using.  By default, GNU Readline starts up in Emacs
          editing mode, where the keystrokes are most similar to Emacs.
          This variable can either be set to `emacs' or `vi'.

    `horizontal-scroll-mode'
          This variable can either be set to `On' or `Off'.  Setting it
          to `On' means that the text of the lines that you edit will
          scroll horizontally on a single screen line when they are
          larger than the width of the screen, instead of wrapping onto
          a new screen line.  By default, this variable is set to `Off'.

    `mark-modified-lines'
          This variable when set to `On', says to display an asterisk
          (`*') at the starts of history lines which have been modified.
          This variable is off by default.

    `prefer-visible-bell'
          If this variable is set to `On' it means to use a visible
          bell if one is available, rather than simply ringing the
          terminal bell.  By default, the value is `Off'.

Key Bindings
     The syntax for controlling keybindings in the `~/.inputrc' file is
     simple.  First you have to know the name of the command that you
     want to change.  The following pages contain tables of the command
     name, the default keybinding, and a short description of what the
     command does.

     Once you know the name of the command, simply place the name of
     the key you wish to bind the command to, a colon, and then the
     name of the command on a line in the `~/.inputrc' file.  The name
     of the key can be expressed in different ways, depending on which
     is most comfortable for you.

    KEYNAME: FUNCTION-NAME or MACRO
          KEYNAME is the name of a key spelled out in English.  For
          example:
               Control-u: universal-argument
               Meta-Rubout: backward-kill-word
               Control-o: ">&output"

          In the above example, <C-u> is bound to the function
          `universal-argument', and <C-o> is bound to run the macro
          expressed on the right hand side (that is, to insert the text
          `>&output' into the line).

    "KEYSEQ": FUNCTION-NAME or MACRO
          KEYSEQ differs from KEYNAME above in that strings denoting an
          entire key sequence can be specified.  Simply place the key
          sequence in double quotes.  GNU Emacs style key escapes can
          be used, as in the following example:

               "\C-u": universal-argument
               "\C-x\C-r": re-read-init-file
               "\e[11~": "Function Key 1"

          In the above example, <C-u> is bound to the function
          `universal-argument' (just as it was in the first example),
          <C-x C-r> is bound to the function `re-read-init-file', and
          <ESC [ 1 1 ~> is bound to insert the text `Function Key 1'.

Commands For Moving
...................

`beginning-of-line (<C-a>)'
     Move to the start of the current line.

`end-of-line (<C-e>)'
     Move to the end of the line.

`forward-char (<C-f>)'
     Move forward a character.

`backward-char (<C-b>)'
     Move back a character.

`forward-word (<M-f>)'
     Move forward to the end of the next word.

`backward-word (<M-b>)'
     Move back to the start of this, or the previous, word.

`clear-screen (<C-l>)'
     Clear the screen leaving the current line at the top of the screen.

Commands For Manipulating The History
.....................................

`accept-line (Newline, Return)'
     Accept the line regardless of where the cursor is.  If this line is
     non-empty, add it to the history list.  If this line was a history
     line, then restore the history line to its original state.

`previous-history (<C-p>)'
     Move `up' through the history list.

`next-history (<C-n>)'
     Move `down' through the history list.

`beginning-of-history (<M-<>)'
     Move to the first line in the history.

`end-of-history (<M->>)'
     Move to the end of the input history, i.e., the line you are
     entering.

`reverse-search-history (<C-r>)'
     Search backward starting at the current line and moving `up'
     through the history as necessary.  This is an incremental search.

`forward-search-history (<C-s>)'
     Search forward starting at the current line and moving `down'
     through the the history as necessary.

Commands For Changing Text
..........................

`delete-char (<C-d>)'
     Delete the character under the cursor.  If the cursor is at the
     beginning of the line, and there are no characters in the line, and
     the last character typed was not <C-d>, then return EOF.

`backward-delete-char (Rubout)'
     Delete the character behind the cursor.  A numeric argument says
     to kill the characters instead of deleting them.

`quoted-insert (<C-q>, <C-v>)'
     Add the next character that you type to the line verbatim.  This is
     how to insert things like <C-q> for example.

`tab-insert (<M-TAB>)'
     Insert a tab character.

`self-insert (a, b, A, 1, !, ...)'
     Insert yourself.

`transpose-chars (<C-t>)'
     Drag the character before point forward over the character at
     point.  Point moves forward as well.  If point is at the end of
     the line, then transpose the two characters before point.
     Negative arguments don't work.

`transpose-words (<M-t>)'
     Drag the word behind the cursor past the word in front of the
     cursor moving the cursor over that word as well.

`upcase-word (<M-u>)'
     Uppercase all letters in the current (or following) word.  With a
     negative argument, do the previous word, but do not move point.

`downcase-word (<M-l>)'
     Lowercase all letters in the current (or following) word.  With a
     negative argument, do the previous word, but do not move point.

`capitalize-word (<M-c>)'
     Uppercase the first letter in the current (or following) word.
     With a negative argument, do the previous word, but do not move
     point.

Killing And Yanking
...................

`kill-line (<C-k>)'
     Kill the text from the current cursor position to the end of the
     line.

`backward-kill-line ()'
     Kill backward to the beginning of the line.  This is normally
     unbound.

`kill-word (<M-d>)'
     Kill from the cursor to the end of the current word, or if between
     words, to the end of the next word.

`backward-kill-word (<M-DEL>)'
     Kill the word behind the cursor.

`unix-line-discard (<C-u>)'
     Kill the whole line the way <C-u> used to in Unix line input.  The
     killed text is saved on the kill-ring.

`unix-word-rubout (<C-w>)'
     Kill the word the way <C-w> used to in Unix line input.  The
     killed text is saved on the kill-ring.  This is different than
     backward-kill-word because the word boundaries differ.

`yank (<C-y>)'
     Yank the top of the kill ring into the buffer at point.

`yank-pop (<M-y>)'
     Rotate the kill-ring, and yank the new top.  You can only do this
     if the prior command is yank or yank-pop.

Specifying Numeric Arguments
............................

`digit-argument (<M-0>, <M-1>, ... <M-->)'
     Add this digit to the argument already accumulating, or start a new
     argument.  <M-> starts a negative argument.

`universal-argument ()'
     Do what <C-u> does in GNU Emacs.  By default, this is not bound.

Letting Readline Type For You
.............................

`complete (TAB)'
     Attempt to do completion on the text before point.  This is
     implementation defined.  Generally, if you are typing a filename
     argument, you can do filename completion; if you are typing a
     command, you can do command completion, if you are typing in a
     symbol to GDB, you can do symbol name completion, if you are
     typing in a variable to Bash, you can do variable name completion.

`possible-completions (M-?)'
     List the possible completions of the text before point.

Some Miscellaneous Commands
...........................

`re-read-init-file (<C-x> <C-r>)'
     Read in the contents of your `~/.inputrc' file, and incorporate
     any bindings found there.

`abort (<C-g>)'
     Stop running the current editing command.

`prefix-meta (ESC)'
     Make the next character that you type be metafied.  This is for
     people without a meta key.  Typing <ESC f> is equivalent to typing
     <M-f>.

`undo (<C-_>)'
     Incremental undo, separately remembered for each line.

`revert-line (<M-r>)'
     Undo all changes made to this line.  This is like typing the `undo'
     command enough times to get back to the beginning.

Readline `vi' Mode
------------------

   While the Readline library does not have a full set of `vi' editing
functions, it does contain enough to allow simple editing of the line.

   In order to switch interactively between GNU Emacs and `vi' editing
modes, use the command <M-C-j> (toggle-editing-mode).

   When you enter a line in `vi' mode, you are already placed in
`insertion' mode, as if you had typed an `i'.  Pressing <ESC> switches
you into `edit' mode, where you can edit the text of the line with the
standard `vi' movement keys, move to previous history lines with `k',
and following lines with `j', and so forth.

Using History Interactively
***************************

   This chapter describes how to use the GNU History Library
interactively, from a user's standpoint.

History Interaction
===================

   The History library provides a history expansion feature similar to
the history expansion in `csh'.  The following text describes the
syntax you use to manipulate history information.

   History expansion takes two parts.  In the first part, determine
which line from the previous history will be used for substitution.
This line is called the "event".  In the second part, select portions
of that line for inclusion into the current line.  These portions are
called "words".  GDB breaks the line into words in the same way that
the Bash shell does, so that several English (or Unix) words surrounded
by quotes are considered one word.

Event Designators
-----------------

   An "event designator" is a reference to a command line entry in the
history list.

`!'
     Start a history subsititution, except when followed by a space,
     tab, or the end of the line... <=> or <(>.

`!!'
     Refer to the previous command.  This is a synonym for `!-1'.

`!n'
     Refer to command line N.

`!-n'
     Refer to the command line N lines back.

`!string'
     Refer to the most recent command starting with STRING.

`!?string'[`?']
     Refer to the most recent command containing STRING.

Word Designators
----------------

   A <:> separates the event designator from the "word designator".  It
can be omitted if the word designator begins with a <^>, <$>, <*> or
<%>.  Words are numbered from the beginning of the line, with the first
word being denoted by a 0 (zero).

`0 (zero)'
     The zero'th word.  For many applications, this is the command word.

`n'
     The N'th word.

`^'
     The first argument.  that is, word 1.

`$'
     The last argument.

`%'
     The word matched by the most recent `?string?' search.

`x-y'
     A range of words; `-Y' Abbreviates `0-Y'.

`*'
     All of the words, excepting the zero'th.  This is a synonym for
     `1-$'.  It is not an error to use <*> if there is just one word in
     the event.  The empty string is returned in that case.

Modifiers
---------

   After the optional word designator, you can add a sequence of one or
more of the following "modifiers", each preceded by a <:>.

`#'
     The entire command line typed so far.  This means the current
     command, not the previous command.

`h'
     Remove a trailing pathname component, leaving only the head.

`r'
     Remove a trailing suffix of the form `.'SUFFIX, leaving the
     basename.

`e'
     Remove all but the suffix.

`t'
     Remove all leading  pathname  components, leaving the tail.

`p'
     Print the new command but do not execute it.

Formatting Documentation
************************

   The GDB 4 release includes an already-formatted reference card, ready
for printing with PostScript or Ghostscript, in the `gdb' subdirectory
of the main source directory(1).  If you can use PostScript or
Ghostscript with your printer, you can print the reference card
immediately with `refcard.ps'.

   The release also includes the source for the reference card.  You
can format it, using TeX, by typing:

     make refcard.dvi

   The GDB reference card is designed to print in "landscape" mode on
US "letter" size paper; that is, on a sheet 11 inches wide by 8.5 inches
high.  You will need to specify this form of printing as an option to
your DVI output program.

   All the documentation for GDB comes as part of the machine-readable
distribution.  The documentation is written in Texinfo format, which is
a documentation system that uses a single source file to produce both
on-line information and a printed manual.  You can use one of the Info
formatting commands to create the on-line version of the documentation
and TeX (or `texi2roff') to typeset the printed version.

   GDB includes an already formatted copy of the on-line Info version of
this manual in the `gdb' subdirectory.  The main Info file is
`gdb-version-number/gdb/gdb.info', and it refers to subordinate files
matching `gdb.info*' in the same directory.  If necessary, you can
print out these files, or read them with any editor; but they are
easier to read using the `info' subsystem in GNU Emacs or the
standalone `info' program, available as part of the GNU Texinfo
distribution.

   If you want to format these Info files yourself, you need one of the
Info formatting programs, such as `texinfo-format-buffer' or `makeinfo'.

   If you have `makeinfo' installed, and are in the top level GDB
source directory (`gdb-', in the case of version ), you can make the
Info file by typing:

     cd gdb
     make gdb.info

   If you want to typeset and print copies of this manual, you need TeX,
a program to print its DVI output files, and `texinfo.tex', the Texinfo
definitions file.

   TeX is a typesetting program; it does not print files directly, but
produces output files called DVI files.  To print a typeset document,
you need a program to print DVI files.  If your system has TeX
installed, chances are it has such a program.  The precise command to
use depends on your system; `lpr -d' is common; another (for PostScript
devices) is `dvips'.  The DVI print command may require a file name
without any extension or a `.dvi' extension.

   TeX also requires a macro definitions file called `texinfo.tex'.
This file tells TeX how to typeset a document written in Texinfo
format.  On its own, TeX cannot either read or typeset a Texinfo file.
`texinfo.tex' is distributed with GDB and is located in the
`gdb-VERSION-NUMBER/texinfo' directory.

   If you have TeX and a DVI printer program installed, you can typeset
and print this manual.  First switch to the the `gdb' subdirectory of
the main source directory (for example, to `gdb-/gdb') and then type:

     make gdb.dvi

   ---------- Footnotes ----------

   (1) In `gdb-/gdb/refcard.ps' of the version  release.

Installing GDB
**************

   GDB comes with a `configure' script that automates the process of
preparing GDB for installation; you can then use `make' to build the
`gdb' program.

   The GDB distribution includes all the source code you need for GDB
in a single directory, whose name is usually composed by appending the
version number to `gdb'.

   For example, the GDB version  distribution is in the `gdb-'
directory.  That directory contains:

`gdb-/configure (and supporting files)'
     script for configuring GDB and all its supporting libraries

`gdb-/gdb'
     the source specific to GDB itself

`gdb-/bfd'
     source for the Binary File Descriptor library

`gdb-/include'
     GNU include files

`gdb-/libiberty'
     source for the `-liberty' free software library

`gdb-/opcodes'
     source for the library of opcode tables and disassemblers

`gdb-/readline'
     source for the GNU command-line interface

`gdb-/glob'
     source for the GNU filename pattern-matching subroutine

`gdb-/mmalloc'
     source for the GNU memory-mapped malloc package

   The simplest way to configure and build GDB is to run `configure'
from the `gdb-VERSION-NUMBER' source directory, which in this example
is the `gdb-' directory.

   First switch to the `gdb-VERSION-NUMBER' source directory if you are
not already in it; then run `configure'.  Pass the identifier for the
platform on which GDB will run as an argument.

   For example:

     cd gdb-
     ./configure HOST
     make

where HOST is an identifier such as `sun4' or `decstation', that
identifies the platform where GDB will run.  (You can often leave off
HOST; `configure' tries to guess the correct value by examining your
system.)

   Running `configure HOST' and then running `make' builds the `bfd',
`readline', `mmalloc', and `libiberty' libraries, then `gdb' itself.
The configured source files, and the binaries, are left in the
corresponding source directories.

   `configure' is a Bourne-shell (`/bin/sh') script; if your system
does not recognize this automatically when you run a different shell,
you may need to run `sh' on it explicitly:

     sh configure HOST

   If you run `configure' from a directory that contains source
directories for multiple libraries or programs, such as the `gdb-'
source directory for version , `configure' creates configuration files
for every directory level underneath (unless you tell it not to, with
the `--norecursion' option).

   You can run the `configure' script from any of the subordinate
directories in the GDB distribution if you only want to configure that
subdirectory, but be sure to specify a path to it.

   For example, with version , type the following to configure only the
`bfd' subdirectory:

     cd gdb-/bfd
     ../configure HOST

   You can install `gdb' anywhere; it has no hardwired paths.  However,
you should make sure that the shell on your path (named by the `SHELL'
environment variable) is publicly readable.  Remember that GDB uses the
shell to start your program--some systems refuse to let GDB debug child
processes whose programs are not readable.

Compiling GDB in another directory
==================================

   If you want to run GDB versions for several host or target machines,
you need a different `gdb' compiled for each combination of host and
target.  `configure' is designed to make this easy by allowing you to
generate each configuration in a separate subdirectory, rather than in
the source directory.  If your `make' program handles the `VPATH'
feature (GNU `make' does), running `make' in each of these directories
builds the `gdb' program specified there.

   To build `gdb' in a separate directory, run `configure' with the
`--srcdir' option to specify where to find the source.  (You also need
to specify a path to find `configure' itself from your working
directory.  If the path to `configure' would be the same as the
argument to `--srcdir', you can leave out the `--srcdir' option; it is
assumed.)

   For example, with version , you can build GDB in a separate
directory for a Sun 4 like this:

     cd gdb-
     mkdir ../gdb-sun4
     cd ../gdb-sun4
     ../gdb-/configure sun4
     make

   When `configure' builds a configuration using a remote source
directory, it creates a tree for the binaries with the same structure
(and using the same names) as the tree under the source directory.  In
the example, you'd find the Sun 4 library `libiberty.a' in the
directory `gdb-sun4/libiberty', and GDB itself in `gdb-sun4/gdb'.

   One popular reason to build several GDB configurations in separate
directories is to configure GDB for cross-compiling (where GDB runs on
one machine--the "host"--while debugging programs that run on another
machine--the "target").  You specify a cross-debugging target by giving
the `--target=TARGET' option to `configure'.

   When you run `make' to build a program or library, you must run it
in a configured directory--whatever directory you were in when you
called `configure' (or one of its subdirectories).

   The `Makefile' that `configure' generates in each source directory
also runs recursively.  If you type `make' in a source directory such
as `gdb-' (or in a separate configured directory configured with
`--srcdir=DIRNAME/gdb-'), you will build all the required libraries,
and then build GDB.

   When you have multiple hosts or targets configured in separate
directories, you can run `make' on them in parallel (for example, if
they are NFS-mounted on each of the hosts); they will not interfere
with each other.

Specifying names for hosts and targets
======================================

   The specifications used for hosts and targets in the `configure'
script are based on a three-part naming scheme, but some short
predefined aliases are also supported.  The full naming scheme encodes
three pieces of information in the following pattern:

     ARCHITECTURE-VENDOR-OS

   For example, you can use the alias `sun4' as a HOST argument, or as
the value for TARGET in a `--target=TARGET' option.  The equivalent
full name is `sparc-sun-sunos4'.

   The `configure' script accompanying GDB does not provide any query
facility to list all supported host and target names or aliases.
`configure' calls the Bourne shell script `config.sub' to map
abbreviations to full names; you can read the script, if you wish, or
you can use it to test your guesses on abbreviations--for example:

     % sh config.sub sun4
     sparc-sun-sunos4.1.1
     % sh config.sub sun3
     m68k-sun-sunos4.1.1
     % sh config.sub decstation
     mips-dec-ultrix4.2
     % sh config.sub hp300bsd
     m68k-hp-bsd
     % sh config.sub i386v
     i386-unknown-sysv
     % sh config.sub i786v
     Invalid configuration `i786v': machine `i786v' not recognized

`config.sub' is also distributed in the GDB source directory (`gdb-',
for version ).

`configure' options
===================

   Here is a summary of the `configure' options and arguments that are
most often useful for building GDB.  `configure' also has several other
options not listed here.  See What Configure Does (configure.info),
for a full explanation of `configure'.

     configure [--help]
               [--prefix=DIR]
               [--srcdir=DIRNAME]
               [--norecursion] [--rm]
               [--target=TARGET] HOST

You may introduce options with a single `-' rather than `--' if you
prefer; but you may abbreviate option names if you use `--'.

`--help'
     Display a quick summary of how to invoke `configure'.

`-prefix=DIR'
     Configure the source to install programs and files under directory
     `DIR'.

`--srcdir=DIRNAME'
     *Warning: using this option requires GNU `make', or another `make'
     that implements the `VPATH' feature.*
     Use this option to make configurations in directories separate
     from the GDB source directories.  Among other things, you can use
     this to build (or maintain) several configurations simultaneously,
     in separate directories.  `configure' writes configuration
     specific files in the current directory, but arranges for them to
     use the source in the directory DIRNAME.  `configure' creates
     directories under the working directory in parallel to the source
     directories below DIRNAME.

`--norecursion'
     Configure only the directory level where `configure' is executed;
     do not propagate configuration to subdirectories.

`--rm'
     *Remove* files otherwise built during configuration.

`--target=TARGET'
     Configure GDB for cross-debugging programs running on the specified
     TARGET.  Without this option, GDB is configured to debug programs
     that run on the same machine (HOST) as GDB itself.

     There is no convenient way to generate a list of all available
     targets.

`HOST ...'
     Configure GDB to run on the specified HOST.

     There is no convenient way to generate a list of all available
     hosts.

`configure' accepts other options, for compatibility with configuring
other GNU tools recursively; but these are the only options that affect
GDB or its supporting libraries.