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