Buglet in last commit, the first argument of bpf_ptap is the actual bpf_if.
[dragonfly.git] / contrib / libreadline / readline.3
1 .\" $FreeBSD: src/contrib/libreadline/readline.3,v 1.5.2.2 2000/07/06 23:04:24 ache Exp $
2 .\" $DragonFly: src/contrib/libreadline/Attic/readline.3,v 1.2 2003/06/17 04:24:03 dillon Exp $
3 .\"
4 .\" MAN PAGE COMMENTS to
5 .\"
6 .\"     Chet Ramey
7 .\"     Information Network Services
8 .\"     Case Western Reserve University
9 .\"     chet@ins.CWRU.Edu
10 .\"
11 .\"     Last Change: Tue Jun  1 13:28:03 EDT 1999
12 .\"
13 .TH READLINE 3 "1999 Jun 1" GNU
14 .\"
15 .\" File Name macro.  This used to be `.PN', for Path Name,
16 .\" but Sun doesn't seem to like that very much.
17 .\"
18 .de FN
19 \fI\|\\$1\|\fP
20 ..
21 .SH NAME
22 readline \- get a line from a user with editing
23 .SH SYNOPSIS
24 .LP
25 .nf
26 .ft B
27 #include <stdio.h>
28 #include <readline/readline.h>
29 #include <readline/history.h>
30 .ft
31 .fi
32 .LP
33 .nf
34 .ft B
35 char *readline (prompt)
36 char *prompt;
37 .ft
38 .fi
39 .SH COPYRIGHT
40 .if n Readline is Copyright (C) 1989, 1991, 1993, 1995, 1996 by the Free Software Foundation, Inc.
41 .if t Readline is Copyright \(co 1989, 1991, 1993, 1995, 1996 by the Free Software Foundation, Inc.
42 .SH DESCRIPTION
43 .LP
44 .B readline
45 will read a line from the terminal
46 and return it, using
47 .B prompt
48 as a prompt.  If 
49 .B prompt
50 is null, no prompt is issued.  The line returned is allocated with
51 .IR malloc (3),
52 so the caller must free it when finished.  The line returned
53 has the final newline removed, so only the text of the line
54 remains.
55 .LP
56 .B readline
57 offers editing capabilities while the user is entering the
58 line.
59 By default, the line editing commands
60 are similar to those of emacs.
61 A vi\-style line editing interface is also available.
62 .SH RETURN VALUE
63 .LP
64 .B readline
65 returns the text of the line read.  A blank line
66 returns the empty string.  If
67 .B EOF
68 is encountered while reading a line, and the line is empty,
69 .B NULL
70 is returned.  If an
71 .B EOF
72 is read with a non\-empty line, it is
73 treated as a newline.
74 .SH NOTATION
75 .LP
76 An emacs-style notation is used to denote
77 keystrokes.  Control keys are denoted by C\-\fIkey\fR, e.g., C\-n
78 means Control\-N.  Similarly, 
79 .I meta
80 keys are denoted by M\-\fIkey\fR, so M\-x means Meta\-X.  (On keyboards
81 without a 
82 .I meta
83 key, M\-\fIx\fP means ESC \fIx\fP, i.e., press the Escape key
84 then the
85 .I x
86 key.  This makes ESC the \fImeta prefix\fP.
87 The combination M\-C\-\fIx\fP means ESC\-Control\-\fIx\fP,
88 or press the Escape key
89 then hold the Control key while pressing the
90 .I x
91 key.)
92 .PP
93 Readline commands may be given numeric
94 .IR arguments ,
95 which normally act as a repeat count.  Sometimes, however, it is the
96 sign of the argument that is significant.  Passing a negative argument
97 to a command that acts in the forward direction (e.g., \fBkill\-line\fP)
98 causes that command to act in a backward direction.  Commands whose
99 behavior with arguments deviates from this are noted.
100 .PP
101 When a command is described as \fIkilling\fP text, the text
102 deleted is saved for possible future retrieval
103 (\fIyanking\fP).  The killed text is saved in a
104 \fIkill ring\fP.  Consecutive kills cause the text to be
105 accumulated into one unit, which can be yanked all at once. 
106 Commands which do not kill text separate the chunks of text
107 on the kill ring.
108 .SH INITIALIZATION FILE
109 .LP
110 Readline is customized by putting commands in an initialization
111 file (the \fIinputrc\fP file).
112 The name of this file is taken from the value of the
113 .B INPUTRC
114 environment variable.  If that variable is unset, the default is
115 .IR ~/.inputrc .
116 When a program which uses the readline library starts up, the
117 init file is read, and the key bindings and variables are set.
118 There are only a few basic constructs allowed in the
119 readline init file.  Blank lines are ignored.
120 Lines beginning with a \fB#\fP are comments.
121 Lines beginning with a \fB$\fP indicate conditional constructs.
122 Other lines denote key bindings and variable settings.
123 Each program using this library may add its own commands
124 and bindings.
125 .PP
126 For example, placing
127 .RS
128 .PP
129 M\-Control\-u: universal\-argument
130 .RE
131 or
132 .RS
133 C\-Meta\-u: universal\-argument
134 .RE
135 into the 
136 .I inputrc
137 would make M\-C\-u execute the readline command
138 .IR universal\-argument .
139 .PP
140 The following symbolic character names are recognized while
141 processing key bindings:
142 .IR RUBOUT ,
143 .IR DEL ,
144 .IR ESC ,
145 .IR LFD ,
146 .IR NEWLINE ,
147 .IR RET ,
148 .IR RETURN ,
149 .IR SPC ,
150 .IR SPACE ,
151 and
152 .IR TAB .
153 .PP
154 In addition to command names, readline allows keys to be bound
155 to a string that is inserted when the key is pressed (a \fImacro\fP).
156 .PP
157 .SS Key Bindings
158 .PP
159 The syntax for controlling key bindings in the
160 .I inputrc
161 file is simple.  All that is required is the name of the
162 command or the text of a macro and a key sequence to which
163 it should be bound. The name may be specified in one of two ways:
164 as a symbolic key name, possibly with \fIMeta\-\fP or \fIControl\-\fP
165 prefixes, or as a key sequence.
166 When using the form \fBkeyname\fP:\^\fIfunction-name\fP or \fImacro\fP,
167 .I keyname
168 is the name of a key spelled out in English.  For example:
169 .sp
170 .RS
171 Control\-u: universal\-argument
172 .br
173 Meta\-Rubout: backward\-kill\-word
174 .br
175 Control\-o: ">&output"
176 .RE
177 .LP
178 In the above example,
179 .I C\-u
180 is bound to the function
181 .BR universal\-argument ,
182 .I M-DEL
183 is bound to the function
184 .BR backward\-kill\-word ,
185 and
186 .I C\-o
187 is bound to run the macro
188 expressed on the right hand side (that is, to insert the text
189 .I >&output
190 into the line).
191 .PP
192 In the second form, \fB"keyseq"\fP:\^\fIfunction\-name\fP or \fImacro\fP,
193 .B keyseq
194 differs from
195 .B keyname
196 above in that strings denoting
197 an entire key sequence may be specified by placing the sequence
198 within double quotes.  Some GNU Emacs style key escapes can be
199 used, as in the following example.
200 .sp
201 .RS
202 "\eC\-u": universal\-argument
203 .br
204 "\eC\-x\eC\-r": re\-read\-init\-file
205 .br
206 "\ee[11~": "Function Key 1"
207 .RE
208 .PP
209 In this example,
210 .I C-u
211 is again bound to the function
212 .BR universal\-argument .
213 .I "C-x C-r"
214 is bound to the function
215 .BR re\-read\-init\-file ,
216 and 
217 .I "ESC [ 1 1 ~"
218 is bound to insert the text
219 .BR "Function Key 1" .
220 The full set of GNU Emacs style escape sequences is
221 .RS
222 .PD 0
223 .TP
224 .B \eC\-
225 control prefix
226 .TP
227 .B \eM\-
228 meta prefix
229 .TP
230 .B \ee
231 an escape character
232 .TP
233 .B \e\e
234 backslash
235 .TP
236 .B \e"
237 literal "
238 .TP
239 .B \e'
240 literal '
241 .RE
242 .PD
243 .PP
244 In addition to the GNU Emacs style escape sequences, a second
245 set of backslash escapes is available:
246 .RS
247 .PD 0
248 .TP
249 .B \ea
250 alert (bell)
251 .TP
252 .B \eb
253 backspace
254 .TP
255 .B \ed
256 delete
257 .TP
258 .B \ef
259 form feed
260 .TP
261 .B \en
262 newline
263 .TP
264 .B \er
265 carriage return
266 .TP
267 .B \et
268 horizontal tab
269 .TP
270 .B \ev
271 vertical tab
272 .TP
273 .B \e\fInnn\fP
274 the character whose ASCII code is the octal value \fInnn\fP
275 (one to three digits)
276 .TP
277 .B \ex\fInnn\fP
278 the character whose ASCII code is the hexadecimal value \fInnn\fP
279 (one to three digits)
280 .RE
281 .PD
282 .PP
283 When entering the text of a macro, single or double quotes should
284 be used to indicate a macro definition.  Unquoted text
285 is assumed to be a function name.
286 In the macro body, the backslash escapes described above are expanded.
287 Backslash will quote any other character in the macro text,
288 including " and '.
289 .PP
290 .B Bash
291 allows the current readline key bindings to be displayed or modified
292 with the
293 .B bind
294 builtin command.  The editing mode may be switched during interactive
295 use by using the
296 .B \-o
297 option to the
298 .B set
299 builtin command.  Other programs using this library provide
300 similar mechanisms.  The
301 .I inputrc
302 file may be edited and re-read if a program does not provide
303 any other means to incorporate new bindings.
304 .SS Variables
305 .PP
306 Readline has variables that can be used to further customize its
307 behavior.  A variable may be set in the
308 .I inputrc
309 file with a statement of the form
310 .RS
311 .PP
312 \fBset\fP \fIvariable\-name\fP \fIvalue\fP
313 .RE
314 .PP
315 Except where noted, readline variables can take the values
316 .B On
317 or
318 .BR Off .
319 The variables and their default values are:
320 .PP
321 .PD 0
322 .TP
323 .B bell\-style (audible)
324 Controls what happens when readline wants to ring the terminal bell.
325 If set to \fBnone\fP, readline never rings the bell.  If set to
326 \fBvisible\fP, readline uses a visible bell if one is available.
327 If set to \fBaudible\fP, readline attempts to ring the terminal's bell.
328 .TP
329 .B comment\-begin (``#'')
330 The string that is inserted in \fBvi\fP mode when the
331 .B insert\-comment
332 command is executed.
333 This command is bound to
334 .B M\-#
335 in emacs mode and to
336 .B #
337 in vi command mode.
338 .TP 
339 .B completion\-ignore\-case (Off)
340 If set to \fBOn\fP, readline performs filename matching and completion
341 in a case\-insensitive fashion.
342 .TP
343 .B completion\-query\-items (100)
344 This determines when the user is queried about viewing
345 the number of possible completions
346 generated by the \fBpossible\-completions\fP command.
347 It may be set to any integer value greater than or equal to
348 zero.  If the number of possible completions is greater than
349 or equal to the value of this variable, the user is asked whether
350 or not he wishes to view them; otherwise they are simply listed
351 on the terminal.
352 .TP
353 .B convert\-meta (On)
354 If set to \fBOn\fP, readline will convert characters with the
355 eighth bit set to an ASCII key sequence
356 by stripping the eighth bit and prepending an
357 escape character (in effect, using escape as the \fImeta prefix\fP).
358 .TP
359 .B disable\-completion (Off)
360 If set to \fBOn\fP, readline will inhibit word completion.  Completion 
361 characters will be inserted into the line as if they had been
362 mapped to \fBself-insert\fP.
363 .TP
364 .B editing\-mode (emacs)
365 Controls whether readline begins with a set of key bindings similar
366 to \fIemacs\fP or \fIvi\fP.
367 .B editing\-mode
368 can be set to either
369 .B emacs
370 or
371 .BR vi .
372 .TP
373 .B enable\-keypad (Off)
374 When set to \fBOn\fP, readline will try to enable the application
375 keypad when it is called.  Some systems need this to enable the
376 arrow keys.
377 .TP
378 .B expand\-tilde (Off)
379 If set to \fBon\fP, tilde expansion is performed when readline
380 attempts word completion.
381 .TP
382 .B horizontal\-scroll\-mode (Off)
383 When set to \fBOn\fP, makes readline use a single line for display,
384 scrolling the input horizontally on a single screen line when it
385 becomes longer than the screen width rather than wrapping to a new line.
386 .TP
387 .B input\-meta (Off)
388 If set to \fBOn\fP, readline will enable eight-bit input (that is,
389 it will not strip the high bit from the characters it reads),
390 regardless of what the terminal claims it can support.  The name
391 .B meta\-flag
392 is a synonym for this variable.
393 .TP
394 .B isearch\-terminators (``C\-[C\-J'')
395 The string of characters that should terminate an incremental
396 search without subsequently executing the character as a command.
397 If this variable has not been given a value, the characters
398 \fIESC\fP and \fIC\-J\fP will terminate an incremental search.
399 .TP
400 .B keymap (emacs)
401 Set the current readline keymap.  The set of legal keymap names is
402 \fIemacs, emacs-standard, emacs-meta, emacs-ctlx, vi, vi-move,
403 vi-command\fP, and
404 .IR vi-insert .
405 \fIvi\fP is equivalent to \fIvi-command\fP; \fIemacs\fP is
406 equivalent to \fIemacs-standard\fP.  The default value is
407 .IR emacs ;
408 the value of
409 .B editing\-mode
410 also affects the default keymap.
411 .TP
412 .B mark\-directories (On)
413 If set to \fBOn\fP, complete<d directory names have a slash
414 appended.
415 .TP
416 .B mark\-modified\-lines (Off)
417 If set to \fBOn\fP, history lines that have been modified are displayed
418 with a preceding asterisk (\fB*\fP).
419 .TP
420 .B output\-meta (Off)
421 If set to \fBOn\fP, readline will display characters with the
422 eighth bit set directly rather than as a meta-prefixed escape
423 sequence.
424 .TP
425 .B print\-completions\-horizontally (Off)
426 If set to \fBOn\fP, readline will display completions with matches
427 sorted horizontally in alphabetical order, rather than down the screen.
428 .TP
429 .B show\-all\-if\-ambiguous (Off)
430 This alters the default behavior of the completion functions.  If
431 set to
432 .BR on ,
433 words which have more than one possible completion cause the
434 matches to be listed immediately instead of ringing the bell.
435 .TP
436 .B visible\-stats (Off)
437 If set to \fBOn\fP, a character denoting a file's type as reported  
438 by \fBstat\fP(2) is appended to the filename when listing possible
439 completions.
440 .PD
441 .SS Conditional Constructs
442 .PP
443 Readline implements a facility similar in spirit to the conditional
444 compilation features of the C preprocessor which allows key
445 bindings and variable settings to be performed as the result
446 of tests.  There are four parser directives used.
447 .IP \fB$if\fP
448 The 
449 .B $if
450 construct allows bindings to be made based on the
451 editing mode, the terminal being used, or the application using
452 readline.  The text of the test extends to the end of the line;
453 no characters are required to isolate it.
454 .RS
455 .IP \fBmode\fP
456 The \fBmode=\fP form of the \fB$if\fP directive is used to test
457 whether readline is in emacs or vi mode.
458 This may be used in conjunction
459 with the \fBset keymap\fP command, for instance, to set bindings in
460 the \fIemacs-standard\fP and \fIemacs-ctlx\fP keymaps only if
461 readline is starting out in emacs mode.
462 .IP \fBterm\fP
463 The \fBterm=\fP form may be used to include terminal-specific
464 key bindings, perhaps to bind the key sequences output by the
465 terminal's function keys.  The word on the right side of the
466 .B =
467 is tested against the full name of the terminal and the portion
468 of the terminal name before the first \fB\-\fP.  This allows
469 .I sun
470 to match both
471 .I sun
472 and
473 .IR sun\-cmd ,
474 for instance.
475 .IP \fBapplication\fP
476 The \fBapplication\fP construct is used to include
477 application-specific settings.  Each program using the readline
478 library sets the \fIapplication name\fP, and an initialization
479 file can test for a particular value.
480 This could be used to bind key sequences to functions useful for
481 a specific program.  For instance, the following command adds a
482 key sequence that quotes the current or previous word in Bash:
483 .sp 1
484 .RS
485 .nf
486 \fB$if\fP bash
487 # Quote the current or previous word
488 "\eC-xq": "\eeb\e"\eef\e""
489 \fB$endif\fP
490 .fi
491 .RE
492 .RE
493 .IP \fB$endif\fP
494 This command, as seen in the previous example, terminates an
495 \fB$if\fP command.
496 .IP \fB$else\fP
497 Commands in this branch of the \fB$if\fP directive are executed if
498 the test fails.
499 .IP \fB$include\fP
500 This directive takes a single filename as an argument and reads commands
501 and bindings from that file.  For example, the following directive
502 would read \fI/etc/inputrc\fP:
503 .sp 1
504 .RS
505 .nf
506 \fB$include\fP \^ \fI/etc/inputrc\fP
507 .fi 
508 .RE
509 .SH SEARCHING
510 .PP
511 Readline provides commands for searching through the command history
512 for lines containing a specified string.
513 There are two search modes:
514 .I incremental
515 and
516 .IR non-incremental .
517 .PP
518 Incremental searches begin before the user has finished typing the
519 search string.
520 As each character of the search string is typed, readline displays
521 the next entry from the history matching the string typed so far.
522 An incremental search requires only as many characters as needed to
523 find the desired history entry.
524 The characters present in the value of the \fIisearch-terminators\fP
525 variable are used to terminate an incremental search.
526 If that variable has not been assigned a value the Escape and
527 Control-J characters will terminate an incremental search.
528 Control-G will abort an incremental search and restore the original
529 line.
530 When the search is terminated, the history entry containing the
531 search string becomes the current line.
532 To find other matching entries in the history list, type Control-S or
533 Control-R as appropriate.
534 This will search backward or forward in the history for the next
535 line matching the search string typed so far.
536 Any other key sequence bound to a readline command will terminate
537 the search and execute that command.
538 For instance, a \fInewline\fP will terminate the search and accept
539 the line, thereby executing the command from the history list.
540 .PP
541 Non-incremental searches read the entire search string before starting
542 to search for matching history lines.  The search string may be
543 typed by the user or be part of the contents of the current line.
544 .SH EDITING COMMANDS
545 .PP
546 The following is a list of the names of the commands and the default
547 key sequences to which they are bound.
548 Command names without an accompanying key sequence are unbound by default.
549 .SS Commands for Moving
550 .PP
551 .PD 0
552 .TP
553 .B beginning\-of\-line (C\-a)
554 Move to the start of the current line.
555 .TP
556 .B end\-of\-line (C\-e)
557 Move to the end of the line.
558 .TP
559 .B forward\-char (C\-f)
560 Move forward a character.
561 .TP
562 .B backward\-char (C\-b)
563 Move back a character.
564 .TP
565 .B forward\-word (M\-f)
566 Move forward to the end of the next word.  Words are composed of
567 alphanumeric characters (letters and digits).
568 .TP
569 .B backward\-word (M\-b)
570 Move back to the start of the current or previous word.  Words are
571 composed of alphanumeric characters (letters and digits).
572 .TP
573 .B clear\-screen (C\-l)
574 Clear the screen leaving the current line at the top of the screen.
575 With an argument, refresh the current line without clearing the
576 screen.
577 .TP
578 .B redraw\-current\-line
579 Refresh the current line.
580 .PD
581 .SS Commands for Manipulating the History
582 .PP
583 .PD 0
584 .TP
585 .B accept\-line (Newline, Return)
586 Accept the line regardless of where the cursor is.  If this line is
587 non-empty, add it to the history list. If the line is a modified
588 history line, then restore the history line to its original state.
589 .TP
590 .B previous\-history (C\-p)
591 Fetch the previous command from the history list, moving back in
592 the list.
593 .TP
594 .B next\-history (C\-n)
595 Fetch the next command from the history list, moving forward in the
596 list.
597 .TP
598 .B beginning\-of\-history (M\-<)
599 Move to the first line in the history.
600 .TP
601 .B end\-of\-history (M\->)
602 Move to the end of the input history, i.e., the line currently being
603 entered.
604 .TP
605 .B reverse\-search\-history (C\-r)
606 Search backward starting at the current line and moving `up' through
607 the history as necessary.  This is an incremental search.
608 .TP
609 .B forward\-search\-history (C\-s)
610 Search forward starting at the current line and moving `down' through
611 the history as necessary.  This is an incremental search.
612 .TP
613 .B non\-incremental\-reverse\-search\-history (M\-p)
614 Search backward through the history starting at the current line
615 using a non-incremental search for a string supplied by the user.
616 .TP
617 .B non\-incremental\-forward\-search\-history (M\-n)
618 Search forward through the history using a non-incremental search
619 for a string supplied by the user.
620 .TP
621 .B history\-search\-forward
622 Search forward through the history for the string of characters
623 between the start of the current line and the current cursor
624 position (the \fIpoint\fP).
625 This is a non-incremental search.
626 .TP
627 .B history\-search\-backward
628 Search backward through the history for the string of characters
629 between the start of the current line and the point.
630 This is a non-incremental search.
631 .TP
632 .B yank\-nth\-arg (M\-C\-y)
633 Insert the first argument to the previous command (usually
634 the second word on the previous line) at point (the current
635 cursor position).  With an argument
636 .IR n ,
637 insert the \fIn\fPth word from the previous command (the words
638 in the previous command begin with word 0).  A negative argument
639 inserts the \fIn\fPth word from the end of the previous command.
640 .TP
641 .B
642 yank\-last\-arg (M\-.\^, M\-_\^)
643 Insert the last argument to the previous command (the last word of
644 the previous history entry).  With an argument,
645 behave exactly like \fByank\-nth\-arg\fP.
646 Successive calls to \fByank\-last\-arg\fP move back through the history
647 list, inserting the last argument of each line in turn.
648 .PD
649 .SS Commands for Changing Text
650 .PP
651 .PD 0
652 .TP
653 .B delete\-char (C\-d)
654 Delete the character under the cursor.  If point is at the
655 beginning of the line, there are no characters in the line, and
656 the last character typed was not bound to \fBBdelete\-char\fP, then return
657 .SM
658 .BR EOF .
659 .TP
660 .B backward\-delete\-char (Rubout)
661 Delete the character behind the cursor.  When given a numeric argument,
662 save the deleted text on the kill ring.
663 .TP
664 .B forward\-backward\-delete\-char   
665 Delete the character under the cursor, unless the cursor is at the
666 end of the line, in which case the character behind the cursor is
667 deleted.  By default, this is not bound to a key.
668 .TP
669 .B quoted\-insert (C\-q, C\-v)
670 Add the next character that you type to the line verbatim.  This is
671 how to insert characters like \fBC\-q\fP, for example.
672 .TP
673 .B tab\-insert (M-TAB)
674 Insert a tab character.
675 .TP
676 .B self\-insert (a,\ b,\ A,\ 1,\ !,\ ...)
677 Insert the character typed.
678 .TP
679 .B transpose\-chars (C\-t)
680 Drag the character before point forward over the character at point.
681 Point moves forward as well.  If point is at the end of the line, then
682 transpose the two characters before point.  Negative arguments don't work.
683 .TP
684 .B transpose\-words (M\-t)
685 Drag the word behind the cursor past the word in front of the cursor
686 moving the cursor over that word as well.
687 .TP
688 .B upcase\-word (M\-u)
689 Uppercase the current (or following) word.  With a negative argument,
690 uppercase the previous word, but do not move point.
691 .TP
692 .B downcase\-word (M\-l)
693 Lowercase the current (or following) word.  With a negative argument,
694 lowercase the previous word, but do not move point.
695 .TP
696 .B capitalize\-word (M\-c)
697 Capitalize the current (or following) word.  With a negative argument,
698 capitalize the previous word, but do not move point.
699 .PD
700 .SS Killing and Yanking
701 .PP
702 .PD 0
703 .TP
704 .B kill\-line (C\-k)
705 Kill the text from the current cursor position to the end of the line.
706 .TP
707 .B backward\-kill\-line (C\-x Rubout)
708 Kill backward to the beginning of the line.
709 .TP
710 .B unix\-line\-discard (C\-u)
711 Kill backward from point to the beginning of the line.
712 The killed text is saved on the kill-ring.
713 .\" There is no real difference between this and backward-kill-line
714 .TP
715 .B kill\-whole\-line
716 Kill all characters on the current line, no matter where the
717 cursor is.
718 .TP
719 .B kill\-word  (M\-d)
720 Kill from the cursor to the end of the current word, or if between
721 words, to the end of the next word.  Word boundaries are the same as
722 those used by \fBforward\-word\fP.
723 .TP
724 .B backward\-kill\-word (M\-Rubout)
725 Kill the word behind the cursor.  Word boundaries are the same as
726 those used by \fBbackward\-word\fP.
727 .TP
728 .B unix\-word\-rubout (C\-w)
729 Kill the word behind the cursor, using white space as a word boundary.
730 The word boundaries are different from
731 .BR backward\-kill\-word .
732 .TP
733 .B delete\-horizontal\-space (M\-\e)
734 Delete all spaces and tabs around point.
735 .TP
736 .B kill\-region
737 Kill the text between the point and \fImark\fP (saved cursor position).
738 This text is referred to as the \fIregion\fP.
739 .TP
740 .B copy\-region\-as\-kill
741 Copy the text in the region to the kill buffer.
742 .TP
743 .B copy\-backward\-word
744 Copy the word before point to the kill buffer.
745 The word boundaries are the same as \fBbackward\-word\fP.
746 .TP
747 .B copy\-forward\-word
748 Copy the word following point to the kill buffer.
749 The word boundaries are the same as \fBforward\-word\fP.
750 .TP
751 .B yank (C\-y)
752 Yank the top of the kill ring into the buffer at the cursor.
753 .TP
754 .B yank\-pop (M\-y)
755 Rotate the kill ring, and yank the new top.  Only works following
756 .B yank
757 or
758 .BR yank\-pop .
759 .PD
760 .SS Numeric Arguments
761 .PP
762 .PD 0
763 .TP
764 .B digit\-argument (M\-0, M\-1, ..., M\-\-)
765 Add this digit to the argument already accumulating, or start a new
766 argument.  M\-\- starts a negative argument.
767 .TP
768 .B universal\-argument
769 This is another way to specify an argument.
770 If this command is followed by one or more digits, optionally with a
771 leading minus sign, those digits define the argument.
772 If the command is followed by digits, executing
773 .B universal\-argument
774 again ends the numeric argument, but is otherwise ignored.
775 As a special case, if this command is immediately followed by a
776 character that is neither a digit or minus sign, the argument count
777 for the next command is multiplied by four.
778 The argument count is initially one, so executing this function the
779 first time makes the argument count four, a second time makes the
780 argument count sixteen, and so on.
781 .PD
782 .SS Completing
783 .PP
784 .PD 0
785 .TP
786 .B complete (TAB)
787 Attempt to perform completion on the text before point.
788 The actual completion performed is application-specific.
789 .BR Bash ,
790 for instance, attempts completion treating the text as a variable
791 (if the text begins with \fB$\fP), username (if the text begins with
792 \fB~\fP), hostname (if the text begins with \fB@\fP), or
793 command (including aliases and functions) in turn.  If none
794 of these produces a match, filename completion is attempted.
795 .BR Gdb ,
796 on the other hand,
797 allows completion of program functions and variables, and
798 only attempts filename completion under certain circumstances.
799 .TP
800 .B possible\-completions (M\-?)
801 List the possible completions of the text before point.
802 .TP
803 .B insert\-completions (M\-*)
804 Insert all completions of the text before point
805 that would have been generated by
806 \fBpossible\-completions\fP.
807 .TP
808 .B menu\-complete
809 Similar to \fBcomplete\fP, but replaces the word to be completed
810 with a single match from the list of possible completions.
811 Repeated execution of \fBmenu\-complete\fP steps through the list
812 of possible completions, inserting each match in turn.
813 At the end of the list of completions, the bell is rung and the
814 original text is restored.
815 An argument of \fIn\fP moves \fIn\fP positions forward in the list
816 of matches; a negative argument may be used to move backward 
817 through the list.
818 This command is intended to be bound to \fBTAB\fP, but is unbound
819 by default.
820 .TP
821 .B delete\-char\-or\-list
822 Deletes the character under the cursor if not at the beginning or
823 end of the line (like \fBdelete-char\fP).
824 If at the end of the line, behaves identically to
825 \fBpossible-completions\fP.
826 This command is unbound by default.
827 .PD
828 .SS Keyboard Macros
829 .PP
830 .PD 0
831 .TP
832 .B start\-kbd\-macro (C\-x (\^)
833 Begin saving the characters typed into the current keyboard macro.
834 .TP
835 .B end\-kbd\-macro (C\-x )\^)
836 Stop saving the characters typed into the current keyboard macro
837 and store the definition.
838 .TP
839 .B call\-last\-kbd\-macro (C\-x e)
840 Re-execute the last keyboard macro defined, by making the characters
841 in the macro appear as if typed at the keyboard.
842 .PD
843 .SS Miscellaneous
844 .PP
845 .PD 0
846 .TP
847 .B re\-read\-init\-file (C\-x C\-r)
848 Read in the contents of the \fIinputrc\fP file, and incorporate
849 any bindings or variable assignments found there.
850 .TP
851 .B abort (C\-g)
852 Abort the current editing command and
853 ring the terminal's bell (subject to the setting of
854 .BR bell\-style ).
855 .TP
856 .B do\-uppercase\-version (M\-a, M\-b, M\-\fIx\fP, ...)
857 If the metafied character \fIx\fP is lowercase, run the command
858 that is bound to the corresponding uppercase character.
859 .TP
860 .B prefix\-meta (ESC)
861 Metafy the next character typed.
862 .SM
863 .B ESC
864 .B f
865 is equivalent to
866 .BR Meta\-f .
867 .TP
868 .B undo (C\-_, C\-x C\-u)
869 Incremental undo, separately remembered for each line.
870 .TP
871 .B revert\-line (M\-r)
872 Undo all changes made to this line.  This is like executing the
873 .B undo
874 command enough times to return the line to its initial state.
875 .TP
876 .B tilde\-expand (M\-&)
877 Perform tilde expansion on the current word.
878 .TP
879 .B set\-mark (C\-@, M-<space>)
880 Set the mark to the current point.  If a
881 numeric argument is supplied, the mark is set to that position.
882 .TP
883 .B exchange\-point\-and\-mark (C\-x C\-x)
884 Swap the point with the mark.  The current cursor position is set to
885 the saved position, and the old cursor position is saved as the mark.
886 .TP
887 .B character\-search (C\-])
888 A character is read and point is moved to the next occurrence of that
889 character.  A negative count searches for previous occurrences.
890 .TP
891 .B character\-search\-backward (M\-C\-])
892 A character is read and point is moved to the previous occurrence of that
893 character.  A negative count searches for subsequent occurrences.
894 .TP
895 .B insert\-comment (M\-#)
896 The value of the readline
897 .B comment\-begin
898 variable is inserted at the beginning of the current line, and the line
899 is accepted as if a newline had been typed.  This makes the current line
900 a shell comment.
901 .TP
902 .B dump\-functions
903 Print all of the functions and their key bindings to the
904 readline output stream.  If a numeric argument is supplied,
905 the output is formatted in such a way that it can be made part
906 of an \fIinputrc\fP file.
907 .TP
908 .B dump\-variables
909 Print all of the settable variables and their values to the
910 readline output stream.  If a numeric argument is supplied,
911 the output is formatted in such a way that it can be made part
912 of an \fIinputrc\fP file.
913 .TP
914 .B dump\-macros
915 Print all of the readline key sequences bound to macros and the
916 strings they ouput.  If a numeric argument is supplied,
917 the output is formatted in such a way that it can be made part
918 of an \fIinputrc\fP file.
919 .TP
920 .B emacs\-editing\-mode (C\-e)
921 When in
922 .B vi
923 editing mode, this causes a switch to
924 .B emacs
925 editing mode.
926 .TP
927 .B vi\-editing\-mode (M\-C\-j)
928 When in
929 .B emacs
930 editing mode, this causes a switch to
931 .B vi
932 editing mode.
933 .PD
934 .SH DEFAULT KEY BINDINGS
935 .LP
936 The following is a list of the default emacs and vi bindings.
937 Characters with the 8th bit set are written as M\-<character>, and
938 are referred to as
939 .I metafied
940 characters.
941 The printable ASCII characters not mentioned in the list of emacs
942 standard bindings are bound to the
943 .I self\-insert
944 function, which just inserts the given character into the input line.
945 In vi insertion mode, all characters not specifically mentioned are
946 bound to
947 .IR self\-insert .
948 Characters assigned to signal generation by
949 .IR stty (1)
950 or the terminal driver, such as C-Z or C-C,
951 retain that function.
952 Upper and lower case
953 .I metafied
954 characters are bound to the same function in the emacs mode
955 meta keymap.
956 The remaining characters are unbound, which causes readline
957 to ring the bell (subject to the setting of the
958 .B bell\-style
959 variable).
960 .SS Emacs Mode
961 .RS +.6i
962 .nf
963 .ta 2.5i
964 .sp
965 Emacs Standard bindings
966 .sp
967 "C-@"  set-mark
968 "C-A"  beginning-of-line
969 "C-B"  backward-char
970 "C-D"  delete-char
971 "C-E"  end-of-line
972 "C-F"  forward-char
973 "C-G"  abort
974 "C-H"  backward-delete-char
975 "C-I"  complete
976 "C-J"  accept-line
977 "C-K"  kill-line
978 "C-L"  clear-screen
979 "C-M"  accept-line
980 "C-N"  next-history
981 "C-P"  previous-history
982 "C-Q"  quoted-insert
983 "C-R"  reverse-search-history
984 "C-S"  forward-search-history
985 "C-T"  transpose-chars
986 "C-U"  unix-line-discard
987 "C-V"  quoted-insert
988 "C-W"  unix-word-rubout
989 "C-Y"  yank
990 "C-]"  character-search
991 "C-_"  undo
992 "\^ " to "/"  self-insert
993 "0"  to "9"  self-insert
994 ":"  to "~"  self-insert
995 "C-?"  backward-delete-char
996 .PP
997 Emacs Meta bindings
998 .sp
999 "M-C-G"  abort
1000 "M-C-H"  backward-kill-word
1001 "M-C-I"  tab-insert
1002 "M-C-J"  vi-editing-mode
1003 "M-C-M"  vi-editing-mode
1004 "M-C-R"  revert-line
1005 "M-C-Y"  yank-nth-arg
1006 "M-C-["  complete
1007 "M-C-]"  character-search-backward
1008 "M-space"  set-mark
1009 "M-#"  insert-comment
1010 "M-&"  tilde-expand
1011 "M-*"  insert-completions
1012 "M--"  digit-argument
1013 "M-."  yank-last-arg
1014 "M-0"  digit-argument
1015 "M-1"  digit-argument
1016 "M-2"  digit-argument
1017 "M-3"  digit-argument
1018 "M-4"  digit-argument
1019 "M-5"  digit-argument
1020 "M-6"  digit-argument
1021 "M-7"  digit-argument
1022 "M-8"  digit-argument
1023 "M-9"  digit-argument
1024 "M-<"  beginning-of-history
1025 "M-="  possible-completions
1026 "M->"  end-of-history
1027 "M-?"  possible-completions
1028 "M-B"  backward-word
1029 "M-C"  capitalize-word
1030 "M-D"  kill-word
1031 "M-F"  forward-word
1032 "M-L"  downcase-word
1033 "M-N"  non-incremental-forward-search-history
1034 "M-P"  non-incremental-reverse-search-history
1035 "M-R"  revert-line
1036 "M-T"  transpose-words
1037 "M-U"  upcase-word
1038 "M-Y"  yank-pop
1039 "M-\e"  delete-horizontal-space
1040 "M-~"  tilde-expand
1041 "M-C-?"  backward-delete-word
1042 "M-_"  yank-last-arg
1043 .PP
1044 Emacs Control-X bindings
1045 .sp
1046 "C-XC-G"  abort
1047 "C-XC-R"  re-read-init-file
1048 "C-XC-U"  undo
1049 "C-XC-X"  exchange-point-and-mark
1050 "C-X("  start-kbd-macro
1051 "C-X)"  end-kbd-macro
1052 "C-XE"  call-last-kbd-macro
1053 "C-XC-?"  backward-kill-line
1054 .sp
1055 .RE
1056 .SS VI Mode bindings
1057 .RS +.6i
1058 .nf
1059 .ta 2.5i
1060 .sp
1061 .PP
1062 VI Insert Mode functions
1063 .sp
1064 "C-D"  vi-eof-maybe
1065 "C-H"  backward-delete-char
1066 "C-I"  complete
1067 "C-J"  accept-line
1068 "C-M"  accept-line
1069 "C-R"  reverse-search-history
1070 "C-S"  forward-search-history
1071 "C-T"  transpose-chars
1072 "C-U"  unix-line-discard
1073 "C-V"  quoted-insert
1074 "C-W"  unix-word-rubout
1075 "C-Y"  yank
1076 "C-["  vi-movement-mode
1077 "C-_"  undo
1078 "\^ " to "~"  self-insert
1079 "C-?"  backward-delete-char
1080 .PP
1081 VI Command Mode functions
1082 .sp
1083 "C-D"  vi-eof-maybe
1084 "C-E"  emacs-editing-mode
1085 "C-G"  abort
1086 "C-H"  backward-char
1087 "C-J"  accept-line
1088 "C-K"  kill-line
1089 "C-L"  clear-screen
1090 "C-M"  accept-line
1091 "C-N"  next-history
1092 "C-P"  previous-history
1093 "C-Q"  quoted-insert
1094 "C-R"  reverse-search-history
1095 "C-S"  forward-search-history
1096 "C-T"  transpose-chars
1097 "C-U"  unix-line-discard
1098 "C-V"  quoted-insert
1099 "C-W"  unix-word-rubout
1100 "C-Y"  yank
1101 "\^ "  forward-char
1102 "#"  insert-comment
1103 "$"  end-of-line
1104 "%"  vi-match
1105 "&"  vi-tilde-expand
1106 "*"  vi-complete
1107 "+"  next-history
1108 ","  vi-char-search
1109 "-"  previous-history
1110 "."  vi-redo
1111 "/"  vi-search
1112 "0"  beginning-of-line
1113 "1" to "9"  vi-arg-digit
1114 ";"  vi-char-search
1115 "="  vi-complete
1116 "?"  vi-search
1117 "A"  vi-append-eol
1118 "B"  vi-prev-word
1119 "C"  vi-change-to
1120 "D"  vi-delete-to
1121 "E"  vi-end-word
1122 "F"  vi-char-search
1123 "G"  vi-fetch-history
1124 "I"  vi-insert-beg
1125 "N"  vi-search-again
1126 "P"  vi-put
1127 "R"  vi-replace
1128 "S"  vi-subst
1129 "T"  vi-char-search
1130 "U"  revert-line
1131 "W"  vi-next-word
1132 "X"  backward-delete-char
1133 "Y"  vi-yank-to
1134 "\e"  vi-complete
1135 "^"  vi-first-print
1136 "_"  vi-yank-arg
1137 "`"  vi-goto-mark
1138 "a"  vi-append-mode
1139 "b"  vi-prev-word
1140 "c"  vi-change-to
1141 "d"  vi-delete-to
1142 "e"  vi-end-word
1143 "f"  vi-char-search
1144 "h"  backward-char
1145 "i"  vi-insertion-mode
1146 "j"  next-history
1147 "k"  prev-history
1148 "l"  forward-char
1149 "m"  vi-set-mark
1150 "n"  vi-search-again
1151 "p"  vi-put
1152 "r"  vi-change-char
1153 "s"  vi-subst
1154 "t"  vi-char-search
1155 "u"  undo
1156 "w"  vi-next-word
1157 "x"  vi-delete
1158 "y"  vi-yank-to
1159 "|"  vi-column
1160 "~"  vi-change-case
1161 .RE
1162 .SH "SEE ALSO"
1163 .PD 0
1164 .TP
1165 \fIThe Gnu Readline Library\fP, Brian Fox and Chet Ramey
1166 .TP
1167 \fIThe Gnu History Library\fP, Brian Fox and Chet Ramey
1168 .TP
1169 \fIbash\fP(1)
1170 .PD
1171 .SH FILES
1172 .PD 0
1173 .TP
1174 .FN ~/.inputrc
1175 Individual \fBreadline\fP initialization file
1176 .PD
1177 .SH AUTHORS
1178 Brian Fox, Free Software Foundation
1179 .br
1180 bfox@gnu.org
1181 .PP
1182 Chet Ramey, Case Western Reserve University
1183 .br
1184 chet@ins.CWRU.Edu
1185 .SH BUG REPORTS
1186 If you find a bug in
1187 .B readline,
1188 you should report it.  But first, you should
1189 make sure that it really is a bug, and that it appears in the latest
1190 version of the
1191 .B readline
1192 library that you have.
1193 .PP
1194 Once you have determined that a bug actually exists, mail a
1195 bug report to \fIbug\-readline\fP@\fIgnu.org\fP.
1196 If you have a fix, you are welcome to mail that
1197 as well!  Suggestions and `philosophical' bug reports may be mailed
1198 to \fPbug-readline\fP@\fIgnu.org\fP or posted to the Usenet
1199 newsgroup
1200 .BR gnu.bash.bug .
1201 .PP
1202 Comments and bug reports concerning
1203 this manual page should be directed to
1204 .IR chet@ins.CWRU.Edu .
1205 .SH BUGS
1206 .PP
1207 It's too big and too slow.