2 This file documents the user interface to the GNU History library.
4 Copyright (C) 1988-2014 Free Software Foundation, Inc.
5 Authored by Brian Fox and Chet Ramey.
7 Permission is granted to make and distribute verbatim copies of this manual
8 provided the copyright notice and this permission notice are preserved on
11 Permission is granted to process this file through Tex and print the
12 results, provided the printed document carries copying permission notice
13 identical to this one except for the removal of this paragraph (this
14 paragraph not being relevant to the printed manual).
16 Permission is granted to copy and distribute modified versions of this
17 manual under the conditions for verbatim copying, provided also that the
18 GNU Copyright statement is available to the distributee, and provided that
19 the entire resulting derived work is distributed under the terms of a
20 permission notice identical to this one.
22 Permission is granted to copy and distribute translations of this manual
23 into another language, under the above conditions for modified versions.
26 @node Programming with GNU History
27 @chapter Programming with GNU History
29 This chapter describes how to interface programs that you write
30 with the @sc{gnu} History Library.
31 It should be considered a technical guide.
32 For information on the interactive use of @sc{gnu} History, @pxref{Using
33 History Interactively}.
36 * Introduction to History:: What is the GNU History library for?
37 * History Storage:: How information is stored.
38 * History Functions:: Functions that you can use.
39 * History Variables:: Variables that control behaviour.
40 * History Programming Example:: Example of using the GNU History Library.
43 @node Introduction to History
44 @section Introduction to History
46 Many programs read input from the user a line at a time. The @sc{gnu}
47 History library is able to keep track of those lines, associate arbitrary
48 data with each line, and utilize information from previous lines in
51 The programmer using the History library has available functions
52 for remembering lines on a history list, associating arbitrary data
53 with a line, removing lines from the list, searching through the list
54 for a line containing an arbitrary text string, and referencing any line
55 in the list directly. In addition, a history @dfn{expansion} function
56 is available which provides for a consistent user interface across
59 The user using programs written with the History library has the
60 benefit of a consistent user interface with a set of well-known
61 commands for manipulating the text of previous lines and using that text
62 in new commands. The basic history manipulation commands are similar to
63 the history substitution provided by @code{csh}.
65 If the programmer desires, he can use the Readline library, which
66 includes some history manipulation by default, and has the added
67 advantage of command line editing.
69 Before declaring any functions using any functionality the History
70 library provides in other code, an application writer should include
71 the file @code{<readline/history.h>} in any file that uses the
72 History library's features. It supplies extern declarations for all
73 of the library's public functions and variables, and declares all of
74 the public data structures.
77 @section History Storage
79 The history list is an array of history entries. A history entry is
83 typedef void *histdata_t;
85 typedef struct _hist_entry @{
92 The history list itself might therefore be declared as
95 HIST_ENTRY **the_history_list;
98 The state of the History library is encapsulated into a single structure:
102 * A structure used to pass around the current state of the history.
104 typedef struct _hist_state @{
105 HIST_ENTRY **entries; /* Pointer to the entries themselves. */
106 int offset; /* The location pointer within this array. */
107 int length; /* Number of elements within this array. */
108 int size; /* Number of slots allocated to this array. */
113 If the flags member includes @code{HS_STIFLED}, the history has been
116 @node History Functions
117 @section History Functions
119 This section describes the calling sequence for the various functions
120 exported by the @sc{gnu} History library.
123 * Initializing History and State Management:: Functions to call when you
124 want to use history in a
126 * History List Management:: Functions used to manage the list
128 * Information About the History List:: Functions returning information about
130 * Moving Around the History List:: Functions used to change the position
132 * Searching the History List:: Functions to search the history list
133 for entries containing a string.
134 * Managing the History File:: Functions that read and write a file
135 containing the history list.
136 * History Expansion:: Functions to perform csh-like history
140 @node Initializing History and State Management
141 @subsection Initializing History and State Management
143 This section describes functions used to initialize and manage
144 the state of the History library when you want to use the history
145 functions in your program.
147 @deftypefun void using_history (void)
148 Begin a session in which the history functions might be used. This
149 initializes the interactive variables.
152 @deftypefun {HISTORY_STATE *} history_get_history_state (void)
153 Return a structure describing the current state of the input history.
156 @deftypefun void history_set_history_state (HISTORY_STATE *state)
157 Set the state of the history list according to @var{state}.
160 @node History List Management
161 @subsection History List Management
163 These functions manage individual entries on the history list, or set
164 parameters managing the list itself.
166 @deftypefun void add_history (const char *string)
167 Place @var{string} at the end of the history list. The associated data
168 field (if any) is set to @code{NULL}.
171 @deftypefun void add_history_time (const char *string)
172 Change the time stamp associated with the most recent history entry to
176 @deftypefun {HIST_ENTRY *} remove_history (int which)
177 Remove history entry at offset @var{which} from the history. The
178 removed element is returned so you can free the line, data,
179 and containing structure.
182 @deftypefun {histdata_t} free_history_entry (HIST_ENTRY *histent)
183 Free the history entry @var{histent} and any history library private
184 data associated with it. Returns the application-specific data
185 so the caller can dispose of it.
188 @deftypefun {HIST_ENTRY *} replace_history_entry (int which, const char *line, histdata_t data)
189 Make the history entry at offset @var{which} have @var{line} and @var{data}.
190 This returns the old entry so the caller can dispose of any
191 application-specific data. In the case
192 of an invalid @var{which}, a @code{NULL} pointer is returned.
195 @deftypefun void clear_history (void)
196 Clear the history list by deleting all the entries.
199 @deftypefun void stifle_history (int max)
200 Stifle the history list, remembering only the last @var{max} entries.
203 @deftypefun int unstifle_history (void)
204 Stop stifling the history. This returns the previously-set
205 maximum number of history entries (as set by @code{stifle_history()}).
206 The value is positive if the history was
207 stifled, negative if it wasn't.
210 @deftypefun int history_is_stifled (void)
211 Returns non-zero if the history is stifled, zero if it is not.
214 @node Information About the History List
215 @subsection Information About the History List
217 These functions return information about the entire history list or
218 individual list entries.
220 @deftypefun {HIST_ENTRY **} history_list (void)
221 Return a @code{NULL} terminated array of @code{HIST_ENTRY *} which is the
222 current input history. Element 0 of this list is the beginning of time.
223 If there is no history, return @code{NULL}.
226 @deftypefun int where_history (void)
227 Returns the offset of the current history element.
230 @deftypefun {HIST_ENTRY *} current_history (void)
231 Return the history entry at the current position, as determined by
232 @code{where_history()}. If there is no entry there, return a @code{NULL}
236 @deftypefun {HIST_ENTRY *} history_get (int offset)
237 Return the history entry at position @var{offset}, starting from
238 @code{history_base} (@pxref{History Variables}).
239 If there is no entry there, or if @var{offset}
240 is greater than the history length, return a @code{NULL} pointer.
243 @deftypefun time_t history_get_time (HIST_ENTRY *entry)
244 Return the time stamp associated with the history entry @var{entry}.
247 @deftypefun int history_total_bytes (void)
248 Return the number of bytes that the primary history entries are using.
249 This function returns the sum of the lengths of all the lines in the
253 @node Moving Around the History List
254 @subsection Moving Around the History List
256 These functions allow the current index into the history list to be
259 @deftypefun int history_set_pos (int pos)
260 Set the current history offset to @var{pos}, an absolute index
262 Returns 1 on success, 0 if @var{pos} is less than zero or greater
263 than the number of history entries.
266 @deftypefun {HIST_ENTRY *} previous_history (void)
267 Back up the current history offset to the previous history entry, and
268 return a pointer to that entry. If there is no previous entry, return
269 a @code{NULL} pointer.
272 @deftypefun {HIST_ENTRY *} next_history (void)
273 If the current history offset refers to a valid history entry,
274 increment the current history offset.
275 If the possibly-incremented history offset refers to a valid history
276 entry, return a pointer to that entry;
277 otherwise, return a @code{BNULL} pointer.
280 @node Searching the History List
281 @subsection Searching the History List
282 @cindex History Searching
284 These functions allow searching of the history list for entries containing
285 a specific string. Searching may be performed both forward and backward
286 from the current history position. The search may be @dfn{anchored},
287 meaning that the string must match at the beginning of the history entry.
288 @cindex anchored search
290 @deftypefun int history_search (const char *string, int direction)
291 Search the history for @var{string}, starting at the current history offset.
292 If @var{direction} is less than 0, then the search is through
293 previous entries, otherwise through subsequent entries.
294 If @var{string} is found, then
295 the current history index is set to that history entry, and the value
296 returned is the offset in the line of the entry where
297 @var{string} was found. Otherwise, nothing is changed, and a -1 is
301 @deftypefun int history_search_prefix (const char *string, int direction)
302 Search the history for @var{string}, starting at the current history
303 offset. The search is anchored: matching lines must begin with
304 @var{string}. If @var{direction} is less than 0, then the search is
305 through previous entries, otherwise through subsequent entries.
306 If @var{string} is found, then the
307 current history index is set to that entry, and the return value is 0.
308 Otherwise, nothing is changed, and a -1 is returned.
311 @deftypefun int history_search_pos (const char *string, int direction, int pos)
312 Search for @var{string} in the history list, starting at @var{pos}, an
313 absolute index into the list. If @var{direction} is negative, the search
314 proceeds backward from @var{pos}, otherwise forward. Returns the absolute
315 index of the history element where @var{string} was found, or -1 otherwise.
318 @node Managing the History File
319 @subsection Managing the History File
321 The History library can read the history from and write it to a file.
322 This section documents the functions for managing a history file.
324 @deftypefun int read_history (const char *filename)
325 Add the contents of @var{filename} to the history list, a line at a time.
326 If @var{filename} is @code{NULL}, then read from @file{~/.history}.
327 Returns 0 if successful, or @code{errno} if not.
330 @deftypefun int read_history_range (const char *filename, int from, int to)
331 Read a range of lines from @var{filename}, adding them to the history list.
332 Start reading at line @var{from} and end at @var{to}.
333 If @var{from} is zero, start at the beginning. If @var{to} is less than
334 @var{from}, then read until the end of the file. If @var{filename} is
335 @code{NULL}, then read from @file{~/.history}. Returns 0 if successful,
336 or @code{errno} if not.
339 @deftypefun int write_history (const char *filename)
340 Write the current history to @var{filename}, overwriting @var{filename}
342 If @var{filename} is @code{NULL}, then write the history list to
344 Returns 0 on success, or @code{errno} on a read or write error.
347 @deftypefun int append_history (int nelements, const char *filename)
348 Append the last @var{nelements} of the history list to @var{filename}.
349 If @var{filename} is @code{NULL}, then append to @file{~/.history}.
350 Returns 0 on success, or @code{errno} on a read or write error.
353 @deftypefun int history_truncate_file (const char *filename, int nlines)
354 Truncate the history file @var{filename}, leaving only the last
356 If @var{filename} is @code{NULL}, then @file{~/.history} is truncated.
357 Returns 0 on success, or @code{errno} on failure.
360 @node History Expansion
361 @subsection History Expansion
363 These functions implement history expansion.
365 @deftypefun int history_expand (char *string, char **output)
366 Expand @var{string}, placing the result into @var{output}, a pointer
367 to a string (@pxref{History Interaction}). Returns:
370 If no expansions took place (or, if the only change in
371 the text was the removal of escape characters preceding the history expansion
374 if expansions did take place;
376 if there was an error in expansion;
378 if the returned line should be displayed, but not executed,
379 as with the @code{:p} modifier (@pxref{Modifiers}).
382 If an error occurred in expansion, then @var{output} contains a descriptive
386 @deftypefun {char *} get_history_event (const char *string, int *cindex, int qchar)
387 Returns the text of the history event beginning at @var{string} +
388 @var{*cindex}. @var{*cindex} is modified to point to after the event
389 specifier. At function entry, @var{cindex} points to the index into
390 @var{string} where the history event specification begins. @var{qchar}
391 is a character that is allowed to end the event specification in addition
392 to the ``normal'' terminating characters.
395 @deftypefun {char **} history_tokenize (const char *string)
396 Return an array of tokens parsed out of @var{string}, much as the
397 shell might. The tokens are split on the characters in the
398 @var{history_word_delimiters} variable,
399 and shell quoting conventions are obeyed.
402 @deftypefun {char *} history_arg_extract (int first, int last, const char *string)
403 Extract a string segment consisting of the @var{first} through @var{last}
404 arguments present in @var{string}. Arguments are split using
405 @code{history_tokenize}.
408 @node History Variables
409 @section History Variables
411 This section describes the externally-visible variables exported by
412 the @sc{gnu} History Library.
414 @deftypevar int history_base
415 The logical offset of the first entry in the history list.
418 @deftypevar int history_length
419 The number of entries currently stored in the history list.
422 @deftypevar int history_max_entries
423 The maximum number of history entries. This must be changed using
424 @code{stifle_history()}.
427 @deftypevar int history_write_timestamps
428 If non-zero, timestamps are written to the history file, so they can be
429 preserved between sessions. The default value is 0, meaning that
430 timestamps are not saved.
432 The current timestamp format uses the value of @var{history_comment_char}
433 to delimit timestamp entries in the history file. If that variable does
434 not have a value (the default), timestamps will not be written.
437 @deftypevar char history_expansion_char
438 The character that introduces a history event. The default is @samp{!}.
439 Setting this to 0 inhibits history expansion.
442 @deftypevar char history_subst_char
443 The character that invokes word substitution if found at the start of
444 a line. The default is @samp{^}.
447 @deftypevar char history_comment_char
448 During tokenization, if this character is seen as the first character
449 of a word, then it and all subsequent characters up to a newline are
450 ignored, suppressing history expansion for the remainder of the line.
451 This is disabled by default.
454 @deftypevar {char *} history_word_delimiters
455 The characters that separate tokens for @code{history_tokenize()}.
456 The default value is @code{" \t\n()<>;&|"}.
459 @deftypevar {char *} history_search_delimiter_chars
460 The list of additional characters which can delimit a history search
461 string, in addition to space, TAB, @samp{:} and @samp{?} in the case of
462 a substring search. The default is empty.
465 @deftypevar {char *} history_no_expand_chars
466 The list of characters which inhibit history expansion if found immediately
467 following @var{history_expansion_char}. The default is space, tab, newline,
468 carriage return, and @samp{=}.
471 @deftypevar int history_quotes_inhibit_expansion
472 If non-zero, double-quoted words are not scanned for the history expansion
473 character or the history comment character. The default value is 0.
476 @deftypevar {rl_linebuf_func_t *} history_inhibit_expansion_function
477 This should be set to the address of a function that takes two arguments:
478 a @code{char *} (@var{string})
479 and an @code{int} index into that string (@var{i}).
480 It should return a non-zero value if the history expansion starting at
481 @var{string[i]} should not be performed; zero if the expansion should
483 It is intended for use by applications like Bash that use the history
484 expansion character for additional purposes.
485 By default, this variable is set to @code{NULL}.
488 @node History Programming Example
489 @section History Programming Example
491 The following program demonstrates simple use of the @sc{gnu} History Library.
495 #include <readline/history.h>
509 printf ("history$ ");
511 t = fgets (line, sizeof (line) - 1, stdin);
515 if (t[len - 1] == '\n')
520 strcpy (line, "quit");
527 result = history_expand (line, &expansion);
529 fprintf (stderr, "%s\n", expansion);
531 if (result < 0 || result == 2)
537 add_history (expansion);
538 strncpy (line, expansion, sizeof (line) - 1);
542 if (strcmp (line, "quit") == 0)
544 else if (strcmp (line, "save") == 0)
545 write_history ("history_file");
546 else if (strcmp (line, "read") == 0)
547 read_history ("history_file");
548 else if (strcmp (line, "list") == 0)
550 register HIST_ENTRY **the_list;
553 the_list = history_list ();
555 for (i = 0; the_list[i]; i++)
556 printf ("%d: %s\n", i + history_base, the_list[i]->line);
558 else if (strncmp (line, "delete", 6) == 0)
561 if ((sscanf (line + 6, "%d", &which)) == 1)
563 HIST_ENTRY *entry = remove_history (which);
565 fprintf (stderr, "No such entry %d\n", which);
574 fprintf (stderr, "non-numeric arg given to `delete'\n");