h 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.

   Readline performs some expansion on the PROMPT before it is displayed
on the screen.  See the description of 'rl_expand_prompt' (*note
Redisplay::) for additional details, especially if PROMPT will contain
characters that do not consume physical screen space when displayed.

   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.

     add_history (line);

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

   It is preferable to avoid saving empty lines on the history list,
since users rarely have a burning need to reuse a blank line.  Here is a
function which usefully replaces the standard 'gets()' library function,
and has the advantage of no static buffer to overflow:

     /* A static variable for holding the line. */
     static char *line_read = (char *)NULL;

     /* Read a string, and return a pointer to it.
        Returns NULL on EOF. */
     char *
     rl_gets ()
     {
       /* If the buffer has already been allocated,
          return the memory to the free pool. */
       if (line_read)
         {
           free (line_read);
           line_read = (char *)NULL;
         }

       /* Get a line from the user. */
       line_read = readline ("");

       /* If the line has any text in it,
          save it on the history. */
       if (line_read && *line_read)
         add_history (line_read);

       return (line_read);
     }

   This function gives the user the default behaviour of <TAB>
completion: completion on file names.  If you do not want Readline to
complete on filenames, you can change the binding of the <TAB> key with
'rl_bind_key()'.

     int rl_bind_key (int KEY, rl_command_func_t *FUNCTION);

   'rl_bind_key()' takes two arguments: KEY is the character that you
want to bind, and FUNCTION is the address of the function to call when
KEY is pressed.  Binding <TAB> to 'rl_insert()' makes <TAB> insert
itself.  'rl_bind_key()' returns non-zero if KEY is not a valid ASCII
character code (between 0 and 255).

   Thus, to disable the default <TAB> behavior, the following suffices:
     rl_bind_key ('\t', rl_insert);

   This code should be executed once at the start of your program; you
might write a function called 'initialize_readline()' which performs
this and other desired initializations, such as installing custom
completers (*note Custom Completers::).