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