history.html

在非GUI环境下

<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.2 History List Management </H3>
<!--docid::SEC11::-->
<P>

These functions manage individual entries on the history list, or set
parameters managing the list itself.
</P><P>

<A NAME="IDX5"></A>
<DL>
<DT><U>Function:</U> void <B>add_history</B> <I>(const char *string)</I>
<DD>Place <VAR>string</VAR> at the end of the history list.  The associated data
field (if any) is set to <CODE>NULL</CODE>.
</DL>
</P><P>

<A NAME="IDX6"></A>
<DL>
<DT><U>Function:</U> void <B>add_history_time</B> <I>(const char *string)</I>
<DD>Change the time stamp associated with the most recent history entry to
<VAR>string</VAR>.
</DL>
</P><P>

<A NAME="IDX7"></A>
<DL>
<DT><U>Function:</U> HIST_ENTRY * <B>remove_history</B> <I>(int which)</I>
<DD>Remove history entry at offset <VAR>which</VAR> from the history.  The
removed element is returned so you can free the line, data,
and containing structure.
</DL>
</P><P>

<A NAME="IDX8"></A>
<DL>
<DT><U>Function:</U> histdata_t <B>free_history_entry</B> <I>(HIST_ENTRY *histent)</I>
<DD>Free the history entry <VAR>histent</VAR> and any history library private
data associated with it.  Returns the application-specific data
so the caller can dispose of it.
</DL>
</P><P>

<A NAME="IDX9"></A>
<DL>
<DT><U>Function:</U> HIST_ENTRY * <B>replace_history_entry</B> <I>(int which, const char *line, histdata_t data)</I>
<DD>Make the history entry at offset <VAR>which</VAR> have <VAR>line</VAR> and <VAR>data</VAR>.
This returns the old entry so the caller can dispose of any
application-specific data.  In the case
of an invalid <VAR>which</VAR>, a <CODE>NULL</CODE> pointer is returned.
</DL>
</P><P>

<A NAME="IDX10"></A>
<DL>
<DT><U>Function:</U> void <B>clear_history</B> <I>(void)</I>
<DD>Clear the history list by deleting all the entries.
</DL>
</P><P>

<A NAME="IDX11"></A>
<DL>
<DT><U>Function:</U> void <B>stifle_history</B> <I>(int max)</I>
<DD>Stifle the history list, remembering only the last <VAR>max</VAR> entries.
</DL>
</P><P>

<A NAME="IDX12"></A>
<DL>
<DT><U>Function:</U> int <B>unstifle_history</B> <I>(void)</I>
<DD>Stop stifling the history.  This returns the previously-set
maximum number of history entries (as set by <CODE>stifle_history()</CODE>).
The value is positive if the history was
stifled, negative if it wasn't.
</DL>
</P><P>

<A NAME="IDX13"></A>
<DL>
<DT><U>Function:</U> int <B>history_is_stifled</B> <I>(void)</I>
<DD>Returns non-zero if the history is stifled, zero if it is not.
</DL>
</P><P>

<A NAME="Information About the History List"></A>
<HR SIZE="6">
<A NAME="SEC12"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC11"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC13"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC13"> &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.3 Information About the History List </H3>
<!--docid::SEC12::-->
<P>

These functions return information about the entire history list or
individual list entries.
</P><P>

<A NAME="IDX14"></A>
<DL>
<DT><U>Function:</U> HIST_ENTRY ** <B>history_list</B> <I>(void)</I>
<DD>Return a <CODE>NULL</CODE> terminated array of <CODE>HIST_ENTRY *</CODE> which is the
current input history.  Element 0 of this list is the beginning of time.
If there is no history, return <CODE>NULL</CODE>.
</DL>
</P><P>

<A NAME="IDX15"></A>
<DL>
<DT><U>Function:</U> int <B>where_history</B> <I>(void)</I>
<DD>Returns the offset of the current history element.
</DL>
</P><P>

<A NAME="IDX16"></A>
<DL>
<DT><U>Function:</U> HIST_ENTRY * <B>current_history</B> <I>(void)</I>
<DD>Return the history entry at the current position, as determined by
<CODE>where_history()</CODE>.  If there is no entry there, return a <CODE>NULL</CODE>
pointer.
</DL>
</P><P>

<A NAME="IDX17"></A>
<DL>
<DT><U>Function:</U> HIST_ENTRY * <B>history_get</B> <I>(int offset)</I>
<DD>Return the history entry at position <VAR>offset</VAR>, starting from
<CODE>history_base</CODE> (see section <A HREF="history.html#SEC17">2.4 History Variables</A>).
If there is no entry there, or if <VAR>offset</VAR>
is greater than the history length, return a <CODE>NULL</CODE> pointer.
</DL>
</P><P>

<A NAME="IDX18"></A>
<DL>
<DT><U>Function:</U> time_t <B>history_get_time</B> <I>(HIST_ENTRY *entry)</I>
<DD>Return the time stamp associated with the history entry <VAR>entry</VAR>.
</DL>
</P><P>

<A NAME="IDX19"></A>
<DL>
<DT><U>Function:</U> int <B>history_total_bytes</B> <I>(void)</I>
<DD>Return the number of bytes that the primary history entries are using.
This function returns the sum of the lengths of all the lines in the
history.
</DL>
</P><P>

<A NAME="Moving Around the History List"></A>
<HR SIZE="6">
<A NAME="SEC13"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC12"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC14"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC14"> &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.4 Moving Around the History List </H3>
<!--docid::SEC13::-->
<P>

These functions allow the current index into the history list to be
set or changed.
</P><P>

<A NAME="IDX20"></A>
<DL>
<DT><U>Function:</U> int <B>history_set_pos</B> <I>(int pos)</I>
<DD>Set the current history offset to <VAR>pos</VAR>, an absolute index
into the list.
Returns 1 on success, 0 if <VAR>pos</VAR> is less than zero or greater
than the number of history entries.
</DL>
</P><P>

<A NAME="IDX21"></A>
<DL>
<DT><U>Function:</U> HIST_ENTRY * <B>previous_history</B> <I>(void)</I>
<DD>Back up the current history offset to the previous history entry, and
return a pointer to that entry.  If there is no previous entry, return
a <CODE>NULL</CODE> pointer.
</DL>
</P><P>

<A NAME="IDX22"></A>
<DL>
<DT><U>Function:</U> HIST_ENTRY * <B>next_history</B> <I>(void)</I>
<DD>Move the current history offset forward to the next history entry, and
return the a pointer to that entry.  If there is no next entry, return
a <CODE>NULL</CODE> pointer.
</DL>
</P><P>

<A NAME="Searching the History List"></A>
<HR SIZE="6">
<A NAME="SEC14"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC13"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC15"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC15"> &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.5 Searching the History List </H3>
<!--docid::SEC14::-->
<P>

These functions allow searching of the history list for entries containing
a specific string.  Searching may be performed both forward and backward
from the current history position.  The search may be <EM>anchored</EM>,
meaning that the string must match at the beginning of the history entry.
<A NAME="IDX23"></A>
</P><P>

<A NAME="IDX24"></A>
<DL>
<DT><U>Function:</U> int <B>history_search</B> <I>(const char *string, int direction)</I>
<DD>Search the history for <VAR>string</VAR>, starting at the current history offset.
If <VAR>direction</VAR> is less than 0, then the search is through
previous entries, otherwise through subsequent entries.
If <VAR>string</VAR> is found, then
the current history index is set to that history entry, and the value
returned is the offset in the line of the entry where
<VAR>string</VAR> was found.  Otherwise, nothing is changed, and a -1 is
returned.
</DL>
</P><P>

<A NAME="IDX25"></A>
<DL>
<DT><U>Function:</U> int <B>history_search_prefix</B> <I>(const char *string, int direction)</I>
<DD>Search the history for <VAR>string</VAR>, starting at the current history
offset.  The search is anchored: matching lines must begin with
<VAR>string</VAR>.  If <VAR>direction</VAR> is less than 0, then the search is
through previous entries, otherwise through subsequent entries.
If <VAR>string</VAR> is found, then the
current history index is set to that entry, and the return value is 0. 
Otherwise, nothing is changed, and a -1 is returned. 
</DL>
</P><P>

<A NAME="IDX26"></A>
<DL>
<DT><U>Function:</U> int <B>history_search_pos</B> <I>(const char *string, int direction, int pos)</I>
<DD>Search for <VAR>string</VAR> in the history list, starting at <VAR>pos</VAR>, an
absolute index into the list.  If <VAR>direction</VAR> is negative, the search
proceeds backward from <VAR>pos</VAR>, otherwise forward.  Returns the absolute
index of the history element where <VAR>string</VAR> was found, or -1 otherwise.
</DL>
</P><P>

<A NAME="Managing the History File"></A>
<HR SIZE="6">
<A NAME="SEC15"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC14"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC16"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC16"> &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.6 Managing the History File </H3>
<!--docid::SEC15::-->
<P>

The History library can read the history from and write it to a file.
This section documents the functions for managing a history file.
</P><P>

<A NAME="IDX27"></A>
<DL>
<DT><U>Function:</U> int <B>read_history</B> <I>(const char *filename)</I>
<DD>Add the contents of <VAR>filename</VAR> to the history list, a line at a time.
If <VAR>filename</VAR> is <CODE>NULL</CODE>, then read from <TT>`~/.history'</TT>.