1HISTORY(3)                 Library Functions Manual                 HISTORY(3)
2
3
4

NAME

6       history - GNU History Library
7
9       The GNU History Library is Copyright (C) 1989-2020 by the Free Software
10       Foundation, Inc.
11

DESCRIPTION

13       Many programs read input from the user a line at a time.  The GNU  His‐
14       tory  library is able to keep track of those lines, associate arbitrary
15       data with each line, and utilize information  from  previous  lines  in
16       composing new ones.
17

HISTORY EXPANSION

19       The  history library supports a history expansion feature that is iden‐
20       tical to the history expansion in bash.  This  section  describes  what
21       syntax features are available.
22
23       History expansions introduce words from the history list into the input
24       stream, making it easy to repeat commands, insert the  arguments  to  a
25       previous command into the current input line, or fix errors in previous
26       commands quickly.
27
28       History expansion is usually performed  immediately  after  a  complete
29       line  is read.  It takes place in two parts.  The first is to determine
30       which line from the history list to use during substitution.  The  sec‐
31       ond  is  to select portions of that line for inclusion into the current
32       one.  The line selected from the history is the event, and the portions
33       of  that  line  that  are  acted upon are words.  Various modifiers are
34       available to manipulate the selected words.  The line  is  broken  into
35       words in the same fashion as bash does when reading input, so that sev‐
36       eral words that would otherwise be separated are  considered  one  word
37       when  surrounded  by  quotes (see the description of history_tokenize()
38       below).  History expansions are introduced by  the  appearance  of  the
39       history expansion character, which is ! by default.  Only backslash (\)
40       and single quotes can quote the history expansion character.
41
42   Event Designators
43       An event designator is a reference to a command line entry in the  his‐
44       tory  list.   Unless  the reference is absolute, events are relative to
45       the current position in the history list.
46
47       !      Start a history substitution, except when followed by  a  blank,
48              newline, = or (.
49       !n     Refer to command line n.
50       !-n    Refer to the current command minus n.
51       !!     Refer to the previous command.  This is a synonym for `!-1'.
52       !string
53              Refer  to the most recent command preceding the current position
54              in the history list starting with string.
55       !?string[?]
56              Refer to the most recent command preceding the current  position
57              in  the  history  list containing string.  The trailing ? may be
58              omitted if string is followed  immediately  by  a  newline.   If
59              string  is  missing,  the  string from the most recent search is
60              used; it is an error if there is no previous search string.
61       ^string1^string2^
62              Quick substitution.  Repeat the last command, replacing  string1
63              with string2.  Equivalent to ``!!:s^string1^string2^'' (see Mod‐
64              ifiers below).
65       !#     The entire command line typed so far.
66
67   Word Designators
68       Word designators are used to select desired words from the event.  A  :
69       separates  the event specification from the word designator.  It may be
70       omitted if the word designator begins with a ^, $, *, -, or  %.   Words
71       are  numbered from the beginning of the line, with the first word being
72       denoted by 0 (zero).  Words are inserted into the  current  line  sepa‐
73       rated by single spaces.
74
75       0 (zero)
76              The zeroth word.  For the shell, this is the command word.
77       n      The nth word.
78       ^      The first argument.  That is, word 1.
79       $      The  last word.  This is usually the last argument, but will ex‐
80              pand to the zeroth word if there is only one word in the line.
81       %      The first word matched by the most recent `?string?' search,  if
82              the  search  string  begins  with  a character that is part of a
83              word.
84       x-y    A range of words; `-y' abbreviates `0-y'.
85       *      All of the words but the zeroth.  This is a synonym  for  `1-$'.
86              It  is  not  an  error to use * if there is just one word in the
87              event; the empty string is returned in that case.
88       x*     Abbreviates x-$.
89       x-     Abbreviates x-$ like x*, but omits the last word.  If x is miss‐
90              ing, it defaults to 0.
91
92       If  a  word  designator is supplied without an event specification, the
93       previous command is used as the event.
94
95   Modifiers
96       After the optional word designator, there may appear a sequence of  one
97       or more of the following modifiers, each preceded by a `:'.  These mod‐
98       ify, or edit, the word or words selected from the history event.
99
100       h      Remove a trailing file name component, leaving only the head.
101       t      Remove all leading file name components, leaving the tail.
102       r      Remove a trailing suffix of the form .xxx, leaving the basename.
103       e      Remove all but the trailing suffix.
104       p      Print the new command but do not execute it.
105       q      Quote the substituted words, escaping further substitutions.
106       x      Quote the substituted words as with q, but break into  words  at
107              blanks  and newlines.  The q and x modifiers are mutually exclu‐
108              sive; the last one supplied is used.
109       s/old/new/
110              Substitute new for the first occurrence  of  old  in  the  event
111              line.  Any character may be used as the delimiter in place of /.
112              The final delimiter is optional if it is the last  character  of
113              the event line.  The delimiter may be quoted in old and new with
114              a single backslash.  If & appears in new, it is replaced by old.
115              A  single backslash will quote the &.  If old is null, it is set
116              to the last old substituted, or, if no previous history  substi‐
117              tutions  took  place,  the last string in a !?string[?]  search.
118              If new is null, each matching old is deleted.
119       &      Repeat the previous substitution.
120       g      Cause changes to be applied over the entire event line.  This is
121              used  in  conjunction  with `:s' (e.g., `:gs/old/new/') or `:&'.
122              If used with `:s', any delimiter can be used in place of /,  and
123              the  final  delimiter is optional if it is the last character of
124              the event line.  An a may be used as a synonym for g.
125       G      Apply the following `s' or `&' modifier once to each word in the
126              event line.
127

PROGRAMMING WITH HISTORY FUNCTIONS

129       This  section  describes  how  to use the History library in other pro‐
130       grams.
131
132   Introduction to History
133       A programmer using the History library has available functions for  re‐
134       membering  lines  on  a history list, associating arbitrary data with a
135       line, removing lines from the list, searching through the  list  for  a
136       line  containing  an arbitrary text string, and referencing any line in
137       the list directly.  In addition, a history expansion function is avail‐
138       able  which  provides  for a consistent user interface across different
139       programs.
140
141       The user using programs written with the History library has the  bene‐
142       fit  of  a  consistent user interface with a set of well-known commands
143       for manipulating the text of previous lines and using that text in  new
144       commands.  The basic history manipulation commands are identical to the
145       history substitution provided by bash.
146
147       The programmer can also use the Readline library, which  includes  some
148       history manipulation by default, and has the added advantage of command
149       line editing.
150
151       Before declaring any functions using any functionality the History  li‐
152       brary  provides in other code, an application writer should include the
153       file <readline/history.h> in any file that uses the  History  library's
154       features.   It  supplies  extern  declarations for all of the library's
155       public functions and variables, and declares all  of  the  public  data
156       structures.
157
158   History Storage
159       The  history  list  is an array of history entries.  A history entry is
160       declared as follows:
161
162       typedef void * histdata_t;
163
164       typedef struct _hist_entry {
165         char *line;
166         char *timestamp;
167         histdata_t data;
168       } HIST_ENTRY;
169
170       The history list itself might therefore be declared as
171
172       HIST_ENTRY ** the_history_list;
173
174       The state of the History library is encapsulated into a  single  struc‐
175       ture:
176
177       /*
178        * A structure used to pass around the current state of the history.
179        */
180       typedef struct _hist_state {
181         HIST_ENTRY **entries; /* Pointer to the entries themselves. */
182         int offset;           /* The location pointer within this array. */
183         int length;           /* Number of elements within this array. */
184         int size;             /* Number of slots allocated to this array. */
185         int flags;
186       } HISTORY_STATE;
187
188       If the flags member includes HS_STIFLED, the history has been stifled.
189

History Functions

191       This  section  describes the calling sequence for the various functions
192       exported by the GNU History library.
193
194   Initializing History and State Management
195       This section describes functions used  to  initialize  and  manage  the
196       state of the History library when you want to use the history functions
197       in your program.
198
199       void using_history (void)
200       Begin a session in which the history functions  might  be  used.   This
201       initializes the interactive variables.
202
203       HISTORY_STATE * history_get_history_state (void)
204       Return a structure describing the current state of the input history.
205
206       void history_set_history_state (HISTORY_STATE *state)
207       Set the state of the history list according to state.
208
209
210   History List Management
211       These  functions  manage individual entries on the history list, or set
212       parameters managing the list itself.
213
214       void add_history (const char *string)
215       Place string at the end of the history list.  The associated data field
216       (if  any) is set to NULL.  If the maximum number of history entries has
217       been set using stifle_history(), and the new number of history  entries
218       would exceed that maximum, the oldest history entry is removed.
219
220       void add_history_time (const char *string)
221       Change  the time stamp associated with the most recent history entry to
222       string.
223
224       HIST_ENTRY * remove_history (int which)
225       Remove history entry at offset which from the history.  The removed el‐
226       ement is returned so you can free the line, data, and containing struc‐
227       ture.
228
229       histdata_t free_history_entry (HIST_ENTRY *histent)
230       Free the history entry histent and any history library private data as‐
231       sociated  with it.  Returns the application-specific data so the caller
232       can dispose of it.
233
234       HIST_ENTRY * replace_history_entry (int which, const char *line,  hist‐
235       data_t data)
236       Make  the  history  entry at offset which have line and data.  This re‐
237       turns the old entry so the caller can dispose of  any  application-spe‐
238       cific  data.   In  the  case of an invalid which, a NULL pointer is re‐
239       turned.
240
241       void clear_history (void)
242       Clear the history list by deleting all the entries.
243
244       void stifle_history (int max)
245       Stifle the history list, remembering only the last  max  entries.   The
246       history list will contain only max entries at a time.
247
248       int unstifle_history (void)
249       Stop  stifling  the  history.   This returns the previously-set maximum
250       number of history entries (as set by  stifle_history()).   history  was
251       stifled.  The value is positive if the history was stifled, negative if
252       it wasn't.
253
254       int history_is_stifled (void)
255       Returns non-zero if the history is stifled, zero if it is not.
256
257
258   Information About the History List
259       These functions return information about the entire history list or in‐
260       dividual list entries.
261
262       HIST_ENTRY ** history_list (void)
263       Return a NULL terminated array of HIST_ENTRY * which is the current in‐
264       put history.  Element 0 of this list is  the  beginning  of  time.   If
265       there is no history, return NULL.
266
267       int where_history (void)
268       Returns the offset of the current history element.
269
270       HIST_ENTRY * current_history (void)
271       Return  the  history  entry  at  the current position, as determined by
272       where_history().  If there is no entry there, return a NULL pointer.
273
274       HIST_ENTRY * history_get (int offset)
275       Return the history entry at position offset.  The range of valid values
276       of  offset  starts  at history_base and ends at history_length - 1.  If
277       there is no entry there, or if offset is outside the valid  range,  re‐
278       turn a NULL pointer.
279
280       time_t history_get_time (HIST_ENTRY *)
281       Return  the  time stamp associated with the history entry passed as the
282       argument.
283
284       int history_total_bytes (void)
285       Return the number of bytes that the primary history entries are  using.
286       This  function  returns  the sum of the lengths of all the lines in the
287       history.
288
289
290   Moving Around the History List
291       These functions allow the current index into the history list to be set
292       or changed.
293
294       int history_set_pos (int pos)
295       Set the current history offset to pos, an absolute index into the list.
296       Returns 1 on success, 0 if pos is less than zero or  greater  than  the
297       number of history entries.
298
299       HIST_ENTRY * previous_history (void)
300       Back  up  the current history offset to the previous history entry, and
301       return a pointer to that entry.  If there is no previous entry,  return
302       a NULL pointer.
303
304       HIST_ENTRY * next_history (void)
305       If  the  current history offset refers to a valid history entry, incre‐
306       ment the current history offset.  If the  possibly-incremented  history
307       offset refers to a valid history entry, return a pointer to that entry;
308       otherwise, return a NULL pointer.
309
310
311   Searching the History List
312       These functions allow searching of the history list  for  entries  con‐
313       taining a specific string.  Searching may be performed both forward and
314       backward from the current history position.   The  search  may  be  an‐
315       chored, meaning that the string must match at the beginning of the his‐
316       tory entry.
317
318       int history_search (const char *string, int direction)
319       Search the history for string, starting at the current history  offset.
320       If  direction  is  less than 0, then the search is through previous en‐
321       tries, otherwise through subsequent entries.  If string is found,  then
322       the  current  history index is set to that history entry, and the value
323       returned is the offset in the line of the entry where string was found.
324       Otherwise, nothing is changed, and a -1 is returned.
325
326       int history_search_prefix (const char *string, int direction)
327       Search  the history for string, starting at the current history offset.
328       The search is anchored: matching lines must begin with string.  If  di‐
329       rection  is  less  than 0, then the search is through previous entries,
330       otherwise through subsequent entries.  If string  is  found,  then  the
331       current  history index is set to that entry, and the return value is 0.
332       Otherwise, nothing is changed, and a -1 is returned.
333
334       int history_search_pos (const char *string, int direction, int pos)
335       Search for string in the history list, starting at pos, an absolute in‐
336       dex into the list.  If direction is negative, the search proceeds back‐
337       ward from pos, otherwise forward.  Returns the absolute  index  of  the
338       history element where string was found, or -1 otherwise.
339
340
341   Managing the History File
342       The  History  library can read the history from and write it to a file.
343       This section documents the functions for managing a history file.
344
345       int read_history (const char *filename)
346       Add the contents of filename to the history list, a line at a time.  If
347       filename  is NULL, then read from ~/.history.  Returns 0 if successful,
348       or errno if not.
349
350       int read_history_range (const char *filename, int from, int to)
351       Read a range of lines from filename, adding them to the  history  list.
352       Start  reading  at  line from and end at to.  If from is zero, start at
353       the beginning.  If to is less than from, then read until the end of the
354       file.   If  filename  is NULL, then read from ~/.history.  Returns 0 if
355       successful, or errno if not.
356
357       int write_history (const char *filename)
358       Write the current history to filename, overwriting filename  if  neces‐
359       sary.   If filename is NULL, then write the history list to ~/.history.
360       Returns 0 on success, or errno on a read or write error.
361
362
363       int append_history (int nelements, const char *filename)
364       Append the last nelements of the history list to filename.  If filename
365       is  NULL, then append to ~/.history.  Returns 0 on success, or errno on
366       a read or write error.
367
368       int history_truncate_file (const char *filename, int nlines)
369       Truncate the history file filename, leaving only the last nlines lines.
370       If  filename  is NULL, then ~/.history is truncated.  Returns 0 on suc‐
371       cess, or errno on failure.
372
373
374   History Expansion
375       These functions implement history expansion.
376
377       int history_expand (char *string, char **output)
378       Expand string, placing the result into output, a pointer to  a  string.
379       Returns:
380              0      If  no  expansions  took place (or, if the only change in
381                     the text was the removal of escape  characters  preceding
382                     the history expansion character);
383              1      if expansions did take place;
384              -1     if there was an error in expansion;
385              2      if  the  returned  line should be displayed, but not exe‐
386                     cuted, as with the :p modifier.
387       If an error occurred in expansion, then output contains  a  descriptive
388       error message.
389
390       char * get_history_event (const char *string, int *cindex, int qchar)
391       Returns  the  text  of the history event beginning at string + *cindex.
392       *cindex is modified to point to after the event specifier.  At function
393       entry,  cindex  points to the index into string where the history event
394       specification begins.  qchar is a character that is allowed to end  the
395       event  specification  in addition to the ``normal'' terminating charac‐
396       ters.
397
398       char ** history_tokenize (const char *string)
399       Return an array of tokens parsed out  of  string,  much  as  the  shell
400       might.   The tokens are split on the characters in the history_word_de‐
401       limiters variable, and shell quoting conventions are obeyed.
402
403       char * history_arg_extract (int first, int last, const char *string)
404       Extract a string segment consisting of the first through last arguments
405       present in string.  Arguments are split using history_tokenize().
406
407
408   History Variables
409       This section describes the externally-visible variables exported by the
410       GNU History Library.
411
412       int history_base
413       The logical offset of the first entry in the history list.
414
415       int history_length
416       The number of entries currently stored in the history list.
417
418       int history_max_entries
419       The maximum number of history entries.  This must be changed using sti‐
420       fle_history().
421
422       int history_write_timestamps
423       If non-zero, timestamps are written to the history file, so they can be
424       preserved between sessions.  The default value is 0, meaning that time‐
425       stamps  are  not saved.  The current timestamp format uses the value of
426       history_comment_char to delimit timestamp entries in the history  file.
427       If  that  variable does not have a value (the default), timestamps will
428       not be written.
429
430       char history_expansion_char
431       The character that introduces a history event.  The default is !.  Set‐
432       ting this to 0 inhibits history expansion.
433
434       char history_subst_char
435       The character that invokes word substitution if found at the start of a
436       line.  The default is ^.
437
438       char history_comment_char
439       During tokenization, if this character is seen as the  first  character
440       of  a  word,  then it and all subsequent characters up to a newline are
441       ignored, suppressing history expansion for the remainder of  the  line.
442       This is disabled by default.
443
444       char * history_word_delimiters
445       The  characters  that  separate tokens for history_tokenize().  The de‐
446       fault value is " \t\n()<>;&|".
447
448       char * history_no_expand_chars
449       The list of characters which inhibit history expansion if found immedi‐
450       ately  following  history_expansion_char.   The  default is space, tab,
451       newline, \r, and =.
452
453       char * history_search_delimiter_chars
454       The list of additional characters which can delimit  a  history  search
455       string,  in  addition to space, tab, : and ? in the case of a substring
456       search.  The default is empty.
457
458       int history_quotes_inhibit_expansion
459       If non-zero, double-quoted words are not scanned for the history expan‐
460       sion  character or the history comment character.  The default value is
461       0.
462
463       rl_linebuf_func_t * history_inhibit_expansion_function
464       This should be set to the address of a function that  takes  two  argu‐
465       ments:  a  char  *  (string) and an int index into that string (i).  It
466       should return a non-zero value if the  history  expansion  starting  at
467       string[i]  should  not  be  performed;  zero if the expansion should be
468       done.  It is intended for use by applications like bash  that  use  the
469       history  expansion character for additional purposes.  By default, this
470       variable is set to NULL.
471

FILES

473       ~/.history
474              Default filename for reading and writing saved history
475

SEE ALSO

477       The Gnu Readline Library, Brian Fox and Chet Ramey
478       The Gnu History Library, Brian Fox and Chet Ramey
479       bash(1)
480       readline(3)
481

AUTHORS

483       Brian Fox, Free Software Foundation
484       bfox@gnu.org
485
486       Chet Ramey, Case Western Reserve University
487       chet.ramey@case.edu
488

BUG REPORTS

490       If you find a bug in the history library, you should  report  it.   But
491       first,  you  should  make sure that it really is a bug, and that it ap‐
492       pears in the latest version of the history library that you have.
493
494       Once you have determined that a bug actually exists, mail a bug  report
495       to  bug-readline@gnu.org.   If  you have a fix, you are welcome to mail
496       that as well!  Suggestions  and  `philosophical'  bug  reports  may  be
497       mailed  to  bug-readline@gnu.org  or  posted  to  the  Usenet newsgroup
498       gnu.bash.bug.
499
500       Comments and bug reports concerning this manual page should be directed
501       to chet.ramey@case.edu.
502
503
504
505GNU History 8.1                  2020 July 17                       HISTORY(3)
Impressum