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