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: Emacs, Next: GDB Bugs, Prev: Sequences, Up: Top
30 Using GDB under GNU Emacs
31 *************************
33 A special interface allows you to use GNU Emacs to view (and edit)
34 the source files for the program you are debugging with GDB.
36 To use this interface, use the command `M-x gdb' in Emacs. Give the
37 executable file you want to debug as an argument. This command starts
38 GDB as a subprocess of Emacs, with input and output through a newly
41 Using GDB under Emacs is just like using GDB normally except for two
44 * All "terminal" input and output goes through the Emacs buffer.
46 This applies both to GDB commands and their output, and to the input
47 and output done by the program you are debugging.
49 This is useful because it means that you can copy the text of
50 previous commands and input them again; you can even use parts of the
53 All the facilities of Emacs' Shell mode are available for interacting
54 with your program. In particular, you can send signals the usual
55 way--for example, `C-c C-c' for an interrupt, `C-c C-z' for a stop.
57 * GDB displays source code through Emacs.
59 Each time GDB displays a stack frame, Emacs automatically finds the
60 source file for that frame and puts an arrow (`=>') at the left margin
61 of the current line. Emacs uses a separate buffer for source display,
62 and splits the screen to show both your GDB session and the source.
64 Explicit GDB `list' or search commands still produce output as
65 usual, but you probably have no reason to use them from Emacs.
67 *Warning:* If the directory where your program resides is not your
68 current directory, it can be easy to confuse Emacs about the
69 location of the source files, in which case the auxiliary display
70 buffer does not appear to show your source. GDB can find programs
71 by searching your environment's `PATH' variable, so the GDB input
72 and output session proceeds normally; but Emacs does not get
73 enough information back from GDB to locate the source files in
74 this situation. To avoid this problem, either start GDB mode from
75 the directory where your program resides, or specify an absolute
76 file name when prompted for the `M-x gdb' argument.
78 A similar confusion can result if you use the GDB `file' command to
79 switch to debugging a program in some other location, from an
80 existing GDB buffer in Emacs.
82 By default, `M-x gdb' calls the program called `gdb'. If you need
83 to call GDB by a different name (for example, if you keep several
84 configurations around, with different names) you can set the Emacs
85 variable `gdb-command-name'; for example,
87 (setq gdb-command-name "mygdb")
89 (preceded by `ESC ESC', or typed in the `*scratch*' buffer, or in your
90 `.emacs' file) makes Emacs call the program named "`mygdb'" instead.
92 In the GDB I/O buffer, you can use these special Emacs commands in
93 addition to the standard Shell mode commands:
96 Describe the features of Emacs' GDB Mode.
99 Execute to another source line, like the GDB `step' command; also
100 update the display window to show the current file and location.
103 Execute to next source line in this function, skipping all function
104 calls, like the GDB `next' command. Then update the display window
105 to show the current file and location.
108 Execute one instruction, like the GDB `stepi' command; update
109 display window accordingly.
112 Execute to next instruction, using the GDB `nexti' command; update
113 display window accordingly.
116 Execute until exit from the selected stack frame, like the GDB
120 Continue execution of your program, like the GDB `continue'
123 *Warning:* In Emacs v19, this command is `C-c C-p'.
126 Go up the number of frames indicated by the numeric argument
127 (*note Numeric Arguments: (Emacs)Arguments.), like the GDB `up'
130 *Warning:* In Emacs v19, this command is `C-c C-u'.
133 Go down the number of frames indicated by the numeric argument,
134 like the GDB `down' command.
136 *Warning:* In Emacs v19, this command is `C-c C-d'.
139 Read the number where the cursor is positioned, and insert it at
140 the end of the GDB I/O buffer. For example, if you wish to
141 disassemble code around an address that was displayed earlier,
142 type `disassemble'; then move the cursor to the address display,
143 and pick up the argument for `disassemble' by typing `C-x &'.
145 You can customize this further by defining elements of the list
146 `gdb-print-command'; once it is defined, you can format or
147 otherwise process numbers picked up by `C-x &' before they are
148 inserted. A numeric argument to `C-x &' indicates that you wish
149 special formatting, and also acts as an index to pick an element
150 of the list. If the list element is a string, the number to be
151 inserted is formatted using the Emacs function `format'; otherwise
152 the number is passed as an argument to the corresponding list
155 In any source file, the Emacs command `C-x SPC' (`gdb-break') tells
156 GDB to set a breakpoint on the source line point is on.
158 If you accidentally delete the source-display buffer, an easy way to
159 get it back is to type the command `f' in the GDB buffer, to request a
160 frame display; when you run under Emacs, this recreates the source
161 buffer if necessary to show you the context of the current frame.
163 The source files displayed in Emacs are in ordinary Emacs buffers
164 which are visiting the source files in the usual way. You can edit the
165 files with these buffers if you wish; but keep in mind that GDB
166 communicates with Emacs in terms of line numbers. If you add or delete
167 lines from the text, the line numbers that GDB knows cease to
168 correspond properly with the code.
171 File: gdb.info, Node: GDB Bugs, Next: Formatting Documentation, Prev: Emacs, Up: Top
173 Reporting Bugs in GDB
174 *********************
176 Your bug reports play an essential role in making GDB reliable.
178 Reporting a bug may help you by bringing a solution to your problem,
179 or it may not. But in any case the principal function of a bug report
180 is to help the entire community by making the next version of GDB work
181 better. Bug reports are your contribution to the maintenance of GDB.
183 In order for a bug report to serve its purpose, you must include the
184 information that enables us to fix the bug.
188 * Bug Criteria:: Have you found a bug?
189 * Bug Reporting:: How to report bugs
192 File: gdb.info, Node: Bug Criteria, Next: Bug Reporting, Prev: GDB Bugs, Up: GDB Bugs
194 Have you found a bug?
195 =====================
197 If you are not sure whether you have found a bug, here are some
200 * If the debugger gets a fatal signal, for any input whatever, that
201 is a GDB bug. Reliable debuggers never crash.
203 * If GDB produces an error message for valid input, that is a bug.
204 (Note that if you're cross debugging, the problem may also be
205 somewhere in the connection to the target.)
207 * If GDB does not produce an error message for invalid input, that
208 is a bug. However, you should note that your idea of "invalid
209 input" might be our idea of "an extension" or "support for
210 traditional practice".
212 * If you are an experienced user of debugging tools, your suggestions
213 for improvement of GDB are welcome in any case.
216 File: gdb.info, Node: Bug Reporting, Prev: Bug Criteria, Up: GDB Bugs
221 A number of companies and individuals offer support for GNU products.
222 If you obtained GDB from a support organization, we recommend you
223 contact that organization first.
225 You can find contact information for many support companies and
226 individuals in the file `etc/SERVICE' in the GNU Emacs distribution.
228 In any event, we also recommend that you send bug reports for GDB to
231 bug-gdb@prep.ai.mit.edu
233 *Do not send bug reports to `info-gdb', or to `help-gdb', or to any
234 newsgroups.* Most users of GDB do not want to receive bug reports.
235 Those that do have arranged to receive `bug-gdb'.
237 The mailing list `bug-gdb' has a newsgroup `gnu.gdb.bug' which
238 serves as a repeater. The mailing list and the newsgroup carry exactly
239 the same messages. Often people think of posting bug reports to the
240 newsgroup instead of mailing them. This appears to work, but it has one
241 problem which can be crucial: a newsgroup posting often lacks a mail
242 path back to the sender. Thus, if we need to ask for more information,
243 we may be unable to reach you. For this reason, it is better to send
244 bug reports to the mailing list.
246 As a last resort, send bug reports on paper to:
249 Free Software Foundation Inc.
250 59 Temple Place - Suite 330
251 Boston, MA 02111-1307
254 The fundamental principle of reporting bugs usefully is this:
255 *report all the facts*. If you are not sure whether to state a fact or
256 leave it out, state it!
258 Often people omit facts because they think they know what causes the
259 problem and assume that some details do not matter. Thus, you might
260 assume that the name of the variable you use in an example does not
261 matter. Well, probably it does not, but one cannot be sure. Perhaps
262 the bug is a stray memory reference which happens to fetch from the
263 location where that name is stored in memory; perhaps, if the name were
264 different, the contents of that location would fool the debugger into
265 doing the right thing despite the bug. Play it safe and give a
266 specific, complete example. That is the easiest thing for you to do,
267 and the most helpful.
269 Keep in mind that the purpose of a bug report is to enable us to fix
270 the bug. It may be that the bug has been reported previously, but
271 neither you nor we can know that unless your bug report is complete and
274 Sometimes people give a few sketchy facts and ask, "Does this ring a
275 bell?" Those bug reports are useless, and we urge everyone to *refuse
276 to respond to them* except to chide the sender to report bugs properly.
278 To enable us to fix the bug, you should include all these things:
280 * The version of GDB. GDB announces it if you start with no
281 arguments; you can also print it at any time using `show version'.
283 Without this, we will not know whether there is any point in
284 looking for the bug in the current version of GDB.
286 * The type of machine you are using, and the operating system name
289 1. What compiler (and its version) was used to compile GDB--e.g.
292 * What compiler (and its version) was used to compile the program
293 you are debugging--e.g. "gcc-2.8.1", or "HP92453-01 A.10.32.03 HP
294 C Compiler". For GCC, you can say `gcc --version' to get this
295 information; for other compilers, see the documentation for those
298 * The command arguments you gave the compiler to compile your
299 example and observe the bug. For example, did you use `-O'? To
300 guarantee you will not omit something important, list them all. A
301 copy of the Makefile (or the output from make) is sufficient.
303 If we were to try to guess the arguments, we would probably guess
304 wrong and then we might not encounter the bug.
306 * A complete input script, and all necessary source files, that will
309 * A description of what behavior you observe that you believe is
310 incorrect. For example, "It gets a fatal signal."
312 Of course, if the bug is that GDB gets a fatal signal, then we
313 will certainly notice it. But if the bug is incorrect output, we
314 might not notice unless it is glaringly wrong. You might as well
315 not give us a chance to make a mistake.
317 Even if the problem you experience is a fatal signal, you should
318 still say so explicitly. Suppose something strange is going on,
319 such as, your copy of GDB is out of synch, or you have encountered
320 a bug in the C library on your system. (This has happened!) Your
321 copy might crash and ours would not. If you told us to expect a
322 crash, then when ours fails to crash, we would know that the bug
323 was not happening for us. If you had not told us to expect a
324 crash, then we would not be able to draw any conclusion from our
327 2. If you wish to suggest changes to the GDB source, send us context
328 diffs. If you even discuss something in the GDB source, refer to
329 it by context, not by line number.
331 The line numbers in our development sources will not match those
332 in your sources. Your line numbers would convey no useful
335 Here are some things that are not necessary:
337 * A description of the envelope of the bug.
339 Often people who encounter a bug spend a lot of time investigating
340 which changes to the input file will make the bug go away and which
341 changes will not affect it.
343 This is often time consuming and not very useful, because the way
344 we will find the bug is by running a single example under the
345 debugger with breakpoints, not by pure deduction from a series of
346 examples. We recommend that you save your time for something else.
348 Of course, if you can find a simpler example to report *instead*
349 of the original one, that is a convenience for us. Errors in the
350 output will be easier to spot, running under the debugger will take
351 less time, and so on.
353 However, simplification is not vital; if you do not want to do
354 this, report the bug anyway and send us the entire test case you
357 * A patch for the bug.
359 A patch for the bug does help us if it is a good one. But do not
360 omit the necessary information, such as the test case, on the
361 assumption that a patch is all we need. We might see problems
362 with your patch and decide to fix the problem another way, or we
363 might not understand it at all.
365 Sometimes with a program as complicated as GDB it is very hard to
366 construct an example that will make the program follow a certain
367 path through the code. If you do not send us the example, we will
368 not be able to construct one, so we will not be able to verify
369 that the bug is fixed.
371 And if we cannot understand what bug you are trying to fix, or why
372 your patch should be an improvement, we will not install it. A
373 test case will help us to understand.
375 * A guess about what the bug is or what it depends on.
377 Such guesses are usually wrong. Even we cannot guess right about
378 such things without first using the debugger to find the facts.
381 File: gdb.info, Node: Command Line Editing, Next: Using History Interactively, Prev: Formatting Documentation, Up: Top
386 This chapter describes the basic features of the GNU command line
391 * Introduction and Notation:: Notation used in this text.
392 * Readline Interaction:: The minimum set of commands for editing a line.
393 * Readline Init File:: Customizing Readline from a user's view.
394 * Bindable Readline Commands:: A description of most of the Readline commands
395 available for binding
396 * Readline vi Mode:: A short description of how to make Readline
397 behave like the vi editor.
400 File: gdb.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing
402 Introduction to Line Editing
403 ============================
405 The following paragraphs describe the notation used to represent
408 The text <C-k> is read as `Control-K' and describes the character
409 produced when the <k> key is pressed while the Control key is depressed.
411 The text <M-k> is read as `Meta-K' and describes the character
412 produced when the meta key (if you have one) is depressed, and the <k>
413 key is pressed. If you do not have a meta key, the identical keystroke
414 can be generated by typing <ESC> first, and then typing <k>. Either
415 process is known as "metafying" the <k> key.
417 The text <M-C-k> is read as `Meta-Control-k' and describes the
418 character produced by "metafying" <C-k>.
420 In addition, several keys have their own names. Specifically,
421 <DEL>, <ESC>, <LFD>, <SPC>, <RET>, and <TAB> all stand for themselves
422 when seen in this text, or in an init file (*note Readline Init
426 File: gdb.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing
431 Often during an interactive session you type in a long line of text,
432 only to notice that the first word on the line is misspelled. The
433 Readline library gives you a set of commands for manipulating the text
434 as you type it in, allowing you to just fix your typo, and not forcing
435 you to retype the majority of the line. Using these editing commands,
436 you move the cursor to the place that needs correction, and delete or
437 insert the text of the corrections. Then, when you are satisfied with
438 the line, you simply press <RETURN>. You do not have to be at the end
439 of the line to press <RETURN>; the entire line is accepted regardless
440 of the location of the cursor within the line.
444 * Readline Bare Essentials:: The least you need to know about Readline.
445 * Readline Movement Commands:: Moving about the input line.
446 * Readline Killing Commands:: How to delete text, and how to get it back!
447 * Readline Arguments:: Giving numeric arguments to commands.
448 * Searching:: Searching through previous lines.
451 File: gdb.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction
453 Readline Bare Essentials
454 ------------------------
456 In order to enter characters into the line, simply type them. The
457 typed character appears where the cursor was, and then the cursor moves
458 one space to the right. If you mistype a character, you can use your
459 erase character to back up and delete the mistyped character.
461 Sometimes you may miss typing a character that you wanted to type,
462 and not notice your error until you have typed several other
463 characters. In that case, you can type <C-b> to move the cursor to the
464 left, and then correct your mistake. Afterwards, you can move the
465 cursor to the right with <C-f>.
467 When you add text in the middle of a line, you will notice that
468 characters to the right of the cursor are `pushed over' to make room
469 for the text that you have inserted. Likewise, when you delete text
470 behind the cursor, characters to the right of the cursor are `pulled
471 back' to fill in the blank space created by the removal of the text. A
472 list of the basic bare essentials for editing the text of an input line
476 Move back one character.
479 Move forward one character.
482 Delete the character to the left of the cursor.
485 Delete the character underneath the cursor.
488 Insert the character into the line at the cursor.
491 Undo the last editing command. You can undo all the way back to an
495 File: gdb.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction
497 Readline Movement Commands
498 --------------------------
500 The above table describes the most basic possible keystrokes that
501 you need in order to do editing of the input line. For your
502 convenience, many other commands have been added in addition to <C-b>,
503 <C-f>, <C-d>, and <DEL>. Here are some commands for moving more rapidly
507 Move to the start of the line.
510 Move to the end of the line.
513 Move forward a word, where a word is composed of letters and
517 Move backward a word.
520 Clear the screen, reprinting the current line at the top.
522 Notice how <C-f> moves forward a character, while <M-f> moves
523 forward a word. It is a loose convention that control keystrokes
524 operate on characters while meta keystrokes operate on words.
527 File: gdb.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction
529 Readline Killing Commands
530 -------------------------
532 "Killing" text means to delete the text from the line, but to save
533 it away for later use, usually by "yanking" (re-inserting) it back into
534 the line. If the description for a command says that it `kills' text,
535 then you can be sure that you can get the text back in a different (or
536 the same) place later.
538 When you use a kill command, the text is saved in a "kill-ring".
539 Any number of consecutive kills save all of the killed text together, so
540 that when you yank it back, you get it all. The kill ring is not line
541 specific; the text that you killed on a previously typed line is
542 available to be yanked back later, when you are typing another line.
544 Here is the list of commands for killing text.
547 Kill the text from the current cursor position to the end of the
551 Kill from the cursor to the end of the current word, or if between
552 words, to the end of the next word.
555 Kill from the cursor the start of the previous word, or if between
556 words, to the start of the previous word.
559 Kill from the cursor to the previous whitespace. This is
560 different than <M-DEL> because the word boundaries differ.
562 Here is how to "yank" the text back into the line. Yanking means to
563 copy the most-recently-killed text from the kill buffer.
566 Yank the most recently killed text back into the buffer at the
570 Rotate the kill-ring, and yank the new top. You can only do this
571 if the prior command is <C-y> or <M-y>.
574 File: gdb.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction
579 You can pass numeric arguments to Readline commands. Sometimes the
580 argument acts as a repeat count, other times it is the sign of the
581 argument that is significant. If you pass a negative argument to a
582 command which normally acts in a forward direction, that command will
583 act in a backward direction. For example, to kill text back to the
584 start of the line, you might type `M-- C-k'.
586 The general way to pass numeric arguments to a command is to type
587 meta digits before the command. If the first `digit' typed is a minus
588 sign (<->), then the sign of the argument will be negative. Once you
589 have typed one meta digit to get the argument started, you can type the
590 remainder of the digits, and then the command. For example, to give
591 the <C-d> command an argument of 10, you could type `M-1 0 C-d'.
594 File: gdb.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction
596 Searching for Commands in the History
597 -------------------------------------
599 Readline provides commands for searching through the command history
600 for lines containing a specified string. There are two search modes:
601 INCREMENTAL and NON-INCREMENTAL.
603 Incremental searches begin before the user has finished typing the
604 search string. As each character of the search string is typed,
605 Readline displays the next entry from the history matching the string
606 typed so far. An incremental search requires only as many characters
607 as needed to find the desired history entry. The <ESC> character is
608 used to terminate an incremental search. <C-j> will also terminate the
609 search. <C-g> will abort an incremental search and restore the
610 original line. When the search is terminated, the history entry
611 containing the search string becomes the current line. To find other
612 matching entries in the history list, type <C-s> or <C-r> as
613 appropriate. This will search backward or forward in the history for
614 the next entry matching the search string typed so far. Any other key
615 sequence bound to a Readline command will terminate the search and
616 execute that command. For instance, a <RET> will terminate the search
617 and accept the line, thereby executing the command from the history
620 Non-incremental searches read the entire search string before
621 starting to search for matching history lines. The search string may be
622 typed by the user or be part of the contents of the current line.
625 File: gdb.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing
630 Although the Readline library comes with a set of `emacs'-like
631 keybindings installed by default, it is possible to use a different set
632 of keybindings. Any user can customize programs that use Readline by
633 putting commands in an "inputrc" file in his home directory. The name
634 of this file is taken from the value of the environment variable
635 `INPUTRC'. If that variable is unset, the default is `~/.inputrc'.
637 When a program which uses the Readline library starts up, the init
638 file is read, and the key bindings are set.
640 In addition, the `C-x C-r' command re-reads this init file, thus
641 incorporating any changes that you might have made to it.
645 * Readline Init File Syntax:: Syntax for the commands in the inputrc file.
647 * Conditional Init Constructs:: Conditional key bindings in the inputrc file.
649 * Sample Init File:: An example inputrc file.
652 File: gdb.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File
654 Readline Init File Syntax
655 -------------------------
657 There are only a few basic constructs allowed in the Readline init
658 file. Blank lines are ignored. Lines beginning with a `#' are
659 comments. Lines beginning with a `$' indicate conditional constructs
660 (*note Conditional Init Constructs::.). Other lines denote variable
661 settings and key bindings.
664 You can modify the run-time behavior of Readline by altering the
665 values of variables in Readline using the `set' command within the
666 init file. Here is how to change from the default Emacs-like key
667 binding to use `vi' line editing commands:
671 A great deal of run-time behavior is changeable with the following
675 Controls what happens when Readline wants to ring the
676 terminal bell. If set to `none', Readline never rings the
677 bell. If set to `visible', Readline uses a visible bell if
678 one is available. If set to `audible' (the default),
679 Readline attempts to ring the terminal's bell.
682 The string to insert at the beginning of the line when the
683 `insert-comment' command is executed. The default value is
686 `completion-ignore-case'
687 If set to `on', Readline performs filename matching and
688 completion in a case-insensitive fashion. The default value
691 `completion-query-items'
692 The number of possible completions that determines when the
693 user is asked whether he wants to see the list of
694 possibilities. If the number of possible completions is
695 greater than this value, Readline will ask the user whether
696 or not he wishes to view them; otherwise, they are simply
697 listed. The default limit is `100'.
700 If set to `on', Readline will convert characters with the
701 eighth bit set to an ASCII key sequence by stripping the
702 eighth bit and prepending an <ESC> character, converting them
703 to a meta-prefixed key sequence. The default value is `on'.
706 If set to `On', Readline will inhibit word completion.
707 Completion characters will be inserted into the line as if
708 they had been mapped to `self-insert'. The default is `off'.
711 The `editing-mode' variable controls which default set of key
712 bindings is used. By default, Readline starts up in Emacs
713 editing mode, where the keystrokes are most similar to Emacs.
714 This variable can be set to either `emacs' or `vi'.
717 When set to `on', Readline will try to enable the application
718 keypad when it is called. Some systems need this to enable
719 the arrow keys. The default is `off'.
722 If set to `on', tilde expansion is performed when Readline
723 attempts word completion. The default is `off'.
725 `horizontal-scroll-mode'
726 This variable can be set to either `on' or `off'. Setting it
727 to `on' means that the text of the lines being edited will
728 scroll horizontally on a single screen line when they are
729 longer than the width of the screen, instead of wrapping onto
730 a new screen line. By default, this variable is set to `off'.
733 Sets Readline's idea of the current keymap for key binding
734 commands. Acceptable `keymap' names are `emacs',
735 `emacs-standard', `emacs-meta', `emacs-ctlx', `vi',
736 `vi-command', and `vi-insert'. `vi' is equivalent to
737 `vi-command'; `emacs' is equivalent to `emacs-standard'. The
738 default value is `emacs'. The value of the `editing-mode'
739 variable also affects the default keymap.
742 If set to `on', completed directory names have a slash
743 appended. The default is `on'.
745 `mark-modified-lines'
746 This variable, when set to `on', causes Readline to display an
747 asterisk (`*') at the start of history lines which have been
748 modified. This variable is `off' by default.
751 If set to `on', Readline will enable eight-bit input (it will
752 not strip the eighth bit from the characters it reads),
753 regardless of what the terminal claims it can support. The
754 default value is `off'. The name `meta-flag' is a synonym
758 If set to `on', Readline will display characters with the
759 eighth bit set directly rather than as a meta-prefixed escape
760 sequence. The default is `off'.
762 `print-completions-horizontally'
763 If set to `on', Readline will display completions with matches
764 sorted horizontally in alphabetical order, rather than down
765 the screen. The default is `off'.
767 `show-all-if-ambiguous'
768 This alters the default behavior of the completion functions.
769 If set to `on', words which have more than one possible
770 completion cause the matches to be listed immediately instead
771 of ringing the bell. The default value is `off'.
774 If set to `on', a character denoting a file's type is
775 appended to the filename when listing possible completions.
776 The default is `off'.
779 The syntax for controlling key bindings in the init file is
780 simple. First you have to know the name of the command that you
781 want to change. The following sections contain tables of the
782 command name, the default keybinding, if any, and a short
783 description of what the command does.
785 Once you know the name of the command, simply place the name of
786 the key you wish to bind the command to, a colon, and then the
787 name of the command on a line in the init file. The name of the
788 key can be expressed in different ways, depending on which is most
791 KEYNAME: FUNCTION-NAME or MACRO
792 KEYNAME is the name of a key spelled out in English. For
794 Control-u: universal-argument
795 Meta-Rubout: backward-kill-word
796 Control-o: "> output"
798 In the above example, <C-u> is bound to the function
799 `universal-argument', and <C-o> is bound to run the macro
800 expressed on the right hand side (that is, to insert the text
801 `> output' into the line).
803 "KEYSEQ": FUNCTION-NAME or MACRO
804 KEYSEQ differs from KEYNAME above in that strings denoting an
805 entire key sequence can be specified, by placing the key
806 sequence in double quotes. Some GNU Emacs style key escapes
807 can be used, as in the following example, but the special
808 character names are not recognized.
810 "\C-u": universal-argument
811 "\C-x\C-r": re-read-init-file
812 "\e[11~": "Function Key 1"
814 In the above example, <C-u> is bound to the function
815 `universal-argument' (just as it was in the first example),
816 `<C-x> <C-r>' is bound to the function `re-read-init-file',
817 and `<ESC> <[> <1> <1> <~>' is bound to insert the text
820 The following GNU Emacs style escape sequences are available when
821 specifying key sequences:
841 In addition to the GNU Emacs style escape sequences, a second set
842 of backslash escapes is available:
869 the character whose ASCII code is the octal value NNN (one to
873 the character whose ASCII code is the hexadecimal value NNN
874 (one to three digits)
876 When entering the text of a macro, single or double quotes must be
877 used to indicate a macro definition. Unquoted text is assumed to
878 be a function name. In the macro body, the backslash escapes
879 described above are expanded. Backslash will quote any other
880 character in the macro text, including `"' and `''. For example,
881 the following binding will make `C-x \' insert a single `\' into
886 File: gdb.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File
888 Conditional Init Constructs
889 ---------------------------
891 Readline implements a facility similar in spirit to the conditional
892 compilation features of the C preprocessor which allows key bindings
893 and variable settings to be performed as the result of tests. There
894 are four parser directives used.
897 The `$if' construct allows bindings to be made based on the
898 editing mode, the terminal being used, or the application using
899 Readline. The text of the test extends to the end of the line; no
900 characters are required to isolate it.
903 The `mode=' form of the `$if' directive is used to test
904 whether Readline is in `emacs' or `vi' mode. This may be
905 used in conjunction with the `set keymap' command, for
906 instance, to set bindings in the `emacs-standard' and
907 `emacs-ctlx' keymaps only if Readline is starting out in
911 The `term=' form may be used to include terminal-specific key
912 bindings, perhaps to bind the key sequences output by the
913 terminal's function keys. The word on the right side of the
914 `=' is tested against both the full name of the terminal and
915 the portion of the terminal name before the first `-'. This
916 allows `sun' to match both `sun' and `sun-cmd', for instance.
919 The APPLICATION construct is used to include
920 application-specific settings. Each program using the
921 Readline library sets the APPLICATION NAME, and you can test
922 for it. This could be used to bind key sequences to
923 functions useful for a specific program. For instance, the
924 following command adds a key sequence that quotes the current
925 or previous word in Bash:
927 # Quote the current or previous word
928 "\C-xq": "\eb\"\ef\""
932 This command, as seen in the previous example, terminates an `$if'
936 Commands in this branch of the `$if' directive are executed if the
940 This directive takes a single filename as an argument and reads
941 commands and bindings from that file.
942 $include /etc/inputrc
945 File: gdb.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File
950 Here is an example of an inputrc file. This illustrates key
951 binding, variable assignment, and conditional syntax.
954 # This file controls the behaviour of line input editing for
955 # programs that use the Gnu Readline library. Existing programs
956 # include FTP, Bash, and Gdb.
958 # You can re-read the inputrc file with C-x C-r.
959 # Lines beginning with '#' are comments.
961 # First, include any systemwide bindings and variable assignments from
963 $include /etc/Inputrc
966 # Set various bindings for emacs mode.
968 set editing-mode emacs
972 Meta-Control-h: backward-kill-word Text after the function name is ignored
975 # Arrow keys in keypad mode
977 #"\M-OD": backward-char
978 #"\M-OC": forward-char
979 #"\M-OA": previous-history
980 #"\M-OB": next-history
982 # Arrow keys in ANSI mode
984 "\M-[D": backward-char
985 "\M-[C": forward-char
986 "\M-[A": previous-history
987 "\M-[B": next-history
989 # Arrow keys in 8 bit keypad mode
991 #"\M-\C-OD": backward-char
992 #"\M-\C-OC": forward-char
993 #"\M-\C-OA": previous-history
994 #"\M-\C-OB": next-history
996 # Arrow keys in 8 bit ANSI mode
998 #"\M-\C-[D": backward-char
999 #"\M-\C-[C": forward-char
1000 #"\M-\C-[A": previous-history
1001 #"\M-\C-[B": next-history
1007 # An old-style binding. This happens to be the default.
1010 # Macros that are convenient for shell interaction
1013 "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f"
1014 # prepare to type a quoted word -- insert open and close double quotes
1015 # and move to just after the open quote
1016 "\C-x\"": "\"\"\C-b"
1017 # insert a backslash (testing backslash escapes in sequences and macros)
1019 # Quote the current or previous word
1020 "\C-xq": "\eb\"\ef\""
1021 # Add a binding to refresh the line, which is unbound
1022 "\C-xr": redraw-current-line
1023 # Edit variable on current line.
1024 "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y="
1027 # use a visible bell if one is available
1028 set bell-style visible
1030 # don't strip characters to 7 bits when reading
1033 # allow iso-latin1 characters to be inserted rather than converted to
1034 # prefix-meta sequences
1035 set convert-meta off
1037 # display characters with the eighth bit set directly rather than
1038 # as meta-prefixed characters
1041 # if there are more than 150 possible completions for a word, ask the
1042 # user if he wants to see all of them
1043 set completion-query-items 150
1049 "\M-.": yank-last-arg
1053 File: gdb.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing
1055 Bindable Readline Commands
1056 ==========================
1060 * Commands For Moving:: Moving about the line.
1061 * Commands For History:: Getting at previous lines.
1062 * Commands For Text:: Commands for changing text.
1063 * Commands For Killing:: Commands for killing and yanking.
1064 * Numeric Arguments:: Specifying numeric arguments, repeat counts.
1065 * Commands For Completion:: Getting Readline to do the typing for you.
1066 * Keyboard Macros:: Saving and re-executing typed characters
1067 * Miscellaneous Commands:: Other miscellaneous commands.
1069 This section describes Readline commands that may be bound to key
1073 File: gdb.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands
1078 `beginning-of-line (C-a)'
1079 Move to the start of the current line.
1082 Move to the end of the line.
1084 `forward-char (C-f)'
1085 Move forward a character.
1087 `backward-char (C-b)'
1088 Move back a character.
1090 `forward-word (M-f)'
1091 Move forward to the end of the next word. Words are composed of
1094 `backward-word (M-b)'
1095 Move back to the start of this, or the previous, word. Words are
1096 composed of letters and digits.
1098 `clear-screen (C-l)'
1099 Clear the screen and redraw the current line, leaving the current
1100 line at the top of the screen.
1102 `redraw-current-line ()'
1103 Refresh the current line. By default, this is unbound.
1106 File: gdb.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands
1108 Commands For Manipulating The History
1109 -------------------------------------
1111 `accept-line (Newline, Return)'
1112 Accept the line regardless of where the cursor is. If this line is
1113 non-empty, add it to the history list. If this line was a history
1114 line, then restore the history line to its original state.
1116 `previous-history (C-p)'
1117 Move `up' through the history list.
1119 `next-history (C-n)'
1120 Move `down' through the history list.
1122 `beginning-of-history (M-<)'
1123 Move to the first line in the history.
1125 `end-of-history (M->)'
1126 Move to the end of the input history, i.e., the line currently
1129 `reverse-search-history (C-r)'
1130 Search backward starting at the current line and moving `up'
1131 through the history as necessary. This is an incremental search.
1133 `forward-search-history (C-s)'
1134 Search forward starting at the current line and moving `down'
1135 through the the history as necessary. This is an incremental
1138 `non-incremental-reverse-search-history (M-p)'
1139 Search backward starting at the current line and moving `up'
1140 through the history as necessary using a non-incremental search
1141 for a string supplied by the user.
1143 `non-incremental-forward-search-history (M-n)'
1144 Search forward starting at the current line and moving `down'
1145 through the the history as necessary using a non-incremental search
1146 for a string supplied by the user.
1148 `history-search-forward ()'
1149 Search forward through the history for the string of characters
1150 between the start of the current line and the current cursor
1151 position (the POINT). This is a non-incremental search. By
1152 default, this command is unbound.
1154 `history-search-backward ()'
1155 Search backward through the history for the string of characters
1156 between the start of the current line and the point. This is a
1157 non-incremental search. By default, this command is unbound.
1159 `yank-nth-arg (M-C-y)'
1160 Insert the first argument to the previous command (usually the
1161 second word on the previous line). With an argument N, insert the
1162 Nth word from the previous command (the words in the previous
1163 command begin with word 0). A negative argument inserts the Nth
1164 word from the end of the previous command.
1166 `yank-last-arg (M-., M-_)'
1167 Insert last argument to the previous command (the last word of the
1168 previous history entry). With an argument, behave exactly like
1169 `yank-nth-arg'. Successive calls to `yank-last-arg' move back
1170 through the history list, inserting the last argument of each line
1174 File: gdb.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands
1176 Commands For Changing Text
1177 --------------------------
1180 Delete the character under the cursor. If the cursor is at the
1181 beginning of the line, there are no characters in the line, and
1182 the last character typed was not bound to `delete-char', then
1185 `backward-delete-char (Rubout)'
1186 Delete the character behind the cursor. A numeric argument means
1187 to kill the characters instead of deleting them.
1189 `quoted-insert (C-q, C-v)'
1190 Add the next character typed to the line verbatim. This is how to
1191 insert key sequences like <C-q>, for example.
1193 `tab-insert (M-TAB)'
1194 Insert a tab character.
1196 `self-insert (a, b, A, 1, !, ...)'
1199 `transpose-chars (C-t)'
1200 Drag the character before the cursor forward over the character at
1201 the cursor, moving the cursor forward as well. If the insertion
1202 point is at the end of the line, then this transposes the last two
1203 characters of the line. Negative arguments don't work.
1205 `transpose-words (M-t)'
1206 Drag the word behind the cursor past the word in front of the
1207 cursor moving the cursor over that word as well.
1210 Uppercase the current (or following) word. With a negative
1211 argument, uppercase the previous word, but do not move the cursor.
1213 `downcase-word (M-l)'
1214 Lowercase the current (or following) word. With a negative
1215 argument, lowercase the previous word, but do not move the cursor.
1217 `capitalize-word (M-c)'
1218 Capitalize the current (or following) word. With a negative
1219 argument, capitalize the previous word, but do not move the cursor.
1222 File: gdb.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands
1228 Kill the text from the current cursor position to the end of the
1231 `backward-kill-line (C-x Rubout)'
1232 Kill backward to the beginning of the line.
1234 `unix-line-discard (C-u)'
1235 Kill backward from the cursor to the beginning of the current line.
1236 The killed text is saved on the kill-ring.
1238 `kill-whole-line ()'
1239 Kill all characters on the current line, no matter where the
1240 cursor is. By default, this is unbound.
1243 Kill from the cursor to the end of the current word, or if between
1244 words, to the end of the next word. Word boundaries are the same
1247 `backward-kill-word (M-DEL)'
1248 Kill the word behind the cursor. Word boundaries are the same as
1251 `unix-word-rubout (C-w)'
1252 Kill the word behind the cursor, using white space as a word
1253 boundary. The killed text is saved on the kill-ring.
1255 `delete-horizontal-space ()'
1256 Delete all spaces and tabs around point. By default, this is
1260 Kill the text between the point and the *mark* (saved cursor
1261 position). This text is referred to as the REGION. By default,
1262 this command is unbound.
1264 `copy-region-as-kill ()'
1265 Copy the text in the region to the kill buffer, so it can be yanked
1266 right away. By default, this command is unbound.
1268 `copy-backward-word ()'
1269 Copy the word before point to the kill buffer. The word
1270 boundaries are the same as `backward-word'. By default, this
1273 `copy-forward-word ()'
1274 Copy the word following point to the kill buffer. The word
1275 boundaries are the same as `forward-word'. By default, this
1279 Yank the top of the kill ring into the buffer at the current
1283 Rotate the kill-ring, and yank the new top. You can only do this
1284 if the prior command is yank or yank-pop.
1287 File: gdb.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands
1289 Specifying Numeric Arguments
1290 ----------------------------
1292 `digit-argument (M-0, M-1, ... M--)'
1293 Add this digit to the argument already accumulating, or start a new
1294 argument. <M-> starts a negative argument.
1296 `universal-argument ()'
1297 This is another way to specify an argument. If this command is
1298 followed by one or more digits, optionally with a leading minus
1299 sign, those digits define the argument. If the command is
1300 followed by digits, executing `universal-argument' again ends the
1301 numeric argument, but is otherwise ignored. As a special case, if
1302 this command is immediately followed by a character that is
1303 neither a digit or minus sign, the argument count for the next
1304 command is multiplied by four. The argument count is initially
1305 one, so executing this function the first time makes the argument
1306 count four, a second time makes the argument count sixteen, and so
1307 on. By default, this is not bound to a key.