history.html

在非GUI环境下

Returns 0 if successful, or <CODE>errno</CODE> if not.
</DL>
</P><P>

<A NAME="IDX28"></A>
<DL>
<DT><U>Function:</U> int <B>read_history_range</B> <I>(const char *filename, int from, int to)</I>
<DD>Read a range of lines from <VAR>filename</VAR>, adding them to the history list.
Start reading at line <VAR>from</VAR> and end at <VAR>to</VAR>.
If <VAR>from</VAR> is zero, start at the beginning.  If <VAR>to</VAR> is less than
<VAR>from</VAR>, then read until the end of the file.  If <VAR>filename</VAR> is
<CODE>NULL</CODE>, then read from <TT>`~/.history'</TT>.  Returns 0 if successful,
or <CODE>errno</CODE> if not.
</DL>
</P><P>

<A NAME="IDX29"></A>
<DL>
<DT><U>Function:</U> int <B>write_history</B> <I>(const char *filename)</I>
<DD>Write the current history to <VAR>filename</VAR>, overwriting <VAR>filename</VAR>
if necessary.
If <VAR>filename</VAR> is <CODE>NULL</CODE>, then write the history list to
<TT>`~/.history'</TT>.
Returns 0 on success, or <CODE>errno</CODE> on a read or write error.
</DL>
</P><P>

<A NAME="IDX30"></A>
<DL>
<DT><U>Function:</U> int <B>append_history</B> <I>(int nelements, const char *filename)</I>
<DD>Append the last <VAR>nelements</VAR> of the history list to <VAR>filename</VAR>.
If <VAR>filename</VAR> is <CODE>NULL</CODE>, then append to <TT>`~/.history'</TT>.
Returns 0 on success, or <CODE>errno</CODE> on a read or write error.
</DL>
</P><P>

<A NAME="IDX31"></A>
<DL>
<DT><U>Function:</U> int <B>history_truncate_file</B> <I>(const char *filename, int nlines)</I>
<DD>Truncate the history file <VAR>filename</VAR>, leaving only the last
<VAR>nlines</VAR> lines.
If <VAR>filename</VAR> is <CODE>NULL</CODE>, then <TT>`~/.history'</TT> is truncated.
Returns 0 on success, or <CODE>errno</CODE> on failure.
</DL>
</P><P>

<A NAME="History Expansion"></A>
<HR SIZE="6">
<A NAME="SEC16"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC15"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC9"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> &gt;&gt; </A>]</TD>
<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>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC22">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H3> 2.3.7 History Expansion </H3>
<!--docid::SEC16::-->
<P>

These functions implement history expansion.
</P><P>

<A NAME="IDX32"></A>
<DL>
<DT><U>Function:</U> int <B>history_expand</B> <I>(char *string, char **output)</I>
<DD>Expand <VAR>string</VAR>, placing the result into <VAR>output</VAR>, a pointer
to a string (see section <A HREF="history.html#SEC2">1.1 History Expansion</A>).  Returns:
<DL COMPACT>
<DT><CODE>0</CODE>
<DD>If no expansions took place (or, if the only change in
the text was the removal of escape characters preceding the history expansion
character);
<DT><CODE>1</CODE>
<DD>if expansions did take place;
<DT><CODE>-1</CODE>
<DD>if there was an error in expansion;
<DT><CODE>2</CODE>
<DD>if the returned line should be displayed, but not executed,
as with the <CODE>:p</CODE> modifier (see section <A HREF="history.html#SEC5">1.1.3 Modifiers</A>).
</DL>
<P>

If an error ocurred in expansion, then <VAR>output</VAR> contains a descriptive
error message.
</DL>
</P><P>

<A NAME="IDX33"></A>
<DL>
<DT><U>Function:</U> char * <B>get_history_event</B> <I>(const char *string, int *cindex, int qchar)</I>
<DD>Returns the text of the history event beginning at <VAR>string</VAR> +
<VAR>*cindex</VAR>.  <VAR>*cindex</VAR> is modified to point to after the event
specifier.  At function entry, <VAR>cindex</VAR> points to the index into
<VAR>string</VAR> where the history event specification begins.  <VAR>qchar</VAR>
is a character that is allowed to end the event specification in addition
to the "normal" terminating characters.
</DL>
</P><P>

<A NAME="IDX34"></A>
<DL>
<DT><U>Function:</U> char ** <B>history_tokenize</B> <I>(const char *string)</I>
<DD>Return an array of tokens parsed out of <VAR>string</VAR>, much as the
shell might.  The tokens are split on the characters in the
<VAR>history_word_delimiters</VAR> variable,
and shell quoting conventions are obeyed.
</DL>
</P><P>

<A NAME="IDX35"></A>
<DL>
<DT><U>Function:</U> char * <B>history_arg_extract</B> <I>(int first, int last, const char *string)</I>
<DD>Extract a string segment consisting of the <VAR>first</VAR> through <VAR>last</VAR>
arguments present in <VAR>string</VAR>.  Arguments are split using
<CODE>history_tokenize</CODE>.
</DL>
</P><P>

<A NAME="History Variables"></A>
<HR SIZE="6">
<A NAME="SEC17"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC16"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC18"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC18"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC6"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19"> &gt;&gt; </A>]</TD>
<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>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC22">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 2.4 History Variables </H2>
<!--docid::SEC17::-->
<P>

This section describes the externally-visible variables exported by
the GNU History Library.
</P><P>

<A NAME="IDX36"></A>
<DL>
<DT><U>Variable:</U> int <B>history_base</B>
<DD>The logical offset of the first entry in the history list.
</DL>
</P><P>

<A NAME="IDX37"></A>
<DL>
<DT><U>Variable:</U> int <B>history_length</B>
<DD>The number of entries currently stored in the history list.
</DL>
</P><P>

<A NAME="IDX38"></A>
<DL>
<DT><U>Variable:</U> int <B>history_max_entries</B>
<DD>The maximum number of history entries.  This must be changed using
<CODE>stifle_history()</CODE>.
</DL>
</P><P>

<A NAME="IDX39"></A>
<DL>
<DT><U>Variable:</U> int <B>history_write_timestamps</B>
<DD>If non-zero, timestamps are written to the history file, so they can be
preserved between sessions.  The default value is 0, meaning that
timestamps are not saved.
</DL>
</P><P>

<A NAME="IDX40"></A>
<DL>
<DT><U>Variable:</U> char <B>history_expansion_char</B>
<DD>The character that introduces a history event.  The default is <SAMP>`!'</SAMP>.
Setting this to 0 inhibits history expansion.
</DL>
</P><P>

<A NAME="IDX41"></A>
<DL>
<DT><U>Variable:</U> char <B>history_subst_char</B>
<DD>The character that invokes word substitution if found at the start of
a line.  The default is <SAMP>`^'</SAMP>.
</DL>
</P><P>

<A NAME="IDX42"></A>
<DL>
<DT><U>Variable:</U> char <B>history_comment_char</B>
<DD>During tokenization, if this character is seen as the first character
of a word, then it and all subsequent characters up to a newline are
ignored, suppressing history expansion for the remainder of the line.
This is disabled by default.
</DL>
</P><P>

<A NAME="IDX43"></A>
<DL>
<DT><U>Variable:</U> char * <B>history_word_delimiters</B>
<DD>The characters that separate tokens for <CODE>history_tokenize()</CODE>.
The default value is <CODE>" \t\n()<>;&|"</CODE>.
</DL>
</P><P>

<A NAME="IDX44"></A>
<DL>
<DT><U>Variable:</U> char * <B>history_search_delimiter_chars</B>
<DD>The list of additional characters which can delimit a history search
string, in addition to space, TAB, <SAMP>`:'</SAMP> and <SAMP>`?'</SAMP> in the case of
a substring search.  The default is empty.
</DL>
</P><P>

<A NAME="IDX45"></A>
<DL>
<DT><U>Variable:</U> char * <B>history_no_expand_chars</B>
<DD>The list of characters which inhibit history expansion if found immediately
following <VAR>history_expansion_char</VAR>.  The default is space, tab, newline,
carriage return, and <SAMP>`='</SAMP>.
</DL>
</P><P>

<A NAME="IDX46"></A>
<DL>
<DT><U>Variable:</U> int <B>history_quotes_inhibit_expansion</B>
<DD>If non-zero, single-quoted words are not scanned for the history expansion
character.  The default value is 0.
</DL>
</P><P>

<A NAME="IDX47"></A>
<DL>
<DT><U>Variable:</U> rl_linebuf_func_t * <B>history_inhibit_expansion_function</B>
<DD>This should be set to the address of a function that takes two arguments:
a <CODE>char *</CODE> (<VAR>string</VAR>)
and an <CODE>int</CODE> index into that string (<VAR>i</VAR>).
It should return a non-zero value if the history expansion starting at
<VAR>string[i]</VAR> should not be performed; zero if the expansion should
be done.
It is intended for use by applications like Bash that use the history
expansion character for additional purposes.
By default, this variable is set to <CODE>NULL</CODE>.
</DL>
</P><P>

<A NAME="History Programming Example"></A>
<HR SIZE="6">
<A NAME="SEC18"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC6"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19"> &gt;&gt; </A>]</TD>
<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>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC22">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 2.5 History Programming Example </H2>
<!--docid::SEC18::-->
<P>

The following program demonstrates simple use of the GNU History Library.
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=-1><pre>#include &#60;stdio.h&#62;
#include &#60;readline/history.h&#62;

main (argc, argv)
     int argc;
     char **argv;
{
  char line[1024], *t;
  int len, done = 0;

  line[0] = 0;

  using_history ();
  while (!done)
    {
      printf ("history$ ");
      fflush (stdout);
      t = fgets (line, sizeof (line) - 1, stdin);
      if (t &#38;&#38; *t)
        {
          len = strlen (t);
          if (t[len - 1] == '\n')
            t[len - 1] = '\0';
        }

      if (!t)
        strcpy (line, "quit");