gl_get_line(3) Library Functions Manual gl_get_line(3)
NAME
gl_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_inactivity_timeout, gl_terminal_size, gl_set_term_size, gl_resize_history, gl_limit_his-
tory, 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, gl_completion_action, gl_display_text, gl_return_sta-
tus, gl_error_message, gl_catch_blocked, gl_list_signals, gl_bind_keyseq, gl_erase_terminal, gl_automatic_history, gl_append_history,
gl_query_char, gl_read_char - allow the user to compose an input line
SYNOPSIS
#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_query_char(GetLine *gl, const char *prompt,
char defchar);
int gl_read_char(GetLine *gl);
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_bind_keyseq(GetLine *gl, GlKeyOrigin origin,
const char *keyseq, const char *action);
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_inactivity_timeout(GetLine *gl, GlTimeoutFn *callback,
void *data, unsigned long sec,
unsigned long nsec);
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_set_term_size(GetLine *gl, int ncolumn, int 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(GetLine *gl);
int gl_completion_action(GetLine *gl,
void *data, CplMatchFn *match_fn,
int list_only, const char *name,
const char *keyseq);
int gl_register_action(GetLine *gl, void *data,
GlActionFn *fn, const char *name,
const char *keyseq);
int gl_display_text(GetLine *gl, int indentation,
const char *prefix,
const char *suffix, int fill_char,
int def_width, int start,
const char *string);
GlReturnStatus gl_return_status(GetLine *gl);
const char *gl_error_message(GetLine *gl, char *buff,
size_t n);
void gl_catch_blocked(GetLine *gl);
int gl_list_signals(GetLine *gl, sigset_t *set);
int gl_append_history(GetLine *gl, const char *line);
int gl_automatic_history(GetLine *gl, int enable);
DESCRIPTION
The gl_get_line() function is part of the tecla library (see the libtecla(3) man page). If the user is typing at a terminal, each call
prompts them for an line of input, then provides interactive editing facilities, similar to those of the unix tcsh shell. In addition to
simple command-line editing, it supports recall of previously entered command lines, TAB completion of file names, and in-line wild-card
expansion of filenames. Documentation of both the user-level command-line editing features and all user configuration options, can be found
in the tecla(7) man page. This man page concerns itself with documentation for programmers interested in using this library in their appli-
cation.
AN EXAMPLE
The following shows a complete example of how to use the gl_get_line() function to get input from the user:
#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
") != 0)
printf("You typed: %s
", line);
gl = del_GetLine(gl);
return 0;
}
In the example, first the resources needed by the gl_get_line() function are created by calling new_GetLine(). This allocates the memory
used in subsequent calls to the gl_get_line() function, including the history buffer for recording previously entered lines. Then one or
more lines are read from the user, until either an error occurs, or the user types exit. Then finally the resources that were allocated by
new_GetLine(), are returned to the system by calling del_GetLine(). Note the use of the NULL return value of del_GetLine() to make gl NULL.
This is a safety precaution. If the program subsequently attempts to pass gl to gl_get_line(), said function will complain, and return an
error, instead of attempting to use the deleted resource object.
THE FUNCTIONS USED IN THE EXAMPLE
The descriptions of the functions used in the example are as follows:
GetLine *new_GetLine(size_t linelen, size_t histlen)
This function creates the resources used by the gl_get_line() function and returns an opaque pointer to the object that contains them. The
maximum length of an input line is specified via the linelen argument, and the number of bytes to allocate for storing history lines is set
by the histlen argument. History lines are stored back-to-back in a single buffer of this size. Note that this means that the number of
history lines that can be stored at any given time, depends on the lengths of the individual lines. If you want to place an upper limit on
the number of lines that can be stored, see the gl_limit_history() function described later. If you don't want history at all, specify
histlen as zero, and no history buffer will be allocated.
On error, a message is printed to stderr and NULL is returned.
GetLine *del_GetLine(GetLine *gl)
This function deletes the resources that were returned by a previous call to new_GetLine(). It always returns NULL (ie a deleted object).
It does nothing if the gl argument is NULL.
char *gl_get_line(GetLine *gl, const char *prompt,
const char *start_line, int start_pos);
The gl_get_line() function can be called any number of times to read input from the user. The gl argument must have been previously
returned by a call to new_GetLine(). The prompt argument should be a normal NUL terminated string, specifying the prompt to present the
user with. By default prompts are displayed literally, but if enabled with the gl_prompt_style() function (see later), prompts can contain
directives to do underlining, switch to and from bold fonts, or turn highlighting on and off.
If you want to specify the initial contents of the line, for the user to edit, pass the desired string via the start_line argument. You can
then specify which character of this line the cursor is initially positioned over, using the start_pos argument. This should be -1 if you
want the cursor to follow the last character of the start line. If you don't want to preload the line in this manner, send start_line as
NULL, and set start_pos to -1. Note that the line pointer returned by one call to gl_get_line() can be passed back to the next call to
gl_get_line() via the start_line. This allows the application to take the last entered line, and if it contains an error, to then present
it back to the user for re-editing, with the cursor initially positioned where the error was encountered.
The gl_get_line() function returns a pointer to the line entered by the user, or NULL on error or at the end of the input. The returned
pointer is part of the specified gl resource object, and thus should not be free'd by the caller, or assumed to be unchanging from one call
to the next. When reading from a user at a terminal, there will always be a newline character at the end of the returned line. When stan-
dard input is being taken from a pipe or a file, there will similarly be a newline unless the input line was too long to store in the
internal buffer. In the latter case you should call gl_get_line() again to read the rest of the line. Note that this behavior makes
gl_get_line() similar to fgets(). In fact when stdin isn't connected to a terminal,gl_get_line() just calls fgets().
THE RETURN STATUS OF GL_GET_LINE
As described above, the gl_get_line() function has two possible return values; a pointer to the completed input line, or NULL. Extra infor-
mation about what caused gl_get_line() to return is available both by inspecting errno, and by calling the gl_return_status() function.
GlReturnStatus gl_return_status(GetLine *gl);
The following are the possible enumerated values that this function returns.
GLR_NEWLINE - The last call to gl_get_line()
successfully returned a completed
input line.
GLR_BLOCKED - gl_get_line() was in non-blocking
server mode, and returned early to
avoid blocking the process while
waiting for terminal I/O. The
gl_pending_io() function can be
used to see what type of I/O
gl_get_line() was waiting for.
(see the gl_io_mode(3) man page
for details).
GLR_SIGNAL - A signal was caught by
gl_get_line() that had an
after-signal disposition of
GLS_ABORT (See gl_trap_signal()).
GLR_TIMEOUT - The inactivity timer expired while
gl_get_line() was waiting for
input, and the timeout callback
function returned GLTO_ABORT.
See gl_inactivity_timeout() for
information about timeouts.
GLR_FDABORT - An application I/O callack returned
GLFD_ABORT (see gl_watch_fd()).
GLR_EOF - End of file reached. This can happen
when input is coming from a file or a
pipe, instead of the terminal. It also
occurs if the user invokes the
list-or-eof or del-char-or-list-or-eof
actions at the start of a new line.
GLR_ERROR - An unexpected error caused
gl_get_line() to abort (consult
errno and/or
gl_error_message() for details.
When gl_return_status() returns GLR_ERROR, and the value of errno isn't sufficient to explain what happened, you can use the gl_error_mes-
sage() function to request a description of the last error that occurred.
const char *gl_error_message(GetLine *gl, char *buff,
size_t n);
The return value is a pointer to the message that occurred. If the buff argument is NULL, this will be a pointer to a buffer within gl,
who's value will probably change on the next call to any function associated with gl_get_line(). Otherwise, if a non-NULL buff argument is
provided, the error message, including a '