【Linux】man readline中译

朝饮坠露兮

已于 2023-10-29 19:00:57 修改

阅读量160

点赞数 1

文章标签：数据库

于 2023-10-29 18:52:31 首次发布

本文链接：https://blog.csdn.net/weixin_46151516/article/details/134106028

版权

NAME
readline - get a line from a user with editing

SYNOPSIS
#include
#include
#include

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 issued.    The line returned is allocated with mal‐
loc(3);   the caller must free it when finished.    The line returned has the final newline removed, 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 key‐
boards  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 default 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 universal-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 specified 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

名字
Readline -通过编辑从用户处获取一行

剧情简介
# include
# include
# include

char *
Readline (const char *prompt);

描述
Readline将从终端读取一行并返回它，使用prompt作为提示符。如果prompt为NULL或空字符串，则不发出提示。返回的行被分配为mal‐
代码行(3);调用者必须在完成后释放它。返回的行删除了最后的换行符，因此只保留该行的文本。

Readline在用户输入行时提供编辑功能。默认情况下，行编辑命令与emacs类似。还有一个vi风格的行编辑界面可用。

本手册页只介绍readline最基本的用法。更多的功能可用;参见GNU Readline库和GNU历史库获取更多信息。

返回值
Readline返回所读行的文本。空行返回空字符串。如果在读取一行时遇到EOF，并且该行为空，则返回NULL。如果读取EOF
对于非空行，它被视为换行符。

符号
emacs风格的符号用于表示击键。控制键用C键表示，例如，C-n表示Control- n。类似地，元键用M-key表示，所以M-x表示meta -x。(在关键检测
没有元键的面板，M-x表示ESC x，即按Escape键然后按x键。这使得ESC成为元前缀。组合M-C-x表示ESC-Control-x，或按Escape键
然后按住Control键同时按下x键。)

Readline命令可以被赋予数字参数，这些参数通常用作重复计数。然而，有时候，争论的标志是有意义的。传递一个否定参数
对一个向前执行的命令(例如，杀伤线)，导致该命令向向后执行。其带有参数的行为与此不同的命令如下所示。当命令被描述为终止文本时，删除的文本将被保存以备将来检索(抽取)。被杀死的文本保存在一个杀死环中。连续的击杀会导致文本
它们被累积成一个单元，可以一次全部拉动。不终止文本的命令在终止环上分隔文本块。

初始化文件
Readline是通过将命令放入初始化文件(inputrc文件)来定制的。该文件的名称取自INPUTRC环境变量的值。如果这个变量
未设置，默认为~/.inputrc。如果该文件不存在或无法读取，则最终默认为/etc/inputrc当使用readline库的程序启动时，init
读取文件，并设置键绑定和变量。在readline init文件中只允许使用几个基本结构。空行将被忽略。以#开头的行为
评论。以$开头的行表示条件结构。其他行表示键绑定和变量设置。使用此库的每个程序都可以添加自己的命令和
绑定。

例如，放置

M-Control-u: universal-argument
或
C-Meta-u: universal-argument

进入输入将使M-C-u执行readline命令通用参数。

在处理键绑定时可以识别以下符号字符名:DEL、ESC、ESCAPE、LFD、NEWLINE、RET、RETURN、RUBOUT、SPACE、SPC和TAB。

除了命令名之外，readline还允许将键绑定到按下键时插入的字符串(宏)。

键绑定
在输入文件中控制键绑定的语法很简单。所需要的只是命令的名称或宏的文本以及应该与之绑定的键序列。
该名称可以用以下两种方式之一指定:作为符号键名(可能带有Meta或Control前缀)，或者作为键序列。名称和键序列由冒号分隔。
名称和冒号之间不能有空格。

当使用keyname:function-name或macro形式时，keyname是用英文拼写的键名。例如:

Control-u: universal-argument
Meta-Rubout: backward-kill-word
control - 0:“>输出”

在上面的例子中，C-u被绑定到函数通用参数，M-DEL被绑定到函数反杀-word, C-o被绑定到运行右边表示的宏
(也就是说，将文本“> output”插入行中)。在第二种形式中，"keyseq":function-name或macro, keyseq与上面的keyname不同之处在于，表示整个键序列的字符串可以通过将序列放在double中来指定
引号。可以使用一些GNU Emacs风格的键转义，如下面的示例所示，但是不能识别符号字符名。

“\ c u”:universal-argument

"\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 specifying 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 modified with the bind builtin command.   The editing mode may be switched during interactive use by using the -o option to the
set  builtin  command.    Other programs using this library provide similar mechanisms.   The inputrc file may be edited and re-read if a program does not provide any other means to incorporate
new bindings.

Variables
Readline has variables that can be used to further customize its behavior.   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-insensitive), and "1" are equivalent to On.   All other values are equivalent to Off.   The variables and their default values are:

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 avail‐
able.   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 control 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 different color.   The color definitions are taken from the  value
of the LS_COLORS environment variable.
colored-stats (Off)
If  set  to  On, readline displays possible completions using different colors to indicate their file type.   The color definitions 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 performing case-insensitive filename matching and completion.
completion-prefix-display-length (0)
The  length  in characters of the common prefix of a list of possible 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 possible completions.

“\ c u”:universal-argument
“\ cx \ c - r”:re-read-init-file
"\e[11~] ": "功能键1"

在本例中，C-u再次绑定到函数通用参数。C-x C-r绑定到reread -init-file函数，ESC[1 1 ~]绑定到插入文本“功能键1”。

指定键序列时可用的GNU Emacs风格转义序列的完整集合是
\C-控制前缀
\M-元前缀
\e一个转义字符
\ \反斜杠
" literal "，双引号
' literal '，单引号

除了GNU Emacs风格的转义序列之外，还有第二组反斜杠转义:
警报(铃声)
\ b退格
\ d删除
f格式馈送
\ n换行符
回车符
\t horizontal TAB
\v垂直制表符
\nnn八位字符，其值为八进制值nnn(一到三位数字)
8位字符，其值为十六进制值HH(一个或两个十六进制数字)

在输入宏文本时，应使用单引号或双引号来指示宏定义。未加引号的文本被认为是函数名。在宏主体中，反斜杠
上面描述的转义是展开的。反斜杠将引用宏文本中的任何其他字符，包括" and "。

Bash允许使用bind内置命令显示或修改当前的readline键绑定。控件的-o选项可以在交互使用期间切换编辑模式
设置内置命令。使用这个库的其他程序也提供了类似的机制。输入文件可以被编辑和重新读取，如果一个程序没有提供任何其他的方法来合并
新绑定。

变量
Readline具有可用于进一步自定义其行为的变量。变量可以在输入文件中使用如下形式的语句进行设置
设置变量名值

除特别说明外，readline变量可以取值On或Off(不考虑大小写)。无法识别的变量名将被忽略。当读取变量值时，为空值或null值，
"on"(不区分大小写)和"1"相当于on。所有其他值都等同于Off。这些变量及其默认值是:

bell-style(音响)
控制readline想要敲响终端铃时发生的事情。如果设置为none，则readline永远不会响铃。如果设置为可见，则readline使用一个可见的铃声
可以。如果设置为可听，readline将尝试敲响终端的铃声。
bind-tty-special-chars(上)
如果设置为On(默认值)，readline将尝试将内核终端驱动程序专门处理的控制字符绑定到相应的readline。
blink-matching-paren(下)
如果设置为On，则在插入右括号时，readline将尝试短暂地将光标移动到左括号上。
colored-completion-prefix(下)
如果设置为On，则在列出补全时，readline将使用不同的颜色显示可能的补全集的公共前缀。颜色定义取自值
LS_COLORS环境变量。
colored-stats(下)
如果设置为On, readline将使用不同的颜色显示可能的补全，以指示它们的文件类型。颜色定义取自LS_COLORS环境的值
变量。
comment-begin(“#”)
在vi模式下执行insert-comment命令时插入的字符串。该命令在emacs模式下与M-#绑定，在vi命令模式下与#绑定。
completion-display-width (1)
执行补全时用于显示可能匹配的屏幕列数。如果该值小于0或大于终端屏幕宽度，则忽略该值。一个值
的值将导致每行显示一个匹配项。默认值为-1。
completion-ignore-case(下)
如果设置为On, readline将以不区分大小写的方式执行文件名匹配和补全。
completion-map-case(下)
如果设置为On，并且启用了completion-ignore-case，则readline在执行不区分大小写的文件名匹配和补全时将连字符(-)和下划线(_)视为等同。
completion-prefix-display-length (0)
在不修改的情况下显示的可能补全列表的公共前缀的字符长度。当设置为大于零的值时，常用前缀变长
那么在显示可能的补全时，此值将被替换为省略号。

The  length  in characters of the common prefix of a list of possible 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 possible completions.
       completion-query-items (100)
              This determines when the user is queried about viewing the number of possible completions generated by the possible-completions 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.
       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 generated from the keyboard.
       editing-mode (emacs)
              Controls whether readline begins with a set of key bindings similar 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 ex‐
              panded 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-bracketed-paste (On)
              When  set  to  On,  readline will configure the terminal in a way that will enable it 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 can prevent pasted characters from being interpreted as editing commands.
       enable-keypad (Off)
              When set to On, readline will try to enable the application keypad when it is called.  Some systems need this to enable the arrow 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  charac‐
              ters.
   expand-tilde (Off)
              If set to On, tilde expansion is performed when readline attempts 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-history 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), regardless 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.
       isearch-terminators (``C-[ C-J'')
              The  string of characters that should terminate an incremental search without subsequently executing the character as a command.  If this variable has not been given a value, the char‐
              acters ESC and C-J will terminate an incremental search.
       keymap (emacs)

在不修改的情况下显示的可能补全列表的公共前缀的字符长度。当设置为大于零的值时，常用前缀变长
那么在显示可能的补全时，此值将被替换为省略号。
completion-query-items (100)
这决定何时向用户查询查看由possible-completions命令生成的可能完成的数量。它可以设置为大于它的任何整数值
大于等于0。如果可能的补全数目大于或等于这个变量的值，readline将询问用户是否希望查看它们;
否则，它们只是在终端上列出。负值将导致readline永远不会请求。
convert-meta(上)
如果设置为On, readline将把第八位设置为ASCII密钥序列的字符转换为ASCII密钥序列，方法是去掉第八位并以转义字符作为前缀(实际上，使用
转义作为元前缀)。默认值是On，但是如果区域设置包含8位字符，readline会将其设置为Off。
disable-completion(下)
如果设置为On, readline将禁止单词补全。补全字符将被插入到行中，就像它们被映射到自插入一样。
echo-control-characters(上)
当设置为On时，在表示支持它的操作系统上，readline会回显一个与键盘产生的信号相对应的字符。
编辑模式(emacs)
控制readline是否以一组类似于Emacs或vi的键绑定开始。编辑模式可以设置为Emacs或vi。
emacs-mode-string (@)
如果启用了show-mode-in-prompt变量，那么当emacs编辑模式处于活动状态时，这个字符串将显示在主提示符的最后一行之前。该值为ex‐
与键绑定类似，因此可以使用元前缀和控制前缀以及反斜杠转义序列的标准集。使用\1和\2转义来开始和结束非-序列
打印字符，可用于在模式字符串中嵌入终端控制序列。
enable-bracketed-paste(上)
当设置为On时，readline将以一种方式配置终端，使其能够将每个粘贴作为单个字符串插入编辑缓冲区，而不是将每个粘贴作为单个字符串处理
每个字符都像是从键盘上读出来的。这可以防止粘贴的字符被解释为编辑命令。
启用小键盘(下)
当设置为On时，readline将在调用它时尝试启用应用程序键盘。有些系统需要这个来启用方向键。
enable-meta-key(上)
当设置为On时，readline将在调用时尝试启用终端声称支持的任何元修饰符键。在许多终端上，元密钥用于发送8位字符
发疯。
expand-tilde(下)
如果设置为On，则在readline尝试补全单词时执行波浪展开。
history-preserve-point(下)
如果设置为On，历史代码将尝试在使用previous-history或next-history检索的每条历史行上的相同位置放置一个点。
history-size(设置)
设置保存在历史记录列表中的历史记录的最大数目。如果设置为零，则删除所有现有的历史记录条目，并且不保存任何新条目。如果设置为小于
大于0时，历史条目的数量不受限制。缺省情况下，不限制历史表项的数量。如果尝试将history-size设置为非数字值，
历史记录条目的最大数量将设置为500。
horizontal-scroll-mode(下)
当设置为On时，使readline使用单行显示，当输入比屏幕宽度长时，在单行屏幕上水平滚动输入，而不是换行
换一条新线。高度为1的终端自动启用此设置。
input-meta(下)
如果设置为On, readline将启用8位输入(也就是说，它不会清除它读取的字符中的第8位)，而不管终端声称它可以支持什么。的
Name - meta-flag是这个变量的同义词。默认值是Off，但是如果区域设置包含8位字符，readline会将其设置为On。
isearch-terminators ('' C-[C- j ")
应该终止增量搜索而不随后将该字符作为命令执行的字符串。如果这个变量没有被赋值，char‐
ESC和C-J将终止增量搜索。
keymap (emacs)