Annotation of embedaddon/readline/doc/history.html, revision 1.1.1.2
1.1 misho 1: <HTML>
2: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
1.1.1.2 ! misho 3: <!-- Created on October, 30 2020 by texi2html 1.64 -->
1.1 misho 4: <!--
5: Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
6: Karl Berry <karl@freefriends.org>
7: Olaf Bachmann <obachman@mathematik.uni-kl.de>
8: and many others.
9: Maintained by: Olaf Bachmann <obachman@mathematik.uni-kl.de>
10: Send bugs and suggestions to <texi2html@mathematik.uni-kl.de>
11:
12: -->
13: <HEAD>
14: <TITLE>GNU History Library: </TITLE>
15:
16: <META NAME="description" CONTENT="GNU History Library: ">
17: <META NAME="keywords" CONTENT="GNU History Library: ">
18: <META NAME="resource-type" CONTENT="document">
19: <META NAME="distribution" CONTENT="global">
20: <META NAME="Generator" CONTENT="texi2html 1.64">
21:
22: </HEAD>
23:
24: <BODY LANG="" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000">
25:
26: <A NAME="SEC_Top"></A>
27: <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
28: <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
29: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
30: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC21">Index</A>]</TD>
31: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
32: </TR></TABLE>
33: <H1>GNU History Library</H1></P><P>
34:
35: This document describes the GNU History library, a programming tool that
36: provides a consistent user interface for recalling lines of previously
37: typed input.
38: </P><P>
39:
40: <BLOCKQUOTE><TABLE BORDER=0 CELLSPACING=0>
41: <TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC1">1. Using History Interactively</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">GNU History User's Manual.</TD></TR>
42: <TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC6">2. Programming with GNU History</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">GNU History Programmer's Manual.</TD></TR>
43: <TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC19">A. GNU Free Documentation License</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">License for copying this manual.</TD></TR>
44: <TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC21">B. Concept Index</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Index of concepts described in this manual.</TD></TR>
45: <TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC22">C. Function and Variable Index</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Index of externally visible functions
46: and variables.</TD></TR>
47: </TABLE></BLOCKQUOTE>
48: <P>
49:
50: <HR SIZE=1>
51: <A NAME="SEC1"></A>
52: <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
53: <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top"> < </A>]</TD>
54: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC2"> > </A>]</TD>
55: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
56: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top"> Up </A>]</TD>
57: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC6"> >> </A>]</TD>
58: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
59: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
60: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC21">Index</A>]</TD>
61: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
62: </TR></TABLE>
63: <A NAME="Using History Interactively"></A>
64: <H1> 1. Using History Interactively </H1>
65: <!--docid::SEC1::-->
66: <P>
67:
68: This chapter describes how to use the GNU History Library interactively,
69: from a user's standpoint. It should be considered a user's guide. For
70: information on using the GNU History Library in your own programs,
71: see section <A HREF="history.html#SEC6">2. Programming with GNU History</A>.
72: </P><P>
73:
74: <BLOCKQUOTE><TABLE BORDER=0 CELLSPACING=0>
75: <TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC2">1.1 History Expansion</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">What it feels like using History as a user.</TD></TR>
76: </TABLE></BLOCKQUOTE>
77: <P>
78:
79: <A NAME="History Interaction"></A>
80: <HR SIZE="6">
81: <A NAME="SEC2"></A>
82: <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
83: <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC1"> < </A>]</TD>
84: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC3"> > </A>]</TD>
85: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
86: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC1"> Up </A>]</TD>
87: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC6"> >> </A>]</TD>
88: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
89: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
90: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC21">Index</A>]</TD>
91: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
92: </TR></TABLE>
93: <H2> 1.1 History Expansion </H2>
94: <!--docid::SEC2::-->
95: <P>
96:
97: The History library provides a history expansion feature that is similar
98: to the history expansion provided by <CODE>csh</CODE>. This section
99: describes the syntax used to manipulate the history information.
100: </P><P>
101:
102: History expansions introduce words from the history list into
103: the input stream, making it easy to repeat commands, insert the
104: arguments to a previous command into the current input line, or
105: fix errors in previous commands quickly.
106: </P><P>
107:
108: History expansion takes place in two parts. The first is to determine
109: which line from the history list should be used during substitution.
110: The second is to select portions of that line for inclusion into the
111: current one. The line selected from the history is called the
112: <EM>event</EM>, and the portions of that line that are acted upon are
113: called <EM>words</EM>. Various <EM>modifiers</EM> are available to manipulate
114: the selected words. The line is broken into words in the same fashion
115: that Bash does, so that several words
116: surrounded by quotes are considered one word.
117: History expansions are introduced by the appearance of the
118: history expansion character, which is <SAMP>`!'</SAMP> by default.
119: </P><P>
120:
1.1.1.2 ! misho 121: History expansion implements shell-like quoting conventions:
! 122: a backslash can be used to remove the special handling for the next character;
! 123: single quotes enclose verbatim sequences of characters, and can be used to
! 124: inhibit history expansion;
! 125: and characters enclosed within double quotes may be subject to history
! 126: expansion, since backslash can escape the history expansion character,
! 127: but single quotes may not, since they are not treated specially within
! 128: double quotes.
! 129: </P><P>
! 130:
1.1 misho 131: <BLOCKQUOTE><TABLE BORDER=0 CELLSPACING=0>
132: <TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC3">1.1.1 Event Designators</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">How to specify which history line to use.</TD></TR>
133: <TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC4">1.1.2 Word Designators</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Specifying which words are of interest.</TD></TR>
134: <TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC5">1.1.3 Modifiers</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Modifying the results of substitution.</TD></TR>
135: </TABLE></BLOCKQUOTE>
136: <P>
137:
138: <A NAME="Event Designators"></A>
139: <HR SIZE="6">
140: <A NAME="SEC3"></A>
141: <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
142: <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC2"> < </A>]</TD>
143: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC4"> > </A>]</TD>
144: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
145: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC2"> Up </A>]</TD>
146: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC6"> >> </A>]</TD>
147: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
148: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
149: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC21">Index</A>]</TD>
150: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
151: </TR></TABLE>
152: <H3> 1.1.1 Event Designators </H3>
153: <!--docid::SEC3::-->
154: <P>
155:
156: An event designator is a reference to a command line entry in the
157: history list.
158: Unless the reference is absolute, events are relative to the current
159: position in the history list.
160: <A NAME="IDX1"></A>
161: </P><P>
162:
163: <DL COMPACT>
164:
165: <DT><CODE>!</CODE>
166: <DD>Start a history substitution, except when followed by a space, tab,
167: the end of the line, or <SAMP>`='</SAMP>.
168: <P>
169:
170: <DT><CODE>!<VAR>n</VAR></CODE>
171: <DD>Refer to command line <VAR>n</VAR>.
172: <P>
173:
174: <DT><CODE>!-<VAR>n</VAR></CODE>
175: <DD>Refer to the command <VAR>n</VAR> lines back.
176: <P>
177:
178: <DT><CODE>!!</CODE>
179: <DD>Refer to the previous command. This is a synonym for <SAMP>`!-1'</SAMP>.
180: <P>
181:
182: <DT><CODE>!<VAR>string</VAR></CODE>
183: <DD>Refer to the most recent command
184: preceding the current position in the history list
185: starting with <VAR>string</VAR>.
186: <P>
187:
188: <DT><CODE>!?<VAR>string</VAR>[?]</CODE>
189: <DD>Refer to the most recent command
190: preceding the current position in the history list
191: containing <VAR>string</VAR>.
192: The trailing
193: <SAMP>`?'</SAMP> may be omitted if the <VAR>string</VAR> is followed immediately by
194: a newline.
1.1.1.2 ! misho 195: If <VAR>string</VAR> is missing, the string from the most recent search is used;
! 196: it is an error if there is no previous search string.
1.1 misho 197: <P>
198:
199: <DT><CODE>^<VAR>string1</VAR>^<VAR>string2</VAR>^</CODE>
200: <DD>Quick Substitution. Repeat the last command, replacing <VAR>string1</VAR>
201: with <VAR>string2</VAR>. Equivalent to
1.1.1.2 ! misho 202: <CODE>!!:s^<VAR>string1</VAR>^<VAR>string2</VAR>^</CODE>.
1.1 misho 203: <P>
204:
205: <DT><CODE>!#</CODE>
206: <DD>The entire command line typed so far.
207: <P>
208:
209: </DL>
210: <P>
211:
212: <A NAME="Word Designators"></A>
213: <HR SIZE="6">
214: <A NAME="SEC4"></A>
215: <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
216: <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC3"> < </A>]</TD>
217: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC5"> > </A>]</TD>
218: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC5"> << </A>]</TD>
219: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC2"> Up </A>]</TD>
220: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC6"> >> </A>]</TD>
221: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
222: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
223: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC21">Index</A>]</TD>
224: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
225: </TR></TABLE>
226: <H3> 1.1.2 Word Designators </H3>
227: <!--docid::SEC4::-->
228: <P>
229:
230: Word designators are used to select desired words from the event.
231: A <SAMP>`:'</SAMP> separates the event specification from the word designator. It
232: may be omitted if the word designator begins with a <SAMP>`^'</SAMP>, <SAMP>`$'</SAMP>,
233: <SAMP>`*'</SAMP>, <SAMP>`-'</SAMP>, or <SAMP>`%'</SAMP>. Words are numbered from the beginning
234: of the line, with the first word being denoted by 0 (zero). Words are
235: inserted into the current line separated by single spaces.
236: </P><P>
237:
238: For example,
239: </P><P>
240:
241: <DL COMPACT>
242: <DT><CODE>!!</CODE>
243: <DD>designates the preceding command. When you type this, the preceding
244: command is repeated in toto.
245: <P>
246:
247: <DT><CODE>!!:$</CODE>
248: <DD>designates the last argument of the preceding command. This may be
249: shortened to <CODE>!$</CODE>.
250: <P>
251:
252: <DT><CODE>!fi:2</CODE>
253: <DD>designates the second argument of the most recent command starting with
254: the letters <CODE>fi</CODE>.
255: </DL>
256: <P>
257:
258: Here are the word designators:
259:
260: <DL COMPACT>
261:
262: <DT><CODE>0 (zero)</CODE>
263: <DD>The <CODE>0</CODE>th word. For many applications, this is the command word.
264: <P>
265:
266: <DT><CODE><VAR>n</VAR></CODE>
267: <DD>The <VAR>n</VAR>th word.
268: <P>
269:
270: <DT><CODE>^</CODE>
271: <DD>The first argument; that is, word 1.
272: <P>
273:
274: <DT><CODE>$</CODE>
275: <DD>The last argument.
276: <P>
277:
278: <DT><CODE>%</CODE>
1.1.1.2 ! misho 279: <DD>The first word matched by the most recent <SAMP>`?<VAR>string</VAR>?'</SAMP> search,
! 280: if the search string begins with a character that is part of a word.
1.1 misho 281: <P>
282:
283: <DT><CODE><VAR>x</VAR>-<VAR>y</VAR></CODE>
284: <DD>A range of words; <SAMP>`-<VAR>y</VAR>'</SAMP> abbreviates <SAMP>`0-<VAR>y</VAR>'</SAMP>.
285: <P>
286:
287: <DT><CODE>*</CODE>
288: <DD>All of the words, except the <CODE>0</CODE>th. This is a synonym for <SAMP>`1-$'</SAMP>.
289: It is not an error to use <SAMP>`*'</SAMP> if there is just one word in the event;
290: the empty string is returned in that case.
291: <P>
292:
293: <DT><CODE><VAR>x</VAR>*</CODE>
294: <DD>Abbreviates <SAMP>`<VAR>x</VAR>-$'</SAMP>
295: <P>
296:
297: <DT><CODE><VAR>x</VAR>-</CODE>
298: <DD>Abbreviates <SAMP>`<VAR>x</VAR>-$'</SAMP> like <SAMP>`<VAR>x</VAR>*'</SAMP>, but omits the last word.
1.1.1.2 ! misho 299: If <SAMP>`x'</SAMP> is missing, it defaults to 0.
1.1 misho 300: <P>
301:
302: </DL>
303: <P>
304:
305: If a word designator is supplied without an event specification, the
306: previous command is used as the event.
307: </P><P>
308:
309: <A NAME="Modifiers"></A>
310: <HR SIZE="6">
311: <A NAME="SEC5"></A>
312: <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
313: <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC4"> < </A>]</TD>
314: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC6"> > </A>]</TD>
315: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
316: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC2"> Up </A>]</TD>
317: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC6"> >> </A>]</TD>
318: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
319: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
320: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC21">Index</A>]</TD>
321: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
322: </TR></TABLE>
323: <H3> 1.1.3 Modifiers </H3>
324: <!--docid::SEC5::-->
325: <P>
326:
327: After the optional word designator, you can add a sequence of one or more
328: of the following modifiers, each preceded by a <SAMP>`:'</SAMP>.
1.1.1.2 ! misho 329: These modify, or edit, the word or words selected from the history event.
1.1 misho 330: </P><P>
331:
332: <DL COMPACT>
333:
334: <DT><CODE>h</CODE>
335: <DD>Remove a trailing pathname component, leaving only the head.
336: <P>
337:
338: <DT><CODE>t</CODE>
339: <DD>Remove all leading pathname components, leaving the tail.
340: <P>
341:
342: <DT><CODE>r</CODE>
343: <DD>Remove a trailing suffix of the form <SAMP>`.<VAR>suffix</VAR>'</SAMP>, leaving
344: the basename.
345: <P>
346:
347: <DT><CODE>e</CODE>
348: <DD>Remove all but the trailing suffix.
349: <P>
350:
351: <DT><CODE>p</CODE>
352: <DD>Print the new command but do not execute it.
353: <P>
354:
355: <DT><CODE>s/<VAR>old</VAR>/<VAR>new</VAR>/</CODE>
356: <DD>Substitute <VAR>new</VAR> for the first occurrence of <VAR>old</VAR> in the
1.1.1.2 ! misho 357: event line.
! 358: Any character may be used as the delimiter in place of <SAMP>`/'</SAMP>.
1.1 misho 359: The delimiter may be quoted in <VAR>old</VAR> and <VAR>new</VAR>
360: with a single backslash. If <SAMP>`&'</SAMP> appears in <VAR>new</VAR>,
361: it is replaced by <VAR>old</VAR>. A single backslash will quote
1.1.1.2 ! misho 362: the <SAMP>`&'</SAMP>.
! 363: If <VAR>old</VAR> is null, it is set to the last <VAR>old</VAR>
! 364: substituted, or, if no previous history substitutions took place,
! 365: the last <VAR>string</VAR>
! 366: in a !?<VAR>string</VAR><CODE>[?]</CODE>
! 367: search.
! 368: If <VAR>new</VAR> is is null, each matching <VAR>old</VAR> is deleted.
! 369: The final delimiter is optional if it is the last
1.1 misho 370: character on the input line.
371: <P>
372:
373: <DT><CODE>&</CODE>
374: <DD>Repeat the previous substitution.
375: <P>
376:
377: <DT><CODE>g</CODE>
378: <DD><DT><CODE>a</CODE>
379: <DD>Cause changes to be applied over the entire event line. Used in
380: conjunction with <SAMP>`s'</SAMP>, as in <CODE>gs/<VAR>old</VAR>/<VAR>new</VAR>/</CODE>,
381: or with <SAMP>`&'</SAMP>.
382: <P>
383:
384: <DT><CODE>G</CODE>
1.1.1.2 ! misho 385: <DD>Apply the following <SAMP>`s'</SAMP> or <SAMP>`&'</SAMP> modifier once to each word
! 386: in the event.
1.1 misho 387: <P>
388:
389: </DL>
390: <P>
391:
392: <A NAME="Programming with GNU History"></A>
393: <HR SIZE="6">
394: <A NAME="SEC6"></A>
395: <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
396: <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC5"> < </A>]</TD>
397: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC7"> > </A>]</TD>
398: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
399: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top"> Up </A>]</TD>
400: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19"> >> </A>]</TD>
401: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
402: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
403: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC21">Index</A>]</TD>
404: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
405: </TR></TABLE>
406: <H1> 2. Programming with GNU History </H1>
407: <!--docid::SEC6::-->
408: <P>
409:
410: This chapter describes how to interface programs that you write
411: with the GNU History Library.
412: It should be considered a technical guide.
413: For information on the interactive use of GNU History, see section <A HREF="history.html#SEC1">1. Using History Interactively</A>.
414: </P><P>
415:
416: <BLOCKQUOTE><TABLE BORDER=0 CELLSPACING=0>
417: <TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC7">2.1 Introduction to History</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">What is the GNU History library for?</TD></TR>
418: <TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC8">2.2 History Storage</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">How information is stored.</TD></TR>
419: <TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC9">2.3 History Functions</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Functions that you can use.</TD></TR>
420: <TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC17">2.4 History Variables</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Variables that control behaviour.</TD></TR>
421: <TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC18">2.5 History Programming Example</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Example of using the GNU History Library.</TD></TR>
422: </TABLE></BLOCKQUOTE>
423: <P>
424:
425: <A NAME="Introduction to History"></A>
426: <HR SIZE="6">
427: <A NAME="SEC7"></A>
428: <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
429: <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC6"> < </A>]</TD>
430: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC8"> > </A>]</TD>
431: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
432: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC6"> Up </A>]</TD>
433: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19"> >> </A>]</TD>
434: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
435: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
436: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC21">Index</A>]</TD>
437: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
438: </TR></TABLE>
439: <H2> 2.1 Introduction to History </H2>
440: <!--docid::SEC7::-->
441: <P>
442:
443: Many programs read input from the user a line at a time. The GNU
444: History library is able to keep track of those lines, associate arbitrary
445: data with each line, and utilize information from previous lines in
446: composing new ones.
447: </P><P>
448:
1.1.1.2 ! misho 449: A programmer using the History library has available functions
1.1 misho 450: for remembering lines on a history list, associating arbitrary data
451: with a line, removing lines from the list, searching through the list
452: for a line containing an arbitrary text string, and referencing any line
453: in the list directly. In addition, a history <EM>expansion</EM> function
454: is available which provides for a consistent user interface across
455: different programs.
456: </P><P>
457:
458: The user using programs written with the History library has the
459: benefit of a consistent user interface with a set of well-known
460: commands for manipulating the text of previous lines and using that text
461: in new commands. The basic history manipulation commands are similar to
462: the history substitution provided by <CODE>csh</CODE>.
463: </P><P>
464:
1.1.1.2 ! misho 465: The programmer can also use the Readline library, which
1.1 misho 466: includes some history manipulation by default, and has the added
467: advantage of command line editing.
468: </P><P>
469:
470: Before declaring any functions using any functionality the History
471: library provides in other code, an application writer should include
472: the file <CODE><readline/history.h></CODE> in any file that uses the
473: History library's features. It supplies extern declarations for all
474: of the library's public functions and variables, and declares all of
475: the public data structures.
476: </P><P>
477:
478: <A NAME="History Storage"></A>
479: <HR SIZE="6">
480: <A NAME="SEC8"></A>
481: <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
482: <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC7"> < </A>]</TD>
483: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC9"> > </A>]</TD>
484: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC9"> << </A>]</TD>
485: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC6"> Up </A>]</TD>
486: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19"> >> </A>]</TD>
487: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
488: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
489: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC21">Index</A>]</TD>
490: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
491: </TR></TABLE>
492: <H2> 2.2 History Storage </H2>
493: <!--docid::SEC8::-->
494: <P>
495:
496: The history list is an array of history entries. A history entry is
497: declared as follows:
498: </P><P>
499:
500: <TABLE><tr><td> </td><td class=example><pre>typedef void *histdata_t;
501:
502: typedef struct _hist_entry {
503: char *line;
504: char *timestamp;
505: histdata_t data;
506: } HIST_ENTRY;
507: </pre></td></tr></table></P><P>
508:
509: The history list itself might therefore be declared as
510: </P><P>
511:
512: <TABLE><tr><td> </td><td class=example><pre>HIST_ENTRY **the_history_list;
513: </pre></td></tr></table></P><P>
514:
515: The state of the History library is encapsulated into a single structure:
516: </P><P>
517:
518: <TABLE><tr><td> </td><td class=example><pre>/*
519: * A structure used to pass around the current state of the history.
520: */
521: typedef struct _hist_state {
522: HIST_ENTRY **entries; /* Pointer to the entries themselves. */
523: int offset; /* The location pointer within this array. */
524: int length; /* Number of elements within this array. */
525: int size; /* Number of slots allocated to this array. */
526: int flags;
527: } HISTORY_STATE;
528: </pre></td></tr></table></P><P>
529:
530: If the flags member includes <CODE>HS_STIFLED</CODE>, the history has been
531: stifled.
532: </P><P>
533:
534: <A NAME="History Functions"></A>
535: <HR SIZE="6">
536: <A NAME="SEC9"></A>
537: <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
538: <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC8"> < </A>]</TD>
539: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC10"> > </A>]</TD>
540: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> << </A>]</TD>
541: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC6"> Up </A>]</TD>
542: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> >> </A>]</TD>
543: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
544: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
545: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC21">Index</A>]</TD>
546: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
547: </TR></TABLE>
548: <H2> 2.3 History Functions </H2>
549: <!--docid::SEC9::-->
550: <P>
551:
552: This section describes the calling sequence for the various functions
553: exported by the GNU History library.
554: </P><P>
555:
556: <BLOCKQUOTE><TABLE BORDER=0 CELLSPACING=0>
557: <TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC10">2.3.1 Initializing History and State Management</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Functions to call when you
558: want to use history in a
559: program.</TD></TR>
560: <TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC11">2.3.2 History List Management</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Functions used to manage the list
561: of history entries.</TD></TR>
562: <TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC12">2.3.3 Information About the History List</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Functions returning information about
563: the history list.</TD></TR>
564: <TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC13">2.3.4 Moving Around the History List</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Functions used to change the position
565: in the history list.</TD></TR>
566: <TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC14">2.3.5 Searching the History List</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Functions to search the history list
567: for entries containing a string.</TD></TR>
568: <TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC15">2.3.6 Managing the History File</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Functions that read and write a file
569: containing the history list.</TD></TR>
570: <TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC16">2.3.7 History Expansion</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Functions to perform csh-like history
571: expansion.</TD></TR>
572: </TABLE></BLOCKQUOTE>
573: <P>
574:
575: <A NAME="Initializing History and State Management"></A>
576: <HR SIZE="6">
577: <A NAME="SEC10"></A>
578: <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
579: <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC9"> < </A>]</TD>
580: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC11"> > </A>]</TD>
581: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> << </A>]</TD>
582: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC9"> Up </A>]</TD>
583: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> >> </A>]</TD>
584: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
585: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
586: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC21">Index</A>]</TD>
587: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
588: </TR></TABLE>
589: <H3> 2.3.1 Initializing History and State Management </H3>
590: <!--docid::SEC10::-->
591: <P>
592:
593: This section describes functions used to initialize and manage
594: the state of the History library when you want to use the history
595: functions in your program.
596: </P><P>
597:
598: <A NAME="IDX2"></A>
599: <DL>
600: <DT><U>Function:</U> void <B>using_history</B> <I>(void)</I>
601: <DD>Begin a session in which the history functions might be used. This
602: initializes the interactive variables.
603: </DL>
604: </P><P>
605:
606: <A NAME="IDX3"></A>
607: <DL>
608: <DT><U>Function:</U> HISTORY_STATE * <B>history_get_history_state</B> <I>(void)</I>
609: <DD>Return a structure describing the current state of the input history.
610: </DL>
611: </P><P>
612:
613: <A NAME="IDX4"></A>
614: <DL>
615: <DT><U>Function:</U> void <B>history_set_history_state</B> <I>(HISTORY_STATE *state)</I>
616: <DD>Set the state of the history list according to <VAR>state</VAR>.
617: </DL>
618: </P><P>
619:
620: <A NAME="History List Management"></A>
621: <HR SIZE="6">
622: <A NAME="SEC11"></A>
623: <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
624: <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC10"> < </A>]</TD>
625: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC12"> > </A>]</TD>
626: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC12"> << </A>]</TD>
627: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC9"> Up </A>]</TD>
628: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> >> </A>]</TD>
629: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
630: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
631: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC21">Index</A>]</TD>
632: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
633: </TR></TABLE>
634: <H3> 2.3.2 History List Management </H3>
635: <!--docid::SEC11::-->
636: <P>
637:
638: These functions manage individual entries on the history list, or set
639: parameters managing the list itself.
640: </P><P>
641:
642: <A NAME="IDX5"></A>
643: <DL>
644: <DT><U>Function:</U> void <B>add_history</B> <I>(const char *string)</I>
645: <DD>Place <VAR>string</VAR> at the end of the history list. The associated data
646: field (if any) is set to <CODE>NULL</CODE>.
1.1.1.2 ! misho 647: If the maximum number of history entries has been set using
! 648: <CODE>stifle_history()</CODE>, and the new number of history entries would exceed
! 649: that maximum, the oldest history entry is removed.
1.1 misho 650: </DL>
651: </P><P>
652:
653: <A NAME="IDX6"></A>
654: <DL>
655: <DT><U>Function:</U> void <B>add_history_time</B> <I>(const char *string)</I>
656: <DD>Change the time stamp associated with the most recent history entry to
657: <VAR>string</VAR>.
658: </DL>
659: </P><P>
660:
661: <A NAME="IDX7"></A>
662: <DL>
663: <DT><U>Function:</U> HIST_ENTRY * <B>remove_history</B> <I>(int which)</I>
664: <DD>Remove history entry at offset <VAR>which</VAR> from the history. The
665: removed element is returned so you can free the line, data,
666: and containing structure.
667: </DL>
668: </P><P>
669:
670: <A NAME="IDX8"></A>
671: <DL>
672: <DT><U>Function:</U> histdata_t <B>free_history_entry</B> <I>(HIST_ENTRY *histent)</I>
673: <DD>Free the history entry <VAR>histent</VAR> and any history library private
674: data associated with it. Returns the application-specific data
675: so the caller can dispose of it.
676: </DL>
677: </P><P>
678:
679: <A NAME="IDX9"></A>
680: <DL>
681: <DT><U>Function:</U> HIST_ENTRY * <B>replace_history_entry</B> <I>(int which, const char *line, histdata_t data)</I>
682: <DD>Make the history entry at offset <VAR>which</VAR> have <VAR>line</VAR> and <VAR>data</VAR>.
683: This returns the old entry so the caller can dispose of any
684: application-specific data. In the case
685: of an invalid <VAR>which</VAR>, a <CODE>NULL</CODE> pointer is returned.
686: </DL>
687: </P><P>
688:
689: <A NAME="IDX10"></A>
690: <DL>
691: <DT><U>Function:</U> void <B>clear_history</B> <I>(void)</I>
692: <DD>Clear the history list by deleting all the entries.
693: </DL>
694: </P><P>
695:
696: <A NAME="IDX11"></A>
697: <DL>
698: <DT><U>Function:</U> void <B>stifle_history</B> <I>(int max)</I>
699: <DD>Stifle the history list, remembering only the last <VAR>max</VAR> entries.
1.1.1.2 ! misho 700: The history list will contain only <VAR>max</VAR> entries at a time.
1.1 misho 701: </DL>
702: </P><P>
703:
704: <A NAME="IDX12"></A>
705: <DL>
706: <DT><U>Function:</U> int <B>unstifle_history</B> <I>(void)</I>
707: <DD>Stop stifling the history. This returns the previously-set
708: maximum number of history entries (as set by <CODE>stifle_history()</CODE>).
709: The value is positive if the history was
710: stifled, negative if it wasn't.
711: </DL>
712: </P><P>
713:
714: <A NAME="IDX13"></A>
715: <DL>
716: <DT><U>Function:</U> int <B>history_is_stifled</B> <I>(void)</I>
717: <DD>Returns non-zero if the history is stifled, zero if it is not.
718: </DL>
719: </P><P>
720:
721: <A NAME="Information About the History List"></A>
722: <HR SIZE="6">
723: <A NAME="SEC12"></A>
724: <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
725: <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC11"> < </A>]</TD>
726: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC13"> > </A>]</TD>
727: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC13"> << </A>]</TD>
728: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC9"> Up </A>]</TD>
729: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> >> </A>]</TD>
730: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
731: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
732: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC21">Index</A>]</TD>
733: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
734: </TR></TABLE>
735: <H3> 2.3.3 Information About the History List </H3>
736: <!--docid::SEC12::-->
737: <P>
738:
739: These functions return information about the entire history list or
740: individual list entries.
741: </P><P>
742:
743: <A NAME="IDX14"></A>
744: <DL>
745: <DT><U>Function:</U> HIST_ENTRY ** <B>history_list</B> <I>(void)</I>
746: <DD>Return a <CODE>NULL</CODE> terminated array of <CODE>HIST_ENTRY *</CODE> which is the
747: current input history. Element 0 of this list is the beginning of time.
748: If there is no history, return <CODE>NULL</CODE>.
749: </DL>
750: </P><P>
751:
752: <A NAME="IDX15"></A>
753: <DL>
754: <DT><U>Function:</U> int <B>where_history</B> <I>(void)</I>
755: <DD>Returns the offset of the current history element.
756: </DL>
757: </P><P>
758:
759: <A NAME="IDX16"></A>
760: <DL>
761: <DT><U>Function:</U> HIST_ENTRY * <B>current_history</B> <I>(void)</I>
762: <DD>Return the history entry at the current position, as determined by
763: <CODE>where_history()</CODE>. If there is no entry there, return a <CODE>NULL</CODE>
764: pointer.
765: </DL>
766: </P><P>
767:
768: <A NAME="IDX17"></A>
769: <DL>
770: <DT><U>Function:</U> HIST_ENTRY * <B>history_get</B> <I>(int offset)</I>
1.1.1.2 ! misho 771: <DD>Return the history entry at position <VAR>offset</VAR>.
! 772: The range of valid
! 773: values of <VAR>offset</VAR> starts at <CODE>history_base</CODE> and ends at
! 774: <VAR>history_length</VAR> - 1 (see section <A HREF="history.html#SEC17">2.4 History Variables</A>).
! 775: If there is no entry there, or if <VAR>offset</VAR> is outside the valid
! 776: range, return a <CODE>NULL</CODE> pointer.
1.1 misho 777: </DL>
778: </P><P>
779:
780: <A NAME="IDX18"></A>
781: <DL>
782: <DT><U>Function:</U> time_t <B>history_get_time</B> <I>(HIST_ENTRY *entry)</I>
783: <DD>Return the time stamp associated with the history entry <VAR>entry</VAR>.
1.1.1.2 ! misho 784: If the timestamp is missing or invalid, return 0.
1.1 misho 785: </DL>
786: </P><P>
787:
788: <A NAME="IDX19"></A>
789: <DL>
790: <DT><U>Function:</U> int <B>history_total_bytes</B> <I>(void)</I>
791: <DD>Return the number of bytes that the primary history entries are using.
792: This function returns the sum of the lengths of all the lines in the
793: history.
794: </DL>
795: </P><P>
796:
797: <A NAME="Moving Around the History List"></A>
798: <HR SIZE="6">
799: <A NAME="SEC13"></A>
800: <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
801: <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC12"> < </A>]</TD>
802: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC14"> > </A>]</TD>
803: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC14"> << </A>]</TD>
804: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC9"> Up </A>]</TD>
805: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> >> </A>]</TD>
806: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
807: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
808: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC21">Index</A>]</TD>
809: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
810: </TR></TABLE>
811: <H3> 2.3.4 Moving Around the History List </H3>
812: <!--docid::SEC13::-->
813: <P>
814:
815: These functions allow the current index into the history list to be
816: set or changed.
817: </P><P>
818:
819: <A NAME="IDX20"></A>
820: <DL>
821: <DT><U>Function:</U> int <B>history_set_pos</B> <I>(int pos)</I>
822: <DD>Set the current history offset to <VAR>pos</VAR>, an absolute index
823: into the list.
824: Returns 1 on success, 0 if <VAR>pos</VAR> is less than zero or greater
825: than the number of history entries.
826: </DL>
827: </P><P>
828:
829: <A NAME="IDX21"></A>
830: <DL>
831: <DT><U>Function:</U> HIST_ENTRY * <B>previous_history</B> <I>(void)</I>
832: <DD>Back up the current history offset to the previous history entry, and
833: return a pointer to that entry. If there is no previous entry, return
834: a <CODE>NULL</CODE> pointer.
835: </DL>
836: </P><P>
837:
838: <A NAME="IDX22"></A>
839: <DL>
840: <DT><U>Function:</U> HIST_ENTRY * <B>next_history</B> <I>(void)</I>
1.1.1.2 ! misho 841: <DD>If the current history offset refers to a valid history entry,
! 842: increment the current history offset.
! 843: If the possibly-incremented history offset refers to a valid history
! 844: entry, return a pointer to that entry;
! 845: otherwise, return a <CODE>BNULL</CODE> pointer.
1.1 misho 846: </DL>
847: </P><P>
848:
849: <A NAME="Searching the History List"></A>
850: <HR SIZE="6">
851: <A NAME="SEC14"></A>
852: <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
853: <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC13"> < </A>]</TD>
854: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC15"> > </A>]</TD>
855: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC15"> << </A>]</TD>
856: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC9"> Up </A>]</TD>
857: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> >> </A>]</TD>
858: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
859: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
860: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC21">Index</A>]</TD>
861: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
862: </TR></TABLE>
863: <H3> 2.3.5 Searching the History List </H3>
864: <!--docid::SEC14::-->
865: <P>
866:
867: These functions allow searching of the history list for entries containing
868: a specific string. Searching may be performed both forward and backward
869: from the current history position. The search may be <EM>anchored</EM>,
870: meaning that the string must match at the beginning of the history entry.
871: <A NAME="IDX23"></A>
872: </P><P>
873:
874: <A NAME="IDX24"></A>
875: <DL>
876: <DT><U>Function:</U> int <B>history_search</B> <I>(const char *string, int direction)</I>
877: <DD>Search the history for <VAR>string</VAR>, starting at the current history offset.
878: If <VAR>direction</VAR> is less than 0, then the search is through
879: previous entries, otherwise through subsequent entries.
880: If <VAR>string</VAR> is found, then
881: the current history index is set to that history entry, and the value
882: returned is the offset in the line of the entry where
883: <VAR>string</VAR> was found. Otherwise, nothing is changed, and a -1 is
884: returned.
885: </DL>
886: </P><P>
887:
888: <A NAME="IDX25"></A>
889: <DL>
890: <DT><U>Function:</U> int <B>history_search_prefix</B> <I>(const char *string, int direction)</I>
891: <DD>Search the history for <VAR>string</VAR>, starting at the current history
892: offset. The search is anchored: matching lines must begin with
893: <VAR>string</VAR>. If <VAR>direction</VAR> is less than 0, then the search is
894: through previous entries, otherwise through subsequent entries.
895: If <VAR>string</VAR> is found, then the
896: current history index is set to that entry, and the return value is 0.
897: Otherwise, nothing is changed, and a -1 is returned.
898: </DL>
899: </P><P>
900:
901: <A NAME="IDX26"></A>
902: <DL>
903: <DT><U>Function:</U> int <B>history_search_pos</B> <I>(const char *string, int direction, int pos)</I>
904: <DD>Search for <VAR>string</VAR> in the history list, starting at <VAR>pos</VAR>, an
905: absolute index into the list. If <VAR>direction</VAR> is negative, the search
906: proceeds backward from <VAR>pos</VAR>, otherwise forward. Returns the absolute
907: index of the history element where <VAR>string</VAR> was found, or -1 otherwise.
908: </DL>
909: </P><P>
910:
911: <A NAME="Managing the History File"></A>
912: <HR SIZE="6">
913: <A NAME="SEC15"></A>
914: <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
915: <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC14"> < </A>]</TD>
916: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC16"> > </A>]</TD>
917: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC16"> << </A>]</TD>
918: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC9"> Up </A>]</TD>
919: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> >> </A>]</TD>
920: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
921: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
922: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC21">Index</A>]</TD>
923: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
924: </TR></TABLE>
925: <H3> 2.3.6 Managing the History File </H3>
926: <!--docid::SEC15::-->
927: <P>
928:
929: The History library can read the history from and write it to a file.
930: This section documents the functions for managing a history file.
931: </P><P>
932:
933: <A NAME="IDX27"></A>
934: <DL>
935: <DT><U>Function:</U> int <B>read_history</B> <I>(const char *filename)</I>
936: <DD>Add the contents of <VAR>filename</VAR> to the history list, a line at a time.
937: If <VAR>filename</VAR> is <CODE>NULL</CODE>, then read from <TT>`~/.history'</TT>.
938: Returns 0 if successful, or <CODE>errno</CODE> if not.
939: </DL>
940: </P><P>
941:
942: <A NAME="IDX28"></A>
943: <DL>
944: <DT><U>Function:</U> int <B>read_history_range</B> <I>(const char *filename, int from, int to)</I>
945: <DD>Read a range of lines from <VAR>filename</VAR>, adding them to the history list.
946: Start reading at line <VAR>from</VAR> and end at <VAR>to</VAR>.
947: If <VAR>from</VAR> is zero, start at the beginning. If <VAR>to</VAR> is less than
948: <VAR>from</VAR>, then read until the end of the file. If <VAR>filename</VAR> is
949: <CODE>NULL</CODE>, then read from <TT>`~/.history'</TT>. Returns 0 if successful,
950: or <CODE>errno</CODE> if not.
951: </DL>
952: </P><P>
953:
954: <A NAME="IDX29"></A>
955: <DL>
956: <DT><U>Function:</U> int <B>write_history</B> <I>(const char *filename)</I>
957: <DD>Write the current history to <VAR>filename</VAR>, overwriting <VAR>filename</VAR>
958: if necessary.
959: If <VAR>filename</VAR> is <CODE>NULL</CODE>, then write the history list to
960: <TT>`~/.history'</TT>.
961: Returns 0 on success, or <CODE>errno</CODE> on a read or write error.
962: </DL>
963: </P><P>
964:
965: <A NAME="IDX30"></A>
966: <DL>
967: <DT><U>Function:</U> int <B>append_history</B> <I>(int nelements, const char *filename)</I>
968: <DD>Append the last <VAR>nelements</VAR> of the history list to <VAR>filename</VAR>.
969: If <VAR>filename</VAR> is <CODE>NULL</CODE>, then append to <TT>`~/.history'</TT>.
970: Returns 0 on success, or <CODE>errno</CODE> on a read or write error.
971: </DL>
972: </P><P>
973:
974: <A NAME="IDX31"></A>
975: <DL>
976: <DT><U>Function:</U> int <B>history_truncate_file</B> <I>(const char *filename, int nlines)</I>
977: <DD>Truncate the history file <VAR>filename</VAR>, leaving only the last
978: <VAR>nlines</VAR> lines.
979: If <VAR>filename</VAR> is <CODE>NULL</CODE>, then <TT>`~/.history'</TT> is truncated.
980: Returns 0 on success, or <CODE>errno</CODE> on failure.
981: </DL>
982: </P><P>
983:
984: <A NAME="History Expansion"></A>
985: <HR SIZE="6">
986: <A NAME="SEC16"></A>
987: <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
988: <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC15"> < </A>]</TD>
989: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> > </A>]</TD>
990: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> << </A>]</TD>
991: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC9"> Up </A>]</TD>
992: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> >> </A>]</TD>
993: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
994: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
995: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC21">Index</A>]</TD>
996: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
997: </TR></TABLE>
998: <H3> 2.3.7 History Expansion </H3>
999: <!--docid::SEC16::-->
1000: <P>
1001:
1002: These functions implement history expansion.
1003: </P><P>
1004:
1005: <A NAME="IDX32"></A>
1006: <DL>
1007: <DT><U>Function:</U> int <B>history_expand</B> <I>(char *string, char **output)</I>
1008: <DD>Expand <VAR>string</VAR>, placing the result into <VAR>output</VAR>, a pointer
1009: to a string (see section <A HREF="history.html#SEC2">1.1 History Expansion</A>). Returns:
1010: <DL COMPACT>
1011: <DT><CODE>0</CODE>
1012: <DD>If no expansions took place (or, if the only change in
1013: the text was the removal of escape characters preceding the history expansion
1014: character);
1015: <DT><CODE>1</CODE>
1016: <DD>if expansions did take place;
1017: <DT><CODE>-1</CODE>
1018: <DD>if there was an error in expansion;
1019: <DT><CODE>2</CODE>
1020: <DD>if the returned line should be displayed, but not executed,
1021: as with the <CODE>:p</CODE> modifier (see section <A HREF="history.html#SEC5">1.1.3 Modifiers</A>).
1022: </DL>
1023: <P>
1024:
1025: If an error occurred in expansion, then <VAR>output</VAR> contains a descriptive
1026: error message.
1027: </DL>
1028: </P><P>
1029:
1030: <A NAME="IDX33"></A>
1031: <DL>
1032: <DT><U>Function:</U> char * <B>get_history_event</B> <I>(const char *string, int *cindex, int qchar)</I>
1033: <DD>Returns the text of the history event beginning at <VAR>string</VAR> +
1034: <VAR>*cindex</VAR>. <VAR>*cindex</VAR> is modified to point to after the event
1035: specifier. At function entry, <VAR>cindex</VAR> points to the index into
1036: <VAR>string</VAR> where the history event specification begins. <VAR>qchar</VAR>
1037: is a character that is allowed to end the event specification in addition
1038: to the "normal" terminating characters.
1039: </DL>
1040: </P><P>
1041:
1042: <A NAME="IDX34"></A>
1043: <DL>
1044: <DT><U>Function:</U> char ** <B>history_tokenize</B> <I>(const char *string)</I>
1045: <DD>Return an array of tokens parsed out of <VAR>string</VAR>, much as the
1046: shell might. The tokens are split on the characters in the
1047: <VAR>history_word_delimiters</VAR> variable,
1.1.1.2 ! misho 1048: and shell quoting conventions are obeyed as described below.
1.1 misho 1049: </DL>
1050: </P><P>
1051:
1052: <A NAME="IDX35"></A>
1053: <DL>
1054: <DT><U>Function:</U> char * <B>history_arg_extract</B> <I>(int first, int last, const char *string)</I>
1055: <DD>Extract a string segment consisting of the <VAR>first</VAR> through <VAR>last</VAR>
1056: arguments present in <VAR>string</VAR>. Arguments are split using
1057: <CODE>history_tokenize</CODE>.
1058: </DL>
1059: </P><P>
1060:
1061: <A NAME="History Variables"></A>
1062: <HR SIZE="6">
1063: <A NAME="SEC17"></A>
1064: <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1065: <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC16"> < </A>]</TD>
1066: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC18"> > </A>]</TD>
1067: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC18"> << </A>]</TD>
1068: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC6"> Up </A>]</TD>
1069: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19"> >> </A>]</TD>
1070: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
1071: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
1072: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC21">Index</A>]</TD>
1073: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
1074: </TR></TABLE>
1075: <H2> 2.4 History Variables </H2>
1076: <!--docid::SEC17::-->
1077: <P>
1078:
1079: This section describes the externally-visible variables exported by
1080: the GNU History Library.
1081: </P><P>
1082:
1083: <A NAME="IDX36"></A>
1084: <DL>
1085: <DT><U>Variable:</U> int <B>history_base</B>
1086: <DD>The logical offset of the first entry in the history list.
1087: </DL>
1088: </P><P>
1089:
1090: <A NAME="IDX37"></A>
1091: <DL>
1092: <DT><U>Variable:</U> int <B>history_length</B>
1093: <DD>The number of entries currently stored in the history list.
1094: </DL>
1095: </P><P>
1096:
1097: <A NAME="IDX38"></A>
1098: <DL>
1099: <DT><U>Variable:</U> int <B>history_max_entries</B>
1100: <DD>The maximum number of history entries. This must be changed using
1101: <CODE>stifle_history()</CODE>.
1102: </DL>
1103: </P><P>
1104:
1105: <A NAME="IDX39"></A>
1106: <DL>
1107: <DT><U>Variable:</U> int <B>history_write_timestamps</B>
1108: <DD>If non-zero, timestamps are written to the history file, so they can be
1109: preserved between sessions. The default value is 0, meaning that
1110: timestamps are not saved.
1111: </P><P>
1112:
1113: The current timestamp format uses the value of <VAR>history_comment_char</VAR>
1114: to delimit timestamp entries in the history file. If that variable does
1115: not have a value (the default), timestamps will not be written.
1116: </DL>
1117: </P><P>
1118:
1119: <A NAME="IDX40"></A>
1120: <DL>
1121: <DT><U>Variable:</U> char <B>history_expansion_char</B>
1122: <DD>The character that introduces a history event. The default is <SAMP>`!'</SAMP>.
1123: Setting this to 0 inhibits history expansion.
1124: </DL>
1125: </P><P>
1126:
1127: <A NAME="IDX41"></A>
1128: <DL>
1129: <DT><U>Variable:</U> char <B>history_subst_char</B>
1130: <DD>The character that invokes word substitution if found at the start of
1131: a line. The default is <SAMP>`^'</SAMP>.
1132: </DL>
1133: </P><P>
1134:
1135: <A NAME="IDX42"></A>
1136: <DL>
1137: <DT><U>Variable:</U> char <B>history_comment_char</B>
1138: <DD>During tokenization, if this character is seen as the first character
1139: of a word, then it and all subsequent characters up to a newline are
1140: ignored, suppressing history expansion for the remainder of the line.
1141: This is disabled by default.
1142: </DL>
1143: </P><P>
1144:
1145: <A NAME="IDX43"></A>
1146: <DL>
1147: <DT><U>Variable:</U> char * <B>history_word_delimiters</B>
1148: <DD>The characters that separate tokens for <CODE>history_tokenize()</CODE>.
1149: The default value is <CODE>" \t\n()<>;&|"</CODE>.
1150: </DL>
1151: </P><P>
1152:
1153: <A NAME="IDX44"></A>
1154: <DL>
1155: <DT><U>Variable:</U> char * <B>history_search_delimiter_chars</B>
1156: <DD>The list of additional characters which can delimit a history search
1157: string, in addition to space, TAB, <SAMP>`:'</SAMP> and <SAMP>`?'</SAMP> in the case of
1158: a substring search. The default is empty.
1159: </DL>
1160: </P><P>
1161:
1162: <A NAME="IDX45"></A>
1163: <DL>
1164: <DT><U>Variable:</U> char * <B>history_no_expand_chars</B>
1165: <DD>The list of characters which inhibit history expansion if found immediately
1166: following <VAR>history_expansion_char</VAR>. The default is space, tab, newline,
1167: carriage return, and <SAMP>`='</SAMP>.
1168: </DL>
1169: </P><P>
1170:
1171: <A NAME="IDX46"></A>
1172: <DL>
1173: <DT><U>Variable:</U> int <B>history_quotes_inhibit_expansion</B>
1.1.1.2 ! misho 1174: <DD>If non-zero, the history expansion code implements shell-like quoting:
! 1175: single-quoted words are not scanned for the history expansion
! 1176: character or the history comment character, and double-quoted words may
! 1177: have history expansion performed, since single quotes are not special
! 1178: within double quotes.
! 1179: The default value is 0.
1.1 misho 1180: </DL>
1181: </P><P>
1182:
1183: <A NAME="IDX47"></A>
1184: <DL>
1.1.1.2 ! misho 1185: <DT><U>Variable:</U> int <B>history_quoting_state</B>
! 1186: <DD>An application may set this variable to indicate that the current line
! 1187: being expanded is subject to existing quoting. If set to <SAMP>`''</SAMP>, the
! 1188: history expansion function will assume that the line is single-quoted and
! 1189: inhibit expansion until it reads an unquoted closing single quote; if set
! 1190: to <SAMP>`"'</SAMP>, history expansion will assume the line is double quoted until
! 1191: it reads an unquoted closing double quote. If set to zero, the default,
! 1192: the history expansion function will assume the line is not quoted and
! 1193: treat quote characters within the line as described above.
! 1194: This is only effective if <VAR>history_quotes_inhibit_expansion</VAR> is set.
! 1195: </DL>
! 1196: </P><P>
! 1197:
! 1198: <A NAME="IDX48"></A>
! 1199: <DL>
1.1 misho 1200: <DT><U>Variable:</U> rl_linebuf_func_t * <B>history_inhibit_expansion_function</B>
1201: <DD>This should be set to the address of a function that takes two arguments:
1202: a <CODE>char *</CODE> (<VAR>string</VAR>)
1203: and an <CODE>int</CODE> index into that string (<VAR>i</VAR>).
1204: It should return a non-zero value if the history expansion starting at
1205: <VAR>string[i]</VAR> should not be performed; zero if the expansion should
1206: be done.
1207: It is intended for use by applications like Bash that use the history
1208: expansion character for additional purposes.
1209: By default, this variable is set to <CODE>NULL</CODE>.
1210: </DL>
1211: </P><P>
1212:
1213: <A NAME="History Programming Example"></A>
1214: <HR SIZE="6">
1215: <A NAME="SEC18"></A>
1216: <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1217: <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> < </A>]</TD>
1218: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19"> > </A>]</TD>
1219: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
1220: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC6"> Up </A>]</TD>
1221: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19"> >> </A>]</TD>
1222: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
1223: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
1224: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC21">Index</A>]</TD>
1225: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
1226: </TR></TABLE>
1227: <H2> 2.5 History Programming Example </H2>
1228: <!--docid::SEC18::-->
1229: <P>
1230:
1231: The following program demonstrates simple use of the GNU History Library.
1232: </P><P>
1233:
1234: <TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>#include <stdio.h>
1235: #include <readline/history.h>
1236:
1237: main (argc, argv)
1238: int argc;
1239: char **argv;
1240: {
1241: char line[1024], *t;
1242: int len, done = 0;
1243:
1244: line[0] = 0;
1245:
1246: using_history ();
1247: while (!done)
1248: {
1249: printf ("history$ ");
1250: fflush (stdout);
1251: t = fgets (line, sizeof (line) - 1, stdin);
1252: if (t && *t)
1253: {
1254: len = strlen (t);
1255: if (t[len - 1] == '\n')
1256: t[len - 1] = '\0';
1257: }
1258:
1259: if (!t)
1260: strcpy (line, "quit");
1261:
1262: if (line[0])
1263: {
1264: char *expansion;
1265: int result;
1266:
1267: result = history_expand (line, &expansion);
1268: if (result)
1269: fprintf (stderr, "%s\n", expansion);
1270:
1271: if (result < 0 || result == 2)
1272: {
1273: free (expansion);
1274: continue;
1275: }
1276:
1277: add_history (expansion);
1278: strncpy (line, expansion, sizeof (line) - 1);
1279: free (expansion);
1280: }
1281:
1282: if (strcmp (line, "quit") == 0)
1283: done = 1;
1284: else if (strcmp (line, "save") == 0)
1285: write_history ("history_file");
1286: else if (strcmp (line, "read") == 0)
1287: read_history ("history_file");
1288: else if (strcmp (line, "list") == 0)
1289: {
1290: register HIST_ENTRY **the_list;
1291: register int i;
1292:
1293: the_list = history_list ();
1294: if (the_list)
1295: for (i = 0; the_list[i]; i++)
1296: printf ("%d: %s\n", i + history_base, the_list[i]->line);
1297: }
1298: else if (strncmp (line, "delete", 6) == 0)
1299: {
1300: int which;
1301: if ((sscanf (line + 6, "%d", &which)) == 1)
1302: {
1303: HIST_ENTRY *entry = remove_history (which);
1304: if (!entry)
1305: fprintf (stderr, "No such entry %d\n", which);
1306: else
1307: {
1308: free (entry->line);
1309: free (entry);
1310: }
1311: }
1312: else
1313: {
1314: fprintf (stderr, "non-numeric arg given to `delete'\n");
1315: }
1316: }
1317: }
1318: }
1319: </FONT></pre></td></tr></table></P><P>
1320:
1321: <A NAME="GNU Free Documentation License"></A>
1322: <HR SIZE="6">
1323: <A NAME="SEC19"></A>
1324: <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1325: <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC18"> < </A>]</TD>
1326: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC21"> > </A>]</TD>
1327: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC6"> << </A>]</TD>
1328: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top"> Up </A>]</TD>
1329: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC21"> >> </A>]</TD>
1330: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
1331: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
1332: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC21">Index</A>]</TD>
1333: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
1334: </TR></TABLE>
1335: <H1> A. GNU Free Documentation License </H1>
1336: <!--docid::SEC19::-->
1337: <P>
1338:
1339: <center>
1340: Version 1.3, 3 November 2008
1341: </center>
1342: </P><P>
1343:
1344: <TABLE><tr><td> </td><td class=display><pre style="font-family: serif">Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
1345: <A HREF="http://fsf.org/">http://fsf.org/</A>
1346:
1347: Everyone is permitted to copy and distribute verbatim copies
1348: of this license document, but changing it is not allowed.
1349: </pre></td></tr></table></P><P>
1350:
1351: <OL>
1352: <LI>
1353: PREAMBLE
1354: <P>
1355:
1356: The purpose of this License is to make a manual, textbook, or other
1357: functional and useful document <EM>free</EM> in the sense of freedom: to
1358: assure everyone the effective freedom to copy and redistribute it,
1359: with or without modifying it, either commercially or noncommercially.
1360: Secondarily, this License preserves for the author and publisher a way
1361: to get credit for their work, while not being considered responsible
1362: for modifications made by others.
1363: </P><P>
1364:
1365: This License is a kind of "copyleft", which means that derivative
1366: works of the document must themselves be free in the same sense. It
1367: complements the GNU General Public License, which is a copyleft
1368: license designed for free software.
1369: </P><P>
1370:
1371: We have designed this License in order to use it for manuals for free
1372: software, because free software needs free documentation: a free
1373: program should come with manuals providing the same freedoms that the
1374: software does. But this License is not limited to software manuals;
1375: it can be used for any textual work, regardless of subject matter or
1376: whether it is published as a printed book. We recommend this License
1377: principally for works whose purpose is instruction or reference.
1378: </P><P>
1379:
1380: <LI>
1381: APPLICABILITY AND DEFINITIONS
1382: <P>
1383:
1384: This License applies to any manual or other work, in any medium, that
1385: contains a notice placed by the copyright holder saying it can be
1386: distributed under the terms of this License. Such a notice grants a
1387: world-wide, royalty-free license, unlimited in duration, to use that
1388: work under the conditions stated herein. The "Document", below,
1389: refers to any such manual or work. Any member of the public is a
1390: licensee, and is addressed as "you". You accept the license if you
1391: copy, modify or distribute the work in a way requiring permission
1392: under copyright law.
1393: </P><P>
1394:
1395: A "Modified Version" of the Document means any work containing the
1396: Document or a portion of it, either copied verbatim, or with
1397: modifications and/or translated into another language.
1398: </P><P>
1399:
1400: A "Secondary Section" is a named appendix or a front-matter section
1401: of the Document that deals exclusively with the relationship of the
1402: publishers or authors of the Document to the Document's overall
1403: subject (or to related matters) and contains nothing that could fall
1404: directly within that overall subject. (Thus, if the Document is in
1405: part a textbook of mathematics, a Secondary Section may not explain
1406: any mathematics.) The relationship could be a matter of historical
1407: connection with the subject or with related matters, or of legal,
1408: commercial, philosophical, ethical or political position regarding
1409: them.
1410: </P><P>
1411:
1412: The "Invariant Sections" are certain Secondary Sections whose titles
1413: are designated, as being those of Invariant Sections, in the notice
1414: that says that the Document is released under this License. If a
1415: section does not fit the above definition of Secondary then it is not
1416: allowed to be designated as Invariant. The Document may contain zero
1417: Invariant Sections. If the Document does not identify any Invariant
1418: Sections then there are none.
1419: </P><P>
1420:
1421: The "Cover Texts" are certain short passages of text that are listed,
1422: as Front-Cover Texts or Back-Cover Texts, in the notice that says that
1423: the Document is released under this License. A Front-Cover Text may
1424: be at most 5 words, and a Back-Cover Text may be at most 25 words.
1425: </P><P>
1426:
1427: A "Transparent" copy of the Document means a machine-readable copy,
1428: represented in a format whose specification is available to the
1429: general public, that is suitable for revising the document
1430: straightforwardly with generic text editors or (for images composed of
1431: pixels) generic paint programs or (for drawings) some widely available
1432: drawing editor, and that is suitable for input to text formatters or
1433: for automatic translation to a variety of formats suitable for input
1434: to text formatters. A copy made in an otherwise Transparent file
1435: format whose markup, or absence of markup, has been arranged to thwart
1436: or discourage subsequent modification by readers is not Transparent.
1437: An image format is not Transparent if used for any substantial amount
1438: of text. A copy that is not "Transparent" is called "Opaque".
1439: </P><P>
1440:
1441: Examples of suitable formats for Transparent copies include plain
1442: ASCII without markup, Texinfo input format, LaTeX input
1443: format, <FONT SIZE="-1">SGML</FONT> or <FONT SIZE="-1">XML</FONT> using a publicly available
1444: <FONT SIZE="-1">DTD</FONT>, and standard-conforming simple <FONT SIZE="-1">HTML</FONT>,
1445: PostScript or <FONT SIZE="-1">PDF</FONT> designed for human modification. Examples
1446: of transparent image formats include <FONT SIZE="-1">PNG</FONT>, <FONT SIZE="-1">XCF</FONT> and
1447: <FONT SIZE="-1">JPG</FONT>. Opaque formats include proprietary formats that can be
1448: read and edited only by proprietary word processors, <FONT SIZE="-1">SGML</FONT> or
1449: <FONT SIZE="-1">XML</FONT> for which the <FONT SIZE="-1">DTD</FONT> and/or processing tools are
1450: not generally available, and the machine-generated <FONT SIZE="-1">HTML</FONT>,
1451: PostScript or <FONT SIZE="-1">PDF</FONT> produced by some word processors for
1452: output purposes only.
1453: </P><P>
1454:
1455: The "Title Page" means, for a printed book, the title page itself,
1456: plus such following pages as are needed to hold, legibly, the material
1457: this License requires to appear in the title page. For works in
1458: formats which do not have any title page as such, "Title Page" means
1459: the text near the most prominent appearance of the work's title,
1460: preceding the beginning of the body of the text.
1461: </P><P>
1462:
1463: The "publisher" means any person or entity that distributes copies
1464: of the Document to the public.
1465: </P><P>
1466:
1467: A section "Entitled XYZ" means a named subunit of the Document whose
1468: title either is precisely XYZ or contains XYZ in parentheses following
1469: text that translates XYZ in another language. (Here XYZ stands for a
1470: specific section name mentioned below, such as "Acknowledgements",
1471: "Dedications", "Endorsements", or "History".) To "Preserve the Title"
1472: of such a section when you modify the Document means that it remains a
1473: section "Entitled XYZ" according to this definition.
1474: </P><P>
1475:
1476: The Document may include Warranty Disclaimers next to the notice which
1477: states that this License applies to the Document. These Warranty
1478: Disclaimers are considered to be included by reference in this
1479: License, but only as regards disclaiming warranties: any other
1480: implication that these Warranty Disclaimers may have is void and has
1481: no effect on the meaning of this License.
1482: </P><P>
1483:
1484: <LI>
1485: VERBATIM COPYING
1486: <P>
1487:
1488: You may copy and distribute the Document in any medium, either
1489: commercially or noncommercially, provided that this License, the
1490: copyright notices, and the license notice saying this License applies
1491: to the Document are reproduced in all copies, and that you add no other
1492: conditions whatsoever to those of this License. You may not use
1493: technical measures to obstruct or control the reading or further
1494: copying of the copies you make or distribute. However, you may accept
1495: compensation in exchange for copies. If you distribute a large enough
1496: number of copies you must also follow the conditions in section 3.
1497: </P><P>
1498:
1499: You may also lend copies, under the same conditions stated above, and
1500: you may publicly display copies.
1501: </P><P>
1502:
1503: <LI>
1504: COPYING IN QUANTITY
1505: <P>
1506:
1507: If you publish printed copies (or copies in media that commonly have
1508: printed covers) of the Document, numbering more than 100, and the
1509: Document's license notice requires Cover Texts, you must enclose the
1510: copies in covers that carry, clearly and legibly, all these Cover
1511: Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
1512: the back cover. Both covers must also clearly and legibly identify
1513: you as the publisher of these copies. The front cover must present
1514: the full title with all words of the title equally prominent and
1515: visible. You may add other material on the covers in addition.
1516: Copying with changes limited to the covers, as long as they preserve
1517: the title of the Document and satisfy these conditions, can be treated
1518: as verbatim copying in other respects.
1519: </P><P>
1520:
1521: If the required texts for either cover are too voluminous to fit
1522: legibly, you should put the first ones listed (as many as fit
1523: reasonably) on the actual cover, and continue the rest onto adjacent
1524: pages.
1525: </P><P>
1526:
1527: If you publish or distribute Opaque copies of the Document numbering
1528: more than 100, you must either include a machine-readable Transparent
1529: copy along with each Opaque copy, or state in or with each Opaque copy
1530: a computer-network location from which the general network-using
1531: public has access to download using public-standard network protocols
1532: a complete Transparent copy of the Document, free of added material.
1533: If you use the latter option, you must take reasonably prudent steps,
1534: when you begin distribution of Opaque copies in quantity, to ensure
1535: that this Transparent copy will remain thus accessible at the stated
1536: location until at least one year after the last time you distribute an
1537: Opaque copy (directly or through your agents or retailers) of that
1538: edition to the public.
1539: </P><P>
1540:
1541: It is requested, but not required, that you contact the authors of the
1542: Document well before redistributing any large number of copies, to give
1543: them a chance to provide you with an updated version of the Document.
1544: </P><P>
1545:
1546: <LI>
1547: MODIFICATIONS
1548: <P>
1549:
1550: You may copy and distribute a Modified Version of the Document under
1551: the conditions of sections 2 and 3 above, provided that you release
1552: the Modified Version under precisely this License, with the Modified
1553: Version filling the role of the Document, thus licensing distribution
1554: and modification of the Modified Version to whoever possesses a copy
1555: of it. In addition, you must do these things in the Modified Version:
1556: </P><P>
1557:
1558: <OL>
1559: <LI>
1560: Use in the Title Page (and on the covers, if any) a title distinct
1561: from that of the Document, and from those of previous versions
1562: (which should, if there were any, be listed in the History section
1563: of the Document). You may use the same title as a previous version
1564: if the original publisher of that version gives permission.
1565: <P>
1566:
1567: <LI>
1568: List on the Title Page, as authors, one or more persons or entities
1569: responsible for authorship of the modifications in the Modified
1570: Version, together with at least five of the principal authors of the
1571: Document (all of its principal authors, if it has fewer than five),
1572: unless they release you from this requirement.
1573: <P>
1574:
1575: <LI>
1576: State on the Title page the name of the publisher of the
1577: Modified Version, as the publisher.
1578: <P>
1579:
1580: <LI>
1581: Preserve all the copyright notices of the Document.
1582: <P>
1583:
1584: <LI>
1585: Add an appropriate copyright notice for your modifications
1586: adjacent to the other copyright notices.
1587: <P>
1588:
1589: <LI>
1590: Include, immediately after the copyright notices, a license notice
1591: giving the public permission to use the Modified Version under the
1592: terms of this License, in the form shown in the Addendum below.
1593: <P>
1594:
1595: <LI>
1596: Preserve in that license notice the full lists of Invariant Sections
1597: and required Cover Texts given in the Document's license notice.
1598: <P>
1599:
1600: <LI>
1601: Include an unaltered copy of this License.
1602: <P>
1603:
1604: <LI>
1605: Preserve the section Entitled "History", Preserve its Title, and add
1606: to it an item stating at least the title, year, new authors, and
1607: publisher of the Modified Version as given on the Title Page. If
1608: there is no section Entitled "History" in the Document, create one
1609: stating the title, year, authors, and publisher of the Document as
1610: given on its Title Page, then add an item describing the Modified
1611: Version as stated in the previous sentence.
1612: <P>
1613:
1614: <LI>
1615: Preserve the network location, if any, given in the Document for
1616: public access to a Transparent copy of the Document, and likewise
1617: the network locations given in the Document for previous versions
1618: it was based on. These may be placed in the "History" section.
1619: You may omit a network location for a work that was published at
1620: least four years before the Document itself, or if the original
1621: publisher of the version it refers to gives permission.
1622: <P>
1623:
1624: <LI>
1625: For any section Entitled "Acknowledgements" or "Dedications", Preserve
1626: the Title of the section, and preserve in the section all the
1627: substance and tone of each of the contributor acknowledgements and/or
1628: dedications given therein.
1629: <P>
1630:
1631: <LI>
1632: Preserve all the Invariant Sections of the Document,
1633: unaltered in their text and in their titles. Section numbers
1634: or the equivalent are not considered part of the section titles.
1635: <P>
1636:
1637: <LI>
1638: Delete any section Entitled "Endorsements". Such a section
1639: may not be included in the Modified Version.
1640: <P>
1641:
1642: <LI>
1643: Do not retitle any existing section to be Entitled "Endorsements" or
1644: to conflict in title with any Invariant Section.
1645: <P>
1646:
1647: <LI>
1648: Preserve any Warranty Disclaimers.
1649: </OL>
1650: <P>
1651:
1652: If the Modified Version includes new front-matter sections or
1653: appendices that qualify as Secondary Sections and contain no material
1654: copied from the Document, you may at your option designate some or all
1655: of these sections as invariant. To do this, add their titles to the
1656: list of Invariant Sections in the Modified Version's license notice.
1657: These titles must be distinct from any other section titles.
1658: </P><P>
1659:
1660: You may add a section Entitled "Endorsements", provided it contains
1661: nothing but endorsements of your Modified Version by various
1662: parties--for example, statements of peer review or that the text has
1663: been approved by an organization as the authoritative definition of a
1664: standard.
1665: </P><P>
1666:
1667: You may add a passage of up to five words as a Front-Cover Text, and a
1668: passage of up to 25 words as a Back-Cover Text, to the end of the list
1669: of Cover Texts in the Modified Version. Only one passage of
1670: Front-Cover Text and one of Back-Cover Text may be added by (or
1671: through arrangements made by) any one entity. If the Document already
1672: includes a cover text for the same cover, previously added by you or
1673: by arrangement made by the same entity you are acting on behalf of,
1674: you may not add another; but you may replace the old one, on explicit
1675: permission from the previous publisher that added the old one.
1676: </P><P>
1677:
1678: The author(s) and publisher(s) of the Document do not by this License
1679: give permission to use their names for publicity for or to assert or
1680: imply endorsement of any Modified Version.
1681: </P><P>
1682:
1683: <LI>
1684: COMBINING DOCUMENTS
1685: <P>
1686:
1687: You may combine the Document with other documents released under this
1688: License, under the terms defined in section 4 above for modified
1689: versions, provided that you include in the combination all of the
1690: Invariant Sections of all of the original documents, unmodified, and
1691: list them all as Invariant Sections of your combined work in its
1692: license notice, and that you preserve all their Warranty Disclaimers.
1693: </P><P>
1694:
1695: The combined work need only contain one copy of this License, and
1696: multiple identical Invariant Sections may be replaced with a single
1697: copy. If there are multiple Invariant Sections with the same name but
1698: different contents, make the title of each such section unique by
1699: adding at the end of it, in parentheses, the name of the original
1700: author or publisher of that section if known, or else a unique number.
1701: Make the same adjustment to the section titles in the list of
1702: Invariant Sections in the license notice of the combined work.
1703: </P><P>
1704:
1705: In the combination, you must combine any sections Entitled "History"
1706: in the various original documents, forming one section Entitled
1707: "History"; likewise combine any sections Entitled "Acknowledgements",
1708: and any sections Entitled "Dedications". You must delete all
1709: sections Entitled "Endorsements."
1710: </P><P>
1711:
1712: <LI>
1713: COLLECTIONS OF DOCUMENTS
1714: <P>
1715:
1716: You may make a collection consisting of the Document and other documents
1717: released under this License, and replace the individual copies of this
1718: License in the various documents with a single copy that is included in
1719: the collection, provided that you follow the rules of this License for
1720: verbatim copying of each of the documents in all other respects.
1721: </P><P>
1722:
1723: You may extract a single document from such a collection, and distribute
1724: it individually under this License, provided you insert a copy of this
1725: License into the extracted document, and follow this License in all
1726: other respects regarding verbatim copying of that document.
1727: </P><P>
1728:
1729: <LI>
1730: AGGREGATION WITH INDEPENDENT WORKS
1731: <P>
1732:
1733: A compilation of the Document or its derivatives with other separate
1734: and independent documents or works, in or on a volume of a storage or
1735: distribution medium, is called an "aggregate" if the copyright
1736: resulting from the compilation is not used to limit the legal rights
1737: of the compilation's users beyond what the individual works permit.
1738: When the Document is included in an aggregate, this License does not
1739: apply to the other works in the aggregate which are not themselves
1740: derivative works of the Document.
1741: </P><P>
1742:
1743: If the Cover Text requirement of section 3 is applicable to these
1744: copies of the Document, then if the Document is less than one half of
1745: the entire aggregate, the Document's Cover Texts may be placed on
1746: covers that bracket the Document within the aggregate, or the
1747: electronic equivalent of covers if the Document is in electronic form.
1748: Otherwise they must appear on printed covers that bracket the whole
1749: aggregate.
1750: </P><P>
1751:
1752: <LI>
1753: TRANSLATION
1754: <P>
1755:
1756: Translation is considered a kind of modification, so you may
1757: distribute translations of the Document under the terms of section 4.
1758: Replacing Invariant Sections with translations requires special
1759: permission from their copyright holders, but you may include
1760: translations of some or all Invariant Sections in addition to the
1761: original versions of these Invariant Sections. You may include a
1762: translation of this License, and all the license notices in the
1763: Document, and any Warranty Disclaimers, provided that you also include
1764: the original English version of this License and the original versions
1765: of those notices and disclaimers. In case of a disagreement between
1766: the translation and the original version of this License or a notice
1767: or disclaimer, the original version will prevail.
1768: </P><P>
1769:
1770: If a section in the Document is Entitled "Acknowledgements",
1771: "Dedications", or "History", the requirement (section 4) to Preserve
1772: its Title (section 1) will typically require changing the actual
1773: title.
1774: </P><P>
1775:
1776: <LI>
1777: TERMINATION
1778: <P>
1779:
1780: You may not copy, modify, sublicense, or distribute the Document
1781: except as expressly provided under this License. Any attempt
1782: otherwise to copy, modify, sublicense, or distribute it is void, and
1783: will automatically terminate your rights under this License.
1784: </P><P>
1785:
1786: However, if you cease all violation of this License, then your license
1787: from a particular copyright holder is reinstated (a) provisionally,
1788: unless and until the copyright holder explicitly and finally
1789: terminates your license, and (b) permanently, if the copyright holder
1790: fails to notify you of the violation by some reasonable means prior to
1791: 60 days after the cessation.
1792: </P><P>
1793:
1794: Moreover, your license from a particular copyright holder is
1795: reinstated permanently if the copyright holder notifies you of the
1796: violation by some reasonable means, this is the first time you have
1797: received notice of violation of this License (for any work) from that
1798: copyright holder, and you cure the violation prior to 30 days after
1799: your receipt of the notice.
1800: </P><P>
1801:
1802: Termination of your rights under this section does not terminate the
1803: licenses of parties who have received copies or rights from you under
1804: this License. If your rights have been terminated and not permanently
1805: reinstated, receipt of a copy of some or all of the same material does
1806: not give you any rights to use it.
1807: </P><P>
1808:
1809: <LI>
1810: FUTURE REVISIONS OF THIS LICENSE
1811: <P>
1812:
1813: The Free Software Foundation may publish new, revised versions
1814: of the GNU Free Documentation License from time to time. Such new
1815: versions will be similar in spirit to the present version, but may
1816: differ in detail to address new problems or concerns. See
1817: <A HREF="http://www.gnu.org/copyleft/">http://www.gnu.org/copyleft/</A>.
1818: </P><P>
1819:
1820: Each version of the License is given a distinguishing version number.
1821: If the Document specifies that a particular numbered version of this
1822: License "or any later version" applies to it, you have the option of
1823: following the terms and conditions either of that specified version or
1824: of any later version that has been published (not as a draft) by the
1825: Free Software Foundation. If the Document does not specify a version
1826: number of this License, you may choose any version ever published (not
1827: as a draft) by the Free Software Foundation. If the Document
1828: specifies that a proxy can decide which future versions of this
1829: License can be used, that proxy's public statement of acceptance of a
1830: version permanently authorizes you to choose that version for the
1831: Document.
1832: </P><P>
1833:
1834: <LI>
1835: RELICENSING
1836: <P>
1837:
1838: "Massive Multiauthor Collaboration Site" (or "MMC Site") means any
1839: World Wide Web server that publishes copyrightable works and also
1840: provides prominent facilities for anybody to edit those works. A
1841: public wiki that anybody can edit is an example of such a server. A
1842: "Massive Multiauthor Collaboration" (or "MMC") contained in the
1843: site means any set of copyrightable works thus published on the MMC
1844: site.
1845: </P><P>
1846:
1847: "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
1848: license published by Creative Commons Corporation, a not-for-profit
1849: corporation with a principal place of business in San Francisco,
1850: California, as well as future copyleft versions of that license
1851: published by that same organization.
1852: </P><P>
1853:
1854: "Incorporate" means to publish or republish a Document, in whole or
1855: in part, as part of another Document.
1856: </P><P>
1857:
1858: An MMC is "eligible for relicensing" if it is licensed under this
1859: License, and if all works that were first published under this License
1860: somewhere other than this MMC, and subsequently incorporated in whole
1861: or in part into the MMC, (1) had no cover texts or invariant sections,
1862: and (2) were thus incorporated prior to November 1, 2008.
1863: </P><P>
1864:
1865: The operator of an MMC Site may republish an MMC contained in the site
1866: under CC-BY-SA on the same site at any time before August 1, 2009,
1867: provided the MMC is eligible for relicensing.
1868: </P><P>
1869:
1870: </OL>
1871: <P>
1872:
1873: <A NAME="SEC20"></A>
1874: <H2> ADDENDUM: How to use this License for your documents </H2>
1875: <!--docid::SEC20::-->
1876: <P>
1877:
1878: To use this License in a document you have written, include a copy of
1879: the License in the document and put the following copyright and
1880: license notices just after the title page:
1881: </P><P>
1882:
1883: <TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre> Copyright (C) <VAR>year</VAR> <VAR>your name</VAR>.
1884: Permission is granted to copy, distribute and/or modify this document
1885: under the terms of the GNU Free Documentation License, Version 1.3
1886: or any later version published by the Free Software Foundation;
1887: with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
1888: Texts. A copy of the license is included in the section entitled ``GNU
1889: Free Documentation License''.
1890: </FONT></pre></td></tr></table></P><P>
1891:
1892: If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
1893: replace the "with<small>...</small>Texts." line with this:
1894: </P><P>
1895:
1896: <TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre> with the Invariant Sections being <VAR>list their titles</VAR>, with
1897: the Front-Cover Texts being <VAR>list</VAR>, and with the Back-Cover Texts
1898: being <VAR>list</VAR>.
1899: </FONT></pre></td></tr></table></P><P>
1900:
1901: If you have Invariant Sections without Cover Texts, or some other
1902: combination of the three, merge those two alternatives to suit the
1903: situation.
1904: </P><P>
1905:
1906: If your document contains nontrivial examples of program code, we
1907: recommend releasing these examples in parallel under your choice of
1908: free software license, such as the GNU General Public License,
1909: to permit their use in free software.
1910: </P><P>
1911:
1912: <A NAME="Concept Index"></A>
1913: <HR SIZE="6">
1914: <A NAME="SEC21"></A>
1915: <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1916: <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19"> < </A>]</TD>
1917: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC22"> > </A>]</TD>
1918: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC22"> << </A>]</TD>
1919: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top"> Up </A>]</TD>
1920: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC22"> >> </A>]</TD>
1921: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
1922: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
1923: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC21">Index</A>]</TD>
1924: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
1925: </TR></TABLE>
1926: <H1> B. Concept Index </H1>
1927: <!--docid::SEC21::-->
1928: <table><tr><th valign=top>Jump to: </th><td><A HREF="history.html#cp_A" style="text-decoration:none"><b>A</b></A>
1929:
1930: <A HREF="history.html#cp_E" style="text-decoration:none"><b>E</b></A>
1931:
1932: <A HREF="history.html#cp_H" style="text-decoration:none"><b>H</b></A>
1933:
1934: </td></tr></table><br><P></P>
1935: <TABLE border=0>
1936: <TR><TD></TD><TH ALIGN=LEFT>Index Entry</TH><TH ALIGN=LEFT> Section</TH></TR>
1937: <TR><TD COLSPAN=3> <HR></TD></TR>
1938: <TR><TH><A NAME="cp_A"></A>A</TH><TD></TD><TD></TD></TR>
1939: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX23">anchored search</A></TD><TD valign=top><A HREF="history.html#SEC14">2.3.5 Searching the History List</A></TD></TR>
1940: <TR><TD COLSPAN=3> <HR></TD></TR>
1941: <TR><TH><A NAME="cp_E"></A>E</TH><TD></TD><TD></TD></TR>
1942: <TR><TD></TD><TD valign=top><A HREF="history.html#SEC3">event designators</A></TD><TD valign=top><A HREF="history.html#SEC3">1.1.1 Event Designators</A></TD></TR>
1943: <TR><TD COLSPAN=3> <HR></TD></TR>
1944: <TR><TH><A NAME="cp_H"></A>H</TH><TD></TD><TD></TD></TR>
1945: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX1">history events</A></TD><TD valign=top><A HREF="history.html#SEC3">1.1.1 Event Designators</A></TD></TR>
1946: <TR><TD></TD><TD valign=top><A HREF="history.html#SEC2">history expansion</A></TD><TD valign=top><A HREF="history.html#SEC2">1.1 History Expansion</A></TD></TR>
1947: <TR><TD></TD><TD valign=top><A HREF="history.html#SEC14">History Searching</A></TD><TD valign=top><A HREF="history.html#SEC14">2.3.5 Searching the History List</A></TD></TR>
1948: <TR><TD COLSPAN=3> <HR></TD></TR>
1949: </TABLE><P></P><table><tr><th valign=top>Jump to: </th><td><A HREF="history.html#cp_A" style="text-decoration:none"><b>A</b></A>
1950:
1951: <A HREF="history.html#cp_E" style="text-decoration:none"><b>E</b></A>
1952:
1953: <A HREF="history.html#cp_H" style="text-decoration:none"><b>H</b></A>
1954:
1955: </td></tr></table><br><P>
1956:
1957: <A NAME="Function and Variable Index"></A>
1958: <HR SIZE="6">
1959: <A NAME="SEC22"></A>
1960: <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1961: <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC21"> < </A>]</TD>
1962: <TD VALIGN="MIDDLE" ALIGN="LEFT">[ > ]</TD>
1963: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
1964: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top"> Up </A>]</TD>
1965: <TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD>
1966: <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
1967: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
1968: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC21">Index</A>]</TD>
1969: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
1970: </TR></TABLE>
1971: <H1> C. Function and Variable Index </H1>
1972: <!--docid::SEC22::-->
1973: <table><tr><th valign=top>Jump to: </th><td><A HREF="history.html#vr_A" style="text-decoration:none"><b>A</b></A>
1974:
1975: <A HREF="history.html#vr_C" style="text-decoration:none"><b>C</b></A>
1976:
1977: <A HREF="history.html#vr_F" style="text-decoration:none"><b>F</b></A>
1978:
1979: <A HREF="history.html#vr_G" style="text-decoration:none"><b>G</b></A>
1980:
1981: <A HREF="history.html#vr_H" style="text-decoration:none"><b>H</b></A>
1982:
1983: <A HREF="history.html#vr_N" style="text-decoration:none"><b>N</b></A>
1984:
1985: <A HREF="history.html#vr_P" style="text-decoration:none"><b>P</b></A>
1986:
1987: <A HREF="history.html#vr_R" style="text-decoration:none"><b>R</b></A>
1988:
1989: <A HREF="history.html#vr_S" style="text-decoration:none"><b>S</b></A>
1990:
1991: <A HREF="history.html#vr_U" style="text-decoration:none"><b>U</b></A>
1992:
1993: <A HREF="history.html#vr_W" style="text-decoration:none"><b>W</b></A>
1994:
1995: </td></tr></table><br><P></P>
1996: <TABLE border=0>
1997: <TR><TD></TD><TH ALIGN=LEFT>Index Entry</TH><TH ALIGN=LEFT> Section</TH></TR>
1998: <TR><TD COLSPAN=3> <HR></TD></TR>
1999: <TR><TH><A NAME="vr_A"></A>A</TH><TD></TD><TD></TD></TR>
2000: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX5"><CODE>add_history</CODE></A></TD><TD valign=top><A HREF="history.html#SEC11">2.3.2 History List Management</A></TD></TR>
2001: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX6"><CODE>add_history_time</CODE></A></TD><TD valign=top><A HREF="history.html#SEC11">2.3.2 History List Management</A></TD></TR>
2002: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX30"><CODE>append_history</CODE></A></TD><TD valign=top><A HREF="history.html#SEC15">2.3.6 Managing the History File</A></TD></TR>
2003: <TR><TD COLSPAN=3> <HR></TD></TR>
2004: <TR><TH><A NAME="vr_C"></A>C</TH><TD></TD><TD></TD></TR>
2005: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX10"><CODE>clear_history</CODE></A></TD><TD valign=top><A HREF="history.html#SEC11">2.3.2 History List Management</A></TD></TR>
2006: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX16"><CODE>current_history</CODE></A></TD><TD valign=top><A HREF="history.html#SEC12">2.3.3 Information About the History List</A></TD></TR>
2007: <TR><TD COLSPAN=3> <HR></TD></TR>
2008: <TR><TH><A NAME="vr_F"></A>F</TH><TD></TD><TD></TD></TR>
2009: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX8"><CODE>free_history_entry</CODE></A></TD><TD valign=top><A HREF="history.html#SEC11">2.3.2 History List Management</A></TD></TR>
2010: <TR><TD COLSPAN=3> <HR></TD></TR>
2011: <TR><TH><A NAME="vr_G"></A>G</TH><TD></TD><TD></TD></TR>
2012: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX33"><CODE>get_history_event</CODE></A></TD><TD valign=top><A HREF="history.html#SEC16">2.3.7 History Expansion</A></TD></TR>
2013: <TR><TD COLSPAN=3> <HR></TD></TR>
2014: <TR><TH><A NAME="vr_H"></A>H</TH><TD></TD><TD></TD></TR>
2015: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX35"><CODE>history_arg_extract</CODE></A></TD><TD valign=top><A HREF="history.html#SEC16">2.3.7 History Expansion</A></TD></TR>
2016: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX36"><CODE>history_base</CODE></A></TD><TD valign=top><A HREF="history.html#SEC17">2.4 History Variables</A></TD></TR>
2017: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX42"><CODE>history_comment_char</CODE></A></TD><TD valign=top><A HREF="history.html#SEC17">2.4 History Variables</A></TD></TR>
2018: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX32"><CODE>history_expand</CODE></A></TD><TD valign=top><A HREF="history.html#SEC16">2.3.7 History Expansion</A></TD></TR>
2019: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX40"><CODE>history_expansion_char</CODE></A></TD><TD valign=top><A HREF="history.html#SEC17">2.4 History Variables</A></TD></TR>
2020: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX17"><CODE>history_get</CODE></A></TD><TD valign=top><A HREF="history.html#SEC12">2.3.3 Information About the History List</A></TD></TR>
2021: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX3"><CODE>history_get_history_state</CODE></A></TD><TD valign=top><A HREF="history.html#SEC10">2.3.1 Initializing History and State Management</A></TD></TR>
2022: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX18"><CODE>history_get_time</CODE></A></TD><TD valign=top><A HREF="history.html#SEC12">2.3.3 Information About the History List</A></TD></TR>
1.1.1.2 ! misho 2023: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX48"><CODE>history_inhibit_expansion_function</CODE></A></TD><TD valign=top><A HREF="history.html#SEC17">2.4 History Variables</A></TD></TR>
1.1 misho 2024: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX13"><CODE>history_is_stifled</CODE></A></TD><TD valign=top><A HREF="history.html#SEC11">2.3.2 History List Management</A></TD></TR>
2025: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX37"><CODE>history_length</CODE></A></TD><TD valign=top><A HREF="history.html#SEC17">2.4 History Variables</A></TD></TR>
2026: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX14"><CODE>history_list</CODE></A></TD><TD valign=top><A HREF="history.html#SEC12">2.3.3 Information About the History List</A></TD></TR>
2027: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX38"><CODE>history_max_entries</CODE></A></TD><TD valign=top><A HREF="history.html#SEC17">2.4 History Variables</A></TD></TR>
2028: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX45"><CODE>history_no_expand_chars</CODE></A></TD><TD valign=top><A HREF="history.html#SEC17">2.4 History Variables</A></TD></TR>
2029: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX46"><CODE>history_quotes_inhibit_expansion</CODE></A></TD><TD valign=top><A HREF="history.html#SEC17">2.4 History Variables</A></TD></TR>
1.1.1.2 ! misho 2030: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX47"><CODE>history_quoting_state</CODE></A></TD><TD valign=top><A HREF="history.html#SEC17">2.4 History Variables</A></TD></TR>
1.1 misho 2031: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX24"><CODE>history_search</CODE></A></TD><TD valign=top><A HREF="history.html#SEC14">2.3.5 Searching the History List</A></TD></TR>
2032: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX44"><CODE>history_search_delimiter_chars</CODE></A></TD><TD valign=top><A HREF="history.html#SEC17">2.4 History Variables</A></TD></TR>
2033: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX26"><CODE>history_search_pos</CODE></A></TD><TD valign=top><A HREF="history.html#SEC14">2.3.5 Searching the History List</A></TD></TR>
2034: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX25"><CODE>history_search_prefix</CODE></A></TD><TD valign=top><A HREF="history.html#SEC14">2.3.5 Searching the History List</A></TD></TR>
2035: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX4"><CODE>history_set_history_state</CODE></A></TD><TD valign=top><A HREF="history.html#SEC10">2.3.1 Initializing History and State Management</A></TD></TR>
2036: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX20"><CODE>history_set_pos</CODE></A></TD><TD valign=top><A HREF="history.html#SEC13">2.3.4 Moving Around the History List</A></TD></TR>
2037: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX41"><CODE>history_subst_char</CODE></A></TD><TD valign=top><A HREF="history.html#SEC17">2.4 History Variables</A></TD></TR>
2038: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX34"><CODE>history_tokenize</CODE></A></TD><TD valign=top><A HREF="history.html#SEC16">2.3.7 History Expansion</A></TD></TR>
2039: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX19"><CODE>history_total_bytes</CODE></A></TD><TD valign=top><A HREF="history.html#SEC12">2.3.3 Information About the History List</A></TD></TR>
2040: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX31"><CODE>history_truncate_file</CODE></A></TD><TD valign=top><A HREF="history.html#SEC15">2.3.6 Managing the History File</A></TD></TR>
2041: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX43"><CODE>history_word_delimiters</CODE></A></TD><TD valign=top><A HREF="history.html#SEC17">2.4 History Variables</A></TD></TR>
2042: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX39"><CODE>history_write_timestamps</CODE></A></TD><TD valign=top><A HREF="history.html#SEC17">2.4 History Variables</A></TD></TR>
2043: <TR><TD COLSPAN=3> <HR></TD></TR>
2044: <TR><TH><A NAME="vr_N"></A>N</TH><TD></TD><TD></TD></TR>
2045: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX22"><CODE>next_history</CODE></A></TD><TD valign=top><A HREF="history.html#SEC13">2.3.4 Moving Around the History List</A></TD></TR>
2046: <TR><TD COLSPAN=3> <HR></TD></TR>
2047: <TR><TH><A NAME="vr_P"></A>P</TH><TD></TD><TD></TD></TR>
2048: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX21"><CODE>previous_history</CODE></A></TD><TD valign=top><A HREF="history.html#SEC13">2.3.4 Moving Around the History List</A></TD></TR>
2049: <TR><TD COLSPAN=3> <HR></TD></TR>
2050: <TR><TH><A NAME="vr_R"></A>R</TH><TD></TD><TD></TD></TR>
2051: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX27"><CODE>read_history</CODE></A></TD><TD valign=top><A HREF="history.html#SEC15">2.3.6 Managing the History File</A></TD></TR>
2052: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX28"><CODE>read_history_range</CODE></A></TD><TD valign=top><A HREF="history.html#SEC15">2.3.6 Managing the History File</A></TD></TR>
2053: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX7"><CODE>remove_history</CODE></A></TD><TD valign=top><A HREF="history.html#SEC11">2.3.2 History List Management</A></TD></TR>
2054: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX9"><CODE>replace_history_entry</CODE></A></TD><TD valign=top><A HREF="history.html#SEC11">2.3.2 History List Management</A></TD></TR>
2055: <TR><TD COLSPAN=3> <HR></TD></TR>
2056: <TR><TH><A NAME="vr_S"></A>S</TH><TD></TD><TD></TD></TR>
2057: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX11"><CODE>stifle_history</CODE></A></TD><TD valign=top><A HREF="history.html#SEC11">2.3.2 History List Management</A></TD></TR>
2058: <TR><TD COLSPAN=3> <HR></TD></TR>
2059: <TR><TH><A NAME="vr_U"></A>U</TH><TD></TD><TD></TD></TR>
2060: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX12"><CODE>unstifle_history</CODE></A></TD><TD valign=top><A HREF="history.html#SEC11">2.3.2 History List Management</A></TD></TR>
2061: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX2"><CODE>using_history</CODE></A></TD><TD valign=top><A HREF="history.html#SEC10">2.3.1 Initializing History and State Management</A></TD></TR>
2062: <TR><TD COLSPAN=3> <HR></TD></TR>
2063: <TR><TH><A NAME="vr_W"></A>W</TH><TD></TD><TD></TD></TR>
2064: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX15"><CODE>where_history</CODE></A></TD><TD valign=top><A HREF="history.html#SEC12">2.3.3 Information About the History List</A></TD></TR>
2065: <TR><TD></TD><TD valign=top><A HREF="history.html#IDX29"><CODE>write_history</CODE></A></TD><TD valign=top><A HREF="history.html#SEC15">2.3.6 Managing the History File</A></TD></TR>
2066: <TR><TD COLSPAN=3> <HR></TD></TR>
2067: </TABLE><P></P><table><tr><th valign=top>Jump to: </th><td><A HREF="history.html#vr_A" style="text-decoration:none"><b>A</b></A>
2068:
2069: <A HREF="history.html#vr_C" style="text-decoration:none"><b>C</b></A>
2070:
2071: <A HREF="history.html#vr_F" style="text-decoration:none"><b>F</b></A>
2072:
2073: <A HREF="history.html#vr_G" style="text-decoration:none"><b>G</b></A>
2074:
2075: <A HREF="history.html#vr_H" style="text-decoration:none"><b>H</b></A>
2076:
2077: <A HREF="history.html#vr_N" style="text-decoration:none"><b>N</b></A>
2078:
2079: <A HREF="history.html#vr_P" style="text-decoration:none"><b>P</b></A>
2080:
2081: <A HREF="history.html#vr_R" style="text-decoration:none"><b>R</b></A>
2082:
2083: <A HREF="history.html#vr_S" style="text-decoration:none"><b>S</b></A>
2084:
2085: <A HREF="history.html#vr_U" style="text-decoration:none"><b>U</b></A>
2086:
2087: <A HREF="history.html#vr_W" style="text-decoration:none"><b>W</b></A>
2088:
2089: </td></tr></table><br><P>
2090:
2091: <HR SIZE="6">
2092: <A NAME="SEC_Contents"></A>
2093: <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
2094: <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
2095: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
2096: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC21">Index</A>]</TD>
2097: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
2098: </TR></TABLE>
2099: <H1>Table of Contents</H1>
2100: <UL>
2101: <A NAME="TOC1" HREF="history.html#SEC1">1. Using History Interactively</A>
2102: <BR>
2103: <UL>
2104: <A NAME="TOC2" HREF="history.html#SEC2">1.1 History Expansion</A>
2105: <BR>
2106: <UL>
2107: <A NAME="TOC3" HREF="history.html#SEC3">1.1.1 Event Designators</A>
2108: <BR>
2109: <A NAME="TOC4" HREF="history.html#SEC4">1.1.2 Word Designators</A>
2110: <BR>
2111: <A NAME="TOC5" HREF="history.html#SEC5">1.1.3 Modifiers</A>
2112: <BR>
2113: </UL>
2114: </UL>
2115: <A NAME="TOC6" HREF="history.html#SEC6">2. Programming with GNU History</A>
2116: <BR>
2117: <UL>
2118: <A NAME="TOC7" HREF="history.html#SEC7">2.1 Introduction to History</A>
2119: <BR>
2120: <A NAME="TOC8" HREF="history.html#SEC8">2.2 History Storage</A>
2121: <BR>
2122: <A NAME="TOC9" HREF="history.html#SEC9">2.3 History Functions</A>
2123: <BR>
2124: <UL>
2125: <A NAME="TOC10" HREF="history.html#SEC10">2.3.1 Initializing History and State Management</A>
2126: <BR>
2127: <A NAME="TOC11" HREF="history.html#SEC11">2.3.2 History List Management</A>
2128: <BR>
2129: <A NAME="TOC12" HREF="history.html#SEC12">2.3.3 Information About the History List</A>
2130: <BR>
2131: <A NAME="TOC13" HREF="history.html#SEC13">2.3.4 Moving Around the History List</A>
2132: <BR>
2133: <A NAME="TOC14" HREF="history.html#SEC14">2.3.5 Searching the History List</A>
2134: <BR>
2135: <A NAME="TOC15" HREF="history.html#SEC15">2.3.6 Managing the History File</A>
2136: <BR>
2137: <A NAME="TOC16" HREF="history.html#SEC16">2.3.7 History Expansion</A>
2138: <BR>
2139: </UL>
2140: <A NAME="TOC17" HREF="history.html#SEC17">2.4 History Variables</A>
2141: <BR>
2142: <A NAME="TOC18" HREF="history.html#SEC18">2.5 History Programming Example</A>
2143: <BR>
2144: </UL>
2145: <A NAME="TOC19" HREF="history.html#SEC19">A. GNU Free Documentation License</A>
2146: <BR>
2147: <A NAME="TOC21" HREF="history.html#SEC21">B. Concept Index</A>
2148: <BR>
2149: <A NAME="TOC22" HREF="history.html#SEC22">C. Function and Variable Index</A>
2150: <BR>
2151: </UL>
2152: <HR SIZE=1>
2153: <A NAME="SEC_OVERVIEW"></A>
2154: <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
2155: <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
2156: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
2157: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC21">Index</A>]</TD>
2158: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
2159: </TR></TABLE>
2160: <H1>Short Table of Contents</H1>
2161: <BLOCKQUOTE>
2162: <A NAME="TOC1" HREF="history.html#SEC1">1. Using History Interactively</A>
2163: <BR>
2164: <A NAME="TOC6" HREF="history.html#SEC6">2. Programming with GNU History</A>
2165: <BR>
2166: <A NAME="TOC19" HREF="history.html#SEC19">A. GNU Free Documentation License</A>
2167: <BR>
2168: <A NAME="TOC21" HREF="history.html#SEC21">B. Concept Index</A>
2169: <BR>
2170: <A NAME="TOC22" HREF="history.html#SEC22">C. Function and Variable Index</A>
2171: <BR>
2172:
2173: </BLOCKQUOTE>
2174: <HR SIZE=1>
2175: <A NAME="SEC_About"></A>
2176: <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
2177: <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
2178: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
2179: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC21">Index</A>]</TD>
2180: <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
2181: </TR></TABLE>
2182: <H1>About this document</H1>
1.1.1.2 ! misho 2183: This document was generated by <I>Chet Ramey</I> on <I>October, 30 2020</I>
1.1 misho 2184: using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html
2185: "><I>texi2html</I></A>
2186: <P></P>
2187: The buttons in the navigation panels have the following meaning:
2188: <P></P>
2189: <table border = "1">
2190: <TR>
2191: <TH> Button </TH>
2192: <TH> Name </TH>
2193: <TH> Go to </TH>
2194: <TH> From 1.2.3 go to</TH>
2195: </TR>
2196: <TR>
2197: <TD ALIGN="CENTER">
2198: [ < ] </TD>
2199: <TD ALIGN="CENTER">
2200: Back
2201: </TD>
2202: <TD>
2203: previous section in reading order
2204: </TD>
2205: <TD>
2206: 1.2.2
2207: </TD>
2208: </TR>
2209: <TR>
2210: <TD ALIGN="CENTER">
2211: [ > ] </TD>
2212: <TD ALIGN="CENTER">
2213: Forward
2214: </TD>
2215: <TD>
2216: next section in reading order
2217: </TD>
2218: <TD>
2219: 1.2.4
2220: </TD>
2221: </TR>
2222: <TR>
2223: <TD ALIGN="CENTER">
2224: [ << ] </TD>
2225: <TD ALIGN="CENTER">
2226: FastBack
2227: </TD>
2228: <TD>
2229: previous or up-and-previous section
2230: </TD>
2231: <TD>
2232: 1.1
2233: </TD>
2234: </TR>
2235: <TR>
2236: <TD ALIGN="CENTER">
2237: [ Up ] </TD>
2238: <TD ALIGN="CENTER">
2239: Up
2240: </TD>
2241: <TD>
2242: up section
2243: </TD>
2244: <TD>
2245: 1.2
2246: </TD>
2247: </TR>
2248: <TR>
2249: <TD ALIGN="CENTER">
2250: [ >> ] </TD>
2251: <TD ALIGN="CENTER">
2252: FastForward
2253: </TD>
2254: <TD>
2255: next or up-and-next section
2256: </TD>
2257: <TD>
2258: 1.3
2259: </TD>
2260: </TR>
2261: <TR>
2262: <TD ALIGN="CENTER">
2263: [Top] </TD>
2264: <TD ALIGN="CENTER">
2265: Top
2266: </TD>
2267: <TD>
2268: cover (top) of document
2269: </TD>
2270: <TD>
2271:
2272: </TD>
2273: </TR>
2274: <TR>
2275: <TD ALIGN="CENTER">
2276: [Contents] </TD>
2277: <TD ALIGN="CENTER">
2278: Contents
2279: </TD>
2280: <TD>
2281: table of contents
2282: </TD>
2283: <TD>
2284:
2285: </TD>
2286: </TR>
2287: <TR>
2288: <TD ALIGN="CENTER">
2289: [Index] </TD>
2290: <TD ALIGN="CENTER">
2291: Index
2292: </TD>
2293: <TD>
2294: concept index
2295: </TD>
2296: <TD>
2297:
2298: </TD>
2299: </TR>
2300: <TR>
2301: <TD ALIGN="CENTER">
2302: [ ? ] </TD>
2303: <TD ALIGN="CENTER">
2304: About
2305: </TD>
2306: <TD>
2307: this page
2308: </TD>
2309: <TD>
2310:
2311: </TD>
2312: </TR>
2313: </TABLE>
2314: <P></P>
2315: where the <STRONG> Example </STRONG> assumes that the current position
2316: is at <STRONG> Subsubsection One-Two-Three </STRONG> of a document of
2317: the following structure:
2318: <UL>
2319: <LI> 1. Section One </LI>
2320: <UL>
2321: <LI>1.1 Subsection One-One</LI>
2322: <UL>
2323: <LI> ... </LI>
2324: </UL>
2325: <LI>1.2 Subsection One-Two</LI>
2326: <UL>
2327: <LI>1.2.1 Subsubsection One-Two-One
2328: </LI><LI>1.2.2 Subsubsection One-Two-Two
2329: </LI><LI>1.2.3 Subsubsection One-Two-Three <STRONG>
2330: <== Current Position </STRONG>
2331: </LI><LI>1.2.4 Subsubsection One-Two-Four
2332: </LI></UL>
2333: <LI>1.3 Subsection One-Three</LI>
2334: <UL>
2335: <LI> ... </LI>
2336: </UL>
2337: <LI>1.4 Subsection One-Four</LI>
2338: </UL>
2339: </UL>
2340:
2341: <HR SIZE=1>
2342: <BR>
2343: <FONT SIZE="-1">
2344: This document was generated
1.1.1.2 ! misho 2345: by <I>Chet Ramey</I> on <I>October, 30 2020</I>
1.1 misho 2346: using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html
2347: "><I>texi2html</I></A>
2348:
2349: </BODY>
2350: </HTML>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to history.html CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / readline / doc