1 This is history.info, produced by makeinfo version 4.1 from
2 /usr/homes/chet/src/bash/readline-src/doc/hist.texinfo.
4 INFO-DIR-SECTION Libraries
6 * History: (history). The GNU history library API
9 This document describes the GNU History library, a programming tool
10 that provides a consistent user interface for recalling lines of
11 previously typed input.
13 Copyright (C) 1988-2002 Free Software Foundation, Inc.
15 Permission is granted to make and distribute verbatim copies of this
16 manual provided the copyright notice and this permission notice pare
17 preserved on all copies.
19 Permission is granted to copy and distribute modified versions of
20 this manual under the conditions for verbatim copying, provided that
21 the entire resulting derived work is distributed under the terms of a
22 permission notice identical to this one.
24 Permission is granted to copy and distribute translations of this
25 manual into another language, under the above conditions for modified
26 versions, except that this permission notice may be stated in a
27 translation approved by the Free Software Foundation.
30 File: history.info, Node: Top, Next: Using History Interactively, Up: (dir)
35 This document describes the GNU History library, a programming tool
36 that provides a consistent user interface for recalling lines of
37 previously typed input.
41 * Using History Interactively:: GNU History User's Manual.
42 * Programming with GNU History:: GNU History Programmer's Manual.
43 * Concept Index:: Index of concepts described in this manual.
44 * Function and Variable Index:: Index of externally visible functions
48 File: history.info, Node: Using History Interactively, Next: Programming with GNU History, Prev: Top, Up: Top
50 Using History Interactively
51 ***************************
53 This chapter describes how to use the GNU History Library
54 interactively, from a user's standpoint. It should be considered a
55 user's guide. For information on using the GNU History Library in your
56 own programs, *note Programming with GNU History::.
60 * History Interaction:: What it feels like using History as a user.
63 File: history.info, Node: History Interaction, Up: Using History Interactively
68 The History library provides a history expansion feature that is
69 similar to the history expansion provided by `csh'. This section
70 describes the syntax used to manipulate the history information.
72 History expansions introduce words from the history list into the
73 input stream, making it easy to repeat commands, insert the arguments
74 to a previous command into the current input line, or fix errors in
75 previous commands quickly.
77 History expansion takes place in two parts. The first is to
78 determine which line from the history list should be used during
79 substitution. The second is to select portions of that line for
80 inclusion into the current one. The line selected from the history is
81 called the "event", and the portions of that line that are acted upon
82 are called "words". Various "modifiers" are available to manipulate
83 the selected words. The line is broken into words in the same fashion
84 that Bash does, so that several words surrounded by quotes are
85 considered one word. History expansions are introduced by the
86 appearance of the history expansion character, which is `!' by default.
90 * Event Designators:: How to specify which history line to use.
91 * Word Designators:: Specifying which words are of interest.
92 * Modifiers:: Modifying the results of substitution.
95 File: history.info, Node: Event Designators, Next: Word Designators, Up: History Interaction
100 An event designator is a reference to a command line entry in the
104 Start a history substitution, except when followed by a space, tab,
105 the end of the line, `=' or `('.
108 Refer to command line N.
111 Refer to the command N lines back.
114 Refer to the previous command. This is a synonym for `!-1'.
117 Refer to the most recent command starting with STRING.
120 Refer to the most recent command containing STRING. The trailing
121 `?' may be omitted if the STRING is followed immediately by a
125 Quick Substitution. Repeat the last command, replacing STRING1
126 with STRING2. Equivalent to `!!:s/STRING1/STRING2/'.
129 The entire command line typed so far.
132 File: history.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction
137 Word designators are used to select desired words from the event. A
138 `:' separates the event specification from the word designator. It may
139 be omitted if the word designator begins with a `^', `$', `*', `-', or
140 `%'. Words are numbered from the beginning of the line, with the first
141 word being denoted by 0 (zero). Words are inserted into the current
142 line separated by single spaces.
147 designates the preceding command. When you type this, the
148 preceding command is repeated in toto.
151 designates the last argument of the preceding command. This may be
155 designates the second argument of the most recent command starting
156 with the letters `fi'.
158 Here are the word designators:
161 The `0'th word. For many applications, this is the command word.
167 The first argument; that is, word 1.
173 The word matched by the most recent `?STRING?' search.
176 A range of words; `-Y' abbreviates `0-Y'.
179 All of the words, except the `0'th. This is a synonym for `1-$'.
180 It is not an error to use `*' if there is just one word in the
181 event; the empty string is returned in that case.
187 Abbreviates `X-$' like `X*', but omits the last word.
189 If a word designator is supplied without an event specification, the
190 previous command is used as the event.
193 File: history.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction
198 After the optional word designator, you can add a sequence of one or
199 more of the following modifiers, each preceded by a `:'.
202 Remove a trailing pathname component, leaving only the head.
205 Remove all leading pathname components, leaving the tail.
208 Remove a trailing suffix of the form `.SUFFIX', leaving the
212 Remove all but the trailing suffix.
215 Print the new command but do not execute it.
218 Substitute NEW for the first occurrence of OLD in the event line.
219 Any delimiter may be used in place of `/'. The delimiter may be
220 quoted in OLD and NEW with a single backslash. If `&' appears in
221 NEW, it is replaced by OLD. A single backslash will quote the
222 `&'. The final delimiter is optional if it is the last character
226 Repeat the previous substitution.
229 Cause changes to be applied over the entire event line. Used in
230 conjunction with `s', as in `gs/OLD/NEW/', or with `&'.
233 File: history.info, Node: Programming with GNU History, Next: Concept Index, Prev: Using History Interactively, Up: Top
235 Programming with GNU History
236 ****************************
238 This chapter describes how to interface programs that you write with
239 the GNU History Library. It should be considered a technical guide.
240 For information on the interactive use of GNU History, *note Using
241 History Interactively::.
245 * Introduction to History:: What is the GNU History library for?
246 * History Storage:: How information is stored.
247 * History Functions:: Functions that you can use.
248 * History Variables:: Variables that control behaviour.
249 * History Programming Example:: Example of using the GNU History Library.
252 File: history.info, Node: Introduction to History, Next: History Storage, Up: Programming with GNU History
254 Introduction to History
255 =======================
257 Many programs read input from the user a line at a time. The GNU
258 History library is able to keep track of those lines, associate
259 arbitrary data with each line, and utilize information from previous
260 lines in composing new ones.
262 The programmer using the History library has available functions for
263 remembering lines on a history list, associating arbitrary data with a
264 line, removing lines from the list, searching through the list for a
265 line containing an arbitrary text string, and referencing any line in
266 the list directly. In addition, a history "expansion" function is
267 available which provides for a consistent user interface across
270 The user using programs written with the History library has the
271 benefit of a consistent user interface with a set of well-known
272 commands for manipulating the text of previous lines and using that text
273 in new commands. The basic history manipulation commands are similar to
274 the history substitution provided by `csh'.
276 If the programmer desires, he can use the Readline library, which
277 includes some history manipulation by default, and has the added
278 advantage of command line editing.
280 Before declaring any functions using any functionality the History
281 library provides in other code, an application writer should include
282 the file `<readline/history.h>' in any file that uses the History
283 library's features. It supplies extern declarations for all of the
284 library's public functions and variables, and declares all of the
285 public data structures.
288 File: history.info, Node: History Storage, Next: History Functions, Prev: Introduction to History, Up: Programming with GNU History
293 The history list is an array of history entries. A history entry is
296 typedef void *histdata_t;
298 typedef struct _hist_entry {
303 The history list itself might therefore be declared as
305 HIST_ENTRY **the_history_list;
307 The state of the History library is encapsulated into a single
311 * A structure used to pass around the current state of the history.
313 typedef struct _hist_state {
314 HIST_ENTRY **entries; /* Pointer to the entries themselves. */
315 int offset; /* The location pointer within this array. */
316 int length; /* Number of elements within this array. */
317 int size; /* Number of slots allocated to this array. */
321 If the flags member includes `HS_STIFLED', the history has been
325 File: history.info, Node: History Functions, Next: History Variables, Prev: History Storage, Up: Programming with GNU History
330 This section describes the calling sequence for the various functions
331 exported by the GNU History library.
335 * Initializing History and State Management:: Functions to call when you
336 want to use history in a
338 * History List Management:: Functions used to manage the list
340 * Information About the History List:: Functions returning information about
342 * Moving Around the History List:: Functions used to change the position
344 * Searching the History List:: Functions to search the history list
345 for entries containing a string.
346 * Managing the History File:: Functions that read and write a file
347 containing the history list.
348 * History Expansion:: Functions to perform csh-like history
352 File: history.info, Node: Initializing History and State Management, Next: History List Management, Up: History Functions
354 Initializing History and State Management
355 -----------------------------------------
357 This section describes functions used to initialize and manage the
358 state of the History library when you want to use the history functions
361 - Function: void using_history (void)
362 Begin a session in which the history functions might be used. This
363 initializes the interactive variables.
365 - Function: HISTORY_STATE * history_get_history_state (void)
366 Return a structure describing the current state of the input
369 - Function: void history_set_history_state (HISTORY_STATE *state)
370 Set the state of the history list according to STATE.
373 File: history.info, Node: History List Management, Next: Information About the History List, Prev: Initializing History and State Management, Up: History Functions
375 History List Management
376 -----------------------
378 These functions manage individual entries on the history list, or set
379 parameters managing the list itself.
381 - Function: void add_history (const char *string)
382 Place STRING at the end of the history list. The associated data
383 field (if any) is set to `NULL'.
385 - Function: HIST_ENTRY * remove_history (int which)
386 Remove history entry at offset WHICH from the history. The
387 removed element is returned so you can free the line, data, and
388 containing structure.
390 - Function: HIST_ENTRY * replace_history_entry (int which, const char
391 *line, histdata_t data)
392 Make the history entry at offset WHICH have LINE and DATA. This
393 returns the old entry so you can dispose of the data. In the case
394 of an invalid WHICH, a `NULL' pointer is returned.
396 - Function: void clear_history (void)
397 Clear the history list by deleting all the entries.
399 - Function: void stifle_history (int max)
400 Stifle the history list, remembering only the last MAX entries.
402 - Function: int unstifle_history (void)
403 Stop stifling the history. This returns the previously-set
404 maximum number of history entries (as set by `stifle_history()').
405 The value is positive if the history was stifled, negative if it
408 - Function: int history_is_stifled (void)
409 Returns non-zero if the history is stifled, zero if it is not.
412 File: history.info, Node: Information About the History List, Next: Moving Around the History List, Prev: History List Management, Up: History Functions
414 Information About the History List
415 ----------------------------------
417 These functions return information about the entire history list or
418 individual list entries.
420 - Function: HIST_ENTRY ** history_list (void)
421 Return a `NULL' terminated array of `HIST_ENTRY *' which is the
422 current input history. Element 0 of this list is the beginning of
423 time. If there is no history, return `NULL'.
425 - Function: int where_history (void)
426 Returns the offset of the current history element.
428 - Function: HIST_ENTRY * current_history (void)
429 Return the history entry at the current position, as determined by
430 `where_history()'. If there is no entry there, return a `NULL'
433 - Function: HIST_ENTRY * history_get (int offset)
434 Return the history entry at position OFFSET, starting from
435 `history_base' (*note History Variables::). If there is no entry
436 there, or if OFFSET is greater than the history length, return a
439 - Function: int history_total_bytes (void)
440 Return the number of bytes that the primary history entries are
441 using. This function returns the sum of the lengths of all the
442 lines in the history.
445 File: history.info, Node: Moving Around the History List, Next: Searching the History List, Prev: Information About the History List, Up: History Functions
447 Moving Around the History List
448 ------------------------------
450 These functions allow the current index into the history list to be
453 - Function: int history_set_pos (int pos)
454 Set the current history offset to POS, an absolute index into the
455 list. Returns 1 on success, 0 if POS is less than zero or greater
456 than the number of history entries.
458 - Function: HIST_ENTRY * previous_history (void)
459 Back up the current history offset to the previous history entry,
460 and return a pointer to that entry. If there is no previous
461 entry, return a `NULL' pointer.
463 - Function: HIST_ENTRY * next_history (void)
464 Move the current history offset forward to the next history entry,
465 and return the a pointer to that entry. If there is no next
466 entry, return a `NULL' pointer.
469 File: history.info, Node: Searching the History List, Next: Managing the History File, Prev: Moving Around the History List, Up: History Functions
471 Searching the History List
472 --------------------------
474 These functions allow searching of the history list for entries
475 containing a specific string. Searching may be performed both forward
476 and backward from the current history position. The search may be
477 "anchored", meaning that the string must match at the beginning of the
480 - Function: int history_search (const char *string, int direction)
481 Search the history for STRING, starting at the current history
482 offset. If DIRECTION is less than 0, then the search is through
483 previous entries, otherwise through subsequent entries. If STRING
484 is found, then the current history index is set to that history
485 entry, and the value returned is the offset in the line of the
486 entry where STRING was found. Otherwise, nothing is changed, and
489 - Function: int history_search_prefix (const char *string, int
491 Search the history for STRING, starting at the current history
492 offset. The search is anchored: matching lines must begin with
493 STRING. If DIRECTION is less than 0, then the search is through
494 previous entries, otherwise through subsequent entries. If STRING
495 is found, then the current history index is set to that entry, and
496 the return value is 0. Otherwise, nothing is changed, and a -1 is
499 - Function: int history_search_pos (const char *string, int direction,
501 Search for STRING in the history list, starting at POS, an
502 absolute index into the list. If DIRECTION is negative, the search
503 proceeds backward from POS, otherwise forward. Returns the
504 absolute index of the history element where STRING was found, or
508 File: history.info, Node: Managing the History File, Next: History Expansion, Prev: Searching the History List, Up: History Functions
510 Managing the History File
511 -------------------------
513 The History library can read the history from and write it to a file.
514 This section documents the functions for managing a history file.
516 - Function: int read_history (const char *filename)
517 Add the contents of FILENAME to the history list, a line at a time.
518 If FILENAME is `NULL', then read from `~/.history'. Returns 0 if
519 successful, or `errno' if not.
521 - Function: int read_history_range (const char *filename, int from,
523 Read a range of lines from FILENAME, adding them to the history
524 list. Start reading at line FROM and end at TO. If FROM is zero,
525 start at the beginning. If TO is less than FROM, then read until
526 the end of the file. If FILENAME is `NULL', then read from
527 `~/.history'. Returns 0 if successful, or `errno' if not.
529 - Function: int write_history (const char *filename)
530 Write the current history to FILENAME, overwriting FILENAME if
531 necessary. If FILENAME is `NULL', then write the history list to
532 `~/.history'. Returns 0 on success, or `errno' on a read or write
535 - Function: int append_history (int nelements, const char *filename)
536 Append the last NELEMENTS of the history list to FILENAME. If
537 FILENAME is `NULL', then append to `~/.history'. Returns 0 on
538 success, or `errno' on a read or write error.
540 - Function: int history_truncate_file (const char *filename, int
542 Truncate the history file FILENAME, leaving only the last NLINES
543 lines. If FILENAME is `NULL', then `~/.history' is truncated.
544 Returns 0 on success, or `errno' on failure.
547 File: history.info, Node: History Expansion, Prev: Managing the History File, Up: History Functions
552 These functions implement history expansion.
554 - Function: int history_expand (char *string, char **output)
555 Expand STRING, placing the result into OUTPUT, a pointer to a
556 string (*note History Interaction::). Returns:
558 If no expansions took place (or, if the only change in the
559 text was the removal of escape characters preceding the
560 history expansion character);
563 if expansions did take place;
566 if there was an error in expansion;
569 if the returned line should be displayed, but not executed,
570 as with the `:p' modifier (*note Modifiers::).
572 If an error ocurred in expansion, then OUTPUT contains a
573 descriptive error message.
575 - Function: char * get_history_event (const char *string, int *cindex,
577 Returns the text of the history event beginning at STRING +
578 *CINDEX. *CINDEX is modified to point to after the event
579 specifier. At function entry, CINDEX points to the index into
580 STRING where the history event specification begins. QCHAR is a
581 character that is allowed to end the event specification in
582 addition to the "normal" terminating characters.
584 - Function: char ** history_tokenize (const char *string)
585 Return an array of tokens parsed out of STRING, much as the shell
586 might. The tokens are split on the characters in the
587 HISTORY_WORD_DELIMITERS variable, and shell quoting conventions
590 - Function: char * history_arg_extract (int first, int last, const
592 Extract a string segment consisting of the FIRST through LAST
593 arguments present in STRING. Arguments are split using
597 File: history.info, Node: History Variables, Next: History Programming Example, Prev: History Functions, Up: Programming with GNU History
602 This section describes the externally-visible variables exported by
603 the GNU History Library.
605 - Variable: int history_base
606 The logical offset of the first entry in the history list.
608 - Variable: int history_length
609 The number of entries currently stored in the history list.
611 - Variable: int history_max_entries
612 The maximum number of history entries. This must be changed using
615 - Variable: char history_expansion_char
616 The character that introduces a history event. The default is `!'.
617 Setting this to 0 inhibits history expansion.
619 - Variable: char history_subst_char
620 The character that invokes word substitution if found at the start
621 of a line. The default is `^'.
623 - Variable: char history_comment_char
624 During tokenization, if this character is seen as the first
625 character of a word, then it and all subsequent characters up to a
626 newline are ignored, suppressing history expansion for the
627 remainder of the line. This is disabled by default.
629 - Variable: char * history_word_delimiters
630 The characters that separate tokens for `history_tokenize()'. The
631 default value is `" \t\n()<>;&|"'.
633 - Variable: char * history_no_expand_chars
634 The list of characters which inhibit history expansion if found
635 immediately following HISTORY_EXPANSION_CHAR. The default is
636 space, tab, newline, carriage return, and `='.
638 - Variable: char * history_search_delimiter_chars
639 The list of additional characters which can delimit a history
640 search string, in addition to space, TAB, `:' and `?' in the case
641 of a substring search. The default is empty.
643 - Variable: int history_quotes_inhibit_expansion
644 If non-zero, single-quoted words are not scanned for the history
645 expansion character. The default value is 0.
647 - Variable: rl_linebuf_func_t * history_inhibit_expansion_function
648 This should be set to the address of a function that takes two
649 arguments: a `char *' (STRING) and an `int' index into that string
650 (I). It should return a non-zero value if the history expansion
651 starting at STRING[I] should not be performed; zero if the
652 expansion should be done. It is intended for use by applications
653 like Bash that use the history expansion character for additional
654 purposes. By default, this variable is set to `NULL'.
657 File: history.info, Node: History Programming Example, Prev: History Variables, Up: Programming with GNU History
659 History Programming Example
660 ===========================
662 The following program demonstrates simple use of the GNU History
666 #include <readline/history.h>
680 printf ("history$ ");
682 t = fgets (line, sizeof (line) - 1, stdin);
686 if (t[len - 1] == '\n')
691 strcpy (line, "quit");
698 result = history_expand (line, &expansion);
700 fprintf (stderr, "%s\n", expansion);
702 if (result < 0 || result == 2)
708 add_history (expansion);
709 strncpy (line, expansion, sizeof (line) - 1);
713 if (strcmp (line, "quit") == 0)
715 else if (strcmp (line, "save") == 0)
716 write_history ("history_file");
717 else if (strcmp (line, "read") == 0)
718 read_history ("history_file");
719 else if (strcmp (line, "list") == 0)
721 register HIST_ENTRY **the_list;
724 the_list = history_list ();
726 for (i = 0; the_list[i]; i++)
727 printf ("%d: %s\n", i + history_base, the_list[i]->line);
729 else if (strncmp (line, "delete", 6) == 0)
732 if ((sscanf (line + 6, "%d", &which)) == 1)
734 HIST_ENTRY *entry = remove_history (which);
736 fprintf (stderr, "No such entry %d\n", which);
745 fprintf (stderr, "non-numeric arg given to `delete'\n");
752 File: history.info, Node: Concept Index, Next: Function and Variable Index, Prev: Programming with GNU History, Up: Top
759 * anchored search: Searching the History List.
760 * event designators: Event Designators.
761 * history events: Event Designators.
762 * history expansion: History Interaction.
763 * History Searching: Searching the History List.
766 File: history.info, Node: Function and Variable Index, Prev: Concept Index, Up: Top
768 Function and Variable Index
769 ***************************
773 * add_history: History List Management.
774 * append_history: Managing the History File.
775 * clear_history: History List Management.
776 * current_history: Information About the History List.
777 * get_history_event: History Expansion.
778 * history_arg_extract: History Expansion.
779 * history_base: History Variables.
780 * history_comment_char: History Variables.
781 * history_expand: History Expansion.
782 * history_expansion_char: History Variables.
783 * history_get: Information About the History List.
784 * history_get_history_state: Initializing History and State Management.
785 * history_inhibit_expansion_function: History Variables.
786 * history_is_stifled: History List Management.
787 * history_length: History Variables.
788 * history_list: Information About the History List.
789 * history_max_entries: History Variables.
790 * history_no_expand_chars: History Variables.
791 * history_quotes_inhibit_expansion: History Variables.
792 * history_search: Searching the History List.
793 * history_search_delimiter_chars: History Variables.
794 * history_search_pos: Searching the History List.
795 * history_search_prefix: Searching the History List.
796 * history_set_history_state: Initializing History and State Management.
797 * history_set_pos: Moving Around the History List.
798 * history_subst_char: History Variables.
799 * history_tokenize: History Expansion.
800 * history_total_bytes: Information About the History List.
801 * history_truncate_file: Managing the History File.
802 * history_word_delimiters: History Variables.
803 * next_history: Moving Around the History List.
804 * previous_history: Moving Around the History List.
805 * read_history: Managing the History File.
806 * read_history_range: Managing the History File.
807 * remove_history: History List Management.
808 * replace_history_entry: History List Management.
809 * stifle_history: History List Management.
810 * unstifle_history: History List Management.
811 * using_history: Initializing History and State Management.
812 * where_history: Information About the History List.
813 * write_history: Managing the History File.
819 Node: Using History Interactively
\7f1716
820 Node: History Interaction
\7f2223
821 Node: Event Designators
\7f3642
822 Node: Word Designators
\7f4569
823 Node: Modifiers
\7f6198
824 Node: Programming with GNU History
\7f7336
825 Node: Introduction to History
\7f8061
826 Node: History Storage
\7f9746
827 Node: History Functions
\7f10857
828 Node: Initializing History and State Management
\7f11841
829 Node: History List Management
\7f12641
830 Node: Information About the History List
\7f14235
831 Node: Moving Around the History List
\7f15591
832 Node: Searching the History List
\7f16580
833 Node: Managing the History File
\7f18498
834 Node: History Expansion
\7f20304
835 Node: History Variables
\7f22199
836 Node: History Programming Example
\7f24766
837 Node: Concept Index
\7f27488
838 Node: Function and Variable Index
\7f27974