summaryrefslogtreecommitdiff
path: root/gdb/doc/gdb.info-9
diff options
context:
space:
mode:
Diffstat (limited to 'gdb/doc/gdb.info-9')
-rw-r--r--gdb/doc/gdb.info-9639
1 files changed, 639 insertions, 0 deletions
diff --git a/gdb/doc/gdb.info-9 b/gdb/doc/gdb.info-9
new file mode 100644
index 00000000000..0e6d2fa061e
--- /dev/null
+++ b/gdb/doc/gdb.info-9
@@ -0,0 +1,639 @@
+This is Info file ./gdb.info, produced by Makeinfo version 1.68 from
+the input file gdb.texinfo.
+
+START-INFO-DIR-ENTRY
+* Gdb: (gdb). The GNU debugger.
+END-INFO-DIR-ENTRY
+ This file documents the GNU debugger GDB.
+
+ This is the Seventh Edition, February 1999, of `Debugging with GDB:
+the GNU Source-Level Debugger' for GDB Version 4.18.
+
+ Copyright (C) 1988-1999 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.
+
+
+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.
+
+
+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.
+
+* Menu:
+
+* History Interaction:: What it feels like using History as a user.
+
+
+File: gdb.info, Node: History Interaction, Up: Using History Interactively
+
+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.
+
+* Menu:
+
+* Event Designators:: How to specify which history line to use.
+* Word Designators:: Specifying which words are of interest.
+* Modifiers:: Modifying the results of susbstitution.
+
+
+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 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.
+
+
+File: gdb.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction
+
+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.
+
+
+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 <:>.
+
+`#'
+ 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.
+
+
+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-4.18/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-4.18', in the case of version 4.18), 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-4.18/gdb') and type:
+
+ make gdb.dvi
+
+ Then give `gdb.dvi' to your DVI printing program.
+
+ ---------- Footnotes ----------
+
+ (1) In `gdb-4.18/gdb/refcard.ps' of the version 4.18 release.
+
+
+File: gdb.info, Node: Installing GDB, Next: Index, 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 4.18 distribution is in the `gdb-4.18'
+directory. That directory contains:
+
+`gdb-4.18/configure (and supporting files)'
+ script for configuring GDB and all its supporting libraries
+
+`gdb-4.18/gdb'
+ the source specific to GDB itself
+
+`gdb-4.18/bfd'
+ source for the Binary File Descriptor library
+
+`gdb-4.18/include'
+ GNU include files
+
+`gdb-4.18/libiberty'
+ source for the `-liberty' free software library
+
+`gdb-4.18/opcodes'
+ source for the library of opcode tables and disassemblers
+
+`gdb-4.18/readline'
+ source for the GNU command-line interface
+
+`gdb-4.18/glob'
+ source for the GNU filename pattern-matching subroutine
+
+`gdb-4.18/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-4.18' 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-4.18
+ ./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-4.18'
+source directory for version 4.18, `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 4.18, type the following to configure only
+the `bfd' subdirectory:
+
+ cd gdb-4.18/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, Prev: Installing GDB, 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 4.18, you can build GDB in a separate
+directory for a Sun 4 like this:
+
+ cd gdb-4.18
+ mkdir ../gdb-sun4
+ cd ../gdb-sun4
+ ../gdb-4.18/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-4.18' (or in a separate configured directory configured with
+`--srcdir=DIRNAME/gdb-4.18'), 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-4.18', for version 4.18).
+
+
+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.
+
View Lorry Controller Status