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