1 This is Info file ./gdb.info, produced by Makeinfo version 1.68 from
2 the input file gdb.texinfo.
5 * Gdb: (gdb). The GNU debugger.
7 This file documents the GNU debugger GDB.
9 This is the Seventh Edition, February 1999, of `Debugging with GDB:
10 the GNU Source-Level Debugger' for GDB Version 4.18.
12 Copyright (C) 1988-1999 Free Software Foundation, Inc.
14 Permission is granted to make and distribute verbatim copies of this
15 manual provided the copyright notice and this permission notice are
16 preserved on all copies.
18 Permission is granted to copy and distribute modified versions of
19 this manual under the conditions for verbatim copying, provided also
20 that the entire resulting derived work is distributed under the terms
21 of a permission notice identical to this one.
23 Permission is granted to copy and distribute translations of this
24 manual into another language, under the above conditions for modified
28 File: gdb.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands
30 Letting Readline Type For You
31 -----------------------------
34 Attempt to do completion on the text before the cursor. This is
35 application-specific. Generally, if you are typing a filename
36 argument, you can do filename completion; if you are typing a
37 command, you can do command completion; if you are typing in a
38 symbol to GDB, you can do symbol name completion; if you are
39 typing in a variable to Bash, you can do variable name completion,
42 `possible-completions (M-?)'
43 List the possible completions of the text before the cursor.
45 `insert-completions (M-*)'
46 Insert all completions of the text before point that would have
47 been generated by `possible-completions'.
50 Similar to `complete', but replaces the word to be completed with
51 a single match from the list of possible completions. Repeated
52 execution of `menu-complete' steps through the list of possible
53 completions, inserting each match in turn. At the end of the list
54 of completions, the bell is rung and the original text is restored.
55 An argument of N moves N positions forward in the list of matches;
56 a negative argument may be used to move backward through the list.
57 This command is intended to be bound to `TAB', but is unbound by
61 File: gdb.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands
66 `start-kbd-macro (C-x ()'
67 Begin saving the characters typed into the current keyboard macro.
69 `end-kbd-macro (C-x ))'
70 Stop saving the characters typed into the current keyboard macro
71 and save the definition.
73 `call-last-kbd-macro (C-x e)'
74 Re-execute the last keyboard macro defined, by making the
75 characters in the macro appear as if typed at the keyboard.
78 File: gdb.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands
80 Some Miscellaneous Commands
81 ---------------------------
83 `re-read-init-file (C-x C-r)'
84 Read in the contents of the inputrc file, and incorporate any
85 bindings or variable assignments found there.
88 Abort the current editing command and ring the terminal's bell
89 (subject to the setting of `bell-style').
91 `do-uppercase-version (M-a, M-b, M-X, ...)'
92 If the metafied character X is lowercase, run the command that is
93 bound to the corresponding uppercase character.
96 Make the next character typed be metafied. This is for keyboards
97 without a meta key. Typing `ESC f' is equivalent to typing `M-f'.
100 Incremental undo, separately remembered for each line.
103 Undo all changes made to this line. This is like executing the
104 `undo' command enough times to get back to the beginning.
107 Perform tilde expansion on the current word.
110 Set the mark to the current point. If a numeric argument is
111 supplied, the mark is set to that position.
113 `exchange-point-and-mark (C-x C-x)'
114 Swap the point with the mark. The current cursor position is set
115 to the saved position, and the old cursor position is saved as the
118 `character-search (C-])'
119 A character is read and point is moved to the next occurrence of
120 that character. A negative count searches for previous
123 `character-search-backward (M-C-])'
124 A character is read and point is moved to the previous occurrence
125 of that character. A negative count searches for subsequent
128 `insert-comment (M-#)'
129 The value of the `comment-begin' variable is inserted at the
130 beginning of the current line, and the line is accepted as if a
131 newline had been typed.
134 Print all of the functions and their key bindings to the Readline
135 output stream. If a numeric argument is supplied, the output is
136 formatted in such a way that it can be made part of an INPUTRC
137 file. This command is unbound by default.
140 Print all of the settable variables and their values to the
141 Readline output stream. If a numeric argument is supplied, the
142 output is formatted in such a way that it can be made part of an
143 INPUTRC file. This command is unbound by default.
146 Print all of the Readline key sequences bound to macros and the
147 strings they ouput. If a numeric argument is supplied, the output
148 is formatted in such a way that it can be made part of an INPUTRC
149 file. This command is unbound by default.
152 File: gdb.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing
157 While the Readline library does not have a full set of `vi' editing
158 functions, it does contain enough to allow simple editing of the line.
159 The Readline `vi' mode behaves as specified in the POSIX 1003.2
162 In order to switch interactively between `emacs' and `vi' editing
163 modes, use the command M-C-j (toggle-editing-mode). The Readline
164 default is `emacs' mode.
166 When you enter a line in `vi' mode, you are already placed in
167 `insertion' mode, as if you had typed an `i'. Pressing <ESC> switches
168 you into `command' mode, where you can edit the text of the line with
169 the standard `vi' movement keys, move to previous history lines with
170 `k' and subsequent lines with `j', and so forth.
173 File: gdb.info, Node: Using History Interactively, Next: Installing GDB, Prev: Command Line Editing, Up: Top
175 Using History Interactively
176 ***************************
178 This chapter describes how to use the GNU History Library
179 interactively, from a user's standpoint.
183 * History Interaction:: What it feels like using History as a user.
186 File: gdb.info, Node: History Interaction, Up: Using History Interactively
191 The History library provides a history expansion feature similar to
192 the history expansion in `csh'. The following text describes the
193 syntax you use to manipulate history information.
195 History expansion takes two parts. In the first part, determine
196 which line from the previous history will be used for substitution.
197 This line is called the "event". In the second part, select portions
198 of that line for inclusion into the current line. These portions are
199 called "words". GDB breaks the line into words in the same way that
200 the Bash shell does, so that several English (or Unix) words surrounded
201 by quotes are considered one word.
205 * Event Designators:: How to specify which history line to use.
206 * Word Designators:: Specifying which words are of interest.
207 * Modifiers:: Modifying the results of susbstitution.
210 File: gdb.info, Node: Event Designators, Next: Word Designators, Up: History Interaction
215 An "event designator" is a reference to a command line entry in the
219 Start a history subsititution, except when followed by a space,
220 tab, or the end of the line... <=> or <(>.
223 Refer to the previous command. This is a synonym for `!-1'.
226 Refer to command line N.
229 Refer to the command line N lines back.
232 Refer to the most recent command starting with STRING.
235 Refer to the most recent command containing STRING.
238 File: gdb.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction
243 A <:> separates the event designator from the "word designator". It
244 can be omitted if the word designator begins with a <^>, <$>, <*> or
245 <%>. Words are numbered from the beginning of the line, with the first
246 word being denoted by a 0 (zero).
249 The zero'th word. For many applications, this is the command word.
255 The first argument. that is, word 1.
261 The word matched by the most recent `?string?' search.
264 A range of words; `-Y' Abbreviates `0-Y'.
267 All of the words, excepting the zero'th. This is a synonym for
268 `1-$'. It is not an error to use <*> if there is just one word in
269 the event. The empty string is returned in that case.
272 File: gdb.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction
277 After the optional word designator, you can add a sequence of one or
278 more of the following "modifiers", each preceded by a <:>.
281 The entire command line typed so far. This means the current
282 command, not the previous command.
285 Remove a trailing pathname component, leaving only the head.
288 Remove a trailing suffix of the form `.'SUFFIX, leaving the
292 Remove all but the suffix.
295 Remove all leading pathname components, leaving the tail.
298 Print the new command but do not execute it.
301 File: gdb.info, Node: Formatting Documentation, Next: Command Line Editing, Prev: GDB Bugs, Up: Top
303 Formatting Documentation
304 ************************
306 The GDB 4 release includes an already-formatted reference card, ready
307 for printing with PostScript or Ghostscript, in the `gdb' subdirectory
308 of the main source directory(1). If you can use PostScript or
309 Ghostscript with your printer, you can print the reference card
310 immediately with `refcard.ps'.
312 The release also includes the source for the reference card. You
313 can format it, using TeX, by typing:
317 The GDB reference card is designed to print in "landscape" mode on
318 US "letter" size paper; that is, on a sheet 11 inches wide by 8.5 inches
319 high. You will need to specify this form of printing as an option to
320 your DVI output program.
322 All the documentation for GDB comes as part of the machine-readable
323 distribution. The documentation is written in Texinfo format, which is
324 a documentation system that uses a single source file to produce both
325 on-line information and a printed manual. You can use one of the Info
326 formatting commands to create the on-line version of the documentation
327 and TeX (or `texi2roff') to typeset the printed version.
329 GDB includes an already formatted copy of the on-line Info version
330 of this manual in the `gdb' subdirectory. The main Info file is
331 `gdb-4.18/gdb/gdb.info', and it refers to subordinate files matching
332 `gdb.info*' in the same directory. If necessary, you can print out
333 these files, or read them with any editor; but they are easier to read
334 using the `info' subsystem in GNU Emacs or the standalone `info'
335 program, available as part of the GNU Texinfo distribution.
337 If you want to format these Info files yourself, you need one of the
338 Info formatting programs, such as `texinfo-format-buffer' or `makeinfo'.
340 If you have `makeinfo' installed, and are in the top level GDB
341 source directory (`gdb-4.18', in the case of version 4.18), you can
342 make the Info file by typing:
347 If you want to typeset and print copies of this manual, you need TeX,
348 a program to print its DVI output files, and `texinfo.tex', the Texinfo
351 TeX is a typesetting program; it does not print files directly, but
352 produces output files called DVI files. To print a typeset document,
353 you need a program to print DVI files. If your system has TeX
354 installed, chances are it has such a program. The precise command to
355 use depends on your system; `lpr -d' is common; another (for PostScript
356 devices) is `dvips'. The DVI print command may require a file name
357 without any extension or a `.dvi' extension.
359 TeX also requires a macro definitions file called `texinfo.tex'.
360 This file tells TeX how to typeset a document written in Texinfo
361 format. On its own, TeX cannot either read or typeset a Texinfo file.
362 `texinfo.tex' is distributed with GDB and is located in the
363 `gdb-VERSION-NUMBER/texinfo' directory.
365 If you have TeX and a DVI printer program installed, you can typeset
366 and print this manual. First switch to the the `gdb' subdirectory of
367 the main source directory (for example, to `gdb-4.18/gdb') and type:
371 Then give `gdb.dvi' to your DVI printing program.
373 ---------- Footnotes ----------
375 (1) In `gdb-4.18/gdb/refcard.ps' of the version 4.18 release.
378 File: gdb.info, Node: Installing GDB, Next: Index, Prev: Using History Interactively, Up: Top
383 GDB comes with a `configure' script that automates the process of
384 preparing GDB for installation; you can then use `make' to build the
387 The GDB distribution includes all the source code you need for GDB
388 in a single directory, whose name is usually composed by appending the
389 version number to `gdb'.
391 For example, the GDB version 4.18 distribution is in the `gdb-4.18'
392 directory. That directory contains:
394 `gdb-4.18/configure (and supporting files)'
395 script for configuring GDB and all its supporting libraries
398 the source specific to GDB itself
401 source for the Binary File Descriptor library
407 source for the `-liberty' free software library
410 source for the library of opcode tables and disassemblers
413 source for the GNU command-line interface
416 source for the GNU filename pattern-matching subroutine
419 source for the GNU memory-mapped malloc package
421 The simplest way to configure and build GDB is to run `configure'
422 from the `gdb-VERSION-NUMBER' source directory, which in this example
423 is the `gdb-4.18' directory.
425 First switch to the `gdb-VERSION-NUMBER' source directory if you are
426 not already in it; then run `configure'. Pass the identifier for the
427 platform on which GDB will run as an argument.
435 where HOST is an identifier such as `sun4' or `decstation', that
436 identifies the platform where GDB will run. (You can often leave off
437 HOST; `configure' tries to guess the correct value by examining your
440 Running `configure HOST' and then running `make' builds the `bfd',
441 `readline', `mmalloc', and `libiberty' libraries, then `gdb' itself.
442 The configured source files, and the binaries, are left in the
443 corresponding source directories.
445 `configure' is a Bourne-shell (`/bin/sh') script; if your system
446 does not recognize this automatically when you run a different shell,
447 you may need to run `sh' on it explicitly:
451 If you run `configure' from a directory that contains source
452 directories for multiple libraries or programs, such as the `gdb-4.18'
453 source directory for version 4.18, `configure' creates configuration
454 files for every directory level underneath (unless you tell it not to,
455 with the `--norecursion' option).
457 You can run the `configure' script from any of the subordinate
458 directories in the GDB distribution if you only want to configure that
459 subdirectory, but be sure to specify a path to it.
461 For example, with version 4.18, type the following to configure only
462 the `bfd' subdirectory:
467 You can install `gdb' anywhere; it has no hardwired paths. However,
468 you should make sure that the shell on your path (named by the `SHELL'
469 environment variable) is publicly readable. Remember that GDB uses the
470 shell to start your program--some systems refuse to let GDB debug child
471 processes whose programs are not readable.
475 * Separate Objdir:: Compiling GDB in another directory
476 * Config Names:: Specifying names for hosts and targets
477 * Configure Options:: Summary of options for configure
480 File: gdb.info, Node: Separate Objdir, Next: Config Names, Prev: Installing GDB, Up: Installing GDB
482 Compiling GDB in another directory
483 ==================================
485 If you want to run GDB versions for several host or target machines,
486 you need a different `gdb' compiled for each combination of host and
487 target. `configure' is designed to make this easy by allowing you to
488 generate each configuration in a separate subdirectory, rather than in
489 the source directory. If your `make' program handles the `VPATH'
490 feature (GNU `make' does), running `make' in each of these directories
491 builds the `gdb' program specified there.
493 To build `gdb' in a separate directory, run `configure' with the
494 `--srcdir' option to specify where to find the source. (You also need
495 to specify a path to find `configure' itself from your working
496 directory. If the path to `configure' would be the same as the
497 argument to `--srcdir', you can leave out the `--srcdir' option; it is
500 For example, with version 4.18, you can build GDB in a separate
501 directory for a Sun 4 like this:
506 ../gdb-4.18/configure sun4
509 When `configure' builds a configuration using a remote source
510 directory, it creates a tree for the binaries with the same structure
511 (and using the same names) as the tree under the source directory. In
512 the example, you'd find the Sun 4 library `libiberty.a' in the
513 directory `gdb-sun4/libiberty', and GDB itself in `gdb-sun4/gdb'.
515 One popular reason to build several GDB configurations in separate
516 directories is to configure GDB for cross-compiling (where GDB runs on
517 one machine--the "host"--while debugging programs that run on another
518 machine--the "target"). You specify a cross-debugging target by giving
519 the `--target=TARGET' option to `configure'.
521 When you run `make' to build a program or library, you must run it
522 in a configured directory--whatever directory you were in when you
523 called `configure' (or one of its subdirectories).
525 The `Makefile' that `configure' generates in each source directory
526 also runs recursively. If you type `make' in a source directory such
527 as `gdb-4.18' (or in a separate configured directory configured with
528 `--srcdir=DIRNAME/gdb-4.18'), you will build all the required
529 libraries, and then build GDB.
531 When you have multiple hosts or targets configured in separate
532 directories, you can run `make' on them in parallel (for example, if
533 they are NFS-mounted on each of the hosts); they will not interfere
537 File: gdb.info, Node: Config Names, Next: Configure Options, Prev: Separate Objdir, Up: Installing GDB
539 Specifying names for hosts and targets
540 ======================================
542 The specifications used for hosts and targets in the `configure'
543 script are based on a three-part naming scheme, but some short
544 predefined aliases are also supported. The full naming scheme encodes
545 three pieces of information in the following pattern:
547 ARCHITECTURE-VENDOR-OS
549 For example, you can use the alias `sun4' as a HOST argument, or as
550 the value for TARGET in a `--target=TARGET' option. The equivalent
551 full name is `sparc-sun-sunos4'.
553 The `configure' script accompanying GDB does not provide any query
554 facility to list all supported host and target names or aliases.
555 `configure' calls the Bourne shell script `config.sub' to map
556 abbreviations to full names; you can read the script, if you wish, or
557 you can use it to test your guesses on abbreviations--for example:
559 % sh config.sub i386-linux
561 % sh config.sub alpha-linux
562 alpha-unknown-linux-gnu
563 % sh config.sub hp9k700
569 % sh config.sub i986v
570 Invalid configuration `i986v': machine `i986v' not recognized
572 `config.sub' is also distributed in the GDB source directory
573 (`gdb-4.18', for version 4.18).
576 File: gdb.info, Node: Configure Options, Prev: Config Names, Up: Installing GDB
581 Here is a summary of the `configure' options and arguments that are
582 most often useful for building GDB. `configure' also has several other
583 options not listed here. *note (configure.info)What Configure Does::,
584 for a full explanation of `configure'.
590 [--norecursion] [--rm]
594 You may introduce options with a single `-' rather than `--' if you
595 prefer; but you may abbreviate option names if you use `--'.
598 Display a quick summary of how to invoke `configure'.
601 Configure the source to install programs and files under directory
605 Configure the source to install programs under directory `DIR'.
608 *Warning: using this option requires GNU `make', or another `make'
609 that implements the `VPATH' feature.*
610 Use this option to make configurations in directories separate
611 from the GDB source directories. Among other things, you can use
612 this to build (or maintain) several configurations simultaneously,
613 in separate directories. `configure' writes configuration
614 specific files in the current directory, but arranges for them to
615 use the source in the directory DIRNAME. `configure' creates
616 directories under the working directory in parallel to the source
617 directories below DIRNAME.
620 Configure only the directory level where `configure' is executed;
621 do not propagate configuration to subdirectories.
624 Configure GDB for cross-debugging programs running on the specified
625 TARGET. Without this option, GDB is configured to debug programs
626 that run on the same machine (HOST) as GDB itself.
628 There is no convenient way to generate a list of all available
632 Configure GDB to run on the specified HOST.
634 There is no convenient way to generate a list of all available
637 There are many other options available as well, but they are
638 generally needed for special purposes only.