.\".\" MAN PAGE COMMENTS to.\".\"	Chet Ramey.\"	Information Network Services.\"	Case Western Reserve University.\"	chet@ins.CWRU.Edu.\".\"	Last Change: Wed Jan 28 15:43:53 EST 2004.\".TH READLINE 3 "2004 January 28" "GNU Readline 5.0".\".\" File Name macro.  This used to be `.PN', for Path Name,.\" but Sun doesn't seem to like that very much..\".de FN\fI\|\\$1\|\fP...SH NAMEreadline \- get a line from a user with editing.SH SYNOPSIS.LP.nf.ft B#include <stdio.h>#include <readline/readline.h>#include <readline/history.h>.ft.fi.LP.nf\fIchar *\fP.br\fBreadline\fP (\fIconst char *prompt\fP);.fi.SH COPYRIGHT.if n Readline is Copyright (C) 1989\-2004 by the Free Software Foundation, Inc..if t Readline is Copyright \(co 1989\-2004 by the Free Software Foundation, Inc..SH DESCRIPTION.LP.B readlinewill read a line from the terminaland return it, using.B promptas a prompt.  If .B promptis \fBNULL\fP or the empty string, no prompt is issued.The line returned is allocated with.IR malloc (3);the caller must free it when finished.  The line returnedhas the final newline removed, so only the text of the lineremains..LP.B readlineoffers editing capabilities while the user is entering theline.By default, the line editing commandsare similar to those of emacs.A vi\-style line editing interface is also available..LPThis manual page describes only the most basic use of \fBreadline\fP.Much more functionality is available; see\fIThe GNU Readline Library\fP and \fIThe GNU History Library\fPfor additional information..SH RETURN VALUE.LP.B readlinereturns the text of the line read.  A blank linereturns the empty string.  If.B EOFis encountered while reading a line, and the line is empty,.B NULLis returned.  If an.B EOFis read with a non\-empty line, it istreated as a newline..SH NOTATION.LPAn emacs-style notation is used to denotekeystrokes.  Control keys are denoted by C\-\fIkey\fR, e.g., C\-nmeans Control\-N.  Similarly, .I metakeys are denoted by M\-\fIkey\fR, so M\-x means Meta\-X.  (On keyboardswithout a .I metakey, M\-\fIx\fP means ESC \fIx\fP, i.e., press the Escape keythen the.I xkey.  This makes ESC the \fImeta prefix\fP.The combination M\-C\-\fIx\fP means ESC\-Control\-\fIx\fP,or press the Escape keythen hold the Control key while pressing the.I xkey.).PPReadline commands may be given numeric.IR arguments ,which normally act as a repeat count.  Sometimes, however, it is thesign of the argument that is significant.  Passing a negative argumentto a command that acts in the forward direction (e.g., \fBkill\-line\fP)causes that command to act in a backward direction.  Commands whosebehavior with arguments deviates from this are noted..PPWhen a command is described as \fIkilling\fP text, the textdeleted is saved for possible future retrieval(\fIyanking\fP).  The killed text is saved in a\fIkill ring\fP.  Consecutive kills cause the text to beaccumulated into one unit, which can be yanked all at once. Commands which do not kill text separate the chunks of texton the kill ring..SH INITIALIZATION FILE.LPReadline is customized by putting commands in an initializationfile (the \fIinputrc\fP file).The name of this file is taken from the value of the.B INPUTRCenvironment variable.  If that variable is unset, the default is.IR ~/.inputrc .When a program which uses the readline library starts up, theinit file is read, and the key bindings and variables are set.There are only a few basic constructs allowed in thereadline init file.  Blank lines are ignored.Lines beginning with a \fB#\fP are comments.Lines beginning with a \fB$\fP indicate conditional constructs.Other lines denote key bindings and variable settings.Each program using this library may add its own commandsand bindings..PPFor example, placing.RS.PPM\-Control\-u: universal\-argument.REor.RSC\-Meta\-u: universal\-argument.RE.spinto the .I inputrcwould make M\-C\-u execute the readline command.IR universal\-argument ..PPThe following symbolic character names are recognized whileprocessing key bindings:.IR DEL ,.IR ESC ,.IR ESCAPE ,.IR LFD ,.IR NEWLINE ,.IR RET ,.IR RETURN ,.IR RUBOUT ,.IR SPACE ,.IR SPC ,and.IR TAB ..PPIn addition to command names, readline allows keys to be boundto a string that is inserted when the key is pressed (a \fImacro\fP)..PP.SS Key Bindings.PPThe syntax for controlling key bindings in the.I inputrcfile is simple.  All that is required is the name of thecommand or the text of a macro and a key sequence to whichit should be bound. The name may be specified in one of two ways:as a symbolic key name, possibly with \fIMeta\-\fP or \fIControl\-\fPprefixes, or as a key sequence..PPWhen using the form \fBkeyname\fP:\^\fIfunction-name\fP or \fImacro\fP,.I keynameis the name of a key spelled out in English.  For example:.sp.RSControl\-u: universal\-argument.brMeta\-Rubout: backward\-kill\-word.brControl\-o: "> output".RE.LPIn the above example,.I C\-uis bound to the function.BR universal\-argument ,.I M-DELis bound to the function.BR backward\-kill\-word ,and.I C\-ois bound to run the macroexpressed on the right hand side (that is, to insert the text.if t \f(CW> output\fP.if n ``> output''into the line)..PPIn the second form, \fB"keyseq"\fP:\^\fIfunction\-name\fP or \fImacro\fP,.B keyseqdiffers from.B keynameabove in that strings denotingan entire key sequence may be specified by placing the sequencewithin double quotes.  Some GNU Emacs style key escapes can beused, as in the following example, but the symbolic character namesare not recognized..sp.RS"\eC\-u": universal\-argument.br"\eC\-x\eC\-r": re\-read\-init\-file.br"\ee[11~": "Function Key 1".RE.PPIn this example,.I C-uis again bound to the function.BR universal\-argument ..I "C-x C-r"is bound to the function.BR re\-read\-init\-file ,and .I "ESC [ 1 1 ~"is bound to insert the text.if t \f(CWFunction Key 1\fP..if n ``Function Key 1''..PPThe full set of GNU Emacs style escape sequences available when specifyingkey sequences is.RS.PD 0.TP.B \eC\-control prefix.TP.B \eM\-meta prefix.TP.B \eean escape character.TP.B \e\ebackslash.TP.B \e"literal ", a double quote.TP.B \e'literal ', a single quote.RE.PD.PPIn addition to the GNU Emacs style escape sequences, a secondset of backslash escapes is available:.RS.PD 0.TP.B \eaalert (bell).TP.B \ebbackspace.TP.B \eddelete.TP.B \efform feed.TP.B \ennewline.TP.B \ercarriage return.TP.B \ethorizontal tab.TP.B \evvertical tab.TP.B \e\fInnn\fPthe eight-bit character whose value is the octal value \fInnn\fP(one to three digits).TP.B \ex\fIHH\fPthe eight-bit character whose value is the hexadecimal value \fIHH\fP(one or two hex digits).RE.PD.PPWhen entering the text of a macro, single or double quotes shouldbe used to indicate a macro definition.  Unquoted textis 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 '..PP.B Bashallows the current readline key bindings to be displayed or modifiedwith the.B bindbuiltin command.  The editing mode may be switched during interactiveuse by using the.B \-ooption to the.B setbuiltin command.  Other programs using this library providesimilar mechanisms.  The.I inputrcfile may be edited and re-read if a program does not provideany other means to incorporate new bindings..SS Variables.PPReadline has variables that can be used to further customize itsbehavior.  A variable may be set in the.I inputrcfile with a statement of the form.RS.PP\fBset\fP \fIvariable\-name\fP \fIvalue\fP.RE.PPExcept where noted, readline variables can take the values.B Onor.B Off(without regard to case).The variables and their default values are:.PP.PD 0.TP.B bell\-style (audible)Controls what happens when readline wants to ring the terminal bell.If set to \fBnone\fP, readline never rings the bell.  If set to\fBvisible\fP, readline uses a visible bell if one is available.If set to \fBaudible\fP, readline attempts to ring the terminal's bell..TP.B comment\-begin (``#'')The string that is inserted in \fBvi\fP mode when the.B insert\-commentcommand is executed.This command is bound to.B M\-#in emacs mode and to.B #in vi command mode..TP .B completion\-ignore\-case (Off)If set to \fBOn\fP, readline performs filename matching and completionin a case\-insensitive fashion..TP.B completion\-query\-items (100)This determines when the user is queried about viewingthe number of possible completionsgenerated by the \fBpossible\-completions\fP command.It may be set to any integer value greater than or equal tozero.  If the number of possible completions is greater thanor equal to the value of this variable, the user is asked whetheror not he wishes to view them; otherwise they are simply listedon the terminal..TP.B convert\-meta (On)If set to \fBOn\fP, readline will convert characters with theeighth bit set to an ASCII key sequenceby stripping the eighth bit and prefixing it with anescape character (in effect, using escape as the \fImeta prefix\fP)..TP.B disable\-completion (Off)If set to \fBOn\fP, readline will inhibit word completion.  Completion characters will be inserted into the line as if they had beenmapped to \fBself-insert\fP..TP.B editing\-mode (emacs)Controls whether readline begins with a set of key bindings similarto emacs or vi..B editing\-modecan be set to either.B emacsor.BR vi ..TP.B enable\-keypad (Off)When set to \fBOn\fP, readline will try to enable the applicationkeypad when it is called.  Some systems need this to enable thearrow keys..TP.B expand\-tilde (Off)If set to \fBon\fP, tilde expansion is performed when readlineattempts word completion..TP.B history-preserve-point     If set to \fBon\fP, the history code attempts to place point at the same location on each history line retrived with \fBprevious-history\fP or \fBnext-history\fP..TP.B horizontal\-scroll\-mode (Off)When set to \fBOn\fP, makes readline use a single line for display,scrolling the input horizontally on a single screen line when itbecomes longer than the screen width rather than wrapping to a new line..TP.B input\-meta (Off)If set to \fBOn\fP, 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.B meta\-flagis a synonym for this variable..TP.B isearch\-terminators (``C\-[ C\-J'')The string of characters that should terminate an incrementalsearch without subsequently executing the character as a command.If this variable has not been given a value, the characters\fIESC\fP and \fIC\-J\fP will terminate an incremental search..TP.B keymap (emacs)Set the current readline keymap.  The set of legal keymap names is\fIemacs, emacs-standard, emacs-meta, emacs-ctlx, vi, vi-move,vi-command\fP, and.IR vi-insert .\fIvi\fP is equivalent to \fIvi-command\fP; \fIemacs\fP isequivalent to \fIemacs-standard\fP.  The default value is.IR emacs .The value of.B editing\-modealso affects the default keymap..TP.B mark\-directories (On)If set to \fBOn\fP, completed directory names have a slash