Subversion Repositories or1k_old

This is gdb.info, produced by makeinfo version 4.1 from ./gdb.texinfo.

INFO-DIR-SECTION Programming & development tools.
START-INFO-DIR-ENTRY
* Gdb: (gdb).                     The GNU debugger.
END-INFO-DIR-ENTRY

   This file documents the GNU debugger GDB.

   This is the Ninth Edition, December 2001, of `Debugging with GDB:
the GNU Source-Level Debugger' for GDB Version 5.3.

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

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Free Software" and "Free Software Needs Free
Documentation", with the Front-Cover Texts being "A GNU Manual," and
with the Back-Cover Texts as in (a) below.

   (a) The Free Software Foundation's Back-Cover Text is: "You have
freedom to copy and modify this GNU Manual, like GNU software.  Copies
published by the Free Software Foundation raise funds for GNU
development."


File: gdb.info,  Node: Commands For History,  Next: Commands For Text,  Prev: Commands For Moving,  Up: Bindable Readline Commands

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 currently
     being entered.

`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.  This is an incremental
     search.

`non-incremental-reverse-search-history (M-p)'
     Search backward starting at the current line and moving `up'
     through the history as necessary using a non-incremental search
     for a string supplied by the user.

`non-incremental-forward-search-history (M-n)'
     Search forward starting at the current line and moving `down'
     through the the history as necessary using a non-incremental search
     for a string supplied by the user.

`history-search-forward ()'
     Search forward through the history for the string of characters
     between the start of the current line and the point.  This is a
     non-incremental search.  By default, this command is unbound.

`history-search-backward ()'
     Search backward through the history for the string of characters
     between the start of the current line and the point.  This is a
     non-incremental search.  By default, this command is unbound.

`yank-nth-arg (M-C-y)'
     Insert the first argument to the previous command (usually the
     second word on the previous line).  With an argument N, insert the
     Nth word from the previous command (the words in the previous
     command begin with word 0).  A negative argument inserts the Nth
     word from the end of the previous command.

`yank-last-arg (M-., M-_)'
     Insert last argument to the previous command (the last word of the
     previous history entry).  With an argument, behave exactly like
     `yank-nth-arg'.  Successive calls to `yank-last-arg' move back
     through the history list, inserting the last argument of each line
     in turn.


File: gdb.info,  Node: Commands For Text,  Next: Commands For Killing,  Prev: Commands For History,  Up: Bindable Readline Commands

Commands For Changing Text
--------------------------

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

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

`forward-backward-delete-char ()'
     Delete the character under the cursor, unless the cursor is at the
     end of the line, in which case the character behind the cursor is
     deleted.  By default, this is not bound to a key.

`quoted-insert (C-q, C-v)'
     Add the next character typed to the line verbatim.  This is how to
     insert key sequences 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 the cursor forward over the character at
     the cursor, moving the cursor forward as well.  If the insertion
     point is at the end of the line, then this transposes the last two
     characters of the line.  Negative arguments have no effect.

`transpose-words (M-t)'
     Drag the word before point past the word after point, moving point
     past that word as well.

`upcase-word (M-u)'
     Uppercase the current (or following) word.  With a negative
     argument, uppercase the previous word, but do not move the cursor.

`downcase-word (M-l)'
     Lowercase the current (or following) word.  With a negative
     argument, lowercase the previous word, but do not move the cursor.

`capitalize-word (M-c)'
     Capitalize the current (or following) word.  With a negative
     argument, capitalize the previous word, but do not move the cursor.


File: gdb.info,  Node: Commands For Killing,  Next: Numeric Arguments,  Prev: Commands For Text,  Up: Bindable Readline Commands

Killing And Yanking
-------------------

`kill-line (C-k)'
     Kill the text from point to the end of the line.

`backward-kill-line (C-x Rubout)'
     Kill backward to the beginning of the line.

`unix-line-discard (C-u)'
     Kill backward from the cursor to the beginning of the current line.

`kill-whole-line ()'
     Kill all characters on the current line, no matter point is.  By
     default, this is unbound.

`kill-word (M-d)'
     Kill from point to the end of the current word, or if between
     words, to the end of the next word.  Word boundaries are the same
     as `forward-word'.

`backward-kill-word (M-DEL)'
     Kill the word behind point.  Word boundaries are the same as
     `backward-word'.

`unix-word-rubout (C-w)'
     Kill the word behind point, using white space as a word boundary.
     The killed text is saved on the kill-ring.

`delete-horizontal-space ()'
     Delete all spaces and tabs around point.  By default, this is
     unbound.

`kill-region ()'
     Kill the text in the current region.  By default, this command is
     unbound.

`copy-region-as-kill ()'
     Copy the text in the region to the kill buffer, so it can be yanked
     right away.  By default, this command is unbound.

`copy-backward-word ()'
     Copy the word before point to the kill buffer.  The word
     boundaries are the same as `backward-word'.  By default, this
     command is unbound.

`copy-forward-word ()'
     Copy the word following point to the kill buffer.  The word
     boundaries are the same as `forward-word'.  By default, this
     command is unbound.

`yank (C-y)'
     Yank the top of the kill ring into the buffer at the current
     cursor position.

`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.


File: gdb.info,  Node: Numeric Arguments,  Next: Commands For Completion,  Prev: Commands For Killing,  Up: Bindable Readline Commands

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 ()'
     This is another way to specify an argument.  If this command is
     followed by one or more digits, optionally with a leading minus
     sign, those digits define the argument.  If the command is
     followed by digits, executing `universal-argument' again ends the
     numeric argument, but is otherwise ignored.  As a special case, if
     this command is immediately followed by a character that is
     neither a digit or minus sign, the argument count for the next
     command is multiplied by four.  The argument count is initially
     one, so executing this function the first time makes the argument
     count four, a second time makes the argument count sixteen, and so
     on.  By default, this is not bound to a key.


File: gdb.info,  Node: Commands For Completion,  Next: Keyboard Macros,  Prev: Numeric Arguments,  Up: Bindable Readline Commands

Letting Readline Type For You
-----------------------------

`complete (TAB)'
     Attempt to do completion on the text before the cursor.  This is
     application-specific.  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,
     and so on.

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

`insert-completions (M-*)'
     Insert all completions of the text before point that would have
     been generated by `possible-completions'.

`menu-complete ()'
     Similar to `complete', but replaces the word to be completed with
     a single match from the list of possible completions.  Repeated
     execution of `menu-complete' steps through the list of possible
     completions, inserting each match in turn.  At the end of the list
     of completions, the bell is rung and the original text is restored.
     An argument of N moves N positions forward in the list of matches;
     a negative argument may be used to move backward through the list.
     This command is intended to be bound to `TAB', but is unbound by
     default.

`delete-char-or-list ()'
     Deletes the character under the cursor if not at the beginning or
     end of the line (like `delete-char').  If at the end of the line,
     behaves identically to `possible-completions'.  This command is
     unbound by default.


File: gdb.info,  Node: Keyboard Macros,  Next: Miscellaneous Commands,  Prev: Commands For Completion,  Up: Bindable Readline Commands

Keyboard Macros
---------------

`start-kbd-macro (C-x ()'
     Begin saving the characters typed into the current keyboard macro.

`end-kbd-macro (C-x ))'
     Stop saving the characters typed into the current keyboard macro
     and save the definition.

`call-last-kbd-macro (C-x e)'
     Re-execute the last keyboard macro defined, by making the
     characters in the macro appear as if typed at the keyboard.


File: gdb.info,  Node: Miscellaneous Commands,  Prev: Keyboard Macros,  Up: Bindable Readline Commands

Some Miscellaneous Commands
---------------------------

`re-read-init-file (C-x C-r)'
     Read in the contents of the INPUTRC file, and incorporate any
     bindings or variable assignments found there.

`abort (C-g)'
     Abort the current editing command and ring the terminal's bell
     (subject to the setting of `bell-style').

`do-uppercase-version (M-a, M-b, M-X, ...)'
     If the metafied character X is lowercase, run the command that is
     bound to the corresponding uppercase character.

`prefix-meta (ESC)'
     Make the next character typed be metafied.  This is for keyboards
     without a meta key.  Typing `ESC f' is equivalent to typing `M-f'.

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

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

`tilde-expand (M-~)'
     Perform tilde expansion on the current word.

`set-mark (C-@)'
     Set the mark to the current point.  If a numeric argument is
     supplied, the mark is set to that position.

`exchange-point-and-mark (C-x C-x)'
     Swap the point with the mark.  The current cursor position is set
     to the saved position, and the old cursor position is saved as the
     mark.

`character-search (C-])'
     A character is read and point is moved to the next occurrence of
     that character.  A negative count searches for previous
     occurrences.

`character-search-backward (M-C-])'
     A character is read and point is moved to the previous occurrence
     of that character.  A negative count searches for subsequent
     occurrences.

`insert-comment (M-#)'
     The value of the `comment-begin' variable is inserted at the
     beginning of the current line, and the line is accepted as if a
     newline had been typed.

`dump-functions ()'
     Print all of the functions and their key bindings to the Readline
     output stream.  If a numeric argument is supplied, the output is
     formatted in such a way that it can be made part of an INPUTRC
     file.  This command is unbound by default.

`dump-variables ()'
     Print all of the settable variables and their values to the
     Readline output stream.  If a numeric argument is supplied, the
     output is formatted in such a way that it can be made part of an
     INPUTRC file.  This command is unbound by default.

`dump-macros ()'
     Print all of the Readline key sequences bound to macros and the
     strings they ouput.  If a numeric argument is supplied, the output
     is formatted in such a way that it can be made part of an INPUTRC
     file.  This command is unbound by default.


File: gdb.info,  Node: Readline vi Mode,  Prev: Bindable Readline Commands,  Up: Command Line Editing

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.
The Readline `vi' mode behaves as specified in the POSIX 1003.2
standard.

   In order to switch interactively between `emacs' and `vi' editing
modes, use the command M-C-j (toggle-editing-mode).  The Readline
default is `emacs' 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 `command' mode, where you can edit the text of the line with
the standard `vi' movement keys, move to previous history lines with
`k' and subsequent lines with `j', and so forth.


File: gdb.info,  Node: Using History Interactively,  Next: Installing GDB,  Prev: Command Line Editing,  Up: Top

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

   This chapter describes how to use the GNU History Library
interactively, from a user's standpoint.  It should be considered a
user's guide.

* Menu:

* History Interaction::         What it feels like using History as a user.


File: gdb.info,  Node: History Interaction,  Up: Using History Interactively

History Expansion
=================

   The History library provides a history expansion feature that is
similar to the history expansion provided by `csh'.  This section
describes the syntax used to manipulate the history information.

   History expansions introduce words from the history list into the
input stream, making it easy to repeat commands, insert the arguments
to a previous command into the current input line, or fix errors in
previous commands quickly.

   History expansion takes place in two parts.  The first is to
determine which line from the history list should be used during
substitution.  The second is to select portions of that line for
inclusion into the current one.  The line selected from the history is
called the "event", and the portions of that line that are acted upon
are called "words".  Various "modifiers" are available to manipulate
the selected words.  The line is broken into words in the same fashion
that Bash does, so that several words surrounded by quotes are
considered one word.  History expansions are introduced by the
appearance of the history expansion character, which is `!' by default.

* Menu:

* Event Designators::   How to specify which history line to use.
* Word Designators::    Specifying which words are of interest.
* Modifiers::           Modifying the results of substitution.


File: gdb.info,  Node: Event Designators,  Next: Word Designators,  Up: History Interaction

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

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

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

`!N'
     Refer to command line N.

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

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

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

`!?STRING[?]'
     Refer to the most recent command containing STRING.  The trailing
     `?' may be omitted if the STRING is followed immediately by a
     newline.

`^STRING1^STRING2^'
     Quick Substitution.  Repeat the last command, replacing STRING1
     with STRING2.  Equivalent to `!!:s/STRING1/STRING2/'.

`!#'
     The entire command line typed so far.


File: gdb.info,  Node: Word Designators,  Next: Modifiers,  Prev: Event Designators,  Up: History Interaction

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

   Word designators are used to select desired words from the event.  A
`:' separates the event specification from the word designator.  It may
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 0 (zero).  Words are inserted into the current
line separated by single spaces.

   For example,

`!!'
     designates the preceding command.  When you type this, the
     preceding command is repeated in toto.

`!!:$'
     designates the last argument of the preceding command.  This may be
     shortened to `!$'.

`!fi:2'
     designates the second argument of the most recent command starting
     with the letters `fi'.

   Here are the word designators:

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

`N'
     The Nth 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, except the `0'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.

`X*'
     Abbreviates `X-$'

`X-'
     Abbreviates `X-$' like `X*', but omits the last word.

   If a word designator is supplied without an event specification, the
previous command is used as the event.


File: gdb.info,  Node: Modifiers,  Prev: Word Designators,  Up: History Interaction

Modifiers
---------

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

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

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

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

`e'
     Remove all but the trailing suffix.

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

`s/OLD/NEW/'
     Substitute NEW for the first occurrence of OLD in the event line.
     Any delimiter may be used in place of `/'.  The delimiter may be
     quoted in OLD and NEW with a single backslash.  If `&' appears in
     NEW, it is replaced by OLD.  A single backslash will quote the
     `&'.  The final delimiter is optional if it is the last character
     on the input line.

`&'
     Repeat the previous substitution.

`g'
     Cause changes to be applied over the entire event line.  Used in
     conjunction with `s', as in `gs/OLD/NEW/', or with `&'.


File: gdb.info,  Node: Formatting Documentation,  Next: Command Line Editing,  Prev: GDB Bugs,  Up: Top

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-5.3/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-5.3', in the case of version 5.3), 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-5.3/gdb') and type:

     make gdb.dvi

   Then give `gdb.dvi' to your DVI printing program.

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

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


File: gdb.info,  Node: Installing GDB,  Next: Maintenance Commands,  Prev: Using History Interactively,  Up: Top

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 5.3 distribution is in the `gdb-5.3'
directory.  That directory contains:

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

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

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

`gdb-5.3/include'
     GNU include files

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

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

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

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

`gdb-5.3/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-5.3' 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-5.3
     ./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-5.3'
source directory for version 5.3, `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 5.3, type the following to configure only
the `bfd' subdirectory:

     cd gdb-5.3/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.

* Menu:

* Separate Objdir::             Compiling GDB in another directory
* Config Names::                Specifying names for hosts and targets
* Configure Options::           Summary of options for configure


File: gdb.info,  Node: Separate Objdir,  Next: Config Names,  Up: Installing GDB

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 5.3, you can build GDB in a separate
directory for a Sun 4 like this:

     cd gdb-5.3
     mkdir ../gdb-sun4
     cd ../gdb-sun4
     ../gdb-5.3/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-5.3' (or in a separate configured directory configured with
`--srcdir=DIRNAME/gdb-5.3'), 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.


File: gdb.info,  Node: Config Names,  Next: Configure Options,  Prev: Separate Objdir,  Up: Installing GDB

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 i386-linux
     i386-pc-linux-gnu
     % sh config.sub alpha-linux
     alpha-unknown-linux-gnu
     % sh config.sub hp9k700
     hppa1.1-hp-hpux
     % sh config.sub sun4
     sparc-sun-sunos4.1.1
     % sh config.sub sun3
     m68k-sun-sunos4.1.1
     % sh config.sub i986v
     Invalid configuration `i986v': machine `i986v' not recognized

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


File: gdb.info,  Node: Configure Options,  Prev: Config Names,  Up: Installing GDB

`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.  *note (configure.info)What Configure Does::,
for a full explanation of `configure'.

     configure [--help]
               [--prefix=DIR]
               [--exec-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'.

`--exec-prefix=DIR'
     Configure the source to install programs 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.

`--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.

   There are many other options available as well, but they are
generally needed for special purposes only.


File: gdb.info,  Node: Maintenance Commands,  Next: Remote Protocol,  Prev: Installing GDB,  Up: Top

Maintenance Commands
********************

   In addition to commands intended for GDB users, GDB includes a
number of commands intended for GDB developers.  These commands are
provided here for reference.

`maint info breakpoints'
     Using the same format as `info breakpoints', display both the
     breakpoints you've set explicitly, and those GDB is using for
     internal purposes.  Internal breakpoints are shown with negative
     breakpoint numbers.  The type column identifies what kind of
     breakpoint is shown:

    `breakpoint'
          Normal, explicitly set breakpoint.

    `watchpoint'
          Normal, explicitly set watchpoint.

    `longjmp'
          Internal breakpoint, used to handle correctly stepping through
          `longjmp' calls.

    `longjmp resume'
          Internal breakpoint at the target of a `longjmp'.

    `until'
          Temporary internal breakpoint used by the GDB `until' command.

    `finish'
          Temporary internal breakpoint used by the GDB `finish'
          command.

    `shlib events'
          Shared library events.

`maint print registers'
`maint print raw-registers'
`maint print cooked-registers'
     Print GDB's internal register data structures.

     The command `maint print raw-registers' includes the contents of
     the raw register cache; and the command `maint print
     cooked-registers' includes the (cooked) value of all registers.
     *Note Registers: (gdbint)Registers.

     Takes an optional file parameter.


File: gdb.info,  Node: Remote Protocol,  Next: Copying,  Prev: Maintenance Commands,  Up: Top

GDB Remote Serial Protocol
**************************

* Menu:

* Overview::
* Packets::
* Stop Reply Packets::
* General Query Packets::
* Register Packet Format::
* Examples::


File: gdb.info,  Node: Overview,  Next: Packets,  Up: Remote Protocol

Overview
========

   There may be occasions when you need to know something about the
protocol--for example, if there is only one serial port to your target
machine, you might want your program to do something special if it
recognizes a packet meant for GDB.

   In the examples below, `->' and `<-' are used to indicate
transmitted and received data respectfully.

   All GDB commands and responses (other than acknowledgments) are sent
as a PACKET.  A PACKET is introduced with the character `$', the actual
PACKET-DATA, and the terminating character `#' followed by a two-digit
CHECKSUM:

     `$'PACKET-DATA`#'CHECKSUM

The two-digit CHECKSUM is computed as the modulo 256 sum of all
characters between the leading `$' and the trailing `#' (an eight bit
unsigned checksum).

   Implementors should note that prior to GDB 5.0 the protocol
specification also included an optional two-digit SEQUENCE-ID:

     `$'SEQUENCE-ID`:'PACKET-DATA`#'CHECKSUM

That SEQUENCE-ID was appended to the acknowledgment.  GDB has never
output SEQUENCE-IDs.  Stubs that handle packets added since GDB 5.0
must not accept SEQUENCE-ID.

   When either the host or the target machine receives a packet, the
first response expected is an acknowledgment: either `+' (to indicate
the package was received correctly) or `-' (to request retransmission):

     -> `$'PACKET-DATA`#'CHECKSUM
     <- `+'

The host (GDB) sends COMMANDs, and the target (the debugging stub
incorporated in your program) sends a RESPONSE.  In the case of step
and continue COMMANDs, the response is only sent when the operation has
completed (the target has again stopped).

   PACKET-DATA consists of a sequence of characters with the exception
of `#' and `$' (see `X' packet for additional exceptions).

   Fields within the packet should be separated using `,' `;' or `:'.
Except where otherwise noted all numbers are represented in HEX with
leading zeros suppressed.

   Implementors should note that prior to GDB 5.0, the character `:'
could not appear as the third character in a packet (as it would
potentially conflict with the SEQUENCE-ID).

   Response DATA can be run-length encoded to save space.  A `*' means
that the next character is an ASCII encoding giving a repeat count
which stands for that many repetitions of the character preceding the
`*'.  The encoding is `n+29', yielding a printable character where `n
>=3' (which is where rle starts to win).  The printable characters `$',
`#', `+' and `-' or with a numeric value greater than 126 should not be
used.

   Some remote systems have used a different run-length encoding
mechanism loosely refered to as the cisco encoding.  Following the `*'
character are two hex digits that indicate the size of the packet.

   So:
     "`0* '"

means the same as "0000".

   The error response returned for some packets includes a two character
error number.  That number is not well defined.

   For any COMMAND not supported by the stub, an empty response
(`$#00') should be returned.  That way it is possible to extend the
protocol.  A newer GDB can tell if a packet is supported based on that
response.

   A stub is required to support the `g', `G', `m', `M', `c', and `s'
COMMANDs.  All other COMMANDs are optional.


File: gdb.info,  Node: Packets,  Next: Stop Reply Packets,  Prev: Overview,  Up: Remote Protocol

Packets
=======

   The following table provides a complete list of all currently defined
COMMANDs and their corresponding response DATA.

`!' -- extended mode
     Enable extended mode.  In extended mode, the remote server is made
     persistent.  The `R' packet is used to restart the program being
     debugged.

     Reply:
    `OK'
          The remote target both supports and has enabled extended mode.

`?' -- last signal
     Indicate the reason the target halted.  The reply is the same as
     for step and continue.

     Reply: *Note Stop Reply Packets::, for the reply specifications.

`a' -- reserved
     Reserved for future use.

`A'ARGLEN`,'ARGNUM`,'ARG`,...' --  set program arguments *(reserved)*
     Initialized `argv[]' array passed into program. ARGLEN specifies
     the number of bytes in the hex encoded byte stream ARG.  See
     `gdbserver' for more details.

     Reply:
    `OK'

    `ENN'

`b'BAUD -- set baud *(deprecated)*
     Change the serial line speed to BAUD.

     JTC: _When does the transport layer state change?  When it's
     received, or after the ACK is transmitted.  In either case, there
     are problems if the command or the acknowledgment packet is
     dropped._

     Stan: _If people really wanted to add something like this, and get
     it working for the first time, they ought to modify ser-unix.c to
     send some kind of out-of-band message to a specially-setup stub
     and have the switch happen "in between" packets, so that from
     remote protocol's point of view, nothing actually happened._

`B'ADDR,MODE -- set breakpoint *(deprecated)*
     Set (MODE is `S') or clear (MODE is `C') a breakpoint at ADDR.
     _This has been replaced by the `Z' and `z' packets._

`c'ADDR -- continue
     ADDR is address to resume.  If ADDR is omitted, resume at current
     address.

     Reply: *Note Stop Reply Packets::, for the reply specifications.

`C'SIG`;'ADDR -- continue with signal
     Continue with signal SIG (hex signal number).  If `;'ADDR is
     omitted, resume at same address.

     Reply: *Note Stop Reply Packets::, for the reply specifications.

`d' -- toggle debug *(deprecated)*
     Toggle debug flag.

`D' -- detach
     Detach GDB from the remote system.  Sent to the remote target
     before GDB disconnects.

     Reply:
    `_no response_'
          GDB does not check for any response after sending this packet.

`e' -- reserved
     Reserved for future use.

`E' -- reserved
     Reserved for future use.

`f' -- reserved
     Reserved for future use.

`F' -- reserved
     Reserved for future use.

`g' -- read registers
     Read general registers.

     Reply:
    `XX...'
          Each byte of register data is described by two hex digits.
          The bytes with the register are transmitted in target byte
          order.  The size of each register and their position within
          the `g' PACKET are determined by the GDB internal macros
          REGISTER_RAW_SIZE and REGISTER_NAME macros.  The
          specification of several standard `g' packets is specified
          below.

    `ENN'
          for an error.

`G'XX... -- write regs
     *Note read registers packet::, for a description of the XX...
     data.

     Reply:
    `OK'
          for success

    `ENN'
          for an error

`h' -- reserved
     Reserved for future use.

`H'CT... -- set thread
     Set thread for subsequent operations (`m', `M', `g', `G', et.al.).
     C depends on the operation to be performed: it should be `c' for
     step and continue operations, `g' for other operations.  The
     thread designator T... may be -1, meaning all the threads, a
     thread number, or zero which means pick any thread.

     Reply:
    `OK'
          for success

    `ENN'
          for an error

`i'ADDR`,'NNN -- cycle step *(draft)*
     Step the remote target by a single clock cycle.  If `,'NNN is
     present, cycle step NNN cycles.  If ADDR is present, cycle step
     starting at that address.

`I' -- signal then cycle step *(reserved)*
     *Note step with signal packet::.  *Note cycle step packet::.

`j' -- reserved
     Reserved for future use.

`J' -- reserved
     Reserved for future use.

`k' -- kill request
     FIXME: _There is no description of how to operate when a specific
     thread context has been selected (i.e. does 'k' kill only that
     thread?)_.

`K' -- reserved
     Reserved for future use.

`l' -- reserved
     Reserved for future use.

`L' -- reserved
     Reserved for future use.

`m'ADDR`,'LENGTH -- read memory
     Read LENGTH bytes of memory starting at address ADDR.  Neither GDB
     nor the stub assume that sized memory transfers are assumed using
     word alligned accesses. FIXME: _A word aligned memory transfer
     mechanism is needed._

     Reply:
    `XX...'
          XX... is mem contents. Can be fewer bytes than requested if
          able to read only part of the data.  Neither GDB nor the stub
          assume that sized memory transfers are assumed using word
          alligned accesses. FIXME: _A word aligned memory transfer
          mechanism is needed._

    `ENN'
          NN is errno

`M'ADDR,LENGTH`:'XX... -- write mem
     Write LENGTH bytes of memory starting at address ADDR.  XX... is
     the data.

     Reply:
    `OK'
          for success

    `ENN'
          for an error (this includes the case where only part of the
          data was written).

`n' -- reserved
     Reserved for future use.

`N' -- reserved
     Reserved for future use.

`o' -- reserved
     Reserved for future use.

`O' -- reserved
     Reserved for future use.

`p'N... -- read reg *(reserved)*
     *Note write register packet::.

     Reply:
    `R....'
          The hex encoded value of the register in target byte order.

`P'N...`='R... -- write register
     Write register N... with value R..., which contains two hex digits
     for each byte in the register (target byte order).

     Reply:
    `OK'
          for success

    `ENN'
          for an error

`q'QUERY -- general query
     Request info about QUERY.  In general GDB queries have a leading
     upper case letter.  Custom vendor queries should use a company
     prefix (in lower case) ex: `qfsf.var'.  QUERY may optionally be
     followed by a `,' or `;' separated list.  Stubs must ensure that
     they match the full QUERY name.

     Reply:
    `XX...'
          Hex encoded data from query.  The reply can not be empty.

    `ENN'
          error reply

    `'
          Indicating an unrecognized QUERY.

`Q'VAR`='VAL -- general set
     Set value of VAR to VAL.

     *Note general query packet::, for a discussion of naming
     conventions.

`r' -- reset *(deprecated)*
     Reset the entire system.

`R'XX -- remote restart
     Restart the program being debugged.  XX, while needed, is ignored.
     This packet is only available in extended mode.

     Reply:
    `_no reply_'
          The `R' packet has no reply.

`s'ADDR -- step
     ADDR is address to resume.  If ADDR is omitted, resume at same
     address.

     Reply: *Note Stop Reply Packets::, for the reply specifications.

`S'SIG`;'ADDR -- step with signal
     Like `C' but step not continue.

     Reply: *Note Stop Reply Packets::, for the reply specifications.

`t'ADDR`:'PP`,'MM -- search
     Search backwards starting at address ADDR for a match with pattern
     PP and mask MM.  PP and MM are 4 bytes.  ADDR must be at least 3
     digits.

`T'XX -- thread alive
     Find out if the thread XX is alive.

     Reply:
    `OK'
          thread is still alive

    `ENN'
          thread is dead

`u' -- reserved
     Reserved for future use.

`U' -- reserved
     Reserved for future use.

`v' -- reserved
     Reserved for future use.

`V' -- reserved
     Reserved for future use.

`w' -- reserved
     Reserved for future use.

`W' -- reserved
     Reserved for future use.

`x' -- reserved
     Reserved for future use.

`X'ADDR`,'LENGTH:XX... -- write mem (binary)
     ADDR is address, LENGTH is number of bytes, XX...  is binary data.
     The characters `$', `#', and `0x7d' are escaped using `0x7d'.

     Reply:
    `OK'
          for success

    `ENN'
          for an error

`y' -- reserved
     Reserved for future use.

`Y' reserved
     Reserved for future use.

`z'T`,'ADDR`,'LENGTH -- remove break or watchpoint *(draft)*
     *Note insert breakpoint or watchpoint packet::.

`Z'T`,'ADDR`,'LENGTH -- insert break or watchpoint *(draft)*
     T is type: `0' - software breakpoint, `1' - hardware breakpoint,
     `2' -- write watchpoint, `3' - read watchpoint, `4' - access
     watchpoint; ADDR is address; LENGTH is in bytes.  For a software
     breakpoint, LENGTH specifies the size of the instruction to be
     patched.  For hardware breakpoints and watchpoints LENGTH
     specifies the memory region to be monitored.  To avoid potential
     problems with duplicate packets, the operations should be
     implemented in an idempotent way.

     Reply:
    `ENN'
          for an error

    `OK'
          for success

    ``''
          If not supported.


File: gdb.info,  Node: Stop Reply Packets,  Next: General Query Packets,  Prev: Packets,  Up: Remote Protocol

Stop Reply Packets
==================

   The `C', `c', `S', `s' and `?' packets can receive any of the below
as a reply.  In the case of the `C', `c', `S' and `s' packets, that
reply is only returned when the target halts.  In the below the exact
meaning of `signal number' is poorly defined.  In general one of the
UNIX signal numbering conventions is used.

`SAA'
     AA is the signal number

``T'AAN...`:'R...`;'N...`:'R...`;'N...`:'R...`;''
     AA = two hex digit signal number; N... = register number (hex),
     R...  = target byte ordered register contents, size defined by
     `REGISTER_RAW_SIZE'; N... = `thread', R... = thread process ID,
     this is a hex integer; N... = (`watch' | `rwatch' | `awatch', R...
     = data address, this is a hex integer; N... = other string not
     starting with valid hex digit.  GDB should ignore this N..., R...
     pair and go on to the next.  This way we can extend the protocol.

`WAA'
     The process exited, and AA is the exit status.  This is only
     applicable to certain targets.

`XAA'
     The process terminated with signal AA.

`NAA;T...;D...;B... *(obsolete)*'
     AA = signal number; T... = address of symbol `_start'; D... = base
     of data section; B... = base of bss section.  _Note: only used by
     Cisco Systems targets.  The difference between this reply and the
     `qOffsets' query is that the `N' packet may arrive spontaneously
     whereas the `qOffsets' is a query initiated by the host debugger._

`OXX...'
     XX... is hex encoding of ASCII data.  This can happen at any time
     while the program is running and the debugger should continue to
     wait for `W', `T', etc.