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