.\" Copyright (C) 2000, 2001 by Martin C. Shepherd.\" .\" All rights reserved..\" .\" Permission is hereby granted, free of charge, to any person obtaining a.\" copy of this software and associated documentation files (the.\" "Software"), to deal in the Software without restriction, including.\" without limitation the rights to use, copy, modify, merge, publish,.\" distribute, and/or sell copies of the Software, and to permit persons.\" to whom the Software is furnished to do so, provided that the above.\" copyright notice(s) and this permission notice appear in all copies of.\" the Software and that both the above copyright notice(s) and this.\" permission notice appear in supporting documentation..\" .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\" OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR.\" HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL.\" INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE..\" .\" Except as contained in this notice, the name of a copyright holder.\" shall not be used in advertising or otherwise to promote the sale, use.\" or other dealings in this Software without prior written authorization.\" of the copyright holder..TH gl_get_line 3.SH NAMEgl_get_line, new_GetLine, del_GetLine, gl_customize_completion, gl_change_terminal, gl_configure_getline, gl_load_history, gl_save_history, gl_group_history, gl_show_history, gl_watch_fd, gl_terminal_size, gl_resize_history, gl_limit_history, gl_clear_history, gl_toggle_history, gl_lookup_history, gl_state_of_history, gl_range_of_history, gl_size_of_history, gl_echo_mode, gl_replace_prompt, gl_prompt_style, gl_ignore_signal, gl_trap_signal, gl_last_signal \- allow the user to compose an input line.SH SYNOPSIS.nf#include <stdio.h>#include <libtecla.h>GetLine *new_GetLine(size_t linelen, size_t histlen);GetLine *del_GetLine(GetLine *gl);char *gl_get_line(GetLine *gl, const char *prompt,                 const char *start_line, int start_pos);int gl_customize_completion(GetLine *gl, void *data,                            CplMatchFn *match_fn);int gl_change_terminal(GetLine *gl, FILE *input_fp,                       FILE *output_fp, const char *term);int gl_configure_getline(GetLine *gl,                         const char *app_string,                         const char *app_file,                         const char *user_file);int gl_save_history(GetLine *gl, const char *filename,                    const char *comment, int max_lines);int gl_load_history(GetLine *gl, const char *filename,                    const char *comment);int gl_watch_fd(GetLine *gl, int fd, GlFdEvent event,                GlFdEventFn *callback, void *data);int gl_group_history(GetLine *gl, unsigned stream);int gl_show_history(GetLine *gl, FILE *fp,                    const char *fmt, int all_groups,                    int max_lines);int gl_resize_history(GetLine *gl, size_t bufsize);void gl_limit_history(GetLine *gl, int max_lines);void gl_clear_history(GetLine *gl, int all_groups);void gl_toggle_history(GetLine *gl, int enable);GlTerminalSize gl_terminal_size(GetLine *gl,                                int def_ncolumn,                                int def_nline);int gl_lookup_history(GetLine *gl, unsigned long id,                      GlHistoryLine *hline);void gl_state_of_history(GetLine *gl,                         GlHistoryState *state);void gl_range_of_history(GetLine *gl,                         GlHistoryRange *range);void gl_size_of_history(GetLine *gl, GlHistorySize *size);void gl_echo_mode(GetLine *gl, int enable);void gl_replace_prompt(GetLine *gl, const char *prompt);void gl_prompt_style(GetLine *gl, GlPromptStyle style);int gl_ignore_signal(GetLine *gl, int signo);int gl_trap_signal(GetLine *gl, int signo, unsigned flags,                   GlAfterSignal after, int errno_value);int gl_last_signal(const GetLine *gl);.fi.SH DESCRIPTIONThe \f3gl_get_line()\f1 function is part of the tecla library (seethe libtecla(3) man page). If the user is typing at a terminal, itprompts them for an line of input, then provides interactive editingfacilities, similar to those of the unix \f3tcsh\f1 shell. In additionto simple command-line editing, it supports recall of previouslyentered command lines, TAB completion of file names, and in-linewild-card expansion of filenames..sp.SH AN EXAMPLEThe following shows a complete example of how to use the\f3gl_get_line()\f1 function to get input from the user:.nf  #include <stdio.h>  #include <locale.h>  #include <libtecla.h>  int main(int argc, char *argv[])  {     char *line;    /* The line that the user typed */    GetLine *gl;   /* The gl_get_line() resource object */    setlocale(LC_CTYPE, ""); /* Adopt the user's choice */                             /* of character set. */    gl = new_GetLine(1024, 2048);    if(!gl)      return 1;    while((line=gl_get_line(gl, "$ ", NULL, -1)) != NULL &&           strcmp(line, "exit\\n") != 0)      printf("You typed: %s\\n", line);    gl = del_GetLine(gl);    return 0;  }.fi.spIn the example, first the resources needed by the \f3gl_get_line()\f1 functionare created by calling \f3new_GetLine()\f1. This allocates the memory used insubsequent calls to the \f3gl_get_line()\f1 function, including the historybuffer for recording previously entered lines. Then one or more lines are readfrom the user, until either an error occurs, or the user types \f3exit\f1. Thenfinally the resources that were allocated by \f3new_GetLine()\f1, are returnedto the system by calling \f3del_GetLine()\f1. Note the use of the \f3NULL\f1return value of \f3del_GetLine()\f1 to make \f3gl\f1 \f3NULL\f1. This is asafety precaution. If the program subsequently attempts to pass \f3gl\f1 to\f3gl_get_line()\f1, said function will complain, and return an error, instead ofattempting to use the deleted resource object..sp.SH THE FUNCTIONS USED IN THE EXAMPLEThe descriptions of the functions used in the example are as follows:.sp.nf  GetLine *new_GetLine(size_t linelen, size_t histlen).fi.spThis function creates the resources used by the \f3gl_get_line()\f1function and returns an opaque pointer to the object that containsthem.  The maximum length of an input line is specified via the\f3linelen\f1 argument, and the number of bytes to allocate forstoring history lines is set by the \f3histlen\f1 argument. Historylines are stored back-to-back in a single buffer of this size. Notethat this means that the number of history lines that can be stored atany given time, depends on the lengths of the individual lines.  Ifyou want to place an upper limit on the number of lines that can bestored, see the \f3gl_limit_history()\f1 function described later. Ifyou don't want history at all, specify \f3histlen\f1 as zero, and nohistory buffer will be allocated..spOn error, a message is printed to \f3stderr\f1 and \f3NULL\f1 is returned..sp.nf  GetLine *del_GetLine(GetLine *gl).fi.spThis function deletes the resources that were returned by a previouscall to \f3new_GetLine()\f1. It always returns \f3NULL\f1 (ie adeleted object). It does nothing if the \f3gl\f1 argument is\f3NULL\f1..sp.nf  char *gl_get_line(GetLine *gl, const char *prompt,                   const char *start_line, int start_pos);.fi.spThe \f3gl_get_line()\f1 function can be called any number oftimes to read input from the user. The \f3gl\f1 argumentmust have been previously returned by a call to\f3new_GetLine()\f1. The \f3prompt\f1 argument should be anormal \f3NUL\f1 terminated string, specifying the prompt topresent the user with. By default prompts are displayedliterally, but if enabled with the \f3gl_prompt_style()\f1function (see later), prompts can contain directives to dounderlining, switch to and from bold fonts, or turnhighlighting on and off.If you want to specify the initial contents of the line, forthe user to edit, pass the desired string via the\f3start_line\f1 argument. You can then specify whichcharacter of this line the cursor is initially positionedover, using the \f3start_pos\f1 argument. This should be -1if you want the cursor to follow the last character of thestart line. If you don't want to preload the line in thismanner, send \f3start_line\f1 as \f3NULL\f1, and set\f3start_pos\f1 to -1.The \f3gl_get_line()\f1 function returns a pointer to the line enteredby the user, or \f3NULL\f1 on error or at the end of the input. Thereturned pointer is part of the specified \f3gl\f1 resource object,and thus should not be free'd by the caller, or assumed to beunchanging from one call to the next. When reading from a user at aterminal, there will always be a newline character at the end of thereturned line.  When standard input is being taken from a pipe or afile, there will similarly be a newline unless the input line was toolong to store in the internal buffer. In the latter case you shouldcall \f3gl_get_line()\f1 again to read the rest of the line. Note thatthis behavior makes \f3gl_get_line()\f1 similar to \f3fgets()\f1.  Infact when \f3stdin\f1 isn't connected to a terminal,\f3gl_get_line()\f1just calls \f3fgets()\f1..SH OPTIONAL PROMPT FORMATTINGWhereas by default the prompt string that you specify isdisplayed literally, without any special interpretation ofthe characters within it, the \f3gl_prompt_style()\f1function can be used to enable optional formattingdirectives within the prompt..sp.nf  void gl_prompt_style(GetLine *gl, GlPromptStyle style);.fi.spThe \f3style\f1 argument, which specifies the formattingstyle, can take any of the following values:.sp.nf  GL_FORMAT_PROMPT   -  In this style, the formatting                        directives described below, when                        included in prompt strings, are                        interpreted as follows:                          %B  -  Display subsequent                                 characters with a bold                                 font.                          %b  -  Stop displaying characters                                 with the bold font.                          %F  -  Make subsequent characters                                 flash.                          %f  -  Turn off flashing                                 characters.                          %U  -  Underline subsequent                                 characters.                           %u  -  Stop underlining                                 characters.                          %P  -  Switch to a pale (half                                 brightness) font.                          %p  -  Stop using the pale font.                          %S  -  Highlight subsequent                                 characters (also known as                                 standout mode).                          %s  -  Stop highlighting                                 characters.                          %V  -  Turn on reverse video.                          %v  -  Turn off reverse video.                          %%  -  Display a single %                                 character.                        For example, in this mode, a prompt                        string like \f3"%UOK%u$ "\f1 would                        display the prompt \f3"OK$ "\f1,                        but with the \f3OK\f1 part                        underlined.                        Note that although a pair of                        characters that starts with a %                        character, but doesn't match any of                        the above directives is displayed                        literally, if a new directive is                        subsequently introduced which does                        match, the displayed prompt will                        change, so it is better to always                        use %% to display a literal %.                        Also note that not all terminals