This section describes how to use the History library in other
programs.
Introduction to History
A programmer using the History library has available functions
for remembering lines on a history list, associating arbitrary
data with a line, removing lines from the list, searching through
the list for a line containing an arbitrary text string, and
referencing any line in the list directly. In addition, a
history expansion function is available which provides for a
consistent user interface across different programs.
The user using programs written with the History library has the
benefit of a consistent user interface with a set of well-known
commands for manipulating the text of previous lines and using
that text in new commands. The basic history manipulation
commands are identical to the history substitution provided by
bash.
The programmer can also use the Readline library, which includes
some history manipulation by default, and has the added advantage
of command line editing.
Before declaring any functions using any functionality the
History library provides in other code, an application writer
should include the file <readline/history.h> in any file that
uses the History library's features. It supplies extern
declarations for all of the library's public functions and
variables, and declares all of the public data structures.
History Storage
The history list is an array of history entries. A history entry
is declared as follows:
typedef void * histdata_t;
typedef struct _hist_entry {
char *line;
char *timestamp;
histdata_t data;
} HIST_ENTRY;
The history list itself might therefore be declared as
HIST_ENTRY ** the_history_list;
The state of the History library is encapsulated into a single
structure:
/*
* A structure used to pass around the current state of the history.
*/
typedef struct _hist_state {
HIST_ENTRY **entries; /* Pointer to the entries themselves. */
int offset; /* The location pointer within this array. */
int length; /* Number of elements within this array. */
int size; /* Number of slots allocated to this array. */
int flags;
} HISTORY_STATE;
If the flags member includes HS_STIFLED, the history has been
stifled.
