readline/doc/history.html

   1 <HTML>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   3 <!-- Created on June, 27  2002 by texi2html 1.64 -->
   4 <!--
   5 Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
   6             Karl Berry  <karl@freefriends.org>
   7             Olaf Bachmann <obachman@mathematik.uni-kl.de>
   8             and many others.
   9 Maintained by: Olaf Bachmann <obachman@mathematik.uni-kl.de>
  10 Send bugs and suggestions to <texi2html@mathematik.uni-kl.de>
  11
  12 -->
  13 <HEAD>
  14 <TITLE>GNU History Library: </TITLE>
  15
  16 <META NAME="description" CONTENT="GNU History Library: ">
  17 <META NAME="keywords" CONTENT="GNU History Library: ">
  18 <META NAME="resource-type" CONTENT="document">
  19 <META NAME="distribution" CONTENT="global">
  20 <META NAME="Generator" CONTENT="texi2html 1.64">
  21
  22 </HEAD>
  23
  24 <BODY LANG="" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000">
  25
  26 <A NAME="SEC_Top"></A>
  27 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
  28 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
  29 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
  30 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19">Index</A>]</TD>
  31 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
  32 </TR></TABLE>
  33 <H1>GNU History Library</H1></P><P>
  34
  35 This document describes the GNU History library, a programming tool that
  36 provides a consistent user interface for recalling lines of previously
  37 typed input.
  38 </P><P>
  39
  40 <BLOCKQUOTE><TABLE BORDER=0 CELLSPACING=0>
  41 <TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC1">1. Using History Interactively</A></TD><TD>&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. Concept Index</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP">Index of concepts described in this manual.</TD></TR>
  44 <TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC20">B. Function and Variable Index</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP">Index of externally visible functions
  45                                   and variables.</TD></TR>
  46 </TABLE></BLOCKQUOTE>
  47 <P>
  48
  49 <HR SIZE=1>
  50 <A NAME="SEC1"></A>
  51 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
  52 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top"> &lt; </A>]</TD>
  53 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC2"> &gt; </A>]</TD>
  54 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
  55 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top"> Up </A>]</TD>
  56 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC6"> &gt;&gt; </A>]</TD>
  57 <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>
  58 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
  59 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19">Index</A>]</TD>
  60 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
  61 </TR></TABLE>
  62 <A NAME="Using History Interactively"></A>
  63 <H1> 1. Using History Interactively </H1>
  64 <!--docid::SEC1::-->
  65 <P>
  66
  67 This chapter describes how to use the GNU History Library interactively,
  68 from a user's standpoint.  It should be considered a user's guide.  For
  69 information on using the GNU History Library in your own programs,
  70 see section <A HREF="history.html#SEC6">2. Programming with GNU History</A>.
  71 </P><P>
  72
  73 <BLOCKQUOTE><TABLE BORDER=0 CELLSPACING=0>
  74 <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>
  75 </TABLE></BLOCKQUOTE>
  76 <P>
  77
  78 <A NAME="History Interaction"></A>
  79 <HR SIZE="6">
  80 <A NAME="SEC2"></A>
  81 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
  82 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC1"> &lt; </A>]</TD>
  83 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC3"> &gt; </A>]</TD>
  84 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
  85 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC1"> Up </A>]</TD>
  86 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC6"> &gt;&gt; </A>]</TD>
  87 <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>
  88 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
  89 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19">Index</A>]</TD>
  90 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
  91 </TR></TABLE>
  92 <H2> 1.1 History Expansion </H2>
  93 <!--docid::SEC2::-->
  94 <P>
  95
  96 The History library provides a history expansion feature that is similar
  97 to the history expansion provided by <CODE>csh</CODE>.  This section
  98 describes the syntax used to manipulate the history information.
  99 </P><P>
 100
 101 History expansions introduce words from the history list into
 102 the input stream, making it easy to repeat commands, insert the
 103 arguments to a previous command into the current input line, or
 104 fix errors in previous commands quickly.
 105 </P><P>
 106
 107 History expansion takes place in two parts.  The first is to determine
 108 which line from the history list should be used during substitution.
 109 The second is to select portions of that line for inclusion into the
 110 current one.  The line selected from the history is called the
 111 <EM>event</EM>, and the portions of that line that are acted upon are
 112 called <EM>words</EM>.  Various <EM>modifiers</EM> are available to manipulate
 113 the selected words.  The line is broken into words in the same fashion
 114 that Bash does, so that several words
 115 surrounded by quotes are considered one word.
 116 History expansions are introduced by the appearance of the
 117 history expansion character, which is <SAMP>`!'</SAMP> by default.
 118 </P><P>
 119
 120 <BLOCKQUOTE><TABLE BORDER=0 CELLSPACING=0>
 121 <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>
 122 <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>
 123 <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>
 124 </TABLE></BLOCKQUOTE>
 125 <P>
 126
 127 <A NAME="Event Designators"></A>
 128 <HR SIZE="6">
 129 <A NAME="SEC3"></A>
 130 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
 131 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC2"> &lt; </A>]</TD>
 132 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC4"> &gt; </A>]</TD>
 133 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
 134 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC2"> Up </A>]</TD>
 135 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC6"> &gt;&gt; </A>]</TD>
 136 <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>
 137 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
 138 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19">Index</A>]</TD>
 139 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
 140 </TR></TABLE>
 141 <H3> 1.1.1 Event Designators </H3>
 142 <!--docid::SEC3::-->
 143 <P>
 144
 145 An event designator is a reference to a command line entry in the
 146 history list.
 147 <A NAME="IDX1"></A>
 148 </P><P>
 149
 150 <DL COMPACT>
 151
 152 <DT><CODE>!</CODE>
 153 <DD>Start a history substitution, except when followed by a space, tab,
 154 the end of the line, <SAMP>`='</SAMP> or <SAMP>`('</SAMP>.
 155 <P>
 156
 157 <DT><CODE>!<VAR>n</VAR></CODE>
 158 <DD>Refer to command line <VAR>n</VAR>.
 159 <P>
 160
 161 <DT><CODE>!-<VAR>n</VAR></CODE>
 162 <DD>Refer to the command <VAR>n</VAR> lines back.
 163 <P>
 164
 165 <DT><CODE>!!</CODE>
 166 <DD>Refer to the previous command.  This is a synonym for <SAMP>`!-1'</SAMP>.
 167 <P>
 168
 169 <DT><CODE>!<VAR>string</VAR></CODE>
 170 <DD>Refer to the most recent command starting with <VAR>string</VAR>.
 171 <P>
 172
 173 <DT><CODE>!?<VAR>string</VAR>[?]</CODE>
 174 <DD>Refer to the most recent command containing <VAR>string</VAR>.  The trailing
 175 <SAMP>`?'</SAMP> may be omitted if the <VAR>string</VAR> is followed immediately by
 176 a newline.
 177 <P>
 178
 179 <DT><CODE>^<VAR>string1</VAR>^<VAR>string2</VAR>^</CODE>
 180 <DD>Quick Substitution.  Repeat the last command, replacing <VAR>string1</VAR>
 181 with <VAR>string2</VAR>.  Equivalent to
 182 <CODE>!!:s/<VAR>string1</VAR>/<VAR>string2</VAR>/</CODE>.
 183 <P>
 184
 185 <DT><CODE>!#</CODE>
 186 <DD>The entire command line typed so far.
 187 <P>
 188
 189 </DL>
 190 <P>
 191
 192 <A NAME="Word Designators"></A>
 193 <HR SIZE="6">
 194 <A NAME="SEC4"></A>
 195 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
 196 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC3"> &lt; </A>]</TD>
 197 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC5"> &gt; </A>]</TD>
 198 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC5"> &lt;&lt; </A>]</TD>
 199 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC2"> Up </A>]</TD>
 200 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC6"> &gt;&gt; </A>]</TD>
 201 <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>
 202 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
 203 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19">Index</A>]</TD>
 204 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
 205 </TR></TABLE>
 206 <H3> 1.1.2 Word Designators </H3>
 207 <!--docid::SEC4::-->
 208 <P>
 209
 210 Word designators are used to select desired words from the event.
 211 A <SAMP>`:'</SAMP> separates the event specification from the word designator.  It
 212 may be omitted if the word designator begins with a <SAMP>`^'</SAMP>, <SAMP>`$'</SAMP>,
 213 <SAMP>`*'</SAMP>, <SAMP>`-'</SAMP>, or <SAMP>`%'</SAMP>.  Words are numbered from the beginning
 214 of the line, with the first word being denoted by 0 (zero).  Words are
 215 inserted into the current line separated by single spaces.
 216 </P><P>
 217
 218 For example,
 219 </P><P>
 220
 221 <DL COMPACT>
 222 <DT><CODE>!!</CODE>
 223 <DD>designates the preceding command.  When you type this, the preceding
 224 command is repeated in toto.
 225 <P>
 226
 227 <DT><CODE>!!:$</CODE>
 228 <DD>designates the last argument of the preceding command.  This may be
 229 shortened to <CODE>!$</CODE>.
 230 <P>
 231
 232 <DT><CODE>!fi:2</CODE>
 233 <DD>designates the second argument of the most recent command starting with
 234 the letters <CODE>fi</CODE>.
 235 </DL>
 236 <P>
 237
 238 Here are the word designators:
 239
 240 <DL COMPACT>
 241
 242 <DT><CODE>0 (zero)</CODE>
 243 <DD>The <CODE>0</CODE>th word.  For many applications, this is the command word.
 244 <P>
 245
 246 <DT><CODE><VAR>n</VAR></CODE>
 247 <DD>The <VAR>n</VAR>th word.
 248 <P>
 249
 250 <DT><CODE>^</CODE>
 251 <DD>The first argument; that is, word 1.
 252 <P>
 253
 254 <DT><CODE>$</CODE>
 255 <DD>The last argument.
 256 <P>
 257
 258 <DT><CODE>%</CODE>
 259 <DD>The word matched by the most recent <SAMP>`?<VAR>string</VAR>?'</SAMP> search.
 260 <P>
 261
 262 <DT><CODE><VAR>x</VAR>-<VAR>y</VAR></CODE>
 263 <DD>A range of words; <SAMP>`-<VAR>y</VAR>'</SAMP> abbreviates <SAMP>`0-<VAR>y</VAR>'</SAMP>.
 264 <P>
 265
 266 <DT><CODE>*</CODE>
 267 <DD>All of the words, except the <CODE>0</CODE>th.  This is a synonym for <SAMP>`1-$'</SAMP>.
 268 It is not an error to use <SAMP>`*'</SAMP> if there is just one word in the event;
 269 the empty string is returned in that case.
 270 <P>
 271
 272 <DT><CODE><VAR>x</VAR>*</CODE>
 273 <DD>Abbreviates <SAMP>`<VAR>x</VAR>-$'</SAMP>
 274 <P>
 275
 276 <DT><CODE><VAR>x</VAR>-</CODE>
 277 <DD>Abbreviates <SAMP>`<VAR>x</VAR>-$'</SAMP> like <SAMP>`<VAR>x</VAR>*'</SAMP>, but omits the last word.
 278 <P>
 279
 280 </DL>
 281 <P>
 282
 283 If a word designator is supplied without an event specification, the
 284 previous command is used as the event.
 285 </P><P>
 286
 287 <A NAME="Modifiers"></A>
 288 <HR SIZE="6">
 289 <A NAME="SEC5"></A>
 290 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
 291 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC4"> &lt; </A>]</TD>
 292 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC6"> &gt; </A>]</TD>
 293 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
 294 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC2"> Up </A>]</TD>
 295 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC6"> &gt;&gt; </A>]</TD>
 296 <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>
 297 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
 298 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19">Index</A>]</TD>
 299 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
 300 </TR></TABLE>
 301 <H3> 1.1.3 Modifiers </H3>
 302 <!--docid::SEC5::-->
 303 <P>
 304
 305 After the optional word designator, you can add a sequence of one or more
 306 of the following modifiers, each preceded by a <SAMP>`:'</SAMP>.
 307 </P><P>
 308
 309 <DL COMPACT>
 310
 311 <DT><CODE>h</CODE>
 312 <DD>Remove a trailing pathname component, leaving only the head.
 313 <P>
 314
 315 <DT><CODE>t</CODE>
 316 <DD>Remove all leading  pathname  components, leaving the tail.
 317 <P>
 318
 319 <DT><CODE>r</CODE>
 320 <DD>Remove a trailing suffix of the form <SAMP>`.<VAR>suffix</VAR>'</SAMP>, leaving
 321 the basename.
 322 <P>
 323
 324 <DT><CODE>e</CODE>
 325 <DD>Remove all but the trailing suffix.
 326 <P>
 327
 328 <DT><CODE>p</CODE>
 329 <DD>Print the new command but do not execute it.
 330 <P>
 331
 332 <DT><CODE>s/<VAR>old</VAR>/<VAR>new</VAR>/</CODE>
 333 <DD>Substitute <VAR>new</VAR> for the first occurrence of <VAR>old</VAR> in the
 334 event line.  Any delimiter may be used in place of <SAMP>`/'</SAMP>.
 335 The delimiter may be quoted in <VAR>old</VAR> and <VAR>new</VAR>
 336 with a single backslash.  If <SAMP>`&#38;'</SAMP> appears in <VAR>new</VAR>,
 337 it is replaced by <VAR>old</VAR>.  A single backslash will quote
 338 the <SAMP>`&#38;'</SAMP>.  The final delimiter is optional if it is the last
 339 character on the input line.
 340 <P>
 341
 342 <DT><CODE>&#38;</CODE>
 343 <DD>Repeat the previous substitution.
 344 <P>
 345
 346 <DT><CODE>g</CODE>
 347 <DD>Cause changes to be applied over the entire event line.  Used in
 348 conjunction with <SAMP>`s'</SAMP>, as in <CODE>gs/<VAR>old</VAR>/<VAR>new</VAR>/</CODE>,
 349 or with <SAMP>`&#38;'</SAMP>.
 350 <P>
 351
 352 </DL>
 353 <P>
 354
 355 <A NAME="Programming with GNU History"></A>
 356 <HR SIZE="6">
 357 <A NAME="SEC6"></A>
 358 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
 359 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC5"> &lt; </A>]</TD>
 360 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC7"> &gt; </A>]</TD>
 361 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
 362 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top"> Up </A>]</TD>
 363 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19"> &gt;&gt; </A>]</TD>
 364 <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>
 365 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
 366 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19">Index</A>]</TD>
 367 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
 368 </TR></TABLE>
 369 <H1> 2. Programming with GNU History </H1>
 370 <!--docid::SEC6::-->
 371 <P>
 372
 373 This chapter describes how to interface programs that you write
 374 with the GNU History Library.
 375 It should be considered a technical guide.
 376 For information on the interactive use of GNU History, see section <A HREF="history.html#SEC1">1. Using History Interactively</A>.
 377 </P><P>
 378
 379 <BLOCKQUOTE><TABLE BORDER=0 CELLSPACING=0>
 380 <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>
 381 <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>
 382 <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>
 383 <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>
 384 <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>
 385 </TABLE></BLOCKQUOTE>
 386 <P>
 387
 388 <A NAME="Introduction to History"></A>
 389 <HR SIZE="6">
 390 <A NAME="SEC7"></A>
 391 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
 392 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC6"> &lt; </A>]</TD>
 393 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC8"> &gt; </A>]</TD>
 394 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
 395 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC6"> Up </A>]</TD>
 396 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19"> &gt;&gt; </A>]</TD>
 397 <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>
 398 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
 399 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19">Index</A>]</TD>
 400 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
 401 </TR></TABLE>
 402 <H2> 2.1 Introduction to History </H2>
 403 <!--docid::SEC7::-->
 404 <P>
 405
 406 Many programs read input from the user a line at a time.  The GNU
 407 History library is able to keep track of those lines, associate arbitrary
 408 data with each line, and utilize information from previous lines in
 409 composing new ones.
 410 </P><P>
 411
 412 The programmer using the History library has available functions
 413 for remembering lines on a history list, associating arbitrary data
 414 with a line, removing lines from the list, searching through the list
 415 for a line containing an arbitrary text string, and referencing any line
 416 in the list directly.  In addition, a history <EM>expansion</EM> function
 417 is available which provides for a consistent user interface across
 418 different programs.
 419 </P><P>
 420
 421 The user using programs written with the History library has the
 422 benefit of a consistent user interface with a set of well-known
 423 commands for manipulating the text of previous lines and using that text
 424 in new commands.  The basic history manipulation commands are similar to
 425 the history substitution provided by <CODE>csh</CODE>.
 426 </P><P>
 427
 428 If the programmer desires, he can use the Readline library, which
 429 includes some history manipulation by default, and has the added
 430 advantage of command line editing.
 431 </P><P>
 432
 433 Before declaring any functions using any functionality the History
 434 library provides in other code, an application writer should include
 435 the file <CODE>&#60;readline/history.h&#62;</CODE> in any file that uses the
 436 History library's features.  It supplies extern declarations for all
 437 of the library's public functions and variables, and declares all of
 438 the public data structures.
 439 </P><P>
 440
 441 <A NAME="History Storage"></A>
 442 <HR SIZE="6">
 443 <A NAME="SEC8"></A>
 444 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
 445 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC7"> &lt; </A>]</TD>
 446 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC9"> &gt; </A>]</TD>
 447 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC9"> &lt;&lt; </A>]</TD>
 448 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC6"> Up </A>]</TD>
 449 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19"> &gt;&gt; </A>]</TD>
 450 <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>
 451 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
 452 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19">Index</A>]</TD>
 453 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
 454 </TR></TABLE>
 455 <H2> 2.2 History Storage </H2>
 456 <!--docid::SEC8::-->
 457 <P>
 458
 459 The history list is an array of history entries.  A history entry is
 460 declared as follows:
 461 </P><P>
 462
 463 <TABLE><tr><td>&nbsp;</td><td class=example><pre>typedef void *histdata_t;
 464
 465 typedef struct _hist_entry {
 466   char *line;
 467   histdata_t data;
 468 } HIST_ENTRY;
 469 </pre></td></tr></table></P><P>
 470
 471 The history list itself might therefore be declared as
 472 </P><P>
 473
 474 <TABLE><tr><td>&nbsp;</td><td class=example><pre>HIST_ENTRY **the_history_list;
 475 </pre></td></tr></table></P><P>
 476
 477 The state of the History library is encapsulated into a single structure:
 478 </P><P>
 479
 480 <TABLE><tr><td>&nbsp;</td><td class=example><pre>/*
 481  * A structure used to pass around the current state of the history.
 482  */
 483 typedef struct _hist_state {
 484   HIST_ENTRY **entries; /* Pointer to the entries themselves. */
 485   int offset;           /* The location pointer within this array. */
 486   int length;           /* Number of elements within this array. */
 487   int size;             /* Number of slots allocated to this array. */
 488   int flags;
 489 } HISTORY_STATE;
 490 </pre></td></tr></table></P><P>
 491
 492 If the flags member includes <CODE>HS_STIFLED</CODE>, the history has been
 493 stifled.
 494 </P><P>
 495
 496 <A NAME="History Functions"></A>
 497 <HR SIZE="6">
 498 <A NAME="SEC9"></A>
 499 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
 500 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC8"> &lt; </A>]</TD>
 501 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC10"> &gt; </A>]</TD>
 502 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> &lt;&lt; </A>]</TD>
 503 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC6"> Up </A>]</TD>
 504 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> &gt;&gt; </A>]</TD>
 505 <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>
 506 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
 507 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19">Index</A>]</TD>
 508 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
 509 </TR></TABLE>
 510 <H2> 2.3 History Functions </H2>
 511 <!--docid::SEC9::-->
 512 <P>
 513
 514 This section describes the calling sequence for the various functions
 515 exported by the GNU History library.
 516 </P><P>
 517
 518 <BLOCKQUOTE><TABLE BORDER=0 CELLSPACING=0>
 519 <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
 520                                                 want to use history in a
 521                                                 program.</TD></TR>
 522 <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
 523                                         of history entries.</TD></TR>
 524 <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
 525                                         the history list.</TD></TR>
 526 <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
 527                                         in the history list.</TD></TR>
 528 <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
 529                                         for entries containing a string.</TD></TR>
 530 <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
 531                                         containing the history list.</TD></TR>
 532 <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
 533                                         expansion.</TD></TR>
 534 </TABLE></BLOCKQUOTE>
 535 <P>
 536
 537 <A NAME="Initializing History and State Management"></A>
 538 <HR SIZE="6">
 539 <A NAME="SEC10"></A>
 540 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
 541 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC9"> &lt; </A>]</TD>
 542 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC11"> &gt; </A>]</TD>
 543 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> &lt;&lt; </A>]</TD>
 544 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC9"> Up </A>]</TD>
 545 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> &gt;&gt; </A>]</TD>
 546 <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>
 547 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
 548 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19">Index</A>]</TD>
 549 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
 550 </TR></TABLE>
 551 <H3> 2.3.1 Initializing History and State Management </H3>
 552 <!--docid::SEC10::-->
 553 <P>
 554
 555 This section describes functions used to initialize and manage
 556 the state of the History library when you want to use the history
 557 functions in your program.
 558 </P><P>
 559
 560 <A NAME="IDX2"></A>
 561 <DL>
 562 <DT><U>Function:</U> void <B>using_history</B> <I>(void)</I>
 563 <DD>Begin a session in which the history functions might be used.  This
 564 initializes the interactive variables.
 565 </DL>
 566 </P><P>
 567
 568 <A NAME="IDX3"></A>
 569 <DL>
 570 <DT><U>Function:</U> HISTORY_STATE * <B>history_get_history_state</B> <I>(void)</I>
 571 <DD>Return a structure describing the current state of the input history.
 572 </DL>
 573 </P><P>
 574
 575 <A NAME="IDX4"></A>
 576 <DL>
 577 <DT><U>Function:</U> void <B>history_set_history_state</B> <I>(HISTORY_STATE *state)</I>
 578 <DD>Set the state of the history list according to <VAR>state</VAR>.
 579 </DL>
 580 </P><P>
 581
 582 <A NAME="History List Management"></A>
 583 <HR SIZE="6">
 584 <A NAME="SEC11"></A>
 585 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
 586 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC10"> &lt; </A>]</TD>
 587 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC12"> &gt; </A>]</TD>
 588 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC12"> &lt;&lt; </A>]</TD>
 589 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC9"> Up </A>]</TD>
 590 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> &gt;&gt; </A>]</TD>
 591 <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>
 592 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
 593 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19">Index</A>]</TD>
 594 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
 595 </TR></TABLE>
 596 <H3> 2.3.2 History List Management </H3>
 597 <!--docid::SEC11::-->
 598 <P>
 599
 600 These functions manage individual entries on the history list, or set
 601 parameters managing the list itself.
 602 </P><P>
 603
 604 <A NAME="IDX5"></A>
 605 <DL>
 606 <DT><U>Function:</U> void <B>add_history</B> <I>(const char *string)</I>
 607 <DD>Place <VAR>string</VAR> at the end of the history list.  The associated data
 608 field (if any) is set to <CODE>NULL</CODE>.
 609 </DL>
 610 </P><P>
 611
 612 <A NAME="IDX6"></A>
 613 <DL>
 614 <DT><U>Function:</U> HIST_ENTRY * <B>remove_history</B> <I>(int which)</I>
 615 <DD>Remove history entry at offset <VAR>which</VAR> from the history.  The
 616 removed element is returned so you can free the line, data,
 617 and containing structure.
 618 </DL>
 619 </P><P>
 620
 621 <A NAME="IDX7"></A>
 622 <DL>
 623 <DT><U>Function:</U> HIST_ENTRY * <B>replace_history_entry</B> <I>(int which, const char *line, histdata_t data)</I>
 624 <DD>Make the history entry at offset <VAR>which</VAR> have <VAR>line</VAR> and <VAR>data</VAR>.
 625 This returns the old entry so you can dispose of the data.  In the case
 626 of an invalid <VAR>which</VAR>, a <CODE>NULL</CODE> pointer is returned.
 627 </DL>
 628 </P><P>
 629
 630 <A NAME="IDX8"></A>
 631 <DL>
 632 <DT><U>Function:</U> void <B>clear_history</B> <I>(void)</I>
 633 <DD>Clear the history list by deleting all the entries.
 634 </DL>
 635 </P><P>
 636
 637 <A NAME="IDX9"></A>
 638 <DL>
 639 <DT><U>Function:</U> void <B>stifle_history</B> <I>(int max)</I>
 640 <DD>Stifle the history list, remembering only the last <VAR>max</VAR> entries.
 641 </DL>
 642 </P><P>
 643
 644 <A NAME="IDX10"></A>
 645 <DL>
 646 <DT><U>Function:</U> int <B>unstifle_history</B> <I>(void)</I>
 647 <DD>Stop stifling the history.  This returns the previously-set
 648 maximum number of history entries (as set by <CODE>stifle_history()</CODE>).
 649 The value is positive if the history was
 650 stifled, negative if it wasn't.
 651 </DL>
 652 </P><P>
 653
 654 <A NAME="IDX11"></A>
 655 <DL>
 656 <DT><U>Function:</U> int <B>history_is_stifled</B> <I>(void)</I>
 657 <DD>Returns non-zero if the history is stifled, zero if it is not.
 658 </DL>
 659 </P><P>
 660
 661 <A NAME="Information About the History List"></A>
 662 <HR SIZE="6">
 663 <A NAME="SEC12"></A>
 664 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
 665 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC11"> &lt; </A>]</TD>
 666 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC13"> &gt; </A>]</TD>
 667 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC13"> &lt;&lt; </A>]</TD>
 668 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC9"> Up </A>]</TD>
 669 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> &gt;&gt; </A>]</TD>
 670 <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>
 671 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
 672 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19">Index</A>]</TD>
 673 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
 674 </TR></TABLE>
 675 <H3> 2.3.3 Information About the History List </H3>
 676 <!--docid::SEC12::-->
 677 <P>
 678
 679 These functions return information about the entire history list or
 680 individual list entries.
 681 </P><P>
 682
 683 <A NAME="IDX12"></A>
 684 <DL>
 685 <DT><U>Function:</U> HIST_ENTRY ** <B>history_list</B> <I>(void)</I>
 686 <DD>Return a <CODE>NULL</CODE> terminated array of <CODE>HIST_ENTRY *</CODE> which is the
 687 current input history.  Element 0 of this list is the beginning of time.
 688 If there is no history, return <CODE>NULL</CODE>.
 689 </DL>
 690 </P><P>
 691
 692 <A NAME="IDX13"></A>
 693 <DL>
 694 <DT><U>Function:</U> int <B>where_history</B> <I>(void)</I>
 695 <DD>Returns the offset of the current history element.
 696 </DL>
 697 </P><P>
 698
 699 <A NAME="IDX14"></A>
 700 <DL>
 701 <DT><U>Function:</U> HIST_ENTRY * <B>current_history</B> <I>(void)</I>
 702 <DD>Return the history entry at the current position, as determined by
 703 <CODE>where_history()</CODE>.  If there is no entry there, return a <CODE>NULL</CODE>
 704 pointer.
 705 </DL>
 706 </P><P>
 707
 708 <A NAME="IDX15"></A>
 709 <DL>
 710 <DT><U>Function:</U> HIST_ENTRY * <B>history_get</B> <I>(int offset)</I>
 711 <DD>Return the history entry at position <VAR>offset</VAR>, starting from
 712 <CODE>history_base</CODE> (see section <A HREF="history.html#SEC17">2.4 History Variables</A>).
 713 If there is no entry there, or if <VAR>offset</VAR>
 714 is greater than the history length, return a <CODE>NULL</CODE> pointer.
 715 </DL>
 716 </P><P>
 717
 718 <A NAME="IDX16"></A>
 719 <DL>
 720 <DT><U>Function:</U> int <B>history_total_bytes</B> <I>(void)</I>
 721 <DD>Return the number of bytes that the primary history entries are using.
 722 This function returns the sum of the lengths of all the lines in the
 723 history.
 724 </DL>
 725 </P><P>
 726
 727 <A NAME="Moving Around the History List"></A>
 728 <HR SIZE="6">
 729 <A NAME="SEC13"></A>
 730 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
 731 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC12"> &lt; </A>]</TD>
 732 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC14"> &gt; </A>]</TD>
 733 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC14"> &lt;&lt; </A>]</TD>
 734 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC9"> Up </A>]</TD>
 735 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> &gt;&gt; </A>]</TD>
 736 <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>
 737 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
 738 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19">Index</A>]</TD>
 739 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
 740 </TR></TABLE>
 741 <H3> 2.3.4 Moving Around the History List </H3>
 742 <!--docid::SEC13::-->
 743 <P>
 744
 745 These functions allow the current index into the history list to be
 746 set or changed.
 747 </P><P>
 748
 749 <A NAME="IDX17"></A>
 750 <DL>
 751 <DT><U>Function:</U> int <B>history_set_pos</B> <I>(int pos)</I>
 752 <DD>Set the current history offset to <VAR>pos</VAR>, an absolute index
 753 into the list.
 754 Returns 1 on success, 0 if <VAR>pos</VAR> is less than zero or greater
 755 than the number of history entries.
 756 </DL>
 757 </P><P>
 758
 759 <A NAME="IDX18"></A>
 760 <DL>
 761 <DT><U>Function:</U> HIST_ENTRY * <B>previous_history</B> <I>(void)</I>
 762 <DD>Back up the current history offset to the previous history entry, and
 763 return a pointer to that entry.  If there is no previous entry, return
 764 a <CODE>NULL</CODE> pointer.
 765 </DL>
 766 </P><P>
 767
 768 <A NAME="IDX19"></A>
 769 <DL>
 770 <DT><U>Function:</U> HIST_ENTRY * <B>next_history</B> <I>(void)</I>
 771 <DD>Move the current history offset forward to the next history entry, and
 772 return the a pointer to that entry.  If there is no next entry, return
 773 a <CODE>NULL</CODE> pointer.
 774 </DL>
 775 </P><P>
 776
 777 <A NAME="Searching the History List"></A>
 778 <HR SIZE="6">
 779 <A NAME="SEC14"></A>
 780 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
 781 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC13"> &lt; </A>]</TD>
 782 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC15"> &gt; </A>]</TD>
 783 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC15"> &lt;&lt; </A>]</TD>
 784 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC9"> Up </A>]</TD>
 785 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> &gt;&gt; </A>]</TD>
 786 <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>
 787 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
 788 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19">Index</A>]</TD>
 789 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
 790 </TR></TABLE>
 791 <H3> 2.3.5 Searching the History List </H3>
 792 <!--docid::SEC14::-->
 793 <P>
 794
 795 These functions allow searching of the history list for entries containing
 796 a specific string.  Searching may be performed both forward and backward
 797 from the current history position.  The search may be <EM>anchored</EM>,
 798 meaning that the string must match at the beginning of the history entry.
 799 <A NAME="IDX20"></A>
 800 </P><P>
 801
 802 <A NAME="IDX21"></A>
 803 <DL>
 804 <DT><U>Function:</U> int <B>history_search</B> <I>(const char *string, int direction)</I>
 805 <DD>Search the history for <VAR>string</VAR>, starting at the current history offset.
 806 If <VAR>direction</VAR> is less than 0, then the search is through
 807 previous entries, otherwise through subsequent entries.
 808 If <VAR>string</VAR> is found, then
 809 the current history index is set to that history entry, and the value
 810 returned is the offset in the line of the entry where
 811 <VAR>string</VAR> was found.  Otherwise, nothing is changed, and a -1 is
 812 returned.
 813 </DL>
 814 </P><P>
 815
 816 <A NAME="IDX22"></A>
 817 <DL>
 818 <DT><U>Function:</U> int <B>history_search_prefix</B> <I>(const char *string, int direction)</I>
 819 <DD>Search the history for <VAR>string</VAR>, starting at the current history
 820 offset.  The search is anchored: matching lines must begin with
 821 <VAR>string</VAR>.  If <VAR>direction</VAR> is less than 0, then the search is
 822 through previous entries, otherwise through subsequent entries.
 823 If <VAR>string</VAR> is found, then the
 824 current history index is set to that entry, and the return value is 0.
 825 Otherwise, nothing is changed, and a -1 is returned.
 826 </DL>
 827 </P><P>
 828
 829 <A NAME="IDX23"></A>
 830 <DL>
 831 <DT><U>Function:</U> int <B>history_search_pos</B> <I>(const char *string, int direction, int pos)</I>
 832 <DD>Search for <VAR>string</VAR> in the history list, starting at <VAR>pos</VAR>, an
 833 absolute index into the list.  If <VAR>direction</VAR> is negative, the search
 834 proceeds backward from <VAR>pos</VAR>, otherwise forward.  Returns the absolute
 835 index of the history element where <VAR>string</VAR> was found, or -1 otherwise.
 836 </DL>
 837 </P><P>
 838
 839 <A NAME="Managing the History File"></A>
 840 <HR SIZE="6">
 841 <A NAME="SEC15"></A>
 842 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
 843 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC14"> &lt; </A>]</TD>
 844 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC16"> &gt; </A>]</TD>
 845 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC16"> &lt;&lt; </A>]</TD>
 846 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC9"> Up </A>]</TD>
 847 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> &gt;&gt; </A>]</TD>
 848 <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>
 849 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
 850 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19">Index</A>]</TD>
 851 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
 852 </TR></TABLE>
 853 <H3> 2.3.6 Managing the History File </H3>
 854 <!--docid::SEC15::-->
 855 <P>
 856
 857 The History library can read the history from and write it to a file.
 858 This section documents the functions for managing a history file.
 859 </P><P>
 860
 861 <A NAME="IDX24"></A>
 862 <DL>
 863 <DT><U>Function:</U> int <B>read_history</B> <I>(const char *filename)</I>
 864 <DD>Add the contents of <VAR>filename</VAR> to the history list, a line at a time.
 865 If <VAR>filename</VAR> is <CODE>NULL</CODE>, then read from <TT>`~/.history'</TT>.
 866 Returns 0 if successful, or <CODE>errno</CODE> if not.
 867 </DL>
 868 </P><P>
 869
 870 <A NAME="IDX25"></A>
 871 <DL>
 872 <DT><U>Function:</U> int <B>read_history_range</B> <I>(const char *filename, int from, int to)</I>
 873 <DD>Read a range of lines from <VAR>filename</VAR>, adding them to the history list.
 874 Start reading at line <VAR>from</VAR> and end at <VAR>to</VAR>.
 875 If <VAR>from</VAR> is zero, start at the beginning.  If <VAR>to</VAR> is less than
 876 <VAR>from</VAR>, then read until the end of the file.  If <VAR>filename</VAR> is
 877 <CODE>NULL</CODE>, then read from <TT>`~/.history'</TT>.  Returns 0 if successful,
 878 or <CODE>errno</CODE> if not.
 879 </DL>
 880 </P><P>
 881
 882 <A NAME="IDX26"></A>
 883 <DL>
 884 <DT><U>Function:</U> int <B>write_history</B> <I>(const char *filename)</I>
 885 <DD>Write the current history to <VAR>filename</VAR>, overwriting <VAR>filename</VAR>
 886 if necessary.
 887 If <VAR>filename</VAR> is <CODE>NULL</CODE>, then write the history list to
 888 <TT>`~/.history'</TT>.
 889 Returns 0 on success, or <CODE>errno</CODE> on a read or write error.
 890 </DL>
 891 </P><P>
 892
 893 <A NAME="IDX27"></A>
 894 <DL>
 895 <DT><U>Function:</U> int <B>append_history</B> <I>(int nelements, const char *filename)</I>
 896 <DD>Append the last <VAR>nelements</VAR> of the history list to <VAR>filename</VAR>.
 897 If <VAR>filename</VAR> is <CODE>NULL</CODE>, then append to <TT>`~/.history'</TT>.
 898 Returns 0 on success, or <CODE>errno</CODE> on a read or write error.
 899 </DL>
 900 </P><P>
 901
 902 <A NAME="IDX28"></A>
 903 <DL>
 904 <DT><U>Function:</U> int <B>history_truncate_file</B> <I>(const char *filename, int nlines)</I>
 905 <DD>Truncate the history file <VAR>filename</VAR>, leaving only the last
 906 <VAR>nlines</VAR> lines.
 907 If <VAR>filename</VAR> is <CODE>NULL</CODE>, then <TT>`~/.history'</TT> is truncated.
 908 Returns 0 on success, or <CODE>errno</CODE> on failure.
 909 </DL>
 910 </P><P>
 911
 912 <A NAME="History Expansion"></A>
 913 <HR SIZE="6">
 914 <A NAME="SEC16"></A>
 915 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
 916 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC15"> &lt; </A>]</TD>
 917 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> &gt; </A>]</TD>
 918 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> &lt;&lt; </A>]</TD>
 919 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC9"> Up </A>]</TD>
 920 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> &gt;&gt; </A>]</TD>
 921 <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>
 922 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
 923 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19">Index</A>]</TD>
 924 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
 925 </TR></TABLE>
 926 <H3> 2.3.7 History Expansion </H3>
 927 <!--docid::SEC16::-->
 928 <P>
 929
 930 These functions implement history expansion.
 931 </P><P>
 932
 933 <A NAME="IDX29"></A>
 934 <DL>
 935 <DT><U>Function:</U> int <B>history_expand</B> <I>(char *string, char **output)</I>
 936 <DD>Expand <VAR>string</VAR>, placing the result into <VAR>output</VAR>, a pointer
 937 to a string (see section <A HREF="history.html#SEC2">1.1 History Expansion</A>).  Returns:
 938 <DL COMPACT>
 939 <DT><CODE>0</CODE>
 940 <DD>If no expansions took place (or, if the only change in
 941 the text was the removal of escape characters preceding the history expansion
 942 character);
 943 <DT><CODE>1</CODE>
 944 <DD>if expansions did take place;
 945 <DT><CODE>-1</CODE>
 946 <DD>if there was an error in expansion;
 947 <DT><CODE>2</CODE>
 948 <DD>if the returned line should be displayed, but not executed,
 949 as with the <CODE>:p</CODE> modifier (see section <A HREF="history.html#SEC5">1.1.3 Modifiers</A>).
 950 </DL>
 951 <P>
 952
 953 If an error ocurred in expansion, then <VAR>output</VAR> contains a descriptive
 954 error message.
 955 </DL>
 956 </P><P>
 957
 958 <A NAME="IDX30"></A>
 959 <DL>
 960 <DT><U>Function:</U> char * <B>get_history_event</B> <I>(const char *string, int *cindex, int qchar)</I>
 961 <DD>Returns the text of the history event beginning at <VAR>string</VAR> +
 962 <VAR>*cindex</VAR>.  <VAR>*cindex</VAR> is modified to point to after the event
 963 specifier.  At function entry, <VAR>cindex</VAR> points to the index into
 964 <VAR>string</VAR> where the history event specification begins.  <VAR>qchar</VAR>
 965 is a character that is allowed to end the event specification in addition
 966 to the "normal" terminating characters.
 967 </DL>
 968 </P><P>
 969
 970 <A NAME="IDX31"></A>
 971 <DL>
 972 <DT><U>Function:</U> char ** <B>history_tokenize</B> <I>(const char *string)</I>
 973 <DD>Return an array of tokens parsed out of <VAR>string</VAR>, much as the
 974 shell might.  The tokens are split on the characters in the
 975 <VAR>history_word_delimiters</VAR> variable,
 976 and shell quoting conventions are obeyed.
 977 </DL>
 978 </P><P>
 979
 980 <A NAME="IDX32"></A>
 981 <DL>
 982 <DT><U>Function:</U> char * <B>history_arg_extract</B> <I>(int first, int last, const char *string)</I>
 983 <DD>Extract a string segment consisting of the <VAR>first</VAR> through <VAR>last</VAR>
 984 arguments present in <VAR>string</VAR>.  Arguments are split using
 985 <CODE>history_tokenize</CODE>.
 986 </DL>
 987 </P><P>
 988
 989 <A NAME="History Variables"></A>
 990 <HR SIZE="6">
 991 <A NAME="SEC17"></A>
 992 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
 993 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC16"> &lt; </A>]</TD>
 994 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC18"> &gt; </A>]</TD>
 995 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC18"> &lt;&lt; </A>]</TD>
 996 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC6"> Up </A>]</TD>
 997 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19"> &gt;&gt; </A>]</TD>
 998 <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>
 999 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
1000 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19">Index</A>]</TD>
1001 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
1002 </TR></TABLE>
1003 <H2> 2.4 History Variables </H2>
1004 <!--docid::SEC17::-->
1005 <P>
1006
1007 This section describes the externally-visible variables exported by
1008 the GNU History Library.
1009 </P><P>
1010
1011 <A NAME="IDX33"></A>
1012 <DL>
1013 <DT><U>Variable:</U> int <B>history_base</B>
1014 <DD>The logical offset of the first entry in the history list.
1015 </DL>
1016 </P><P>
1017
1018 <A NAME="IDX34"></A>
1019 <DL>
1020 <DT><U>Variable:</U> int <B>history_length</B>
1021 <DD>The number of entries currently stored in the history list.
1022 </DL>
1023 </P><P>
1024
1025 <A NAME="IDX35"></A>
1026 <DL>
1027 <DT><U>Variable:</U> int <B>history_max_entries</B>
1028 <DD>The maximum number of history entries.  This must be changed using
1029 <CODE>stifle_history()</CODE>.
1030 </DL>
1031 </P><P>
1032
1033 <A NAME="IDX36"></A>
1034 <DL>
1035 <DT><U>Variable:</U> char <B>history_expansion_char</B>
1036 <DD>The character that introduces a history event.  The default is <SAMP>`!'</SAMP>.
1037 Setting this to 0 inhibits history expansion.
1038 </DL>
1039 </P><P>
1040
1041 <A NAME="IDX37"></A>
1042 <DL>
1043 <DT><U>Variable:</U> char <B>history_subst_char</B>
1044 <DD>The character that invokes word substitution if found at the start of
1045 a line.  The default is <SAMP>`^'</SAMP>.
1046 </DL>
1047 </P><P>
1048
1049 <A NAME="IDX38"></A>
1050 <DL>
1051 <DT><U>Variable:</U> char <B>history_comment_char</B>
1052 <DD>During tokenization, if this character is seen as the first character
1053 of a word, then it and all subsequent characters up to a newline are
1054 ignored, suppressing history expansion for the remainder of the line.
1055 This is disabled by default.
1056 </DL>
1057 </P><P>
1058
1059 <A NAME="IDX39"></A>
1060 <DL>
1061 <DT><U>Variable:</U> char * <B>history_word_delimiters</B>
1062 <DD>The characters that separate tokens for <CODE>history_tokenize()</CODE>.
1063 The default value is <CODE>" \t\n()<>;&|"</CODE>.
1064 </DL>
1065 </P><P>
1066
1067 <A NAME="IDX40"></A>
1068 <DL>
1069 <DT><U>Variable:</U> char * <B>history_no_expand_chars</B>
1070 <DD>The list of characters which inhibit history expansion if found immediately
1071 following <VAR>history_expansion_char</VAR>.  The default is space, tab, newline,
1072 carriage return, and <SAMP>`='</SAMP>.
1073 </DL>
1074 </P><P>
1075
1076 <A NAME="IDX41"></A>
1077 <DL>
1078 <DT><U>Variable:</U> char * <B>history_search_delimiter_chars</B>
1079 <DD>The list of additional characters which can delimit a history search
1080 string, in addition to space, TAB, <SAMP>`:'</SAMP> and <SAMP>`?'</SAMP> in the case of
1081 a substring search.  The default is empty.
1082 </DL>
1083 </P><P>
1084
1085 <A NAME="IDX42"></A>
1086 <DL>
1087 <DT><U>Variable:</U> int <B>history_quotes_inhibit_expansion</B>
1088 <DD>If non-zero, single-quoted words are not scanned for the history expansion
1089 character.  The default value is 0.
1090 </DL>
1091 </P><P>
1092
1093 <A NAME="IDX43"></A>
1094 <DL>
1095 <DT><U>Variable:</U> rl_linebuf_func_t * <B>history_inhibit_expansion_function</B>
1096 <DD>This should be set to the address of a function that takes two arguments:
1097 a <CODE>char *</CODE> (<VAR>string</VAR>)
1098 and an <CODE>int</CODE> index into that string (<VAR>i</VAR>).
1099 It should return a non-zero value if the history expansion starting at
1100 <VAR>string[i]</VAR> should not be performed; zero if the expansion should
1101 be done.
1102 It is intended for use by applications like Bash that use the history
1103 expansion character for additional purposes.
1104 By default, this variable is set to <CODE>NULL</CODE>.
1105 </DL>
1106 </P><P>
1107
1108 <A NAME="History Programming Example"></A>
1109 <HR SIZE="6">
1110 <A NAME="SEC18"></A>
1111 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1112 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> &lt; </A>]</TD>
1113 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19"> &gt; </A>]</TD>
1114 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
1115 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC6"> Up </A>]</TD>
1116 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19"> &gt;&gt; </A>]</TD>
1117 <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>
1118 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
1119 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19">Index</A>]</TD>
1120 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
1121 </TR></TABLE>
1122 <H2> 2.5 History Programming Example </H2>
1123 <!--docid::SEC18::-->
1124 <P>
1125
1126 The following program demonstrates simple use of the GNU History Library.
1127 </P><P>
1128
1129 <TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=-1><pre>#include &#60;stdio.h&#62;
1130 #include &#60;readline/history.h&#62;
1131
1132 main (argc, argv)
1133      int argc;
1134      char **argv;
1135 {
1136   char line[1024], *t;
1137   int len, done = 0;
1138
1139   line[0] = 0;
1140
1141   using_history ();
1142   while (!done)
1143     {
1144       printf ("history$ ");
1145       fflush (stdout);
1146       t = fgets (line, sizeof (line) - 1, stdin);
1147       if (t &#38;&#38; *t)
1148         {
1149           len = strlen (t);
1150           if (t[len - 1] == '\n')
1151             t[len - 1] = '\0';
1152         }
1153
1154       if (!t)
1155         strcpy (line, "quit");
1156
1157       if (line[0])
1158         {
1159           char *expansion;
1160           int result;
1161
1162           result = history_expand (line, &#38;expansion);
1163           if (result)
1164             fprintf (stderr, "%s\n", expansion);
1165
1166           if (result &#60; 0 || result == 2)
1167             {
1168               free (expansion);
1169               continue;
1170             }
1171
1172           add_history (expansion);
1173           strncpy (line, expansion, sizeof (line) - 1);
1174           free (expansion);
1175         }
1176
1177       if (strcmp (line, "quit") == 0)
1178         done = 1;
1179       else if (strcmp (line, "save") == 0)
1180         write_history ("history_file");
1181       else if (strcmp (line, "read") == 0)
1182         read_history ("history_file");
1183       else if (strcmp (line, "list") == 0)
1184         {
1185           register HIST_ENTRY **the_list;
1186           register int i;
1187
1188           the_list = history_list ();
1189           if (the_list)
1190             for (i = 0; the_list[i]; i++)
1191               printf ("%d: %s\n", i + history_base, the_list[i]-&#62;line);
1192         }
1193       else if (strncmp (line, "delete", 6) == 0)
1194         {
1195           int which;
1196           if ((sscanf (line + 6, "%d", &#38;which)) == 1)
1197             {
1198               HIST_ENTRY *entry = remove_history (which);
1199               if (!entry)
1200                 fprintf (stderr, "No such entry %d\n", which);
1201               else
1202                 {
1203                   free (entry-&#62;line);
1204                   free (entry);
1205                 }
1206             }
1207           else
1208             {
1209               fprintf (stderr, "non-numeric arg given to `delete'\n");
1210             }
1211         }
1212     }
1213 }
1214 </FONT></pre></td></tr></table></P><P>
1215
1216 <A NAME="Concept Index"></A>
1217 <HR SIZE="6">
1218 <A NAME="SEC19"></A>
1219 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1220 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC18"> &lt; </A>]</TD>
1221 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC20"> &gt; </A>]</TD>
1222 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC6"> &lt;&lt; </A>]</TD>
1223 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top"> Up </A>]</TD>
1224 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC20"> &gt;&gt; </A>]</TD>
1225 <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>
1226 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
1227 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19">Index</A>]</TD>
1228 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
1229 </TR></TABLE>
1230 <H1> A. Concept Index </H1>
1231 <!--docid::SEC19::-->
1232 <table><tr><th valign=top>Jump to: &nbsp; </th><td><A HREF="history.html#cp_A" style="text-decoration:none"><b>A</b></A>
1233  &nbsp;
1234 <A HREF="history.html#cp_E" style="text-decoration:none"><b>E</b></A>
1235  &nbsp;
1236 <A HREF="history.html#cp_H" style="text-decoration:none"><b>H</b></A>
1237  &nbsp;
1238 </td></tr></table><br><P></P>
1239 <TABLE border=0>
1240 <TR><TD></TD><TH ALIGN=LEFT>Index Entry</TH><TH ALIGN=LEFT> Section</TH></TR>
1241 <TR><TD COLSPAN=3> <HR></TD></TR>
1242 <TR><TH><A NAME="cp_A"></A>A</TH><TD></TD><TD></TD></TR>
1243 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX20">anchored search</A></TD><TD valign=top><A HREF="history.html#SEC14">2.3.5 Searching the History List</A></TD></TR>
1244 <TR><TD COLSPAN=3> <HR></TD></TR>
1245 <TR><TH><A NAME="cp_E"></A>E</TH><TD></TD><TD></TD></TR>
1246 <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>
1247 <TR><TD COLSPAN=3> <HR></TD></TR>
1248 <TR><TH><A NAME="cp_H"></A>H</TH><TD></TD><TD></TD></TR>
1249 <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>
1250 <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>
1251 <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>
1252 <TR><TD COLSPAN=3> <HR></TD></TR>
1253 </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>
1254  &nbsp;
1255 <A HREF="history.html#cp_E" style="text-decoration:none"><b>E</b></A>
1256  &nbsp;
1257 <A HREF="history.html#cp_H" style="text-decoration:none"><b>H</b></A>
1258  &nbsp;
1259 </td></tr></table><br><P>
1260
1261 <A NAME="Function and Variable Index"></A>
1262 <HR SIZE="6">
1263 <A NAME="SEC20"></A>
1264 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1265 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19"> &lt; </A>]</TD>
1266 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt; ]</TD>
1267 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
1268 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top"> Up </A>]</TD>
1269 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
1270 <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>
1271 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
1272 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19">Index</A>]</TD>
1273 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
1274 </TR></TABLE>
1275 <H1> B. Function and Variable Index </H1>
1276 <!--docid::SEC20::-->
1277 <table><tr><th valign=top>Jump to: &nbsp; </th><td><A HREF="history.html#vr_A" style="text-decoration:none"><b>A</b></A>
1278  &nbsp;
1279 <A HREF="history.html#vr_C" style="text-decoration:none"><b>C</b></A>
1280  &nbsp;
1281 <A HREF="history.html#vr_G" style="text-decoration:none"><b>G</b></A>
1282  &nbsp;
1283 <A HREF="history.html#vr_H" style="text-decoration:none"><b>H</b></A>
1284  &nbsp;
1285 <A HREF="history.html#vr_N" style="text-decoration:none"><b>N</b></A>
1286  &nbsp;
1287 <A HREF="history.html#vr_P" style="text-decoration:none"><b>P</b></A>
1288  &nbsp;
1289 <A HREF="history.html#vr_R" style="text-decoration:none"><b>R</b></A>
1290  &nbsp;
1291 <A HREF="history.html#vr_S" style="text-decoration:none"><b>S</b></A>
1292  &nbsp;
1293 <A HREF="history.html#vr_U" style="text-decoration:none"><b>U</b></A>
1294  &nbsp;
1295 <A HREF="history.html#vr_W" style="text-decoration:none"><b>W</b></A>
1296  &nbsp;
1297 </td></tr></table><br><P></P>
1298 <TABLE border=0>
1299 <TR><TD></TD><TH ALIGN=LEFT>Index Entry</TH><TH ALIGN=LEFT> Section</TH></TR>
1300 <TR><TD COLSPAN=3> <HR></TD></TR>
1301 <TR><TH><A NAME="vr_A"></A>A</TH><TD></TD><TD></TD></TR>
1302 <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>
1303 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX27"><CODE>append_history</CODE></A></TD><TD valign=top><A HREF="history.html#SEC15">2.3.6 Managing the History File</A></TD></TR>
1304 <TR><TD COLSPAN=3> <HR></TD></TR>
1305 <TR><TH><A NAME="vr_C"></A>C</TH><TD></TD><TD></TD></TR>
1306 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX8"><CODE>clear_history</CODE></A></TD><TD valign=top><A HREF="history.html#SEC11">2.3.2 History List Management</A></TD></TR>
1307 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX14"><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>
1308 <TR><TD COLSPAN=3> <HR></TD></TR>
1309 <TR><TH><A NAME="vr_G"></A>G</TH><TD></TD><TD></TD></TR>
1310 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX30"><CODE>get_history_event</CODE></A></TD><TD valign=top><A HREF="history.html#SEC16">2.3.7 History Expansion</A></TD></TR>
1311 <TR><TD COLSPAN=3> <HR></TD></TR>
1312 <TR><TH><A NAME="vr_H"></A>H</TH><TD></TD><TD></TD></TR>
1313 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX32"><CODE>history_arg_extract</CODE></A></TD><TD valign=top><A HREF="history.html#SEC16">2.3.7 History Expansion</A></TD></TR>
1314 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX33"><CODE>history_base</CODE></A></TD><TD valign=top><A HREF="history.html#SEC17">2.4 History Variables</A></TD></TR>
1315 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX38"><CODE>history_comment_char</CODE></A></TD><TD valign=top><A HREF="history.html#SEC17">2.4 History Variables</A></TD></TR>
1316 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX29"><CODE>history_expand</CODE></A></TD><TD valign=top><A HREF="history.html#SEC16">2.3.7 History Expansion</A></TD></TR>
1317 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX36"><CODE>history_expansion_char</CODE></A></TD><TD valign=top><A HREF="history.html#SEC17">2.4 History Variables</A></TD></TR>
1318 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX15"><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>
1319 <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>
1320 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX43"><CODE>history_inhibit_expansion_function</CODE></A></TD><TD valign=top><A HREF="history.html#SEC17">2.4 History Variables</A></TD></TR>
1321 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX11"><CODE>history_is_stifled</CODE></A></TD><TD valign=top><A HREF="history.html#SEC11">2.3.2 History List Management</A></TD></TR>
1322 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX34"><CODE>history_length</CODE></A></TD><TD valign=top><A HREF="history.html#SEC17">2.4 History Variables</A></TD></TR>
1323 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX12"><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>
1324 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX35"><CODE>history_max_entries</CODE></A></TD><TD valign=top><A HREF="history.html#SEC17">2.4 History Variables</A></TD></TR>
1325 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX40"><CODE>history_no_expand_chars</CODE></A></TD><TD valign=top><A HREF="history.html#SEC17">2.4 History Variables</A></TD></TR>
1326 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX42"><CODE>history_quotes_inhibit_expansion</CODE></A></TD><TD valign=top><A HREF="history.html#SEC17">2.4 History Variables</A></TD></TR>
1327 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX21"><CODE>history_search</CODE></A></TD><TD valign=top><A HREF="history.html#SEC14">2.3.5 Searching the History List</A></TD></TR>
1328 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX41"><CODE>history_search_delimiter_chars</CODE></A></TD><TD valign=top><A HREF="history.html#SEC17">2.4 History Variables</A></TD></TR>
1329 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX23"><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>
1330 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX22"><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>
1331 <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>
1332 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX17"><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>
1333 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX37"><CODE>history_subst_char</CODE></A></TD><TD valign=top><A HREF="history.html#SEC17">2.4 History Variables</A></TD></TR>
1334 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX31"><CODE>history_tokenize</CODE></A></TD><TD valign=top><A HREF="history.html#SEC16">2.3.7 History Expansion</A></TD></TR>
1335 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX16"><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>
1336 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX28"><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>
1337 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX39"><CODE>history_word_delimiters</CODE></A></TD><TD valign=top><A HREF="history.html#SEC17">2.4 History Variables</A></TD></TR>
1338 <TR><TD COLSPAN=3> <HR></TD></TR>
1339 <TR><TH><A NAME="vr_N"></A>N</TH><TD></TD><TD></TD></TR>
1340 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX19"><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>
1341 <TR><TD COLSPAN=3> <HR></TD></TR>
1342 <TR><TH><A NAME="vr_P"></A>P</TH><TD></TD><TD></TD></TR>
1343 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX18"><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>
1344 <TR><TD COLSPAN=3> <HR></TD></TR>
1345 <TR><TH><A NAME="vr_R"></A>R</TH><TD></TD><TD></TD></TR>
1346 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX24"><CODE>read_history</CODE></A></TD><TD valign=top><A HREF="history.html#SEC15">2.3.6 Managing the History File</A></TD></TR>
1347 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX25"><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>
1348 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX6"><CODE>remove_history</CODE></A></TD><TD valign=top><A HREF="history.html#SEC11">2.3.2 History List Management</A></TD></TR>
1349 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX7"><CODE>replace_history_entry</CODE></A></TD><TD valign=top><A HREF="history.html#SEC11">2.3.2 History List Management</A></TD></TR>
1350 <TR><TD COLSPAN=3> <HR></TD></TR>
1351 <TR><TH><A NAME="vr_S"></A>S</TH><TD></TD><TD></TD></TR>
1352 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX9"><CODE>stifle_history</CODE></A></TD><TD valign=top><A HREF="history.html#SEC11">2.3.2 History List Management</A></TD></TR>
1353 <TR><TD COLSPAN=3> <HR></TD></TR>
1354 <TR><TH><A NAME="vr_U"></A>U</TH><TD></TD><TD></TD></TR>
1355 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX10"><CODE>unstifle_history</CODE></A></TD><TD valign=top><A HREF="history.html#SEC11">2.3.2 History List Management</A></TD></TR>
1356 <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>
1357 <TR><TD COLSPAN=3> <HR></TD></TR>
1358 <TR><TH><A NAME="vr_W"></A>W</TH><TD></TD><TD></TD></TR>
1359 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX13"><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>
1360 <TR><TD></TD><TD valign=top><A HREF="history.html#IDX26"><CODE>write_history</CODE></A></TD><TD valign=top><A HREF="history.html#SEC15">2.3.6 Managing the History File</A></TD></TR>
1361 <TR><TD COLSPAN=3> <HR></TD></TR>
1362 </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>
1363  &nbsp;
1364 <A HREF="history.html#vr_C" style="text-decoration:none"><b>C</b></A>
1365  &nbsp;
1366 <A HREF="history.html#vr_G" style="text-decoration:none"><b>G</b></A>
1367  &nbsp;
1368 <A HREF="history.html#vr_H" style="text-decoration:none"><b>H</b></A>
1369  &nbsp;
1370 <A HREF="history.html#vr_N" style="text-decoration:none"><b>N</b></A>
1371  &nbsp;
1372 <A HREF="history.html#vr_P" style="text-decoration:none"><b>P</b></A>
1373  &nbsp;
1374 <A HREF="history.html#vr_R" style="text-decoration:none"><b>R</b></A>
1375  &nbsp;
1376 <A HREF="history.html#vr_S" style="text-decoration:none"><b>S</b></A>
1377  &nbsp;
1378 <A HREF="history.html#vr_U" style="text-decoration:none"><b>U</b></A>
1379  &nbsp;
1380 <A HREF="history.html#vr_W" style="text-decoration:none"><b>W</b></A>
1381  &nbsp;
1382 </td></tr></table><br><P>
1383
1384 <HR SIZE="6">
1385 <A NAME="SEC_Contents"></A>
1386 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1387 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
1388 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
1389 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19">Index</A>]</TD>
1390 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
1391 </TR></TABLE>
1392 <H1>Table of Contents</H1>
1393 <UL>
1394 <A NAME="TOC1" HREF="history.html#SEC1">1. Using History Interactively</A>
1395 <BR>
1396 <UL>
1397 <A NAME="TOC2" HREF="history.html#SEC2">1.1 History Expansion</A>
1398 <BR>
1399 <UL>
1400 <A NAME="TOC3" HREF="history.html#SEC3">1.1.1 Event Designators</A>
1401 <BR>
1402 <A NAME="TOC4" HREF="history.html#SEC4">1.1.2 Word Designators</A>
1403 <BR>
1404 <A NAME="TOC5" HREF="history.html#SEC5">1.1.3 Modifiers</A>
1405 <BR>
1406 </UL>
1407 </UL>
1408 <A NAME="TOC6" HREF="history.html#SEC6">2. Programming with GNU History</A>
1409 <BR>
1410 <UL>
1411 <A NAME="TOC7" HREF="history.html#SEC7">2.1 Introduction to History</A>
1412 <BR>
1413 <A NAME="TOC8" HREF="history.html#SEC8">2.2 History Storage</A>
1414 <BR>
1415 <A NAME="TOC9" HREF="history.html#SEC9">2.3 History Functions</A>
1416 <BR>
1417 <UL>
1418 <A NAME="TOC10" HREF="history.html#SEC10">2.3.1 Initializing History and State Management</A>
1419 <BR>
1420 <A NAME="TOC11" HREF="history.html#SEC11">2.3.2 History List Management</A>
1421 <BR>
1422 <A NAME="TOC12" HREF="history.html#SEC12">2.3.3 Information About the History List</A>
1423 <BR>
1424 <A NAME="TOC13" HREF="history.html#SEC13">2.3.4 Moving Around the History List</A>
1425 <BR>
1426 <A NAME="TOC14" HREF="history.html#SEC14">2.3.5 Searching the History List</A>
1427 <BR>
1428 <A NAME="TOC15" HREF="history.html#SEC15">2.3.6 Managing the History File</A>
1429 <BR>
1430 <A NAME="TOC16" HREF="history.html#SEC16">2.3.7 History Expansion</A>
1431 <BR>
1432 </UL>
1433 <A NAME="TOC17" HREF="history.html#SEC17">2.4 History Variables</A>
1434 <BR>
1435 <A NAME="TOC18" HREF="history.html#SEC18">2.5 History Programming Example</A>
1436 <BR>
1437 </UL>
1438 <A NAME="TOC19" HREF="history.html#SEC19">A. Concept Index</A>
1439 <BR>
1440 <A NAME="TOC20" HREF="history.html#SEC20">B. Function and Variable Index</A>
1441 <BR>
1442 </UL>
1443 <HR SIZE=1>
1444 <A NAME="SEC_OVERVIEW"></A>
1445 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1446 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
1447 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
1448 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19">Index</A>]</TD>
1449 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
1450 </TR></TABLE>
1451 <H1>Short Table of Contents</H1>
1452 <BLOCKQUOTE>
1453 <A NAME="TOC1" HREF="history.html#SEC1">1. Using History Interactively</A>
1454 <BR>
1455 <A NAME="TOC6" HREF="history.html#SEC6">2. Programming with GNU History</A>
1456 <BR>
1457 <A NAME="TOC19" HREF="history.html#SEC19">A. Concept Index</A>
1458 <BR>
1459 <A NAME="TOC20" HREF="history.html#SEC20">B. Function and Variable Index</A>
1460 <BR>
1461
1462 </BLOCKQUOTE>
1463 <HR SIZE=1>
1464 <A NAME="SEC_About"></A>
1465 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1466 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
1467 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
1468 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19">Index</A>]</TD>
1469 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
1470 </TR></TABLE>
1471 <H1>About this document</H1>
1472 This document was generated by <I>Chet Ramey</I> on <I>June, 27  2002</I>
1473 using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html
1474 "><I>texi2html</I></A>
1475 <P></P>
1476 The buttons in the navigation panels have the following meaning:
1477 <P></P>
1478 <table border = "1">
1479 <TR>
1480 <TH> Button </TH>
1481 <TH> Name </TH>
1482 <TH> Go to </TH>
1483 <TH> From 1.2.3 go to</TH>
1484 </TR>
1485 <TR>
1486 <TD ALIGN="CENTER">
1487  [ &lt; ] </TD>
1488 <TD ALIGN="CENTER">
1489 Back
1490 </TD>
1491 <TD>
1492 previous section in reading order
1493 </TD>
1494 <TD>
1495 1.2.2
1496 </TD>
1497 </TR>
1498 <TR>
1499 <TD ALIGN="CENTER">
1500  [ &gt; ] </TD>
1501 <TD ALIGN="CENTER">
1502 Forward
1503 </TD>
1504 <TD>
1505 next section in reading order
1506 </TD>
1507 <TD>
1508 1.2.4
1509 </TD>
1510 </TR>
1511 <TR>
1512 <TD ALIGN="CENTER">
1513  [ &lt;&lt; ] </TD>
1514 <TD ALIGN="CENTER">
1515 FastBack
1516 </TD>
1517 <TD>
1518 previous or up-and-previous section
1519 </TD>
1520 <TD>
1521 1.1
1522 </TD>
1523 </TR>
1524 <TR>
1525 <TD ALIGN="CENTER">
1526  [ Up ] </TD>
1527 <TD ALIGN="CENTER">
1528 Up
1529 </TD>
1530 <TD>
1531 up section
1532 </TD>
1533 <TD>
1534 1.2
1535 </TD>
1536 </TR>
1537 <TR>
1538 <TD ALIGN="CENTER">
1539  [ &gt;&gt; ] </TD>
1540 <TD ALIGN="CENTER">
1541 FastForward
1542 </TD>
1543 <TD>
1544 next or up-and-next section
1545 </TD>
1546 <TD>
1547 1.3
1548 </TD>
1549 </TR>
1550 <TR>
1551 <TD ALIGN="CENTER">
1552  [Top] </TD>
1553 <TD ALIGN="CENTER">
1554 Top
1555 </TD>
1556 <TD>
1557 cover (top) of document
1558 </TD>
1559 <TD>
1560  &nbsp;
1561 </TD>
1562 </TR>
1563 <TR>
1564 <TD ALIGN="CENTER">
1565  [Contents] </TD>
1566 <TD ALIGN="CENTER">
1567 Contents
1568 </TD>
1569 <TD>
1570 table of contents
1571 </TD>
1572 <TD>
1573  &nbsp;
1574 </TD>
1575 </TR>
1576 <TR>
1577 <TD ALIGN="CENTER">
1578  [Index] </TD>
1579 <TD ALIGN="CENTER">
1580 Index
1581 </TD>
1582 <TD>
1583 concept index
1584 </TD>
1585 <TD>
1586  &nbsp;
1587 </TD>
1588 </TR>
1589 <TR>
1590 <TD ALIGN="CENTER">
1591  [ ? ] </TD>
1592 <TD ALIGN="CENTER">
1593 About
1594 </TD>
1595 <TD>
1596 this page
1597 </TD>
1598 <TD>
1599  &nbsp;
1600 </TD>
1601 </TR>
1602 </TABLE>
1603 <P></P>
1604 where the <STRONG> Example </STRONG> assumes that the current position
1605 is at <STRONG> Subsubsection One-Two-Three </STRONG> of a document of
1606 the following structure:
1607 <UL>
1608 <LI> 1. Section One  </LI>
1609 <UL>
1610 <LI>1.1 Subsection One-One</LI>
1611 <UL>
1612 <LI> ... </LI>
1613 </UL>
1614 <LI>1.2 Subsection One-Two</LI>
1615 <UL>
1616 <LI>1.2.1 Subsubsection One-Two-One
1617 </LI><LI>1.2.2 Subsubsection One-Two-Two
1618 </LI><LI>1.2.3 Subsubsection One-Two-Three &nbsp; &nbsp; <STRONG>
1619 &lt;== Current Position </STRONG>
1620 </LI><LI>1.2.4 Subsubsection One-Two-Four
1621 </LI></UL>
1622 <LI>1.3 Subsection One-Three</LI>
1623 <UL>
1624 <LI> ... </LI>
1625 </UL>
1626 <LI>1.4 Subsection One-Four</LI>
1627 </UL>
1628 </UL>
1629
1630 <HR SIZE=1>
1631 <BR>
1632 <FONT SIZE="-1">
1633 This document was generated
1634 by <I>Chet Ramey</I> on <I>June, 27  2002</I>
1635 using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html
1636 "><I>texi2html</I></A>
1637
1638 </BODY>
1639 </HTML>