1: This is history.info, produced by makeinfo version 6.7 from
2: history.texi.
3:
4: This document describes the GNU History library (version 8.1, 29 October
5: 2020), a programming tool that provides a consistent user interface for
6: recalling lines of previously typed input.
7:
8: Copyright (C) 1988-2020 Free Software Foundation, Inc.
9:
10: Permission is granted to copy, distribute and/or modify this
11: document under the terms of the GNU Free Documentation License,
12: Version 1.3 or any later version published by the Free Software
13: Foundation; with no Invariant Sections, no Front-Cover Texts, and
14: no Back-Cover Texts. A copy of the license is included in the
15: section entitled "GNU Free Documentation License".
16:
17: INFO-DIR-SECTION Libraries
18: START-INFO-DIR-ENTRY
19: * History: (history). The GNU history library API.
20: END-INFO-DIR-ENTRY
21:
22:
23: File: history.info, Node: Top, Next: Using History Interactively, Up: (dir)
24:
25: GNU History Library
26: *******************
27:
28: This document describes the GNU History library, a programming tool that
29: provides a consistent user interface for recalling lines of previously
30: typed input.
31:
32: * Menu:
33:
34: * Using History Interactively:: GNU History User's Manual.
35: * Programming with GNU History:: GNU History Programmer's Manual.
36: * GNU Free Documentation License:: License for copying this manual.
37: * Concept Index:: Index of concepts described in this manual.
38: * Function and Variable Index:: Index of externally visible functions
39: and variables.
40:
41:
42: File: history.info, Node: Using History Interactively, Next: Programming with GNU History, Prev: Top, Up: Top
43:
44: 1 Using History Interactively
45: *****************************
46:
47: This chapter describes how to use the GNU History Library interactively,
48: from a user's standpoint. It should be considered a user's guide. For
49: information on using the GNU History Library in your own programs, *note
50: Programming with GNU History::.
51:
52: * Menu:
53:
54: * History Interaction:: What it feels like using History as a user.
55:
56:
57: File: history.info, Node: History Interaction, Up: Using History Interactively
58:
59: 1.1 History Expansion
60: =====================
61:
62: The History library provides a history expansion feature that is similar
63: to the history expansion provided by 'csh'. This section describes the
64: syntax used to manipulate the history information.
65:
66: History expansions introduce words from the history list into the
67: input stream, making it easy to repeat commands, insert the arguments to
68: a previous command into the current input line, or fix errors in
69: previous commands quickly.
70:
71: History expansion takes place in two parts. The first is to
72: determine which line from the history list should be used during
73: substitution. The second is to select portions of that line for
74: inclusion into the current one. The line selected from the history is
75: called the "event", and the portions of that line that are acted upon
76: are called "words". Various "modifiers" are available to manipulate the
77: selected words. The line is broken into words in the same fashion that
78: Bash does, so that several words surrounded by quotes are considered one
79: word. History expansions are introduced by the appearance of the
80: history expansion character, which is '!' by default.
81:
82: History expansion implements shell-like quoting conventions: a
83: backslash can be used to remove the special handling for the next
84: character; single quotes enclose verbatim sequences of characters, and
85: can be used to inhibit history expansion; and characters enclosed within
86: double quotes may be subject to history expansion, since backslash can
87: escape the history expansion character, but single quotes may not, since
88: they are not treated specially within double quotes.
89:
90: * Menu:
91:
92: * Event Designators:: How to specify which history line to use.
93: * Word Designators:: Specifying which words are of interest.
94: * Modifiers:: Modifying the results of substitution.
95:
96:
97: File: history.info, Node: Event Designators, Next: Word Designators, Up: History Interaction
98:
99: 1.1.1 Event Designators
100: -----------------------
101:
102: An event designator is a reference to a command line entry in the
103: history list. Unless the reference is absolute, events are relative to
104: the current position in the history list.
105:
106: '!'
107: Start a history substitution, except when followed by a space, tab,
108: the end of the line, or '='.
109:
110: '!N'
111: Refer to command line N.
112:
113: '!-N'
114: Refer to the command N lines back.
115:
116: '!!'
117: Refer to the previous command. This is a synonym for '!-1'.
118:
119: '!STRING'
120: Refer to the most recent command preceding the current position in
121: the history list starting with STRING.
122:
123: '!?STRING[?]'
124: Refer to the most recent command preceding the current position in
125: the history list containing STRING. The trailing '?' may be
126: omitted if the STRING is followed immediately by a newline. If
127: STRING is missing, the string from the most recent search is used;
128: it is an error if there is no previous search string.
129:
130: '^STRING1^STRING2^'
131: Quick Substitution. Repeat the last command, replacing STRING1
132: with STRING2. Equivalent to '!!:s^STRING1^STRING2^'.
133:
134: '!#'
135: The entire command line typed so far.
136:
137:
138: File: history.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction
139:
140: 1.1.2 Word Designators
141: ----------------------
142:
143: Word designators are used to select desired words from the event. A ':'
144: separates the event specification from the word designator. It may be
145: omitted if the word designator begins with a '^', '$', '*', '-', or '%'.
146: Words are numbered from the beginning of the line, with the first word
147: being denoted by 0 (zero). Words are inserted into the current line
148: separated by single spaces.
149:
150: For example,
151:
152: '!!'
153: designates the preceding command. When you type this, the
154: preceding command is repeated in toto.
155:
156: '!!:$'
157: designates the last argument of the preceding command. This may be
158: shortened to '!$'.
159:
160: '!fi:2'
161: designates the second argument of the most recent command starting
162: with the letters 'fi'.
163:
164: Here are the word designators:
165:
166: '0 (zero)'
167: The '0'th word. For many applications, this is the command word.
168:
169: 'N'
170: The Nth word.
171:
172: '^'
173: The first argument; that is, word 1.
174:
175: '$'
176: The last argument.
177:
178: '%'
179: The first word matched by the most recent '?STRING?' search, if the
180: search string begins with a character that is part of a word.
181:
182: 'X-Y'
183: A range of words; '-Y' abbreviates '0-Y'.
184:
185: '*'
186: All of the words, except the '0'th. This is a synonym for '1-$'.
187: It is not an error to use '*' if there is just one word in the
188: event; the empty string is returned in that case.
189:
190: 'X*'
191: Abbreviates 'X-$'
192:
193: 'X-'
194: Abbreviates 'X-$' like 'X*', but omits the last word. If 'x' is
195: missing, it defaults to 0.
196:
197: If a word designator is supplied without an event specification, the
198: previous command is used as the event.
199:
200:
201: File: history.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction
202:
203: 1.1.3 Modifiers
204: ---------------
205:
206: After the optional word designator, you can add a sequence of one or
207: more of the following modifiers, each preceded by a ':'. These modify,
208: or edit, the word or words selected from the history event.
209:
210: 'h'
211: Remove a trailing pathname component, leaving only the head.
212:
213: 't'
214: Remove all leading pathname components, leaving the tail.
215:
216: 'r'
217: Remove a trailing suffix of the form '.SUFFIX', leaving the
218: basename.
219:
220: 'e'
221: Remove all but the trailing suffix.
222:
223: 'p'
224: Print the new command but do not execute it.
225:
226: 's/OLD/NEW/'
227: Substitute NEW for the first occurrence of OLD in the event line.
228: Any character may be used as the delimiter in place of '/'. The
229: delimiter may be quoted in OLD and NEW with a single backslash. If
230: '&' appears in NEW, it is replaced by OLD. A single backslash will
231: quote the '&'. If OLD is null, it is set to the last OLD
232: substituted, or, if no previous history substitutions took place,
233: the last STRING in a !?STRING'[?]' search. If NEW is is null, each
234: matching OLD is deleted. The final delimiter is optional if it is
235: the last character on the input line.
236:
237: '&'
238: Repeat the previous substitution.
239:
240: 'g'
241: 'a'
242: Cause changes to be applied over the entire event line. Used in
243: conjunction with 's', as in 'gs/OLD/NEW/', or with '&'.
244:
245: 'G'
246: Apply the following 's' or '&' modifier once to each word in the
247: event.
248:
249:
250: File: history.info, Node: Programming with GNU History, Next: GNU Free Documentation License, Prev: Using History Interactively, Up: Top
251:
252: 2 Programming with GNU History
253: ******************************
254:
255: This chapter describes how to interface programs that you write with the
256: GNU History Library. It should be considered a technical guide. For
257: information on the interactive use of GNU History, *note Using History
258: Interactively::.
259:
260: * Menu:
261:
262: * Introduction to History:: What is the GNU History library for?
263: * History Storage:: How information is stored.
264: * History Functions:: Functions that you can use.
265: * History Variables:: Variables that control behaviour.
266: * History Programming Example:: Example of using the GNU History Library.
267:
268:
269: File: history.info, Node: Introduction to History, Next: History Storage, Up: Programming with GNU History
270:
271: 2.1 Introduction to History
272: ===========================
273:
274: Many programs read input from the user a line at a time. The GNU
275: History library is able to keep track of those lines, associate
276: arbitrary data with each line, and utilize information from previous
277: lines in composing new ones.
278:
279: A programmer using the History library has available functions for
280: remembering lines on a history list, associating arbitrary data with a
281: line, removing lines from the list, searching through the list for a
282: line containing an arbitrary text string, and referencing any line in
283: the list directly. In addition, a history "expansion" function is
284: available which provides for a consistent user interface across
285: different programs.
286:
287: The user using programs written with the History library has the
288: benefit of a consistent user interface with a set of well-known commands
289: for manipulating the text of previous lines and using that text in new
290: commands. The basic history manipulation commands are similar to the
291: history substitution provided by 'csh'.
292:
293: The programmer can also use the Readline library, which includes some
294: history manipulation by default, and has the added advantage of command
295: line editing.
296:
297: Before declaring any functions using any functionality the History
298: library provides in other code, an application writer should include the
299: file '<readline/history.h>' in any file that uses the History library's
300: features. It supplies extern declarations for all of the library's
301: public functions and variables, and declares all of the public data
302: structures.
303:
304:
305: File: history.info, Node: History Storage, Next: History Functions, Prev: Introduction to History, Up: Programming with GNU History
306:
307: 2.2 History Storage
308: ===================
309:
310: The history list is an array of history entries. A history entry is
311: declared as follows:
312:
313: typedef void *histdata_t;
314:
315: typedef struct _hist_entry {
316: char *line;
317: char *timestamp;
318: histdata_t data;
319: } HIST_ENTRY;
320:
321: The history list itself might therefore be declared as
322:
323: HIST_ENTRY **the_history_list;
324:
325: The state of the History library is encapsulated into a single
326: structure:
327:
328: /*
329: * A structure used to pass around the current state of the history.
330: */
331: typedef struct _hist_state {
332: HIST_ENTRY **entries; /* Pointer to the entries themselves. */
333: int offset; /* The location pointer within this array. */
334: int length; /* Number of elements within this array. */
335: int size; /* Number of slots allocated to this array. */
336: int flags;
337: } HISTORY_STATE;
338:
339: If the flags member includes 'HS_STIFLED', the history has been
340: stifled.
341:
342:
343: File: history.info, Node: History Functions, Next: History Variables, Prev: History Storage, Up: Programming with GNU History
344:
345: 2.3 History Functions
346: =====================
347:
348: This section describes the calling sequence for the various functions
349: exported by the GNU History library.
350:
351: * Menu:
352:
353: * Initializing History and State Management:: Functions to call when you
354: want to use history in a
355: program.
356: * History List Management:: Functions used to manage the list
357: of history entries.
358: * Information About the History List:: Functions returning information about
359: the history list.
360: * Moving Around the History List:: Functions used to change the position
361: in the history list.
362: * Searching the History List:: Functions to search the history list
363: for entries containing a string.
364: * Managing the History File:: Functions that read and write a file
365: containing the history list.
366: * History Expansion:: Functions to perform csh-like history
367: expansion.
368:
369:
370: File: history.info, Node: Initializing History and State Management, Next: History List Management, Up: History Functions
371:
372: 2.3.1 Initializing History and State Management
373: -----------------------------------------------
374:
375: This section describes functions used to initialize and manage the state
376: of the History library when you want to use the history functions in
377: your program.
378:
379: -- Function: void using_history (void)
380: Begin a session in which the history functions might be used. This
381: initializes the interactive variables.
382:
383: -- Function: HISTORY_STATE * history_get_history_state (void)
384: Return a structure describing the current state of the input
385: history.
386:
387: -- Function: void history_set_history_state (HISTORY_STATE *state)
388: Set the state of the history list according to STATE.
389:
390:
391: File: history.info, Node: History List Management, Next: Information About the History List, Prev: Initializing History and State Management, Up: History Functions
392:
393: 2.3.2 History List Management
394: -----------------------------
395:
396: These functions manage individual entries on the history list, or set
397: parameters managing the list itself.
398:
399: -- Function: void add_history (const char *string)
400: Place STRING at the end of the history list. The associated data
401: field (if any) is set to 'NULL'. If the maximum number of history
402: entries has been set using 'stifle_history()', and the new number
403: of history entries would exceed that maximum, the oldest history
404: entry is removed.
405:
406: -- Function: void add_history_time (const char *string)
407: Change the time stamp associated with the most recent history entry
408: to STRING.
409:
410: -- Function: HIST_ENTRY * remove_history (int which)
411: Remove history entry at offset WHICH from the history. The removed
412: element is returned so you can free the line, data, and containing
413: structure.
414:
415: -- Function: histdata_t free_history_entry (HIST_ENTRY *histent)
416: Free the history entry HISTENT and any history library private data
417: associated with it. Returns the application-specific data so the
418: caller can dispose of it.
419:
420: -- Function: HIST_ENTRY * replace_history_entry (int which, const char
421: *line, histdata_t data)
422: Make the history entry at offset WHICH have LINE and DATA. This
423: returns the old entry so the caller can dispose of any
424: application-specific data. In the case of an invalid WHICH, a
425: 'NULL' pointer is returned.
426:
427: -- Function: void clear_history (void)
428: Clear the history list by deleting all the entries.
429:
430: -- Function: void stifle_history (int max)
431: Stifle the history list, remembering only the last MAX entries.
432: The history list will contain only MAX entries at a time.
433:
434: -- Function: int unstifle_history (void)
435: Stop stifling the history. This returns the previously-set maximum
436: number of history entries (as set by 'stifle_history()'). The
437: value is positive if the history was stifled, negative if it
438: wasn't.
439:
440: -- Function: int history_is_stifled (void)
441: Returns non-zero if the history is stifled, zero if it is not.
442:
443:
444: File: history.info, Node: Information About the History List, Next: Moving Around the History List, Prev: History List Management, Up: History Functions
445:
446: 2.3.3 Information About the History List
447: ----------------------------------------
448:
449: These functions return information about the entire history list or
450: individual list entries.
451:
452: -- Function: HIST_ENTRY ** history_list (void)
453: Return a 'NULL' terminated array of 'HIST_ENTRY *' which is the
454: current input history. Element 0 of this list is the beginning of
455: time. If there is no history, return 'NULL'.
456:
457: -- Function: int where_history (void)
458: Returns the offset of the current history element.
459:
460: -- Function: HIST_ENTRY * current_history (void)
461: Return the history entry at the current position, as determined by
462: 'where_history()'. If there is no entry there, return a 'NULL'
463: pointer.
464:
465: -- Function: HIST_ENTRY * history_get (int offset)
466: Return the history entry at position OFFSET. The range of valid
467: values of OFFSET starts at 'history_base' and ends at
468: HISTORY_LENGTH - 1 (*note History Variables::). If there is no
469: entry there, or if OFFSET is outside the valid range, return a
470: 'NULL' pointer.
471:
472: -- Function: time_t history_get_time (HIST_ENTRY *entry)
473: Return the time stamp associated with the history entry ENTRY. If
474: the timestamp is missing or invalid, return 0.
475:
476: -- Function: int history_total_bytes (void)
477: Return the number of bytes that the primary history entries are
478: using. This function returns the sum of the lengths of all the
479: lines in the history.
480:
481:
482: File: history.info, Node: Moving Around the History List, Next: Searching the History List, Prev: Information About the History List, Up: History Functions
483:
484: 2.3.4 Moving Around the History List
485: ------------------------------------
486:
487: These functions allow the current index into the history list to be set
488: or changed.
489:
490: -- Function: int history_set_pos (int pos)
491: Set the current history offset to POS, an absolute index into the
492: list. Returns 1 on success, 0 if POS is less than zero or greater
493: than the number of history entries.
494:
495: -- Function: HIST_ENTRY * previous_history (void)
496: Back up the current history offset to the previous history entry,
497: and return a pointer to that entry. If there is no previous entry,
498: return a 'NULL' pointer.
499:
500: -- Function: HIST_ENTRY * next_history (void)
501: If the current history offset refers to a valid history entry,
502: increment the current history offset. If the possibly-incremented
503: history offset refers to a valid history entry, return a pointer to
504: that entry; otherwise, return a 'BNULL' pointer.
505:
506:
507: File: history.info, Node: Searching the History List, Next: Managing the History File, Prev: Moving Around the History List, Up: History Functions
508:
509: 2.3.5 Searching the History List
510: --------------------------------
511:
512: These functions allow searching of the history list for entries
513: containing a specific string. Searching may be performed both forward
514: and backward from the current history position. The search may be
515: "anchored", meaning that the string must match at the beginning of the
516: history entry.
517:
518: -- Function: int history_search (const char *string, int direction)
519: Search the history for STRING, starting at the current history
520: offset. If DIRECTION is less than 0, then the search is through
521: previous entries, otherwise through subsequent entries. If STRING
522: is found, then the current history index is set to that history
523: entry, and the value returned is the offset in the line of the
524: entry where STRING was found. Otherwise, nothing is changed, and a
525: -1 is returned.
526:
527: -- Function: int history_search_prefix (const char *string, int
528: direction)
529: Search the history for STRING, starting at the current history
530: offset. The search is anchored: matching lines must begin with
531: STRING. If DIRECTION is less than 0, then the search is through
532: previous entries, otherwise through subsequent entries. If STRING
533: is found, then the current history index is set to that entry, and
534: the return value is 0. Otherwise, nothing is changed, and a -1 is
535: returned.
536:
537: -- Function: int history_search_pos (const char *string, int direction,
538: int pos)
539: Search for STRING in the history list, starting at POS, an absolute
540: index into the list. If DIRECTION is negative, the search proceeds
541: backward from POS, otherwise forward. Returns the absolute index
542: of the history element where STRING was found, or -1 otherwise.
543:
544:
545: File: history.info, Node: Managing the History File, Next: History Expansion, Prev: Searching the History List, Up: History Functions
546:
547: 2.3.6 Managing the History File
548: -------------------------------
549:
550: The History library can read the history from and write it to a file.
551: This section documents the functions for managing a history file.
552:
553: -- Function: int read_history (const char *filename)
554: Add the contents of FILENAME to the history list, a line at a time.
555: If FILENAME is 'NULL', then read from '~/.history'. Returns 0 if
556: successful, or 'errno' if not.
557:
558: -- Function: int read_history_range (const char *filename, int from,
559: int to)
560: Read a range of lines from FILENAME, adding them to the history
561: list. Start reading at line FROM and end at TO. If FROM is zero,
562: start at the beginning. If TO is less than FROM, then read until
563: the end of the file. If FILENAME is 'NULL', then read from
564: '~/.history'. Returns 0 if successful, or 'errno' if not.
565:
566: -- Function: int write_history (const char *filename)
567: Write the current history to FILENAME, overwriting FILENAME if
568: necessary. If FILENAME is 'NULL', then write the history list to
569: '~/.history'. Returns 0 on success, or 'errno' on a read or write
570: error.
571:
572: -- Function: int append_history (int nelements, const char *filename)
573: Append the last NELEMENTS of the history list to FILENAME. If
574: FILENAME is 'NULL', then append to '~/.history'. Returns 0 on
575: success, or 'errno' on a read or write error.
576:
577: -- Function: int history_truncate_file (const char *filename, int
578: nlines)
579: Truncate the history file FILENAME, leaving only the last NLINES
580: lines. If FILENAME is 'NULL', then '~/.history' is truncated.
581: Returns 0 on success, or 'errno' on failure.
582:
583:
584: File: history.info, Node: History Expansion, Prev: Managing the History File, Up: History Functions
585:
586: 2.3.7 History Expansion
587: -----------------------
588:
589: These functions implement history expansion.
590:
591: -- Function: int history_expand (char *string, char **output)
592: Expand STRING, placing the result into OUTPUT, a pointer to a
593: string (*note History Interaction::). Returns:
594: '0'
595: If no expansions took place (or, if the only change in the
596: text was the removal of escape characters preceding the
597: history expansion character);
598: '1'
599: if expansions did take place;
600: '-1'
601: if there was an error in expansion;
602: '2'
603: if the returned line should be displayed, but not executed, as
604: with the ':p' modifier (*note Modifiers::).
605:
606: If an error occurred in expansion, then OUTPUT contains a
607: descriptive error message.
608:
609: -- Function: char * get_history_event (const char *string, int *cindex,
610: int qchar)
611: Returns the text of the history event beginning at STRING +
612: *CINDEX. *CINDEX is modified to point to after the event
613: specifier. At function entry, CINDEX points to the index into
614: STRING where the history event specification begins. QCHAR is a
615: character that is allowed to end the event specification in
616: addition to the "normal" terminating characters.
617:
618: -- Function: char ** history_tokenize (const char *string)
619: Return an array of tokens parsed out of STRING, much as the shell
620: might. The tokens are split on the characters in the
621: HISTORY_WORD_DELIMITERS variable, and shell quoting conventions are
622: obeyed as described below.
623:
624: -- Function: char * history_arg_extract (int first, int last, const
625: char *string)
626: Extract a string segment consisting of the FIRST through LAST
627: arguments present in STRING. Arguments are split using
628: 'history_tokenize'.
629:
630:
631: File: history.info, Node: History Variables, Next: History Programming Example, Prev: History Functions, Up: Programming with GNU History
632:
633: 2.4 History Variables
634: =====================
635:
636: This section describes the externally-visible variables exported by the
637: GNU History Library.
638:
639: -- Variable: int history_base
640: The logical offset of the first entry in the history list.
641:
642: -- Variable: int history_length
643: The number of entries currently stored in the history list.
644:
645: -- Variable: int history_max_entries
646: The maximum number of history entries. This must be changed using
647: 'stifle_history()'.
648:
649: -- Variable: int history_write_timestamps
650: If non-zero, timestamps are written to the history file, so they
651: can be preserved between sessions. The default value is 0, meaning
652: that timestamps are not saved.
653:
654: The current timestamp format uses the value of HISTORY_COMMENT_CHAR
655: to delimit timestamp entries in the history file. If that variable
656: does not have a value (the default), timestamps will not be
657: written.
658:
659: -- Variable: char history_expansion_char
660: The character that introduces a history event. The default is '!'.
661: Setting this to 0 inhibits history expansion.
662:
663: -- Variable: char history_subst_char
664: The character that invokes word substitution if found at the start
665: of a line. The default is '^'.
666:
667: -- Variable: char history_comment_char
668: During tokenization, if this character is seen as the first
669: character of a word, then it and all subsequent characters up to a
670: newline are ignored, suppressing history expansion for the
671: remainder of the line. This is disabled by default.
672:
673: -- Variable: char * history_word_delimiters
674: The characters that separate tokens for 'history_tokenize()'. The
675: default value is '" \t\n()<>;&|"'.
676:
677: -- Variable: char * history_search_delimiter_chars
678: The list of additional characters which can delimit a history
679: search string, in addition to space, TAB, ':' and '?' in the case
680: of a substring search. The default is empty.
681:
682: -- Variable: char * history_no_expand_chars
683: The list of characters which inhibit history expansion if found
684: immediately following HISTORY_EXPANSION_CHAR. The default is
685: space, tab, newline, carriage return, and '='.
686:
687: -- Variable: int history_quotes_inhibit_expansion
688: If non-zero, the history expansion code implements shell-like
689: quoting: single-quoted words are not scanned for the history
690: expansion character or the history comment character, and
691: double-quoted words may have history expansion performed, since
692: single quotes are not special within double quotes. The default
693: value is 0.
694:
695: -- Variable: int history_quoting_state
696: An application may set this variable to indicate that the current
697: line being expanded is subject to existing quoting. If set to ''',
698: the history expansion function will assume that the line is
699: single-quoted and inhibit expansion until it reads an unquoted
700: closing single quote; if set to '"', history expansion will assume
701: the line is double quoted until it reads an unquoted closing double
702: quote. If set to zero, the default, the history expansion function
703: will assume the line is not quoted and treat quote characters
704: within the line as described above. This is only effective if
705: HISTORY_QUOTES_INHIBIT_EXPANSION is set.
706:
707: -- Variable: rl_linebuf_func_t * history_inhibit_expansion_function
708: This should be set to the address of a function that takes two
709: arguments: a 'char *' (STRING) and an 'int' index into that string
710: (I). It should return a non-zero value if the history expansion
711: starting at STRING[I] should not be performed; zero if the
712: expansion should be done. It is intended for use by applications
713: like Bash that use the history expansion character for additional
714: purposes. By default, this variable is set to 'NULL'.
715:
716:
717: File: history.info, Node: History Programming Example, Prev: History Variables, Up: Programming with GNU History
718:
719: 2.5 History Programming Example
720: ===============================
721:
722: The following program demonstrates simple use of the GNU History
723: Library.
724:
725: #include <stdio.h>
726: #include <readline/history.h>
727:
728: main (argc, argv)
729: int argc;
730: char **argv;
731: {
732: char line[1024], *t;
733: int len, done = 0;
734:
735: line[0] = 0;
736:
737: using_history ();
738: while (!done)
739: {
740: printf ("history$ ");
741: fflush (stdout);
742: t = fgets (line, sizeof (line) - 1, stdin);
743: if (t && *t)
744: {
745: len = strlen (t);
746: if (t[len - 1] == '\n')
747: t[len - 1] = '\0';
748: }
749:
750: if (!t)
751: strcpy (line, "quit");
752:
753: if (line[0])
754: {
755: char *expansion;
756: int result;
757:
758: result = history_expand (line, &expansion);
759: if (result)
760: fprintf (stderr, "%s\n", expansion);
761:
762: if (result < 0 || result == 2)
763: {
764: free (expansion);
765: continue;
766: }
767:
768: add_history (expansion);
769: strncpy (line, expansion, sizeof (line) - 1);
770: free (expansion);
771: }
772:
773: if (strcmp (line, "quit") == 0)
774: done = 1;
775: else if (strcmp (line, "save") == 0)
776: write_history ("history_file");
777: else if (strcmp (line, "read") == 0)
778: read_history ("history_file");
779: else if (strcmp (line, "list") == 0)
780: {
781: register HIST_ENTRY **the_list;
782: register int i;
783:
784: the_list = history_list ();
785: if (the_list)
786: for (i = 0; the_list[i]; i++)
787: printf ("%d: %s\n", i + history_base, the_list[i]->line);
788: }
789: else if (strncmp (line, "delete", 6) == 0)
790: {
791: int which;
792: if ((sscanf (line + 6, "%d", &which)) == 1)
793: {
794: HIST_ENTRY *entry = remove_history (which);
795: if (!entry)
796: fprintf (stderr, "No such entry %d\n", which);
797: else
798: {
799: free (entry->line);
800: free (entry);
801: }
802: }
803: else
804: {
805: fprintf (stderr, "non-numeric arg given to `delete'\n");
806: }
807: }
808: }
809: }
810:
811:
812: File: history.info, Node: GNU Free Documentation License, Next: Concept Index, Prev: Programming with GNU History, Up: Top
813:
814: Appendix A GNU Free Documentation License
815: *****************************************
816:
817: Version 1.3, 3 November 2008
818:
819: Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
820: <http://fsf.org/>
821:
822: Everyone is permitted to copy and distribute verbatim copies
823: of this license document, but changing it is not allowed.
824:
825: 0. PREAMBLE
826:
827: The purpose of this License is to make a manual, textbook, or other
828: functional and useful document "free" in the sense of freedom: to
829: assure everyone the effective freedom to copy and redistribute it,
830: with or without modifying it, either commercially or
831: noncommercially. Secondarily, this License preserves for the
832: author and publisher a way to get credit for their work, while not
833: being considered responsible for modifications made by others.
834:
835: This License is a kind of "copyleft", which means that derivative
836: works of the document must themselves be free in the same sense.
837: It complements the GNU General Public License, which is a copyleft
838: license designed for free software.
839:
840: We have designed this License in order to use it for manuals for
841: free software, because free software needs free documentation: a
842: free program should come with manuals providing the same freedoms
843: that the software does. But this License is not limited to
844: software manuals; it can be used for any textual work, regardless
845: of subject matter or whether it is published as a printed book. We
846: recommend this License principally for works whose purpose is
847: instruction or reference.
848:
849: 1. APPLICABILITY AND DEFINITIONS
850:
851: This License applies to any manual or other work, in any medium,
852: that contains a notice placed by the copyright holder saying it can
853: be distributed under the terms of this License. Such a notice
854: grants a world-wide, royalty-free license, unlimited in duration,
855: to use that work under the conditions stated herein. The
856: "Document", below, refers to any such manual or work. Any member
857: of the public is a licensee, and is addressed as "you". You accept
858: the license if you copy, modify or distribute the work in a way
859: requiring permission under copyright law.
860:
861: A "Modified Version" of the Document means any work containing the
862: Document or a portion of it, either copied verbatim, or with
863: modifications and/or translated into another language.
864:
865: A "Secondary Section" is a named appendix or a front-matter section
866: of the Document that deals exclusively with the relationship of the
867: publishers or authors of the Document to the Document's overall
868: subject (or to related matters) and contains nothing that could
869: fall directly within that overall subject. (Thus, if the Document
870: is in part a textbook of mathematics, a Secondary Section may not
871: explain any mathematics.) The relationship could be a matter of
872: historical connection with the subject or with related matters, or
873: of legal, commercial, philosophical, ethical or political position
874: regarding them.
875:
876: The "Invariant Sections" are certain Secondary Sections whose
877: titles are designated, as being those of Invariant Sections, in the
878: notice that says that the Document is released under this License.
879: If a section does not fit the above definition of Secondary then it
880: is not allowed to be designated as Invariant. The Document may
881: contain zero Invariant Sections. If the Document does not identify
882: any Invariant Sections then there are none.
883:
884: The "Cover Texts" are certain short passages of text that are
885: listed, as Front-Cover Texts or Back-Cover Texts, in the notice
886: that says that the Document is released under this License. A
887: Front-Cover Text may be at most 5 words, and a Back-Cover Text may
888: be at most 25 words.
889:
890: A "Transparent" copy of the Document means a machine-readable copy,
891: represented in a format whose specification is available to the
892: general public, that is suitable for revising the document
893: straightforwardly with generic text editors or (for images composed
894: of pixels) generic paint programs or (for drawings) some widely
895: available drawing editor, and that is suitable for input to text
896: formatters or for automatic translation to a variety of formats
897: suitable for input to text formatters. A copy made in an otherwise
898: Transparent file format whose markup, or absence of markup, has
899: been arranged to thwart or discourage subsequent modification by
900: readers is not Transparent. An image format is not Transparent if
901: used for any substantial amount of text. A copy that is not
902: "Transparent" is called "Opaque".
903:
904: Examples of suitable formats for Transparent copies include plain
905: ASCII without markup, Texinfo input format, LaTeX input format,
906: SGML or XML using a publicly available DTD, and standard-conforming
907: simple HTML, PostScript or PDF designed for human modification.
908: Examples of transparent image formats include PNG, XCF and JPG.
909: Opaque formats include proprietary formats that can be read and
910: edited only by proprietary word processors, SGML or XML for which
911: the DTD and/or processing tools are not generally available, and
912: the machine-generated HTML, PostScript or PDF produced by some word
913: processors for output purposes only.
914:
915: The "Title Page" means, for a printed book, the title page itself,
916: plus such following pages as are needed to hold, legibly, the
917: material this License requires to appear in the title page. For
918: works in formats which do not have any title page as such, "Title
919: Page" means the text near the most prominent appearance of the
920: work's title, preceding the beginning of the body of the text.
921:
922: The "publisher" means any person or entity that distributes copies
923: of the Document to the public.
924:
925: A section "Entitled XYZ" means a named subunit of the Document
926: whose title either is precisely XYZ or contains XYZ in parentheses
927: following text that translates XYZ in another language. (Here XYZ
928: stands for a specific section name mentioned below, such as
929: "Acknowledgements", "Dedications", "Endorsements", or "History".)
930: To "Preserve the Title" of such a section when you modify the
931: Document means that it remains a section "Entitled XYZ" according
932: to this definition.
933:
934: The Document may include Warranty Disclaimers next to the notice
935: which states that this License applies to the Document. These
936: Warranty Disclaimers are considered to be included by reference in
937: this License, but only as regards disclaiming warranties: any other
938: implication that these Warranty Disclaimers may have is void and
939: has no effect on the meaning of this License.
940:
941: 2. VERBATIM COPYING
942:
943: You may copy and distribute the Document in any medium, either
944: commercially or noncommercially, provided that this License, the
945: copyright notices, and the license notice saying this License
946: applies to the Document are reproduced in all copies, and that you
947: add no other conditions whatsoever to those of this License. You
948: may not use technical measures to obstruct or control the reading
949: or further copying of the copies you make or distribute. However,
950: you may accept compensation in exchange for copies. If you
951: distribute a large enough number of copies you must also follow the
952: conditions in section 3.
953:
954: You may also lend copies, under the same conditions stated above,
955: and you may publicly display copies.
956:
957: 3. COPYING IN QUANTITY
958:
959: If you publish printed copies (or copies in media that commonly
960: have printed covers) of the Document, numbering more than 100, and
961: the Document's license notice requires Cover Texts, you must
962: enclose the copies in covers that carry, clearly and legibly, all
963: these Cover Texts: Front-Cover Texts on the front cover, and
964: Back-Cover Texts on the back cover. Both covers must also clearly
965: and legibly identify you as the publisher of these copies. The
966: front cover must present the full title with all words of the title
967: equally prominent and visible. You may add other material on the
968: covers in addition. Copying with changes limited to the covers, as
969: long as they preserve the title of the Document and satisfy these
970: conditions, can be treated as verbatim copying in other respects.
971:
972: If the required texts for either cover are too voluminous to fit
973: legibly, you should put the first ones listed (as many as fit
974: reasonably) on the actual cover, and continue the rest onto
975: adjacent pages.
976:
977: If you publish or distribute Opaque copies of the Document
978: numbering more than 100, you must either include a machine-readable
979: Transparent copy along with each Opaque copy, or state in or with
980: each Opaque copy a computer-network location from which the general
981: network-using public has access to download using public-standard
982: network protocols a complete Transparent copy of the Document, free
983: of added material. If you use the latter option, you must take
984: reasonably prudent steps, when you begin distribution of Opaque
985: copies in quantity, to ensure that this Transparent copy will
986: remain thus accessible at the stated location until at least one
987: year after the last time you distribute an Opaque copy (directly or
988: through your agents or retailers) of that edition to the public.
989:
990: It is requested, but not required, that you contact the authors of
991: the Document well before redistributing any large number of copies,
992: to give them a chance to provide you with an updated version of the
993: Document.
994:
995: 4. MODIFICATIONS
996:
997: You may copy and distribute a Modified Version of the Document
998: under the conditions of sections 2 and 3 above, provided that you
999: release the Modified Version under precisely this License, with the
1000: Modified Version filling the role of the Document, thus licensing
1001: distribution and modification of the Modified Version to whoever
1002: possesses a copy of it. In addition, you must do these things in
1003: the Modified Version:
1004:
1005: A. Use in the Title Page (and on the covers, if any) a title
1006: distinct from that of the Document, and from those of previous
1007: versions (which should, if there were any, be listed in the
1008: History section of the Document). You may use the same title
1009: as a previous version if the original publisher of that
1010: version gives permission.
1011:
1012: B. List on the Title Page, as authors, one or more persons or
1013: entities responsible for authorship of the modifications in
1014: the Modified Version, together with at least five of the
1015: principal authors of the Document (all of its principal
1016: authors, if it has fewer than five), unless they release you
1017: from this requirement.
1018:
1019: C. State on the Title page the name of the publisher of the
1020: Modified Version, as the publisher.
1021:
1022: D. Preserve all the copyright notices of the Document.
1023:
1024: E. Add an appropriate copyright notice for your modifications
1025: adjacent to the other copyright notices.
1026:
1027: F. Include, immediately after the copyright notices, a license
1028: notice giving the public permission to use the Modified
1029: Version under the terms of this License, in the form shown in
1030: the Addendum below.
1031:
1032: G. Preserve in that license notice the full lists of Invariant
1033: Sections and required Cover Texts given in the Document's
1034: license notice.
1035:
1036: H. Include an unaltered copy of this License.
1037:
1038: I. Preserve the section Entitled "History", Preserve its Title,
1039: and add to it an item stating at least the title, year, new
1040: authors, and publisher of the Modified Version as given on the
1041: Title Page. If there is no section Entitled "History" in the
1042: Document, create one stating the title, year, authors, and
1043: publisher of the Document as given on its Title Page, then add
1044: an item describing the Modified Version as stated in the
1045: previous sentence.
1046:
1047: J. Preserve the network location, if any, given in the Document
1048: for public access to a Transparent copy of the Document, and
1049: likewise the network locations given in the Document for
1050: previous versions it was based on. These may be placed in the
1051: "History" section. You may omit a network location for a work
1052: that was published at least four years before the Document
1053: itself, or if the original publisher of the version it refers
1054: to gives permission.
1055:
1056: K. For any section Entitled "Acknowledgements" or "Dedications",
1057: Preserve the Title of the section, and preserve in the section
1058: all the substance and tone of each of the contributor
1059: acknowledgements and/or dedications given therein.
1060:
1061: L. Preserve all the Invariant Sections of the Document, unaltered
1062: in their text and in their titles. Section numbers or the
1063: equivalent are not considered part of the section titles.
1064:
1065: M. Delete any section Entitled "Endorsements". Such a section
1066: may not be included in the Modified Version.
1067:
1068: N. Do not retitle any existing section to be Entitled
1069: "Endorsements" or to conflict in title with any Invariant
1070: Section.
1071:
1072: O. Preserve any Warranty Disclaimers.
1073:
1074: If the Modified Version includes new front-matter sections or
1075: appendices that qualify as Secondary Sections and contain no
1076: material copied from the Document, you may at your option designate
1077: some or all of these sections as invariant. To do this, add their
1078: titles to the list of Invariant Sections in the Modified Version's
1079: license notice. These titles must be distinct from any other
1080: section titles.
1081:
1082: You may add a section Entitled "Endorsements", provided it contains
1083: nothing but endorsements of your Modified Version by various
1084: parties--for example, statements of peer review or that the text
1085: has been approved by an organization as the authoritative
1086: definition of a standard.
1087:
1088: You may add a passage of up to five words as a Front-Cover Text,
1089: and a passage of up to 25 words as a Back-Cover Text, to the end of
1090: the list of Cover Texts in the Modified Version. Only one passage
1091: of Front-Cover Text and one of Back-Cover Text may be added by (or
1092: through arrangements made by) any one entity. If the Document
1093: already includes a cover text for the same cover, previously added
1094: by you or by arrangement made by the same entity you are acting on
1095: behalf of, you may not add another; but you may replace the old
1096: one, on explicit permission from the previous publisher that added
1097: the old one.
1098:
1099: The author(s) and publisher(s) of the Document do not by this
1100: License give permission to use their names for publicity for or to
1101: assert or imply endorsement of any Modified Version.
1102:
1103: 5. COMBINING DOCUMENTS
1104:
1105: You may combine the Document with other documents released under
1106: this License, under the terms defined in section 4 above for
1107: modified versions, provided that you include in the combination all
1108: of the Invariant Sections of all of the original documents,
1109: unmodified, and list them all as Invariant Sections of your
1110: combined work in its license notice, and that you preserve all
1111: their Warranty Disclaimers.
1112:
1113: The combined work need only contain one copy of this License, and
1114: multiple identical Invariant Sections may be replaced with a single
1115: copy. If there are multiple Invariant Sections with the same name
1116: but different contents, make the title of each such section unique
1117: by adding at the end of it, in parentheses, the name of the
1118: original author or publisher of that section if known, or else a
1119: unique number. Make the same adjustment to the section titles in
1120: the list of Invariant Sections in the license notice of the
1121: combined work.
1122:
1123: In the combination, you must combine any sections Entitled
1124: "History" in the various original documents, forming one section
1125: Entitled "History"; likewise combine any sections Entitled
1126: "Acknowledgements", and any sections Entitled "Dedications". You
1127: must delete all sections Entitled "Endorsements."
1128:
1129: 6. COLLECTIONS OF DOCUMENTS
1130:
1131: You may make a collection consisting of the Document and other
1132: documents released under this License, and replace the individual
1133: copies of this License in the various documents with a single copy
1134: that is included in the collection, provided that you follow the
1135: rules of this License for verbatim copying of each of the documents
1136: in all other respects.
1137:
1138: You may extract a single document from such a collection, and
1139: distribute it individually under this License, provided you insert
1140: a copy of this License into the extracted document, and follow this
1141: License in all other respects regarding verbatim copying of that
1142: document.
1143:
1144: 7. AGGREGATION WITH INDEPENDENT WORKS
1145:
1146: A compilation of the Document or its derivatives with other
1147: separate and independent documents or works, in or on a volume of a
1148: storage or distribution medium, is called an "aggregate" if the
1149: copyright resulting from the compilation is not used to limit the
1150: legal rights of the compilation's users beyond what the individual
1151: works permit. When the Document is included in an aggregate, this
1152: License does not apply to the other works in the aggregate which
1153: are not themselves derivative works of the Document.
1154:
1155: If the Cover Text requirement of section 3 is applicable to these
1156: copies of the Document, then if the Document is less than one half
1157: of the entire aggregate, the Document's Cover Texts may be placed
1158: on covers that bracket the Document within the aggregate, or the
1159: electronic equivalent of covers if the Document is in electronic
1160: form. Otherwise they must appear on printed covers that bracket
1161: the whole aggregate.
1162:
1163: 8. TRANSLATION
1164:
1165: Translation is considered a kind of modification, so you may
1166: distribute translations of the Document under the terms of section
1167: 4. Replacing Invariant Sections with translations requires special
1168: permission from their copyright holders, but you may include
1169: translations of some or all Invariant Sections in addition to the
1170: original versions of these Invariant Sections. You may include a
1171: translation of this License, and all the license notices in the
1172: Document, and any Warranty Disclaimers, provided that you also
1173: include the original English version of this License and the
1174: original versions of those notices and disclaimers. In case of a
1175: disagreement between the translation and the original version of
1176: this License or a notice or disclaimer, the original version will
1177: prevail.
1178:
1179: If a section in the Document is Entitled "Acknowledgements",
1180: "Dedications", or "History", the requirement (section 4) to
1181: Preserve its Title (section 1) will typically require changing the
1182: actual title.
1183:
1184: 9. TERMINATION
1185:
1186: You may not copy, modify, sublicense, or distribute the Document
1187: except as expressly provided under this License. Any attempt
1188: otherwise to copy, modify, sublicense, or distribute it is void,
1189: and will automatically terminate your rights under this License.
1190:
1191: However, if you cease all violation of this License, then your
1192: license from a particular copyright holder is reinstated (a)
1193: provisionally, unless and until the copyright holder explicitly and
1194: finally terminates your license, and (b) permanently, if the
1195: copyright holder fails to notify you of the violation by some
1196: reasonable means prior to 60 days after the cessation.
1197:
1198: Moreover, your license from a particular copyright holder is
1199: reinstated permanently if the copyright holder notifies you of the
1200: violation by some reasonable means, this is the first time you have
1201: received notice of violation of this License (for any work) from
1202: that copyright holder, and you cure the violation prior to 30 days
1203: after your receipt of the notice.
1204:
1205: Termination of your rights under this section does not terminate
1206: the licenses of parties who have received copies or rights from you
1207: under this License. If your rights have been terminated and not
1208: permanently reinstated, receipt of a copy of some or all of the
1209: same material does not give you any rights to use it.
1210:
1211: 10. FUTURE REVISIONS OF THIS LICENSE
1212:
1213: The Free Software Foundation may publish new, revised versions of
1214: the GNU Free Documentation License from time to time. Such new
1215: versions will be similar in spirit to the present version, but may
1216: differ in detail to address new problems or concerns. See
1217: <http://www.gnu.org/copyleft/>.
1218:
1219: Each version of the License is given a distinguishing version
1220: number. If the Document specifies that a particular numbered
1221: version of this License "or any later version" applies to it, you
1222: have the option of following the terms and conditions either of
1223: that specified version or of any later version that has been
1224: published (not as a draft) by the Free Software Foundation. If the
1225: Document does not specify a version number of this License, you may
1226: choose any version ever published (not as a draft) by the Free
1227: Software Foundation. If the Document specifies that a proxy can
1228: decide which future versions of this License can be used, that
1229: proxy's public statement of acceptance of a version permanently
1230: authorizes you to choose that version for the Document.
1231:
1232: 11. RELICENSING
1233:
1234: "Massive Multiauthor Collaboration Site" (or "MMC Site") means any
1235: World Wide Web server that publishes copyrightable works and also
1236: provides prominent facilities for anybody to edit those works. A
1237: public wiki that anybody can edit is an example of such a server.
1238: A "Massive Multiauthor Collaboration" (or "MMC") contained in the
1239: site means any set of copyrightable works thus published on the MMC
1240: site.
1241:
1242: "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
1243: license published by Creative Commons Corporation, a not-for-profit
1244: corporation with a principal place of business in San Francisco,
1245: California, as well as future copyleft versions of that license
1246: published by that same organization.
1247:
1248: "Incorporate" means to publish or republish a Document, in whole or
1249: in part, as part of another Document.
1250:
1251: An MMC is "eligible for relicensing" if it is licensed under this
1252: License, and if all works that were first published under this
1253: License somewhere other than this MMC, and subsequently
1254: incorporated in whole or in part into the MMC, (1) had no cover
1255: texts or invariant sections, and (2) were thus incorporated prior
1256: to November 1, 2008.
1257:
1258: The operator of an MMC Site may republish an MMC contained in the
1259: site under CC-BY-SA on the same site at any time before August 1,
1260: 2009, provided the MMC is eligible for relicensing.
1261:
1262: ADDENDUM: How to use this License for your documents
1263: ====================================================
1264:
1265: To use this License in a document you have written, include a copy of
1266: the License in the document and put the following copyright and license
1267: notices just after the title page:
1268:
1269: Copyright (C) YEAR YOUR NAME.
1270: Permission is granted to copy, distribute and/or modify this document
1271: under the terms of the GNU Free Documentation License, Version 1.3
1272: or any later version published by the Free Software Foundation;
1273: with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
1274: Texts. A copy of the license is included in the section entitled ``GNU
1275: Free Documentation License''.
1276:
1277: If you have Invariant Sections, Front-Cover Texts and Back-Cover
1278: Texts, replace the "with...Texts." line with this:
1279:
1280: with the Invariant Sections being LIST THEIR TITLES, with
1281: the Front-Cover Texts being LIST, and with the Back-Cover Texts
1282: being LIST.
1283:
1284: If you have Invariant Sections without Cover Texts, or some other
1285: combination of the three, merge those two alternatives to suit the
1286: situation.
1287:
1288: If your document contains nontrivial examples of program code, we
1289: recommend releasing these examples in parallel under your choice of free
1290: software license, such as the GNU General Public License, to permit
1291: their use in free software.
1292:
1293:
1294: File: history.info, Node: Concept Index, Next: Function and Variable Index, Prev: GNU Free Documentation License, Up: Top
1295:
1296: Appendix B Concept Index
1297: ************************
1298:
1299: