COHERENT manpages
This page displays the COHERENT manpage for readline() [Read and edit a line of input].
List of available manpages
Index
readline() -- Editing Function (libedit) Read and edit a line of input char *readline(prompt) char *prompt; The function readline() displays on the standard output the text to which prompt points, then accepts what the user types. It lets the user type simple, EMACS-style commands to edit what she has typed; when the user types <return>, readline() returns the line of text with the trailing newline removed. readline() returns a pointer to the newly entered line. This return value can be passed to the function add_history(), which adds it to an internal ``history'' buffer. The user can use a command within readline() recall a saved line, re-edit it, and re-submit it. readline() returns NULL when the user types EOF, or if it cannot allocate space for the line of input. Otherwise, it returns the address of the edited string that the user input. Editing Commands readline() provides a simple, EMACS-like editing interface. You can type control characters or escape sequences to edit a line before it is sent to the calling program, much like the EMACS editing feature of the Korn shell. readline() recognizes the following editing commands: <ctrl-A> Move the cursor to the beginning of the line. <ctrl-B> Move the cursor one character to the left (backwards). <ctrl-D> Delete the character under which the cursor is positioned (the ``current character''). <ctrl-E> Move the cursor to end of line. <ctrl-F> Move the cursor one character to the right (forwards). <ctrl-G> Ring the bell. <ctrl-H> Delete the character to the left of the cursor. Note that <ctrl-H> is the character that normally is output by the <backspace> key. <ctrl-I> Complete file name. Note that <ctrl-I> is the character that normally is output by the <tab> key. <ctrl-J> Submit the line for processing. Note that <ctrl-J> is the character that normally is output by the <return> key. <ctrl-K> Kill all text from the cursor to end of line. <ctrl-L> Redisplay the line. <ctrl-M> Submit the line for processing. Note that on some systems, <ctrl-M> is output by the <return> key. <ctrl-N> Get the next line from the history buffer. <ctrl-P> Get the previous line from the history buffer. <ctrl-R> Search backwards through the history buffer for a given string. <ctrl-T> Transpose the character over the cursor with the character to its left. <ctrl-V> Insert next character into the line, even if it is a control character. Note that under MicroEMACS, this command is bound to <ctrl-Q>. <ctrl-W> Kill (wipe) all text from the cursor to the mark. <ctrl-X><ctrl-X> Move the cursor from current position to the mark; reset the mark at the previous position of the cursor. <ctrl-Y> Yank back the most recently killed text. <ctrl-]>c Move the cursor forward to next character c. <ctrl-?> Delete the character under which the cursor is positioned. This command is identical with <ctrl-D>. Note that <ctrl-?> is the character that normally is output by the <del> key. <ctrl-[> Begin an escape sequence. Note that <ctrl-[> is the character that normally is output by the <esc> key. <esc><ctrl-H> Delete the previous word (the word to the left of the cursor). A word is delineated by white space. <esc><del> Delete the current word -- that is, from the cursor to the end of the word as delineated by white space or the end of the line. <esc><space> Set the mark. <esc>. Get the last (or n'th) word from previous line. <esc>? Show possible completions. This feature is detailed below. <esc>< Move the cursor to the beginning of the history buffer. <esc>> Move the cursor to the end of the history buffer. <esc>B Move the cursor backwards (to the left) by one word. <esc>D Delete the word under which the cursor is positioned. <esc>F Move the cursor forward (to the right) by one word. <esc>L Make the current word lower case. <esc>M Toggle displaying eight-bit characters normally (meta-mode), or displaying them prefixed with the string M-. In the meta-mode, you can generate characters with the top bit set by pressing the <alt> key with an alphanumeric key; this is interpreted the same as <esc><key>. <esc>U Make the current word upper case. <esc>Y Yank back the most recently killed text. <esc>V Show the version of the library libedit.a. <esc>W Make yankable all text from the cursor to the mark. <esc>n Set the argument to integer n. <esc>C Read input from environment variable _C_, where C is an upper-case letter. Most editing commands can be given an argument n, where n is an integer. To enter a numeric argument, type <esc>, the number, and then the command to execute. For example, <esc> 4 <ctrl-F> moves the cursor four characters forward. Note that you can type an editing command on the line of input, not just at the beginning. Likewise, you can type <return> to submit a line for processing, regardless of where on the line the cursor is positioned. readline() has a modest macro facility. If you type <esc> followed by an upper-case letter, then readline() reads the contents of environment variable _C_ as if you had typed them at the keyboard. readline() also can complete a file name. For example, suppose that the root directory contains the following files: coherent coherent.old If you type rm /c into readline() and then press the <tab> key, readline() completes as much of the name as it can -- in this case, by adding oherent. Because the name is not unique, readline() then beeps. If you press <esc>?, readline() displays the two choices. If you then enter a tie-break character (in this case, `.'), followed by the <tab> character, readline() completes the file name for you. Using Line Editing To include readline() in your program, simply call it as you do any other function. You must link the library libedit.a into your program. Example The following brief example lets you enter a line and edit it, and then displays it. #include <stdlib.h> extern char *readline(); extern void add_history(); int main(ac, av) int ac; char *av[]; { char *p; while ((p = readline ("Enter a line:")) != NULL) { (void) printf ("%s\n", p); add_history (p); free (p); } return 0; } See Also add_history(), libedit Notes readline() calls malloc() to allocate space for the text that the user enters. Therefore, an application must call free() to free this space when it has finished with it. readline() cannot handle lines longer than 80 characters. The original manual page was written by David W. Sanderson <dws@ssec.wisc.edu>.