     GETLINE(3)                                                       GETLINE(3)

     NAME
          getline - command-line editing library with history

     SYNOPSIS
          char *getline(char *prompt);

          void gl_histadd(char *line);
          void gl_setwidth(int width);
          void gl_strwidth(int (*width_func)());

          extern int (*gl_in_hook)(char *buf);
          extern int (*gl_out_hook)(char *buf);
          extern int (*gl_tab_hook)(char *buf, int prompt_width, int
          *cursor_loc);

     DESCRIPTION
          The getline package is a set of library routines that implement an
          editable command-line history.

          Programming Interface
          getline returns a pointer to a line of text read from the user,
          prompting the user with the specified prompt.  The pointer refers to a
          static buffer allocated by the getline package.  Clients may assume
          that the pointer getline returns is always the same, and is never
          NULL.  The buffer getline returns to the caller contains the
          terminating newline character, except on end of file, in which case
          the first character in the buffer is 0 (NUL).  File descriptors 0 and
          1 must be connected to the terminal (not redirected), so the caller
          should check for this condition (using isatty()) and call stdio
          routines if the session is not interactive.

          gl_histadd adds the given line to the getline history list if the line
          is not empty and if it is different from the last line in the history
          list (so the caller need not check for these conditions).  gl_histadd
          makes its own copies of all the lines it adds to the history list.
          This is so the caller can reuse the buffer it supplies to gl_histadd.

          gl_setwidth specifies the terminal width to use for horizontal
          scrolling.  The default value is 80 columns, and it is important to
          properly specify the width or lines may wrap inadvertently.

          gl_strwidth allows the application program to supply a prompt string
          width calculation function that returns the number of screen positions
          used by the argument string. By default strlen is used, but if the
          prompt contains escape sequences the user can bind a function that
          returns the actual number of screen postitions used by the argument
          string, not including the escape characters.

          In addition to the function call interface, getline has three
          externally accessible function pointers that act as hooks if bound to
          user-defined functions.  getline supplies each of the functions with a

                                        - 1 -         Formatted:  March 10, 2000

     GETLINE(3)                                                       GETLINE(3)

          pointer to the current buffer as the first argument, and expects the
          return value to be the index of the first change the function made in
          the buffer (or -1 if the function did not alter the buffer).  After
          the functions return, getline updates the screen as necessary.  Note
          that the functions may not alter the size of the buffer.  Indeed, they
          do not even know how large the buffer is!

          getline calls gl_in_hook (initially NULL) each time it loads a new
          buffer.  More precisely, this is

          o    at the first call to getline (with an empty buffer)

          o    each time the user enters a new buffer from the history list
               (with ^P or ^N)

          o    when the user accepts an incremental search string (when the user
               terminates the search).

          getline calls gl_out_hook (initially NULL) when a line has been
          completed by the user entering a NEWLINE (^J) or RETURN (^M).  The
          buffer gl_out_hook sees does not yet have the newline appended, and
          gl_out_hook should not add a newline.

          getline calls gl_tab_hook whenever the user types a TAB.  In addition
          to the buffer, getline supplies the current prompt_width (presumably
          needed for tabbing calculations) and cursor_loc, a pointer to the
          cursor location.  (*cursor_loc = 0 corresponds to the first character
          in the buffer) *cursor_loc tells gl_tab_hook where the TAB was typed.
          Note that when it redraws the screen, getline will honor any change
          gl_tab_hook may make to *cursor_loc.  Note also that prompt_width may
          not correspond to the actual width of prompt on the screen if prompt
          contains escape sequences.  gl_tab_hook is initially bound to the
          getline internal static function gl_tab, which acts like a normal TAB
          key by inserting spaces.

          User Interface
          To edit, the user moves the cursor to the point needing correction and
          then inserts or deletes characters or words as needed.  All the
          editing commands are control characters, which typed by holding the
          CTRL key down while typing another character.  Control characters are
          indicated below as the caret (^) followed by another character, such
          as ^A.

          All edit commands operate from any place on the line, not just at the
          beginning.

          These are the getline key bindings.

                 ^A   Move cursor to beginning of line.
                 ^B   Move cursor left (back) 1 column.

                                        - 2 -         Formatted:  March 10, 2000

     GETLINE(3)                                                       GETLINE(3)

              ESC-B   Move cursor back one word.
                 ^D   Delete the character under the cursor.
                 ^E   Move cursor to end of line.
                 ^F   Move cursor right (forward) 1 column.
              ESC-F   Move cursor forward one word.
                 ^H   Delete the character left of the cursor.@
                 ^I   Jump to next tab stop (may be redefined by the program).
                 ^J   Return the current line.
                 ^K   Kill from cursor to the end of the line (see ^Y).
                 ^L   Redisplay current line.
                 ^M   Return the current line.
                 ^N   Fetches next line from the history list.
                 ^O   Toggle overwrite/insert mode, initially in insert mode.
                 ^P   Fetches previous line from the history list.
                 ^R   Begin a reverse incremental search through history list.
                      Each printing character typed adds to the search substring
                      (initially empty), and getline finds and displays the
                      first matching location.  Typing ^R again marks the
                      current starting location and begins a new search for the
                      current substring.  Typing ^H or DEL deletes the last
                      character from the search string, and getline restarts the
                      search from the last starting location.  Repeated ^H or
                      DEL characters therefore appear to unwind the search to
                      the match nearest the point where the user last typed ^R
                      or ^S.  Typing ^H or DEL until the search string is empty
                      causes getline to reset the start of the search to the
                      beginning of the history list.  Typing ESC or any other
                      editing character accepts the current match and terminates
                      the search.
                 ^S   Begin a forward incremental search through the history
                      list.  The behavior is like that of ^R but in the opposite
                      direction through the history list.
                 ^T   Transpose current and previous character.
                 ^U   Kill the entire line (see ^Y).
                 ^Y   Yank previously killed text back at current location.
          BACKSPACE   Delete the character left of the cursor.
                DEL   Delete the character left of the cursor.
             RETURN   Return the current line.
                TAB   Jump to next tab stop (may be redefined by the program).

          getline recognizes DOS and ANSI arrow keys.  They cause the following
          actions: up is the same as ^P, down is the same as ^N, left is the
          same as ^P, and right is the same as ^F.

     AUTHORS
          Program by Christopher R. Thewalt (thewalt@ce.berkeley.edu)

          Original man page by DaviD W. Sanderson (dws@cs.wisc.edu) and
          Christopher R. Thewalt

                                        - 3 -         Formatted:  March 10, 2000

     GETLINE(3)                                                       GETLINE(3)

     COPYRIGHT

          (C) Copyright 1992,1993 by Christopher R. Thewalt and DaviD W.
          Sanderson (but freely redistributable)

                                        - 4 -         Formatted:  March 10, 2000