summaryrefslogtreecommitdiffstats
path: root/doc/readline.0
diff options
context:
space:
mode:
Diffstat (limited to 'doc/readline.0')
-rw-r--r--doc/readline.01175
1 files changed, 1175 insertions, 0 deletions
diff --git a/doc/readline.0 b/doc/readline.0
new file mode 100644
index 0000000..b7c45a7
--- /dev/null
+++ b/doc/readline.0
@@ -0,0 +1,1175 @@
+READLINE(3) Library Functions Manual READLINE(3)
+
+
+
+NAME
+ readline - get a line from a user with editing
+
+SYNOPSIS
+ #include <stdio.h>
+ #include <readline/readline.h>
+ #include <readline/history.h>
+
+ char *
+ readline (const char *prompt);
+
+COPYRIGHT
+ Readline is Copyright (C) 1989-2020 Free Software Foundation, Inc.
+
+DESCRIPTION
+ readline will read a line from the terminal and return it, using prompt
+ as a prompt. If prompt is NULL or the empty string, no prompt is is-
+ sued. The line returned is allocated with malloc(3); the caller must
+ free it when finished. The line returned has the final newline re-
+ moved, so only the text of the line remains.
+
+ readline offers editing capabilities while the user is entering the
+ line. By default, the line editing commands are similar to those of
+ emacs. A vi-style line editing interface is also available.
+
+ This manual page describes only the most basic use of readline. Much
+ more functionality is available; see The GNU Readline Library and The
+ GNU History Library for additional information.
+
+RETURN VALUE
+ readline returns the text of the line read. A blank line returns the
+ empty string. If EOF is encountered while reading a line, and the line
+ is empty, NULL is returned. If an EOF is read with a non-empty line,
+ it is treated as a newline.
+
+NOTATION
+ An Emacs-style notation is used to denote keystrokes. Control keys are
+ denoted by C-key, e.g., C-n means Control-N. Similarly, meta keys are
+ denoted by M-key, so M-x means Meta-X. (On keyboards without a meta
+ key, M-x means ESC x, i.e., press the Escape key then the x key. This
+ makes ESC the meta prefix. The combination M-C-x means ESC-Control-x,
+ or press the Escape key then hold the Control key while pressing the x
+ key.)
+
+ Readline commands may be given numeric arguments, which normally act as
+ a repeat count. Sometimes, however, it is the sign of the argument
+ that is significant. Passing a negative argument to a command that
+ acts in the forward direction (e.g., kill-line) causes that command to
+ act in a backward direction. Commands whose behavior with arguments
+ deviates from this are noted below.
+
+ When a command is described as killing text, the text deleted is saved
+ for possible future retrieval (yanking). The killed text is saved in a
+ kill ring. Consecutive kills cause the text to be accumulated into one
+ unit, which can be yanked all at once. Commands which do not kill text
+ separate the chunks of text on the kill ring.
+
+INITIALIZATION FILE
+ Readline is customized by putting commands in an initialization file
+ (the inputrc file). The name of this file is taken from the value of
+ the INPUTRC environment variable. If that variable is unset, the de-
+ fault is ~/.inputrc. If that file does not exist or cannot be read,
+ the ultimate default is /etc/inputrc. When a program which uses the
+ readline library starts up, the init file is read, and the key bindings
+ and variables are set. There are only a few basic constructs allowed
+ in the readline init file. Blank lines are ignored. Lines beginning
+ with a # are comments. Lines beginning with a $ indicate conditional
+ constructs. Other lines denote key bindings and variable settings.
+ Each program using this library may add its own commands and bindings.
+
+ For example, placing
+
+ M-Control-u: universal-argument
+ or
+ C-Meta-u: universal-argument
+
+ into the inputrc would make M-C-u execute the readline command univer-
+ sal-argument.
+
+ The following symbolic character names are recognized while processing
+ key bindings: DEL, ESC, ESCAPE, LFD, NEWLINE, RET, RETURN, RUBOUT,
+ SPACE, SPC, and TAB.
+
+ In addition to command names, readline allows keys to be bound to a
+ string that is inserted when the key is pressed (a macro).
+
+ Key Bindings
+ The syntax for controlling key bindings in the inputrc file is simple.
+ All that is required is the name of the command or the text of a macro
+ and a key sequence to which it should be bound. The name may be speci-
+ fied in one of two ways: as a symbolic key name, possibly with Meta- or
+ Control- prefixes, or as a key sequence. The name and key sequence are
+ separated by a colon. There can be no whitespace between the name and
+ the colon.
+
+ When using the form keyname:function-name or macro, keyname is the name
+ of a key spelled out in English. For example:
+
+ Control-u: universal-argument
+ Meta-Rubout: backward-kill-word
+ Control-o: "> output"
+
+ In the above example, C-u is bound to the function universal-argument,
+ M-DEL is bound to the function backward-kill-word, and C-o is bound to
+ run the macro expressed on the right hand side (that is, to insert the
+ text ``> output'' into the line).
+
+ In the second form, "keyseq":function-name or macro, keyseq differs
+ from keyname above in that strings denoting an entire key sequence may
+ be specified by placing the sequence within double quotes. Some GNU
+ Emacs style key escapes can be used, as in the following example, but
+ the symbolic character names are not recognized.
+
+ "\C-u": universal-argument
+ "\C-x\C-r": re-read-init-file
+ "\e[11~": "Function Key 1"
+
+ In this example, C-u is again bound to the function universal-argument.
+ C-x C-r is bound to the function re-read-init-file, and ESC [ 1 1 ~ is
+ bound to insert the text ``Function Key 1''.
+
+ The full set of GNU Emacs style escape sequences available when speci-
+ fying key sequences is
+ \C- control prefix
+ \M- meta prefix
+ \e an escape character
+ \\ backslash
+ \" literal ", a double quote
+ \' literal ', a single quote
+
+ In addition to the GNU Emacs style escape sequences, a second set of
+ backslash escapes is available:
+ \a alert (bell)
+ \b backspace
+ \d delete
+ \f form feed
+ \n newline
+ \r carriage return
+ \t horizontal tab
+ \v vertical tab
+ \nnn the eight-bit character whose value is the octal value
+ nnn (one to three digits)
+ \xHH the eight-bit character whose value is the hexadecimal
+ value HH (one or two hex digits)
+
+ When entering the text of a macro, single or double quotes should be
+ used to indicate a macro definition. Unquoted text is assumed to be a
+ function name. In the macro body, the backslash escapes described
+ above are expanded. Backslash will quote any other character in the
+ macro text, including " and '.
+
+ Bash allows the current readline key bindings to be displayed or modi-
+ fied with the bind builtin command. The editing mode may be switched
+ during interactive use by using the -o option to the set builtin com-
+ mand. Other programs using this library provide similar mechanisms.
+ The inputrc file may be edited and re-read if a program does not pro-
+ vide any other means to incorporate new bindings.
+
+ Variables
+ Readline has variables that can be used to further customize its behav-
+ ior. A variable may be set in the inputrc file with a statement of the
+ form
+
+ set variable-name value
+
+ Except where noted, readline variables can take the values On or Off
+ (without regard to case). Unrecognized variable names are ignored.
+ When a variable value is read, empty or null values, "on" (case-insen-
+ sitive), and "1" are equivalent to On. All other values are equivalent
+ to Off. The variables and their default values are:
+
+ active-region-start-color
+ A string variable that controls the text color and background
+ when displaying the text in the active region (see the descrip-
+ tion of enable-active-region below). This string must not take
+ up any physical character positions on the display, so it should
+ consist only of terminal escape sequences. It is output to the
+ terminal before displaying the text in the active region. This
+ variable is reset to the default value whenever the terminal
+ type changes. The default value is the string that puts the
+ terminal in standout mode, as obtained from the terminal's ter-
+ minfo description. A sample value might be "\e[01;33m".
+ active-region-end-color
+ A string variable that "undoes" the effects of active-re-
+ gion-start-color and restores "normal" terminal display appear-
+ ance after displaying text in the active region. This string
+ must not take up any physical character positions on the dis-
+ play, so it should consist only of terminal escape sequences.
+ It is output to the terminal after displaying the text in the
+ active region. This variable is reset to the default value
+ whenever the terminal type changes. The default value is the
+ string that restores the terminal from standout mode, as ob-
+ tained from the terminal's terminfo description. A sample value
+ might be "\e[0m".
+ bell-style (audible)
+ Controls what happens when readline wants to ring the terminal
+ bell. If set to none, readline never rings the bell. If set to
+ visible, readline uses a visible bell if one is available. If
+ set to audible, readline attempts to ring the terminal's bell.
+ bind-tty-special-chars (On)
+ If set to On (the default), readline attempts to bind the con-
+ trol characters treated specially by the kernel's terminal
+ driver to their readline equivalents.
+ blink-matching-paren (Off)
+ If set to On, readline attempts to briefly move the cursor to an
+ opening parenthesis when a closing parenthesis is inserted.
+ colored-completion-prefix (Off)
+ If set to On, when listing completions, readline displays the
+ common prefix of the set of possible completions using a differ-
+ ent color. The color definitions are taken from the value of
+ the LS_COLORS environment variable. If there is a color defini-
+ tion in $LS_COLORS for the custom suffix "readline-colored-com-
+ pletion-prefix", readline uses this color for the common prefix
+ instead of its default.
+ colored-stats (Off)
+ If set to On, readline displays possible completions using dif-
+ ferent colors to indicate their file type. The color defini-
+ tions are taken from the value of the LS_COLORS environment
+ variable.
+ comment-begin (``#'')
+ The string that is inserted in vi mode when the insert-comment
+ command is executed. This command is bound to M-# in emacs mode
+ and to # in vi command mode.
+ completion-display-width (-1)
+ The number of screen columns used to display possible matches
+ when performing completion. The value is ignored if it is less
+ than 0 or greater than the terminal screen width. A value of 0
+ will cause matches to be displayed one per line. The default
+ value is -1.
+ completion-ignore-case (Off)
+ If set to On, readline performs filename matching and completion
+ in a case-insensitive fashion.
+ completion-map-case (Off)
+ If set to On, and completion-ignore-case is enabled, readline
+ treats hyphens (-) and underscores (_) as equivalent when per-
+ forming case-insensitive filename matching and completion.
+ completion-prefix-display-length (0)
+ The length in characters of the common prefix of a list of pos-
+ sible completions that is displayed without modification. When
+ set to a value greater than zero, common prefixes longer than
+ this value are replaced with an ellipsis when displaying possi-
+ ble completions.
+ completion-query-items (100)
+ This determines when the user is queried about viewing the num-
+ ber of possible completions generated by the possible-comple-
+ tions command. It may be set to any integer value greater than
+ or equal to zero. If the number of possible completions is
+ greater than or equal to the value of this variable, readline
+ will ask whether or not the user wishes to view them; otherwise
+ they are simply listed on the terminal. A negative value causes
+ readline to never ask.
+ convert-meta (On)
+ If set to On, readline will convert characters with the eighth
+ bit set to an ASCII key sequence by stripping the eighth bit and
+ prefixing it with an escape character (in effect, using escape
+ as the meta prefix). The default is On, but readline will set
+ it to Off if the locale contains eight-bit characters. This
+ variable is dependent on the LC_CTYPE locale category, and may
+ change if the locale is changed.
+ disable-completion (Off)
+ If set to On, readline will inhibit word completion. Completion
+ characters will be inserted into the line as if they had been
+ mapped to self-insert.
+ echo-control-characters (On)
+ When set to On, on operating systems that indicate they support
+ it, readline echoes a character corresponding to a signal gener-
+ ated from the keyboard.
+ editing-mode (emacs)
+ Controls whether readline begins with a set of key bindings sim-
+ ilar to Emacs or vi. editing-mode can be set to either emacs or
+ vi.
+ emacs-mode-string (@)
+ If the show-mode-in-prompt variable is enabled, this string is
+ displayed immediately before the last line of the primary prompt
+ when emacs editing mode is active. The value is expanded like a
+ key binding, so the standard set of meta- and control prefixes
+ and backslash escape sequences is available. Use the \1 and \2
+ escapes to begin and end sequences of non-printing characters,
+ which can be used to embed a terminal control sequence into the
+ mode string.
+ enable-active-region (On)
+ The point is the current cursor position, and mark refers to a
+ saved cursor position. The text between the point and mark is
+ referred to as the region. When this variable is set to On,
+ readline allows certain commands to designate the region as ac-
+ tive. When the region is active, readline highlights the text
+ in the region using the value of the active-region-start-color,
+ which defaults to the string that enables the terminal's stand-
+ out mode. The active region shows the text inserted by brack-
+ eted-paste and any matching text found by incremental and non-
+ incremental history searches.
+ enable-bracketed-paste (On)
+ When set to On, readline configures the terminal to insert each
+ paste into the editing buffer as a single string of characters,
+ instead of treating each character as if it had been read from
+ the keyboard. This prevents readline from executing any editing
+ commands bound to key sequences appearing in the pasted text.
+ enable-keypad (Off)
+ When set to On, readline will try to enable the application key-
+ pad when it is called. Some systems need this to enable the ar-
+ row keys.
+ enable-meta-key (On)
+ When set to On, readline will try to enable any meta modifier
+ key the terminal claims to support when it is called. On many
+ terminals, the meta key is used to send eight-bit characters.
+ expand-tilde (Off)
+ If set to On, tilde expansion is performed when readline at-
+ tempts word completion.
+ history-preserve-point (Off)
+ If set to On, the history code attempts to place point at the
+ same location on each history line retrieved with previous-his-
+ tory or next-history.
+ history-size (unset)
+ Set the maximum number of history entries saved in the history
+ list. If set to zero, any existing history entries are deleted
+ and no new entries are saved. If set to a value less than zero,
+ the number of history entries is not limited. By default, the
+ number of history entries is not limited. If an attempt is made
+ to set history-size to a non-numeric value, the maximum number
+ of history entries will be set to 500.
+ horizontal-scroll-mode (Off)
+ When set to On, makes readline use a single line for display,
+ scrolling the input horizontally on a single screen line when it
+ becomes longer than the screen width rather than wrapping to a
+ new line. This setting is automatically enabled for terminals
+ of height 1.
+ input-meta (Off)
+ If set to On, readline will enable eight-bit input (that is, it
+ will not clear the eighth bit in the characters it reads), re-
+ gardless of what the terminal claims it can support. The name
+ meta-flag is a synonym for this variable. The default is Off,
+ but readline will set it to On if the locale contains eight-bit
+ characters. This variable is dependent on the LC_CTYPE locale
+ category, and may change if the locale is changed.
+ isearch-terminators (``C-[ C-J'')
+ The string of characters that should terminate an incremental
+ search without subsequently executing the character as a com-
+ mand. If this variable has not been given a value, the charac-
+ ters ESC and C-J will terminate an incremental search.
+ keymap (emacs)
+ Set the current readline keymap. The set of legal keymap names
+ is emacs, emacs-standard, emacs-meta, emacs-ctlx, vi, vi-move,
+ vi-command, and vi-insert. vi is equivalent to vi-command;
+ emacs is equivalent to emacs-standard. The default value is
+ emacs. The value of editing-mode also affects the default
+ keymap.
+ keyseq-timeout (500)
+ Specifies the duration readline will wait for a character when
+ reading an ambiguous key sequence (one that can form a complete
+ key sequence using the input read so far, or can take additional
+ input to complete a longer key sequence). If no input is re-
+ ceived within the timeout, readline will use the shorter but
+ complete key sequence. The value is specified in milliseconds,
+ so a value of 1000 means that readline will wait one second for
+ additional input. If this variable is set to a value less than
+ or equal to zero, or to a non-numeric value, readline will wait
+ until another key is pressed to decide which key sequence to
+ complete.
+ mark-directories (On)
+ If set to On, completed directory names have a slash appended.
+ mark-modified-lines (Off)
+ If set to On, history lines that have been modified are dis-
+ played with a preceding asterisk (*).
+ mark-symlinked-directories (Off)
+ If set to On, completed names which are symbolic links to direc-
+ tories have a slash appended (subject to the value of mark-di-
+ rectories).
+ match-hidden-files (On)
+ This variable, when set to On, causes readline to match files
+ whose names begin with a `.' (hidden files) when performing
+ filename completion. If set to Off, the leading `.' must be
+ supplied by the user in the filename to be completed.
+ menu-complete-display-prefix (Off)
+ If set to On, menu completion displays the common prefix of the
+ list of possible completions (which may be empty) before cycling
+ through the list.
+ output-meta (Off)
+ If set to On, readline will display characters with the eighth
+ bit set directly rather than as a meta-prefixed escape sequence.
+ The default is Off, but readline will set it to On if the locale
+ contains eight-bit characters. This variable is dependent on
+ the LC_CTYPE locale category, and may change if the locale is
+ changed.
+ page-completions (On)
+ If set to On, readline uses an internal more-like pager to dis-
+ play a screenful of possible completions at a time.
+ print-completions-horizontally (Off)
+ If set to On, readline will display completions with matches
+ sorted horizontally in alphabetical order, rather than down the
+ screen.
+ revert-all-at-newline (Off)
+ If set to On, readline will undo all changes to history lines
+ before returning when accept-line is executed. By default, his-
+ tory lines may be modified and retain individual undo lists
+ across calls to readline.
+ show-all-if-ambiguous (Off)
+ This alters the default behavior of the completion functions.
+ If set to On, words which have more than one possible completion
+ cause the matches to be listed immediately instead of ringing
+ the bell.
+ show-all-if-unmodified (Off)
+ This alters the default behavior of the completion functions in
+ a fashion similar to show-all-if-ambiguous. If set to On, words
+ which have more than one possible completion without any possi-
+ ble partial completion (the possible completions don't share a
+ common prefix) cause the matches to be listed immediately in-
+ stead of ringing the bell.
+ show-mode-in-prompt (Off)
+ If set to On, add a string to the beginning of the prompt indi-
+ cating the editing mode: emacs, vi command, or vi insertion.
+ The mode strings are user-settable (e.g., emacs-mode-string).
+ skip-completed-text (Off)
+ If set to On, this alters the default completion behavior when
+ inserting a single match into the line. It's only active when
+ performing completion in the middle of a word. If enabled,
+ readline does not insert characters from the completion that
+ match characters after point in the word being completed, so
+ portions of the word following the cursor are not duplicated.
+ vi-cmd-mode-string ((cmd))
+ If the show-mode-in-prompt variable is enabled, this string is
+ displayed immediately before the last line of the primary prompt
+ when vi editing mode is active and in command mode. The value
+ is expanded like a key binding, so the standard set of meta- and
+ control prefixes and backslash escape sequences is available.
+ Use the \1 and \2 escapes to begin and end sequences of non-
+ printing characters, which can be used to embed a terminal con-
+ trol sequence into the mode string.
+ vi-ins-mode-string ((ins))
+ If the show-mode-in-prompt variable is enabled, this string is
+ displayed immediately before the last line of the primary prompt
+ when vi editing mode is active and in insertion mode. The value
+ is expanded like a key binding, so the standard set of meta- and
+ control prefixes and backslash escape sequences is available.
+ Use the \1 and \2 escapes to begin and end sequences of non-
+ printing characters, which can be used to embed a terminal con-
+ trol sequence into the mode string.
+ visible-stats (Off)
+ If set to On, a character denoting a file's type as reported by
+ stat(2) is appended to the filename when listing possible com-
+ pletions.
+
+ Conditional Constructs
+ Readline implements a facility similar in spirit to the conditional
+ compilation features of the C preprocessor which allows key bindings
+ and variable settings to be performed as the result of tests. There
+ are four parser directives used.
+
+ $if The $if construct allows bindings to be made based on the edit-
+ ing mode, the terminal being used, or the application using
+ readline. The text of the test, after any comparison operator,
+ extends to the end of the line; unless otherwise noted, no char-
+ acters are required to isolate it.
+
+ mode The mode= form of the $if directive is used to test
+ whether readline is in emacs or vi mode. This may be
+ used in conjunction with the set keymap command, for in-
+ stance, to set bindings in the emacs-standard and emacs-
+ ctlx keymaps only if readline is starting out in emacs
+ mode.
+
+ term The term= form may be used to include terminal-specific
+ key bindings, perhaps to bind the key sequences output by
+ the terminal's function keys. The word on the right side
+ of the = is tested against the full name of the terminal
+ and the portion of the terminal name before the first -.
+ This allows sun to match both sun and sun-cmd, for in-
+ stance.
+
+ version
+ The version test may be used to perform comparisons
+ against specific readline versions. The version expands
+ to the current readline version. The set of comparison
+ operators includes =, (and ==), !=, <=, >=, <, and >.
+ The version number supplied on the right side of the op-
+ erator consists of a major version number, an optional
+ decimal point, and an optional minor version (e.g., 7.1).
+ If the minor version is omitted, it is assumed to be 0.
+ The operator may be separated from the string version and
+ from the version number argument by whitespace.
+
+ application
+ The application construct is used to include application-
+ specific settings. Each program using the readline li-
+ brary sets the application name, and an initialization
+ file can test for a particular value. This could be used
+ to bind key sequences to functions useful for a specific
+ program. For instance, the following command adds a key
+ sequence that quotes the current or previous word in
+ bash:
+
+ $if Bash
+ # Quote the current or previous word
+ "\C-xq": "\eb\"\ef\""
+ $endif
+
+ variable
+ The variable construct provides simple equality tests for
+ readline variables and values. The permitted comparison
+ operators are =, ==, and !=. The variable name must be
+ separated from the comparison operator by whitespace; the
+ operator may be separated from the value on the right
+ hand side by whitespace. Both string and boolean vari-
+ ables may be tested. Boolean variables must be tested
+ against the values on and off.
+
+ $endif This command, as seen in the previous example, terminates an $if
+ command.
+
+ $else Commands in this branch of the $if directive are executed if the
+ test fails.
+
+ $include
+ This directive takes a single filename as an argument and reads
+ commands and bindings from that file. For example, the follow-
+ ing directive would read /etc/inputrc:
+
+ $include /etc/inputrc
+
+SEARCHING
+ Readline provides commands for searching through the command history
+ for lines containing a specified string. There are two search modes:
+ incremental and non-incremental.
+
+ Incremental searches begin before the user has finished typing the
+ search string. As each character of the search string is typed, read-
+ line displays the next entry from the history matching the string typed
+ so far. An incremental search requires only as many characters as
+ needed to find the desired history entry. To search backward in the
+ history for a particular string, type C-r. Typing C-s searches forward
+ through the history. The characters present in the value of the
+ isearch-terminators variable are used to terminate an incremental
+ search. If that variable has not been assigned a value the Escape and
+ C-J characters will terminate an incremental search. C-G will abort an
+ incremental search and restore the original line. When the search is
+ terminated, the history entry containing the search string becomes the
+ current line.
+
+ To find other matching entries in the history list, type C-s or C-r as
+ appropriate. This will search backward or forward in the history for
+ the next line matching the search string typed so far. Any other key
+ sequence bound to a readline command will terminate the search and exe-
+ cute that command. For instance, a newline will terminate the search
+ and accept the line, thereby executing the command from the history
+ list. A movement command will terminate the search, make the last line
+ found the current line, and begin editing.
+
+ Non-incremental searches read the entire search string before starting
+ to search for matching history lines. The search string may be typed
+ by the user or be part of the contents of the current line.
+
+EDITING COMMANDS
+ The following is a list of the names of the commands and the default
+ key sequences to which they are bound. Command names without an accom-
+ panying key sequence are unbound by default.
+
+ In the following descriptions, point refers to the current cursor posi-
+ tion, and mark refers to a cursor position saved by the set-mark com-
+ mand. The text between the point and mark is referred to as the re-
+ gion.
+
+ Commands for Moving
+ beginning-of-line (C-a)
+ Move to the start of the current line.
+ end-of-line (C-e)
+ Move to the end of the line.
+ forward-char (C-f)
+ Move forward a character.
+ backward-char (C-b)
+ Move back a character.
+ forward-word (M-f)
+ Move forward to the end of the next word. Words are composed of
+ alphanumeric characters (letters and digits).
+ backward-word (M-b)
+ Move back to the start of the current or previous word. Words
+ are composed of alphanumeric characters (letters and digits).
+ previous-screen-line
+ Attempt to move point to the same physical screen column on the
+ previous physical screen line. This will not have the desired
+ effect if the current readline line does not take up more than
+ one physical line or if point is not greater than the length of
+ the prompt plus the screen width.
+ next-screen-line
+ Attempt to move point to the same physical screen column on the
+ next physical screen line. This will not have the desired effect
+ if the current readline line does not take up more than one
+ physical line or if the length of the current readline line is
+ not greater than the length of the prompt plus the screen width.
+ clear-display (M-C-l)
+ Clear the screen and, if possible, the terminal's scrollback
+ buffer, then redraw the current line, leaving the current line
+ at the top of the screen.
+ clear-screen (C-l)
+ Clear the screen, then redraw the current line, leaving the cur-
+ rent line at the top of the screen. With an argument, refresh
+ the current line without clearing the screen.
+ redraw-current-line
+ Refresh the current line.
+
+ Commands for Manipulating the History
+ accept-line (Newline, Return)
+ Accept the line regardless of where the cursor is. If this line
+ is non-empty, it may be added to the history list for future re-
+ call with add_history(). If the line is a modified history
+ line, the history line is restored to its original state.
+ previous-history (C-p)
+ Fetch the previous command from the history list, moving back in
+ the list.
+ next-history (C-n)
+ Fetch the next command from the history list, moving forward in
+ the list.
+ beginning-of-history (M-<)
+ Move to the first line in the history.
+ end-of-history (M->)
+ Move to the end of the input history, i.e., the line currently
+ being entered.
+ operate-and-get-next (C-o)
+ Accept the current line for return to the calling application as
+ if a newline had been entered, and fetch the next line relative
+ to the current line from the history for editing. A numeric ar-
+ gument, if supplied, specifies the history entry to use instead
+ of the current line.
+ fetch-history
+ With a numeric argument, fetch that entry from the history list
+ and make it the current line. Without an argument, move back to
+ the first entry in the history list.
+ reverse-search-history (C-r)
+ Search backward starting at the current line and moving `up'
+ through the history as necessary. This is an incremental
+ search.
+ forward-search-history (C-s)
+ Search forward starting at the current line and moving `down'
+ through the history as necessary. This is an incremental
+ search.
+ non-incremental-reverse-search-history (M-p)
+ Search backward through the history starting at the current line
+ using a non-incremental search for a string supplied by the
+ user.
+ non-incremental-forward-search-history (M-n)
+ Search forward through the history using a non-incremental
+ search for a string supplied by the user.
+ history-search-backward
+ Search backward through the history for the string of characters
+ between the start of the current line and the current cursor po-
+ sition (the point). The search string must match at the begin-
+ ning of a history line. This is a non-incremental search.
+ history-search-forward
+ Search forward through the history for the string of characters
+ between the start of the current line and the point. The search
+ string must match at the beginning of a history line. This is a
+ non-incremental search.
+ history-substring-search-backward
+ Search backward through the history for the string of characters
+ between the start of the current line and the current cursor po-
+ sition (the point). The search string may match anywhere in a
+ history line. This is a non-incremental search.
+ history-substring-search-forward
+ Search forward through the history for the string of characters
+ between the start of the current line and the point. The search
+ string may match anywhere in a history line. This is a non-in-
+ cremental search.
+ yank-nth-arg (M-C-y)
+ Insert the first argument to the previous command (usually the
+ second word on the previous line) at point. With an argument n,
+ insert the nth word from the previous command (the words in the
+ previous command begin with word 0). A negative argument in-
+ serts the nth word from the end of the previous command. Once
+ the argument n is computed, the argument is extracted as if the
+ "!n" history expansion had been specified.
+ yank-last-arg (M-., M-_)
+ Insert the last argument to the previous command (the last word
+ of the previous history entry). With a numeric argument, behave
+ exactly like yank-nth-arg. Successive calls to yank-last-arg
+ move back through the history list, inserting the last word (or
+ the word specified by the argument to the first call) of each
+ line in turn. Any numeric argument supplied to these successive
+ calls determines the direction to move through the history. A
+ negative argument switches the direction through the history
+ (back or forward). The history expansion facilities are used to
+ extract the last argument, as if the "!$" history expansion had
+ been specified.
+
+ Commands for Changing Text
+ end-of-file (usually C-d)
+ The character indicating end-of-file as set, for example, by
+ ``stty''. If this character is read when there are no charac-
+ ters on the line, and point is at the beginning of the line,
+ readline interprets it as the end of input and returns EOF.
+ delete-char (C-d)
+ Delete the character at point. If this function is bound to the
+ same character as the tty EOF character, as C-d commonly is, see
+ above for the effects.
+ backward-delete-char (Rubout)
+ Delete the character behind the cursor. When given a numeric
+ argument, save the deleted text on the kill ring.
+ forward-backward-delete-char
+ Delete the character under the cursor, unless the cursor is at
+ the end of the line, in which case the character behind the cur-
+ sor is deleted.
+ quoted-insert (C-q, C-v)
+ Add the next character that you type to the line verbatim. This
+ is how to insert characters like C-q, for example.
+ tab-insert (M-TAB)
+ Insert a tab character.
+ self-insert (a, b, A, 1, !, ...)
+ Insert the character typed.
+ transpose-chars (C-t)
+ Drag the character before point forward over the character at
+ point, moving point forward as well. If point is at the end of
+ the line, then this transposes the two characters before point.
+ Negative arguments have no effect.
+ transpose-words (M-t)
+ Drag the word before point past the word after point, moving
+ point over that word as well. If point is at the end of the
+ line, this transposes the last two words on the line.
+ upcase-word (M-u)
+ Uppercase the current (or following) word. With a negative ar-
+ gument, uppercase the previous word, but do not move point.
+ downcase-word (M-l)
+ Lowercase the current (or following) word. With a negative ar-
+ gument, lowercase the previous word, but do not move point.
+ capitalize-word (M-c)
+ Capitalize the current (or following) word. With a negative ar-
+ gument, capitalize the previous word, but do not move point.
+ overwrite-mode
+ Toggle overwrite mode. With an explicit positive numeric argu-
+ ment, switches to overwrite mode. With an explicit non-positive
+ numeric argument, switches to insert mode. This command affects
+ only emacs mode; vi mode does overwrite differently. Each call
+ to readline() starts in insert mode. In overwrite mode, charac-
+ ters bound to self-insert replace the text at point rather than
+ pushing the text to the right. Characters bound to back-
+ ward-delete-char replace the character before point with a
+ space. By default, this command is unbound.
+
+ Killing and Yanking
+ kill-line (C-k)
+ Kill the text from point to the end of the line.
+ backward-kill-line (C-x Rubout)
+ Kill backward to the beginning of the line.
+ unix-line-discard (C-u)
+ Kill backward from point to the beginning of the line. The
+ killed text is saved on the kill-ring.
+ kill-whole-line
+ Kill all characters on the current line, no matter where point
+ is.
+ kill-word (M-d)
+ Kill from point the end of the current word, or if between
+ words, to the end of the next word. Word boundaries are the
+ same as those used by forward-word.
+ backward-kill-word (M-Rubout)
+ Kill the word behind point. Word boundaries are the same as
+ those used by backward-word.
+ unix-word-rubout (C-w)
+ Kill the word behind point, using white space as a word bound-
+ ary. The killed text is saved on the kill-ring.
+ unix-filename-rubout
+ Kill the word behind point, using white space and the slash
+ character as the word boundaries. The killed text is saved on
+ the kill-ring.
+ delete-horizontal-space (M-\)
+ Delete all spaces and tabs around point.
+ kill-region
+ Kill the text between the point and mark (saved cursor posi-
+ tion). This text is referred to as the region.
+ copy-region-as-kill
+ Copy the text in the region to the kill buffer.
+ copy-backward-word
+ Copy the word before point to the kill buffer. The word bound-
+ aries are the same as backward-word.
+ copy-forward-word
+ Copy the word following point to the kill buffer. The word
+ boundaries are the same as forward-word.
+ yank (C-y)
+ Yank the top of the kill ring into the buffer at point.
+ yank-pop (M-y)
+ Rotate the kill ring, and yank the new top. Only works follow-
+ ing yank or yank-pop.
+
+ Numeric Arguments
+ digit-argument (M-0, M-1, ..., M--)
+ Add this digit to the argument already accumulating, or start a
+ new argument. M-- starts a negative argument.
+ universal-argument
+ This is another way to specify an argument. If this command is
+ followed by one or more digits, optionally with a leading minus
+ sign, those digits define the argument. If the command is fol-
+ lowed by digits, executing universal-argument again ends the nu-
+ meric argument, but is otherwise ignored. As a special case, if
+ this command is immediately followed by a character that is nei-
+ ther a digit or minus sign, the argument count for the next com-
+ mand is multiplied by four. The argument count is initially
+ one, so executing this function the first time makes the argu-
+ ment count four, a second time makes the argument count sixteen,
+ and so on.
+
+ Completing
+ complete (TAB)
+ Attempt to perform completion on the text before point. The ac-
+ tual completion performed is application-specific. Bash, for
+ instance, attempts completion treating the text as a variable
+ (if the text begins with $), username (if the text begins with
+ ~), hostname (if the text begins with @), or command (including
+ aliases and functions) in turn. If none of these produces a
+ match, filename completion is attempted. Gdb, on the other
+ hand, allows completion of program functions and variables, and
+ only attempts filename completion under certain circumstances.
+ possible-completions (M-?)
+ List the possible completions of the text before point. When
+ displaying completions, readline sets the number of columns used
+ for display to the value of completion-display-width, the value
+ of the environment variable COLUMNS, or the screen width, in
+ that order.
+ insert-completions (M-*)
+ Insert all completions of the text before point that would have
+ been generated by possible-completions.
+ menu-complete
+ Similar to complete, but replaces the word to be completed with
+ a single match from the list of possible completions. Repeated
+ execution of menu-complete steps through the list of possible
+ completions, inserting each match in turn. At the end of the
+ list of completions, the bell is rung (subject to the setting of
+ bell-style) and the original text is restored. An argument of n
+ moves n positions forward in the list of matches; a negative ar-
+ gument may be used to move backward through the list. This com-
+ mand is intended to be bound to TAB, but is unbound by default.
+ menu-complete-backward
+ Identical to menu-complete, but moves backward through the list
+ of possible completions, as if menu-complete had been given a
+ negative argument. This command is unbound by default.
+ delete-char-or-list
+ Deletes the character under the cursor if not at the beginning
+ or end of the line (like delete-char). If at the end of the
+ line, behaves identically to possible-completions.
+
+ Keyboard Macros
+ start-kbd-macro (C-x ()
+ Begin saving the characters typed into the current keyboard
+ macro.
+ end-kbd-macro (C-x ))
+ Stop saving the characters typed into the current keyboard macro
+ and store the definition.
+ call-last-kbd-macro (C-x e)
+ Re-execute the last keyboard macro defined, by making the char-
+ acters in the macro appear as if typed at the keyboard.
+ print-last-kbd-macro ()
+ Print the last keyboard macro defined in a format suitable for
+ the inputrc file.
+
+ Miscellaneous
+ re-read-init-file (C-x C-r)
+ Read in the contents of the inputrc file, and incorporate any
+ bindings or variable assignments found there.
+ abort (C-g)
+ Abort the current editing command and ring the terminal's bell
+ (subject to the setting of bell-style).
+ do-lowercase-version (M-A, M-B, M-x, ...)
+ If the metafied character x is uppercase, run the command that
+ is bound to the corresponding metafied lowercase character. The
+ behavior is undefined if x is already lowercase.
+ prefix-meta (ESC)
+ Metafy the next character typed. ESC f is equivalent to Meta-f.
+ undo (C-_, C-x C-u)
+ Incremental undo, separately remembered for each line.
+ revert-line (M-r)
+ Undo all changes made to this line. This is like executing the
+ undo command enough times to return the line to its initial
+ state.
+ tilde-expand (M-&)
+ Perform tilde expansion on the current word.
+ set-mark (C-@, M-<space>)
+ Set the mark to the point. If a numeric argument is supplied,
+ the mark is set to that position.
+ exchange-point-and-mark (C-x C-x)
+ Swap the point with the mark. The current cursor position is
+ set to the saved position, and the old cursor position is saved
+ as the mark.
+ character-search (C-])
+ A character is read and point is moved to the next occurrence of
+ that character. A negative argument searches for previous oc-
+ currences.
+ character-search-backward (M-C-])
+ A character is read and point is moved to the previous occur-
+ rence of that character. A negative argument searches for sub-
+ sequent occurrences.
+ skip-csi-sequence
+ Read enough characters to consume a multi-key sequence such as
+ those defined for keys like Home and End. Such sequences begin
+ with a Control Sequence Indicator (CSI), usually ESC-[. If this
+ sequence is bound to "\[", keys producing such sequences will
+ have no effect unless explicitly bound to a readline command,
+ instead of inserting stray characters into the editing buffer.
+ This is unbound by default, but usually bound to ESC-[.
+ insert-comment (M-#)
+ Without a numeric argument, the value of the readline com-
+ ment-begin variable is inserted at the beginning of the current
+ line. If a numeric argument is supplied, this command acts as a
+ toggle: if the characters at the beginning of the line do not
+ match the value of comment-begin, the value is inserted, other-
+ wise the characters in comment-begin are deleted from the begin-
+ ning of the line. In either case, the line is accepted as if a
+ newline had been typed. The default value of comment-begin
+ makes the current line a shell comment. If a numeric argument
+ causes the comment character to be removed, the line will be ex-
+ ecuted by the shell.
+ dump-functions
+ Print all of the functions and their key bindings to the read-
+ line output stream. If a numeric argument is supplied, the out-
+ put is formatted in such a way that it can be made part of an
+ inputrc file.
+ dump-variables
+ Print all of the settable variables and their values to the
+ readline output stream. If a numeric argument is supplied, the
+ output is formatted in such a way that it can be made part of an
+ inputrc file.
+ dump-macros
+ Print all of the readline key sequences bound to macros and the
+ strings they output. If a numeric argument is supplied, the
+ output is formatted in such a way that it can be made part of an
+ inputrc file.
+ emacs-editing-mode (C-e)
+ When in vi command mode, this causes a switch to emacs editing
+ mode.
+ vi-editing-mode (M-C-j)
+ When in emacs editing mode, this causes a switch to vi editing
+ mode.
+
+DEFAULT KEY BINDINGS
+ The following is a list of the default emacs and vi bindings. Charac-
+ ters with the eighth bit set are written as M-<character>, and are re-
+ ferred to as metafied characters. The printable ASCII characters not
+ mentioned in the list of emacs standard bindings are bound to the
+ self-insert function, which just inserts the given character into the
+ input line. In vi insertion mode, all characters not specifically men-
+ tioned are bound to self-insert. Characters assigned to signal genera-
+ tion by stty(1) or the terminal driver, such as C-Z or C-C, retain that
+ function. Upper and lower case metafied characters are bound to the
+ same function in the emacs mode meta keymap. The remaining characters
+ are unbound, which causes readline to ring the bell (subject to the
+ setting of the bell-style variable).
+
+ Emacs Mode
+ Emacs Standard bindings
+
+ "C-@" set-mark
+ "C-A" beginning-of-line
+ "C-B" backward-char
+ "C-D" delete-char
+ "C-E" end-of-line
+ "C-F" forward-char
+ "C-G" abort
+ "C-H" backward-delete-char
+ "C-I" complete
+ "C-J" accept-line
+ "C-K" kill-line
+ "C-L" clear-screen
+ "C-M" accept-line
+ "C-N" next-history
+ "C-P" previous-history
+ "C-Q" quoted-insert
+ "C-R" reverse-search-history
+ "C-S" forward-search-history
+ "C-T" transpose-chars
+ "C-U" unix-line-discard
+ "C-V" quoted-insert
+ "C-W" unix-word-rubout
+ "C-Y" yank
+ "C-]" character-search
+ "C-_" undo
+ " " to "/" self-insert
+ "0" to "9" self-insert
+ ":" to "~" self-insert
+ "C-?" backward-delete-char
+
+ Emacs Meta bindings
+
+ "M-C-G" abort
+ "M-C-H" backward-kill-word
+ "M-C-I" tab-insert
+ "M-C-J" vi-editing-mode
+ "M-C-L" clear-display
+ "M-C-M" vi-editing-mode
+ "M-C-R" revert-line
+ "M-C-Y" yank-nth-arg
+ "M-C-[" complete
+ "M-C-]" character-search-backward
+ "M-space" set-mark
+ "M-#" insert-comment
+ "M-&" tilde-expand
+ "M-*" insert-completions
+ "M--" digit-argument
+ "M-." yank-last-arg
+ "M-0" digit-argument
+ "M-1" digit-argument
+ "M-2" digit-argument
+ "M-3" digit-argument
+ "M-4" digit-argument
+ "M-5" digit-argument
+ "M-6" digit-argument
+ "M-7" digit-argument
+ "M-8" digit-argument
+ "M-9" digit-argument
+ "M-<" beginning-of-history
+ "M-=" possible-completions
+ "M->" end-of-history
+ "M-?" possible-completions
+ "M-B" backward-word
+ "M-C" capitalize-word
+ "M-D" kill-word
+ "M-F" forward-word
+ "M-L" downcase-word
+ "M-N" non-incremental-forward-search-history
+ "M-P" non-incremental-reverse-search-history
+ "M-R" revert-line
+ "M-T" transpose-words
+ "M-U" upcase-word
+ "M-Y" yank-pop
+ "M-\" delete-horizontal-space
+ "M-~" tilde-expand
+ "M-C-?" backward-kill-word
+ "M-_" yank-last-arg
+
+ Emacs Control-X bindings
+
+ "C-XC-G" abort
+ "C-XC-R" re-read-init-file
+ "C-XC-U" undo
+ "C-XC-X" exchange-point-and-mark
+ "C-X(" start-kbd-macro
+ "C-X)" end-kbd-macro
+ "C-XE" call-last-kbd-macro
+ "C-XC-?" backward-kill-line
+
+
+ VI Mode bindings
+ VI Insert Mode functions
+
+ "C-D" vi-eof-maybe
+ "C-H" backward-delete-char
+ "C-I" complete
+ "C-J" accept-line
+ "C-M" accept-line
+ "C-R" reverse-search-history
+ "C-S" forward-search-history
+ "C-T" transpose-chars
+ "C-U" unix-line-discard
+ "C-V" quoted-insert
+ "C-W" unix-word-rubout
+ "C-Y" yank
+ "C-[" vi-movement-mode
+ "C-_" undo
+ " " to "~" self-insert
+ "C-?" backward-delete-char
+
+ VI Command Mode functions
+
+ "C-D" vi-eof-maybe
+ "C-E" emacs-editing-mode
+ "C-G" abort
+ "C-H" backward-char
+ "C-J" accept-line
+ "C-K" kill-line
+ "C-L" clear-screen
+ "C-M" accept-line
+ "C-N" next-history
+ "C-P" previous-history
+ "C-Q" quoted-insert
+ "C-R" reverse-search-history
+ "C-S" forward-search-history
+ "C-T" transpose-chars
+ "C-U" unix-line-discard
+ "C-V" quoted-insert
+ "C-W" unix-word-rubout
+ "C-Y" yank
+ "C-_" vi-undo
+ " " forward-char
+ "#" insert-comment
+ "$" end-of-line
+ "%" vi-match
+ "&" vi-tilde-expand
+ "*" vi-complete
+ "+" next-history
+ "," vi-char-search
+ "-" previous-history
+ "." vi-redo
+ "/" vi-search
+ "0" beginning-of-line
+ "1" to "9" vi-arg-digit
+ ";" vi-char-search
+ "=" vi-complete
+ "?" vi-search
+ "A" vi-append-eol
+ "B" vi-prev-word
+ "C" vi-change-to
+ "D" vi-delete-to
+ "E" vi-end-word
+ "F" vi-char-search
+ "G" vi-fetch-history
+ "I" vi-insert-beg
+ "N" vi-search-again
+ "P" vi-put
+ "R" vi-replace
+ "S" vi-subst
+ "T" vi-char-search
+ "U" revert-line
+ "W" vi-next-word
+ "X" backward-delete-char
+ "Y" vi-yank-to
+ "\" vi-complete
+ "^" vi-first-print
+ "_" vi-yank-arg
+ "`" vi-goto-mark
+ "a" vi-append-mode
+ "b" vi-prev-word
+ "c" vi-change-to
+ "d" vi-delete-to
+ "e" vi-end-word
+ "f" vi-char-search
+ "h" backward-char
+ "i" vi-insertion-mode
+ "j" next-history
+ "k" prev-history
+ "l" forward-char
+ "m" vi-set-mark
+ "n" vi-search-again
+ "p" vi-put
+ "r" vi-change-char
+ "s" vi-subst
+ "t" vi-char-search
+ "u" vi-undo
+ "w" vi-next-word
+ "x" vi-delete
+ "y" vi-yank-to
+ "|" vi-column
+ "~" vi-change-case
+
+SEE ALSO
+ The Gnu Readline Library, Brian Fox and Chet Ramey
+ The Gnu History Library, Brian Fox and Chet Ramey
+ bash(1)
+
+FILES
+ ~/.inputrc
+ Individual readline initialization file
+
+AUTHORS
+ Brian Fox, Free Software Foundation
+ bfox@gnu.org
+
+ Chet Ramey, Case Western Reserve University
+ chet.ramey@case.edu
+
+BUG REPORTS
+ If you find a bug in readline, you should report it. But first, you
+ should make sure that it really is a bug, and that it appears in the
+ latest version of the readline library that you have.
+
+ Once you have determined that a bug actually exists, mail a bug report
+ to bug-readline@gnu.org. If you have a fix, you are welcome to mail
+ that as well! Suggestions and `philosophical' bug reports may be
+ mailed to bug-readline@gnu.org or posted to the Usenet newsgroup
+ gnu.bash.bug.
+
+ Comments and bug reports concerning this manual page should be directed
+ to chet.ramey@case.edu.
+
+BUGS
+ It's too big and too slow.
+
+
+
+GNU Readline 8.2 2022 September 19 READLINE(3)
generated by cgit v1.2.3 (git 2.39.1) at 2024-05-15 20:12:45 +0000