Module rl_sys::readline

GNU Readline API

This chapter describes the interface between the GNU Readline Library and other programs. If you are a programmer, and you wish to include the features found in GNU Readline such as completion, line editing, and interactive history manipulation in your own programs, this section is for you.

2.1 Basic Behavior

Many programs provide a command line interface, such as mail, ftp, and sh. For such programs, the default behaviour of Readline is sufficient. This section describes how to use Readline in the simplest way possible, perhaps to replace calls in your code to gets() or fgets().

The function readline() prints a prompt prompt and then reads and returns a single line of text from the user. If prompt is NULL or the empty string, no prompt is displayed. The line readline returns is allocated with malloc(); the caller should free() the line when it has finished with it. The declaration for readline in ANSI C is:

    char *readline (const char *prompt);

So, one might say

    char *line = readline ("Enter a line: ");

in order to read a line of text from the user. The line returned has the final newline removed, so only the text remains.

If readline encounters an EOF while reading the line, and the line is empty at that point, then (char *)NULL is returned. Otherwise, the line is ended just as if a newline had been typed.

If you want the user to be able to get at the line later, (with C-p for example), you must call add_history() to save the line away in a history list of such lines.

For full details on the GNU History Library, see the associated manual.

Modules

binding	2.4.3 Binding Keys
charin	2.4.8 Character Input
funmap	2.4.4 Associating Function Names and Bindings
keymap	2.4.2 Selecting A Keymap
misc	2.4.11 Miscellaneous Functions
modtext	2.4.7 Modifying Text
naming	2.4.1 Naming a Function
redisplay	2.4.6 Redisplay
termmgmt	2.4.9 Terminal Management
undo	2.4.5 Allowing Undoing
util	2.4.10 Utility Functions
vars	2.3 Readline Variables

Structs

IOFile	I/O File Type
IOMarker	I/O Marker
KeymapEntry	Keymap Entry
ReadlineState	Readline State
UndoList	Undo List

Functions

callback_handler_install	2.4.12 Alternate Interface
callback_handler_remove	Restore the terminal to its initial state and remove the line handler. This may be called from within a callback as well as independently. If the lhandler installed by rl_callback_handler_install does not exit the program, either this function or the function referred to by the value of rl_deprep_term_function should be called before the program exits to reset the terminal settings.
callback_read_char	Whenever an application determines that keyboard input is available, it should call rl_callback_read_char(), which will read the next character from the current input source. If that character completes the line, rl_callback_read_char will invoke the lhandler function installed by rl_callback_handler_install to process the line. Before calling the lhandler function, the terminal settings are reset to the values they had before calling rl_callback_handler_install. If the lhandler function returns, and the line handler remains installed, the terminal settings are modified for Readline's use again. EOF is indicated by calling lhandler with a NULL line.
readline	Wraps the libreadline readline function. The argument is the prompt to use.

Type Definitions

CommandFunction	Readline Command Function Type
GetcFunction	Readline getc Function Type
HandlerFunction	Readline Callback Handler
HookFunction	Readline Hook Function Type
Keymap	Keymap
KeymapEntryArray	Keymap Entry Array
PrepFunction	Readline prep Function Type
VoidFunction	Readline void Function Type