1049 lines
26 KiB
HTML
1049 lines
26 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of HISTORY</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>HISTORY</H1>
|
|
Section: C Library Functions (3)<BR>Updated: 2017 October 8<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
history - GNU History Library
|
|
<A NAME="lbAC"> </A>
|
|
<H2>COPYRIGHT</H2>
|
|
|
|
|
|
The GNU History Library is Copyright (C) 1989-2017 by the Free Software Foundation, Inc.
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
Many programs read input from the user a line at a time. The GNU
|
|
History library is able to keep track of those lines, associate arbitrary
|
|
data with each line, and utilize information from previous lines in
|
|
composing new ones.
|
|
<P>
|
|
|
|
<A NAME="lbAE"> </A>
|
|
<H2>HISTORY EXPANSION</H2>
|
|
|
|
<P>
|
|
|
|
The history library supports a history expansion feature that
|
|
is identical to the history expansion in
|
|
<B>bash.</B>
|
|
|
|
This section describes what syntax features are available.
|
|
<P>
|
|
|
|
History expansions introduce words from the history list into
|
|
the input stream, making it easy to repeat commands, insert the
|
|
arguments to a previous command into the current input line, or
|
|
fix errors in previous commands quickly.
|
|
<P>
|
|
|
|
History expansion is usually performed immediately after a complete line
|
|
is read.
|
|
It takes place in two parts.
|
|
The first is to determine which line from the history list
|
|
to use during substitution.
|
|
The second is to select portions of that line for inclusion into
|
|
the current one.
|
|
The line selected from the history is the <I>event</I>,
|
|
and the portions of that line that are acted upon are <I>words</I>.
|
|
Various <I>modifiers</I> are available to manipulate the selected words.
|
|
The line is broken into words in the same fashion as <B>bash</B>
|
|
does when reading input,
|
|
so that several words that would otherwise be separated
|
|
are considered one word when surrounded by quotes (see the
|
|
description of <B>history_tokenize()</B> below).
|
|
History expansions are introduced by the appearance of the
|
|
history expansion character, which is <B>!</B> by default.
|
|
Only backslash (<B>\</B>) and single quotes can quote
|
|
the history expansion character.
|
|
<A NAME="lbAF"> </A>
|
|
<H3>Event Designators</H3>
|
|
|
|
<P>
|
|
|
|
An event designator is a reference to a command line entry in the
|
|
history list.
|
|
Unless the reference is absolute, events are relative to the current
|
|
position in the history list.
|
|
<P>
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="1"><B>!</B>
|
|
|
|
<DD>
|
|
Start a history substitution, except when followed by a
|
|
<B>blank</B>,
|
|
|
|
newline, = or (.
|
|
<DT id="2"><B>!</B><I>n</I>
|
|
|
|
<DD>
|
|
Refer to command line
|
|
<I>n</I>.
|
|
|
|
<DT id="3"><B>!-</B><I>n</I>
|
|
|
|
<DD>
|
|
Refer to the current command minus
|
|
<I>n</I>.
|
|
|
|
<DT id="4"><B>!!</B>
|
|
|
|
<DD>
|
|
Refer to the previous command. This is a synonym for `!-1'.
|
|
<DT id="5"><B>!</B><I>string</I>
|
|
|
|
<DD>
|
|
Refer to the most recent command
|
|
preceding the current position in the history list
|
|
starting with
|
|
<I>string</I>.
|
|
|
|
<DT id="6"><B>!?</B><I>string</I><B>[?]</B>
|
|
|
|
<DD>
|
|
Refer to the most recent command
|
|
preceding the current position in the history list
|
|
containing
|
|
<I>string</I>.
|
|
|
|
The trailing <B>?</B> may be omitted if
|
|
<I>string</I>
|
|
|
|
is followed immediately by a newline.
|
|
<DT id="7"><B></B><FONT SIZE="+2"><B>^</B></FONT><B></B><I>string1</I><FONT SIZE="+2">^</FONT><I>string2</I><FONT SIZE="+2">^</FONT>
|
|
|
|
<DD>
|
|
Quick substitution. Repeat the last command, replacing
|
|
<I>string1</I>
|
|
|
|
with
|
|
<I>string2</I>.
|
|
|
|
Equivalent to
|
|
``!!:s/<I>string1</I>/<I>string2</I>/''
|
|
(see <B>Modifiers</B> below).
|
|
<DT id="8"><B>!#</B>
|
|
|
|
<DD>
|
|
The entire command line typed so far.
|
|
|
|
</DL>
|
|
<A NAME="lbAG"> </A>
|
|
<H3>Word Designators</H3>
|
|
|
|
<P>
|
|
|
|
Word designators are used to select desired words from the event.
|
|
A
|
|
<B>:</B>
|
|
|
|
separates the event specification from the word designator.
|
|
It may be omitted if the word designator begins with a
|
|
<B>^</B>,
|
|
|
|
<B>$</B>,
|
|
|
|
<B>*</B>,
|
|
|
|
<B>-</B>,
|
|
|
|
or
|
|
<B>%</B>.
|
|
|
|
Words are numbered from the beginning of the line,
|
|
with the first word being denoted by 0 (zero).
|
|
Words are inserted into the current line separated by single spaces.
|
|
<P>
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="9"><B>0 (zero)</B>
|
|
|
|
<DD>
|
|
The zeroth word. For the shell, this is the command
|
|
word.
|
|
<DT id="10"><I>n</I>
|
|
|
|
<DD>
|
|
The <I>n</I>th word.
|
|
<DT id="11"><B>^</B>
|
|
|
|
<DD>
|
|
The first argument. That is, word 1.
|
|
<DT id="12"><B>$</B>
|
|
|
|
<DD>
|
|
The last word. This is usually the last argument, but will expand to the
|
|
zeroth word if there is only one word in the line.
|
|
<DT id="13"><B>%</B>
|
|
|
|
<DD>
|
|
The word matched by the most recent `?<I>string</I>?' search.
|
|
<DT id="14"><I>x</I><B>-</B>y
|
|
|
|
<DD>
|
|
A range of words; `-<I>y</I>' abbreviates `0-<I>y</I>'.
|
|
<DT id="15"><B>*</B>
|
|
|
|
<DD>
|
|
All of the words but the zeroth. This is a synonym
|
|
for `<I>1-$</I>'. It is not an error to use
|
|
<B>*</B>
|
|
|
|
if there is just one
|
|
word in the event; the empty string is returned in that case.
|
|
<DT id="16"><B>x*</B>
|
|
|
|
<DD>
|
|
Abbreviates <I>x-$</I>.
|
|
<DT id="17"><B>x-</B>
|
|
|
|
<DD>
|
|
Abbreviates <I>x-$</I> like <B>x*</B>, but omits the last word.
|
|
|
|
</DL>
|
|
<P>
|
|
|
|
If a word designator is supplied without an event specification, the
|
|
previous command is used as the event.
|
|
<A NAME="lbAH"> </A>
|
|
<H3>Modifiers</H3>
|
|
|
|
<P>
|
|
|
|
After the optional word designator, there may appear a sequence of
|
|
one or more of the following modifiers, each preceded by a `:'.
|
|
<P>
|
|
|
|
|
|
<P>
|
|
|
|
<DL COMPACT>
|
|
<DT id="18"><B>h</B>
|
|
|
|
<DD>
|
|
Remove a trailing file name component, leaving only the head.
|
|
<DT id="19"><B>t</B>
|
|
|
|
<DD>
|
|
Remove all leading file name components, leaving the tail.
|
|
<DT id="20"><B>r</B>
|
|
|
|
<DD>
|
|
Remove a trailing suffix of the form <I>.xxx</I>, leaving the
|
|
basename.
|
|
<DT id="21"><B>e</B>
|
|
|
|
<DD>
|
|
Remove all but the trailing suffix.
|
|
<DT id="22"><B>p</B>
|
|
|
|
<DD>
|
|
Print the new command but do not execute it.
|
|
<DT id="23"><B>q</B>
|
|
|
|
<DD>
|
|
Quote the substituted words, escaping further substitutions.
|
|
<DT id="24"><B>x</B>
|
|
|
|
<DD>
|
|
Quote the substituted words as with
|
|
<B>q</B>,
|
|
|
|
but break into words at
|
|
<B>blanks</B>
|
|
|
|
and newlines.
|
|
<DT id="25"><B>s/</B><I>old</I>/<I>new</I>/
|
|
|
|
<DD>
|
|
Substitute
|
|
<I>new</I>
|
|
|
|
for the first occurrence of
|
|
<I>old</I>
|
|
|
|
in the event line. Any delimiter can be used in place of /. The
|
|
final delimiter is optional if it is the last character of the
|
|
event line. The delimiter may be quoted in
|
|
<I>old</I>
|
|
|
|
and
|
|
<I>new</I>
|
|
|
|
with a single backslash. If & appears in
|
|
<I>new</I>,
|
|
|
|
it is replaced by
|
|
<I>old</I>.
|
|
|
|
A single backslash will quote the &. If
|
|
<I>old</I>
|
|
|
|
is null, it is set to the last
|
|
<I>old</I>
|
|
|
|
substituted, or, if no previous history substitutions took place,
|
|
the last
|
|
<I>string</I>
|
|
|
|
in a
|
|
<B>!?</B><I>string</I><B>[?]</B>
|
|
|
|
search.
|
|
<DT id="26"><B>&</B>
|
|
|
|
<DD>
|
|
Repeat the previous substitution.
|
|
<DT id="27"><B>g</B>
|
|
|
|
<DD>
|
|
Cause changes to be applied over the entire event line. This is
|
|
used in conjunction with `<B>:s</B>' (e.g., `<B>:gs/</B><I>old</I>/<I>new</I>/')
|
|
or `<B>:&</B>'. If used with
|
|
`<B>:s</B>', any delimiter can be used
|
|
in place of /, and the final delimiter is optional
|
|
if it is the last character of the event line.
|
|
An <B>a</B> may be used as a synonym for <B>g</B>.
|
|
<DT id="28"><B>G</B>
|
|
|
|
<DD>
|
|
Apply the following `<B>s</B>' modifier once to each word in the event line.
|
|
|
|
</DL>
|
|
<A NAME="lbAI"> </A>
|
|
<H2>PROGRAMMING WITH HISTORY FUNCTIONS</H2>
|
|
|
|
This section describes how to use the History library in other programs.
|
|
<A NAME="lbAJ"> </A>
|
|
<H3>Introduction to History</H3>
|
|
|
|
<P>
|
|
|
|
The programmer using the History library has available functions
|
|
for remembering lines on a history list, associating arbitrary data
|
|
with a line, removing lines from the list, searching through the list
|
|
for a line containing an arbitrary text string, and referencing any line
|
|
in the list directly. In addition, a history <I>expansion</I> function
|
|
is available which provides for a consistent user interface across
|
|
different programs.
|
|
<P>
|
|
|
|
The user using programs written with the History library has the
|
|
benefit of a consistent user interface with a set of well-known
|
|
commands for manipulating the text of previous lines and using that text
|
|
in new commands. The basic history manipulation commands are
|
|
identical to
|
|
the history substitution provided by <B>bash</B>.
|
|
<P>
|
|
|
|
If the programmer desires, he can use the Readline library, which
|
|
includes some history manipulation by default, and has the added
|
|
advantage of command line editing.
|
|
<P>
|
|
|
|
Before declaring any functions using any functionality the History
|
|
library provides in other code, an application writer should include
|
|
the file
|
|
|
|
<I><<A HREF="file:///usr/include/readline/history.h">readline/history.h</A>></I>
|
|
|
|
in any file that uses the
|
|
History library's features. It supplies extern declarations for all
|
|
of the library's public functions and variables, and declares all of
|
|
the public data structures.
|
|
<P>
|
|
<A NAME="lbAK"> </A>
|
|
<H3>History Storage</H3>
|
|
|
|
<P>
|
|
|
|
The history list is an array of history entries. A history entry is
|
|
declared as follows:
|
|
<P>
|
|
|
|
|
|
<I>typedef void *</I> <B>histdata_t;</B>
|
|
<BR>
|
|
|
|
|
|
<P>
|
|
|
|
<PRE>
|
|
typedef struct _hist_entry {
|
|
char *line;
|
|
char *timestamp;
|
|
histdata_t data;
|
|
} HIST_ENTRY;
|
|
</PRE>
|
|
|
|
<P>
|
|
|
|
The history list itself might therefore be declared as
|
|
<P>
|
|
|
|
|
|
<I>HIST_ENTRY **</I> <B>the_history_list;</B>
|
|
<BR>
|
|
|
|
|
|
<P>
|
|
|
|
The state of the History library is encapsulated into a single structure:
|
|
<P>
|
|
|
|
<PRE>
|
|
/*
|
|
* A structure used to pass around the current state of the history.
|
|
*/
|
|
typedef struct _hist_state {
|
|
HIST_ENTRY **entries; /* Pointer to the entries themselves. */
|
|
int offset; /* The location pointer within this array. */
|
|
int length; /* Number of elements within this array. */
|
|
int size; /* Number of slots allocated to this array. */
|
|
int flags;
|
|
} HISTORY_STATE;
|
|
</PRE>
|
|
|
|
<P>
|
|
|
|
If the flags member includes <B>HS_STIFLED</B>, the history has been
|
|
stifled.
|
|
<A NAME="lbAL"> </A>
|
|
<H2>History Functions</H2>
|
|
|
|
<P>
|
|
|
|
This section describes the calling sequence for the various functions
|
|
exported by the GNU History library.
|
|
<A NAME="lbAM"> </A>
|
|
<H3>Initializing History and State Management</H3>
|
|
|
|
This section describes functions used to initialize and manage
|
|
the state of the History library when you want to use the history
|
|
functions in your program.
|
|
<P>
|
|
|
|
<I>void</I> <B>using_history</B> (<I>void</I>)
|
|
<BR>
|
|
|
|
|
|
Begin a session in which the history functions might be used. This
|
|
initializes the interactive variables.
|
|
<P>
|
|
|
|
<I>HISTORY_STATE *</I> <B>history_get_history_state</B> (<I>void</I>)
|
|
<BR>
|
|
|
|
|
|
Return a structure describing the current state of the input history.
|
|
<P>
|
|
|
|
<I>void</I> <B>history_set_history_state</B> (<I>HISTORY_STATE *state</I>)
|
|
<BR>
|
|
|
|
|
|
Set the state of the history list according to <I>state</I>.
|
|
<P>
|
|
<A NAME="lbAN"> </A>
|
|
<H3>History List Management</H3>
|
|
|
|
<P>
|
|
These functions manage individual entries on the history list, or set
|
|
parameters managing the list itself.
|
|
<P>
|
|
|
|
<I>void</I> <B>add_history</B> (<I>const char *string</I>)
|
|
<BR>
|
|
|
|
|
|
Place <I>string</I> at the end of the history list. The associated data
|
|
field (if any) is set to <B>NULL</B>.
|
|
If the maximum number of history entries has been set using
|
|
<B>stifle_history()</B>, and the new number of history entries would exceed
|
|
that maximum, the oldest history entry is removed.
|
|
<P>
|
|
|
|
<I>void</I> <B>add_history_time</B> (<I>const char *string</I>)
|
|
<BR>
|
|
|
|
|
|
Change the time stamp associated with the most recent history entry to
|
|
<I>string</I>.
|
|
<P>
|
|
|
|
<I>HIST_ENTRY *</I> <B>remove_history</B> (<I>int which</I>)
|
|
<BR>
|
|
|
|
|
|
Remove history entry at offset <I>which</I> from the history. The
|
|
removed element is returned so you can free the line, data,
|
|
and containing structure.
|
|
<P>
|
|
|
|
<I>histdata_t</I> <B>free_history_entry</B> (<I>HIST_ENTRY *histent</I>)
|
|
<BR>
|
|
|
|
|
|
Free the history entry <I>histent</I> and any history library private
|
|
data associated with it. Returns the application-specific data
|
|
so the caller can dispose of it.
|
|
<P>
|
|
|
|
|
|
<I>HIST_ENTRY *</I> <B>replace_history_entry</B> (<I>int which, const char *line, histdata_t data</I>)
|
|
<BR>
|
|
|
|
|
|
Make the history entry at offset <I>which</I> have <I>line</I> and <I>data</I>.
|
|
This returns the old entry so the caller can dispose of any
|
|
application-specific data. In the case
|
|
of an invalid <I>which</I>, a <B>NULL</B> pointer is returned.
|
|
<P>
|
|
|
|
<I>void</I> <B>clear_history</B> (<I>void</I>)
|
|
<BR>
|
|
|
|
|
|
Clear the history list by deleting all the entries.
|
|
<P>
|
|
|
|
<I>void</I> <B>stifle_history</B> (<I>int max</I>)
|
|
<BR>
|
|
|
|
|
|
Stifle the history list, remembering only the last <I>max</I> entries.
|
|
The history list will contain only <I>max</I> entries at a time.
|
|
<P>
|
|
|
|
<I>int</I> <B>unstifle_history</B> (<I>void</I>)
|
|
<BR>
|
|
|
|
|
|
Stop stifling the history. This returns the previously-set
|
|
maximum number of history entries (as set by <B>stifle_history()</B>).
|
|
history was stifled. The value is positive if the history was
|
|
stifled, negative if it wasn't.
|
|
<P>
|
|
|
|
<I>int</I> <B>history_is_stifled</B> (<I>void</I>)
|
|
<BR>
|
|
|
|
|
|
Returns non-zero if the history is stifled, zero if it is not.
|
|
<P>
|
|
<A NAME="lbAO"> </A>
|
|
<H3>Information About the History List</H3>
|
|
|
|
<P>
|
|
These functions return information about the entire history list or
|
|
individual list entries.
|
|
<P>
|
|
|
|
<I>HIST_ENTRY **</I> <B>history_list</B> (<I>void</I>)
|
|
<BR>
|
|
|
|
|
|
Return a <B>NULL</B> terminated array of <I>HIST_ENTRY *</I> which is the
|
|
current input history. Element 0 of this list is the beginning of time.
|
|
If there is no history, return <B>NULL</B>.
|
|
<P>
|
|
|
|
<I>int</I> <B>where_history</B> (<I>void</I>)
|
|
<BR>
|
|
|
|
|
|
Returns the offset of the current history element.
|
|
<P>
|
|
|
|
<I>HIST_ENTRY *</I> <B>current_history</B> (<I>void</I>)
|
|
<BR>
|
|
|
|
|
|
Return the history entry at the current position, as determined by
|
|
<B>where_history()</B>. If there is no entry there, return a <B>NULL</B>
|
|
pointer.
|
|
<P>
|
|
|
|
<I>HIST_ENTRY *</I> <B>history_get</B> (<I>int offset</I>)
|
|
<BR>
|
|
|
|
|
|
Return the history entry at position <I>offset</I>.
|
|
The range of valid values of <I>offset</I> starts at <B>history_base</B>
|
|
and ends at <B>history_length</B> - 1.
|
|
If there is no entry there, or if <I>offset</I> is outside the valid
|
|
range, return a <B>NULL</B> pointer.
|
|
<P>
|
|
|
|
<I>time_t</I> <B>history_get_time</B> (<I>HIST_ENTRY *</I>)
|
|
<BR>
|
|
|
|
|
|
Return the time stamp associated with the history entry passed as the argument.
|
|
<P>
|
|
|
|
<I>int</I> <B>history_total_bytes</B> (<I>void</I>)
|
|
<BR>
|
|
|
|
|
|
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.
|
|
<P>
|
|
<A NAME="lbAP"> </A>
|
|
<H3>Moving Around the History List</H3>
|
|
|
|
<P>
|
|
These functions allow the current index into the history list to be
|
|
set or changed.
|
|
<P>
|
|
|
|
<I>int</I> <B>history_set_pos</B> (<I>int pos</I>)
|
|
<BR>
|
|
|
|
|
|
Set the current history offset to <I>pos</I>, an absolute index
|
|
into the list.
|
|
Returns 1 on success, 0 if <I>pos</I> is less than zero or greater
|
|
than the number of history entries.
|
|
<P>
|
|
|
|
<I>HIST_ENTRY *</I> <B>previous_history</B> (<I>void</I>)
|
|
<BR>
|
|
|
|
|
|
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 <B>NULL</B> pointer.
|
|
<P>
|
|
|
|
<I>HIST_ENTRY *</I> <B>next_history</B> (<I>void</I>)
|
|
<BR>
|
|
|
|
|
|
If the current history offset refers to a valid history entry,
|
|
increment the current history offset.
|
|
If the possibly-incremented history offset refers to a valid history
|
|
entry, return a pointer to that entry;
|
|
otherwise, return a <B>NULL</B> pointer.
|
|
<P>
|
|
<A NAME="lbAQ"> </A>
|
|
<H3>Searching the History List</H3>
|
|
|
|
<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 <I>anchored</I>,
|
|
meaning that the string must match at the beginning of the history entry.
|
|
<P>
|
|
|
|
|
|
<I>int</I> <B>history_search</B> (<I>const char *string, int direction</I>)
|
|
<BR>
|
|
|
|
|
|
Search the history for <I>string</I>, starting at the current history offset.
|
|
If <I>direction</I> is less than 0, then the search is through
|
|
previous entries, otherwise through subsequent entries.
|
|
If <I>string</I> 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
|
|
<I>string</I> was found. Otherwise, nothing is changed, and a -1 is
|
|
returned.
|
|
<P>
|
|
|
|
|
|
<I>int</I> <B>history_search_prefix</B> (<I>const char *string, int direction</I>)
|
|
<BR>
|
|
|
|
|
|
Search the history for <I>string</I>, starting at the current history
|
|
offset. The search is anchored: matching lines must begin with
|
|
<I>string</I>. If <I>direction</I> is less than 0, then the search is
|
|
through previous entries, otherwise through subsequent entries.
|
|
If <I>string</I> 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.
|
|
<P>
|
|
|
|
|
|
<I>int</I> <B>history_search_pos</B> (<I>const char *string, int direction, int pos</I>)
|
|
<BR>
|
|
|
|
|
|
Search for <I>string</I> in the history list, starting at <I>pos</I>, an
|
|
absolute index into the list. If <I>direction</I> is negative, the search
|
|
proceeds backward from <I>pos</I>, otherwise forward. Returns the absolute
|
|
index of the history element where <I>string</I> was found, or -1 otherwise.
|
|
<P>
|
|
<A NAME="lbAR"> </A>
|
|
<H3>Managing the History File</H3>
|
|
|
|
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>
|
|
|
|
<I>int</I> <B>read_history</B> (<I>const char *filename</I>)
|
|
<BR>
|
|
|
|
|
|
Add the contents of <I>filename</I> to the history list, a line at a time.
|
|
If <I>filename</I> is <B>NULL</B>, then read from <I>~/.history</I>.
|
|
Returns 0 if successful, or <B>errno</B> if not.
|
|
<P>
|
|
|
|
|
|
<I>int</I> <B>read_history_range</B> (<I>const char *filename, int from, int to</I>)
|
|
<BR>
|
|
|
|
|
|
Read a range of lines from <I>filename</I>, adding them to the history list.
|
|
Start reading at line <I>from</I> and end at <I>to</I>.
|
|
If <I>from</I> is zero, start at the beginning. If <I>to</I> is less than
|
|
<I>from</I>, then read until the end of the file. If <I>filename</I> is
|
|
<B>NULL</B>, then read from <I>~/.history</I>. Returns 0 if successful,
|
|
or <B>errno</B> if not.
|
|
<P>
|
|
|
|
<I>int</I> <B>write_history</B> (<I>const char *filename</I>)
|
|
<BR>
|
|
|
|
|
|
Write the current history to <I>filename</I>, overwriting <I>filename</I>
|
|
if necessary.
|
|
If <I>filename</I> is <B>NULL</B>, then write the history list to <I>~/.history</I>.
|
|
Returns 0 on success, or <B>errno</B> on a read or write error.
|
|
<P>
|
|
<P>
|
|
|
|
|
|
<I>int</I> <B>append_history</B> (<I>int nelements, const char *filename</I>)
|
|
<BR>
|
|
|
|
|
|
Append the last <I>nelements</I> of the history list to <I>filename</I>.
|
|
If <I>filename</I> is <B>NULL</B>, then append to <I>~/.history</I>.
|
|
Returns 0 on success, or <B>errno</B> on a read or write error.
|
|
<P>
|
|
|
|
|
|
<I>int</I> <B>history_truncate_file</B> (<I>const char *filename, int nlines</I>)
|
|
<BR>
|
|
|
|
|
|
Truncate the history file <I>filename</I>, leaving only the last
|
|
<I>nlines</I> lines.
|
|
If <I>filename</I> is <B>NULL</B>, then <I>~/.history</I> is truncated.
|
|
Returns 0 on success, or <B>errno</B> on failure.
|
|
<P>
|
|
<A NAME="lbAS"> </A>
|
|
<H3>History Expansion</H3>
|
|
|
|
<P>
|
|
These functions implement history expansion.
|
|
<P>
|
|
|
|
|
|
<I>int</I> <B>history_expand</B> (<I>char *string, char **output</I>)
|
|
<BR>
|
|
|
|
|
|
Expand <I>string</I>, placing the result into <I>output</I>, a pointer
|
|
to a string. Returns:
|
|
<DL COMPACT><DT id="29"><DD>
|
|
|
|
<DL COMPACT>
|
|
<DT id="30">0<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 id="31">1<DD>
|
|
if expansions did take place;
|
|
<DT id="32">-1<DD>
|
|
if there was an error in expansion;
|
|
<DT id="33">2<DD>
|
|
if the returned line should be displayed, but not executed,
|
|
as with the <B>:p</B> modifier.
|
|
|
|
</DL>
|
|
</DL>
|
|
|
|
If an error ocurred in expansion, then <I>output</I> contains a descriptive
|
|
error message.
|
|
<P>
|
|
|
|
|
|
<I>char *</I> <B>get_history_event</B> (<I>const char *string, int *cindex, int qchar</I>)
|
|
<BR>
|
|
|
|
|
|
Returns the text of the history event beginning at <I>string</I> +
|
|
<I>*cindex</I>. <I>*cindex</I> is modified to point to after the event
|
|
specifier. At function entry, <I>cindex</I> points to the index into
|
|
<I>string</I> where the history event specification begins. <I>qchar</I>
|
|
is a character that is allowed to end the event specification in addition
|
|
to the ``normal'' terminating characters.
|
|
<P>
|
|
|
|
<I>char **</I> <B>history_tokenize</B> (<I>const char *string</I>)
|
|
<BR>
|
|
|
|
|
|
Return an array of tokens parsed out of <I>string</I>, much as the
|
|
shell might.
|
|
The tokens are split on the characters in the
|
|
<B>history_word_delimiters</B> variable,
|
|
and shell quoting conventions are obeyed.
|
|
<P>
|
|
|
|
|
|
<I>char *</I> <B>history_arg_extract</B> (<I>int first, int last, const char *string</I>)
|
|
<BR>
|
|
|
|
|
|
Extract a string segment consisting of the <I>first</I> through <I>last</I>
|
|
arguments present in <I>string</I>. Arguments are split using
|
|
<B>history_tokenize()</B>.
|
|
<P>
|
|
<A NAME="lbAT"> </A>
|
|
<H3>History Variables</H3>
|
|
|
|
<P>
|
|
This section describes the externally-visible variables exported by
|
|
the GNU History Library.
|
|
<P>
|
|
|
|
<I>int</I> <B>history_base</B>
|
|
<BR>
|
|
|
|
|
|
The logical offset of the first entry in the history list.
|
|
<P>
|
|
|
|
<I>int</I> <B>history_length</B>
|
|
<BR>
|
|
|
|
|
|
The number of entries currently stored in the history list.
|
|
<P>
|
|
|
|
<I>int</I> <B>history_max_entries</B>
|
|
<BR>
|
|
|
|
|
|
The maximum number of history entries. This must be changed using
|
|
<B>stifle_history()</B>.
|
|
<P>
|
|
|
|
<I>int</I> <B>history_wite_timestamps</B>
|
|
<BR>
|
|
|
|
|
|
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.
|
|
The current timestamp format uses the value of <I>history_comment_char</I>
|
|
to delimit timestamp entries in the history file. If that variable does
|
|
not have a value (the default), timestamps will not be written.
|
|
<P>
|
|
|
|
<I>char</I> <B>history_expansion_char</B>
|
|
<BR>
|
|
|
|
|
|
The character that introduces a history event. The default is <B>!</B>.
|
|
Setting this to 0 inhibits history expansion.
|
|
<P>
|
|
|
|
<I>char</I> <B>history_subst_char</B>
|
|
<BR>
|
|
|
|
|
|
The character that invokes word substitution if found at the start of
|
|
a line. The default is <B>^</B>.
|
|
<P>
|
|
|
|
<I>char</I> <B>history_comment_char</B>
|
|
<BR>
|
|
|
|
|
|
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.
|
|
<P>
|
|
|
|
<I>char *</I> <B>history_word_delimiters</B>
|
|
<BR>
|
|
|
|
|
|
The characters that separate tokens for <B>history_tokenize()</B>.
|
|
The default value is <B>" \t\n()<>;&|"</B>.
|
|
<P>
|
|
|
|
<I>char *</I> <B>history_no_expand_chars</B>
|
|
<BR>
|
|
|
|
|
|
The list of characters which inhibit history expansion if found immediately
|
|
following <B>history_expansion_char</B>. The default is space, tab, newline,
|
|
<B>\r</B>, and <B>=</B>.
|
|
<P>
|
|
|
|
<I>char *</I> <B>history_search_delimiter_chars</B>
|
|
<BR>
|
|
|
|
|
|
The list of additional characters which can delimit a history search
|
|
string, in addition to space, tab, <I>:</I> and <I>?</I> in the case of
|
|
a substring search. The default is empty.
|
|
<P>
|
|
|
|
<I>int</I> <B>history_quotes_inhibit_expansion</B>
|
|
<BR>
|
|
|
|
|
|
If non-zero, double-quoted words are not scanned for the history expansion
|
|
character or the history comment character. The default value is 0.
|
|
<P>
|
|
|
|
<I>rl_linebuf_func_t *</I> <B>history_inhibit_expansion_function</B>
|
|
<BR>
|
|
|
|
|
|
This should be set to the address of a function that takes two arguments:
|
|
a <B>char *</B> (<I>string</I>)
|
|
and an <B>int</B> index into that string (<I>i</I>).
|
|
It should return a non-zero value if the history expansion starting at
|
|
<I>string[i]</I> should not be performed; zero if the expansion should
|
|
be done.
|
|
It is intended for use by applications like <B>bash</B> that use the history
|
|
expansion character for additional purposes.
|
|
By default, this variable is set to <B>NULL</B>.
|
|
<A NAME="lbAU"> </A>
|
|
<H2>FILES</H2>
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="34">
|
|
<I>~/.history</I>
|
|
|
|
<DD>
|
|
Default filename for reading and writing saved history
|
|
|
|
</DL>
|
|
<A NAME="lbAV"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="35"><I>The Gnu Readline Library</I>, Brian Fox and Chet Ramey<DD>
|
|
<DT id="36"><I>The Gnu History Library</I>, Brian Fox and Chet Ramey<DD>
|
|
<DT id="37"><I><A HREF="/cgi-bin/man/man2html?1+bash">bash</A></I>(1)<DD>
|
|
<DT id="38"><I><A HREF="/cgi-bin/man/man2html?3+readline">readline</A></I>(3)<DD>
|
|
|
|
</DL>
|
|
<A NAME="lbAW"> </A>
|
|
<H2>AUTHORS</H2>
|
|
|
|
Brian Fox, Free Software Foundation
|
|
<BR>
|
|
|
|
<A HREF="mailto:bfox@gnu.org">bfox@gnu.org</A>
|
|
<P>
|
|
|
|
Chet Ramey, Case Western Reserve University
|
|
<BR>
|
|
|
|
<A HREF="mailto:chet.ramey@case.edu">chet.ramey@case.edu</A>
|
|
<A NAME="lbAX"> </A>
|
|
<H2>BUG REPORTS</H2>
|
|
|
|
If you find a bug in the
|
|
<B>history</B>
|
|
|
|
library, you should report it. But first, you should
|
|
make sure that it really is a bug, and that it appears in the latest
|
|
version of the
|
|
<B>history</B>
|
|
|
|
library that you have.
|
|
<P>
|
|
|
|
Once you have determined that a bug actually exists, mail a
|
|
bug report to <I>bug-readline</I>@<I>gnu.org</I>.
|
|
If you have a fix, you are welcome to mail that
|
|
as well! Suggestions and `philosophical' bug reports may be mailed
|
|
to bug-readline@<I>gnu.org</I> or posted to the Usenet
|
|
newsgroup
|
|
<B>gnu.bash.bug</B>.
|
|
|
|
<P>
|
|
|
|
Comments and bug reports concerning
|
|
this manual page should be directed to
|
|
<I><A HREF="mailto:chet.ramey@case.edu">chet.ramey@case.edu</A></I>.
|
|
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="39"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="40"><A HREF="#lbAC">COPYRIGHT</A><DD>
|
|
<DT id="41"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="42"><A HREF="#lbAE">HISTORY EXPANSION</A><DD>
|
|
<DL>
|
|
<DT id="43"><A HREF="#lbAF">Event Designators</A><DD>
|
|
<DT id="44"><A HREF="#lbAG">Word Designators</A><DD>
|
|
<DT id="45"><A HREF="#lbAH">Modifiers</A><DD>
|
|
</DL>
|
|
<DT id="46"><A HREF="#lbAI">PROGRAMMING WITH HISTORY FUNCTIONS</A><DD>
|
|
<DL>
|
|
<DT id="47"><A HREF="#lbAJ">Introduction to History</A><DD>
|
|
<DT id="48"><A HREF="#lbAK">History Storage</A><DD>
|
|
</DL>
|
|
<DT id="49"><A HREF="#lbAL">History Functions</A><DD>
|
|
<DL>
|
|
<DT id="50"><A HREF="#lbAM">Initializing History and State Management</A><DD>
|
|
<DT id="51"><A HREF="#lbAN">History List Management</A><DD>
|
|
<DT id="52"><A HREF="#lbAO">Information About the History List</A><DD>
|
|
<DT id="53"><A HREF="#lbAP">Moving Around the History List</A><DD>
|
|
<DT id="54"><A HREF="#lbAQ">Searching the History List</A><DD>
|
|
<DT id="55"><A HREF="#lbAR">Managing the History File</A><DD>
|
|
<DT id="56"><A HREF="#lbAS">History Expansion</A><DD>
|
|
<DT id="57"><A HREF="#lbAT">History Variables</A><DD>
|
|
</DL>
|
|
<DT id="58"><A HREF="#lbAU">FILES</A><DD>
|
|
<DT id="59"><A HREF="#lbAV">SEE ALSO</A><DD>
|
|
<DT id="60"><A HREF="#lbAW">AUTHORS</A><DD>
|
|
<DT id="61"><A HREF="#lbAX">BUG REPORTS</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:45 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|