|
version 1.1.1.1, 2014/07/30 08:16:45
|
version 1.1.1.2, 2021/03/17 01:01:01
|
|
Line 6
|
Line 6
|
| .\" Case Western Reserve University |
.\" Case Western Reserve University |
| .\" chet.ramey@case.edu |
.\" chet.ramey@case.edu |
| .\" |
.\" |
| .\" Last Change: Thu Thu Jun 27 10:34:44 EDT 2013 | .\" Last Change: Fri Jul 17 09:43:01 EDT 2020 |
| .\" |
.\" |
| .TH HISTORY 3 "2013 June 27" "GNU History 6.3" | .TH HISTORY 3 "2020 July 17" "GNU History 8.1" |
| .\" |
.\" |
| .\" File Name macro. This used to be `.PN', for Path Name, |
.\" File Name macro. This used to be `.PN', for Path Name, |
| .\" but Sun doesn't seem to like that very much. |
.\" but Sun doesn't seem to like that very much. |
|
Line 40
|
Line 40
|
| .SH NAME |
.SH NAME |
| history \- GNU History Library |
history \- GNU History Library |
| .SH COPYRIGHT |
.SH COPYRIGHT |
| .if t The GNU History Library is Copyright \(co 1989-2011 by the Free Software Foundation, Inc. | .if t The GNU History Library is Copyright \(co 1989-2020 by the Free Software Foundation, Inc. |
| .if n The GNU History Library is Copyright (C) 1989-2011 by the Free Software Foundation, Inc. | .if n The GNU History Library is Copyright (C) 1989-2020 by the Free Software Foundation, Inc. |
| .SH DESCRIPTION |
.SH DESCRIPTION |
| Many programs read input from the user a line at a time. The GNU |
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 |
History library is able to keep track of those lines, associate arbitrary |
|
Line 49 data with each line, and utilize information from prev
|
Line 49 data with each line, and utilize information from prev
|
| composing new ones. |
composing new ones. |
| .PP |
.PP |
| .SH "HISTORY EXPANSION" |
.SH "HISTORY EXPANSION" |
| .PP |
|
| The history library supports a history expansion feature that |
The history library supports a history expansion feature that |
| is identical to the history expansion in |
is identical to the history expansion in |
| .BR bash. |
.BR bash. |
|
Line 80 history expansion character, which is \^\fB!\fP\^ by d
|
Line 79 history expansion character, which is \^\fB!\fP\^ by d
|
| Only backslash (\^\fB\e\fP\^) and single quotes can quote |
Only backslash (\^\fB\e\fP\^) and single quotes can quote |
| the history expansion character. |
the history expansion character. |
| .SS Event Designators |
.SS Event Designators |
| .PP |
|
| An event designator is a reference to a command line entry in the |
An event designator is a reference to a command line entry in the |
| history list. |
history list. |
| Unless the reference is absolute, events are relative to the current |
Unless the reference is absolute, events are relative to the current |
|
Line 118 containing
|
Line 116 containing
|
| The trailing \fB?\fP may be omitted if |
The trailing \fB?\fP may be omitted if |
| .I string |
.I string |
| is followed immediately by a newline. |
is followed immediately by a newline. |
| |
If \fIstring\fP is missing, the string from the most recent search is used; |
| |
it is an error if there is no previous search string. |
| .TP |
.TP |
| .B \d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u |
.B \d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u |
| Quick substitution. Repeat the last command, replacing |
Quick substitution. Repeat the last command, replacing |
|
Line 125 Quick substitution. Repeat the last command, replacin
|
Line 125 Quick substitution. Repeat the last command, replacin
|
| with |
with |
| .IR string2 . |
.IR string2 . |
| Equivalent to |
Equivalent to |
| ``!!:s/\fIstring1\fP/\fIstring2\fP/'' | ``!!:s\d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u'' |
| (see \fBModifiers\fP below). |
(see \fBModifiers\fP below). |
| .TP |
.TP |
| .B !# |
.B !# |
| The entire command line typed so far. |
The entire command line typed so far. |
| .PD |
.PD |
| .SS Word Designators |
.SS Word Designators |
| .PP |
|
| Word designators are used to select desired words from the event. |
Word designators are used to select desired words from the event. |
| A | A |
| .B : |
.B : |
| separates the event specification from the word designator. |
separates the event specification from the word designator. |
| It may be omitted if the word designator begins with a |
It may be omitted if the word designator begins with a |
|
Line 165 The last word. This is usually the last argument, but
|
Line 164 The last word. This is usually the last argument, but
|
| zeroth word if there is only one word in the line. |
zeroth word if there is only one word in the line. |
| .TP |
.TP |
| .B % |
.B % |
| The word matched by the most recent `?\fIstring\fR?' search. | The first word matched by the most recent `?\fIstring\fR?' search, |
| | if the search string begins with a character that is part of a word. |
| .TP |
.TP |
| .I x\fB\-\fPy |
.I x\fB\-\fPy |
| A range of words; `\-\fIy\fR' abbreviates `0\-\fIy\fR'. |
A range of words; `\-\fIy\fR' abbreviates `0\-\fIy\fR'. |
|
Line 182 Abbreviates \fIx\-$\fP.
|
Line 182 Abbreviates \fIx\-$\fP.
|
| .TP |
.TP |
| .B x\- |
.B x\- |
| Abbreviates \fIx\-$\fP like \fBx*\fP, but omits the last word. |
Abbreviates \fIx\-$\fP like \fBx*\fP, but omits the last word. |
| |
If \fBx\fP is missing, it defaults to 0. |
| .PD |
.PD |
| .PP |
.PP |
| If a word designator is supplied without an event specification, the |
If a word designator is supplied without an event specification, the |
| previous command is used as the event. |
previous command is used as the event. |
| .SS Modifiers |
.SS Modifiers |
| .PP |
|
| After the optional word designator, there may appear a sequence of |
After the optional word designator, there may appear a sequence of |
| one or more of the following modifiers, each preceded by a `:'. |
one or more of the following modifiers, each preceded by a `:'. |
| |
These modify, or edit, the word or words selected from the history event. |
| .PP |
.PP |
| .PD 0 |
.PD 0 |
| .PP |
.PP |
|
Line 219 Quote the substituted words as with
|
Line 220 Quote the substituted words as with
|
| but break into words at |
but break into words at |
| .B blanks |
.B blanks |
| and newlines. |
and newlines. |
| |
The \fBq\fP and \fBx\fP modifiers are mutually exclusive; the last one |
| |
supplied is used. |
| .TP |
.TP |
| .B s/\fIold\fP/\fInew\fP/ |
.B s/\fIold\fP/\fInew\fP/ |
| Substitute |
Substitute |
| .I new |
.I new |
| for the first occurrence of |
for the first occurrence of |
| .I old |
.I old |
| in the event line. Any delimiter can be used in place of /. The | in the event line. |
| final delimiter is optional if it is the last character of the | Any character may be used as the delimiter in place of /. |
| event line. The delimiter may be quoted in | The final delimiter is optional if it is the last character of the |
| | event line. |
| | The delimiter may be quoted in |
| .I old |
.I old |
| and |
and |
| .I new |
.I new |
|
Line 235 with a single backslash. If & appears in
|
Line 240 with a single backslash. If & appears in
|
| .IR new , |
.IR new , |
| it is replaced by |
it is replaced by |
| .IR old . |
.IR old . |
| A single backslash will quote the &. If | A single backslash will quote the &. |
| | If |
| .I old |
.I old |
| is null, it is set to the last |
is null, it is set to the last |
| .I old |
.I old |
|
Line 245 the last
|
Line 251 the last
|
| in a |
in a |
| .B !?\fIstring\fR\fB[?]\fR |
.B !?\fIstring\fR\fB[?]\fR |
| search. |
search. |
| |
If |
| |
.I new |
| |
is null, each matching |
| |
.I old |
| |
is deleted. |
| .TP |
.TP |
| .B & |
.B & |
| Repeat the previous substitution. |
Repeat the previous substitution. |
|
Line 259 if it is the last character of the event line.
|
Line 270 if it is the last character of the event line.
|
| An \fBa\fP may be used as a synonym for \fBg\fP. |
An \fBa\fP may be used as a synonym for \fBg\fP. |
| .TP |
.TP |
| .B G |
.B G |
| Apply the following `\fBs\fP' modifier once to each word in the event line. | Apply the following `\fBs\fP' or `\fB&\fP' modifier once to each word |
| | in the event line. |
| .PD |
.PD |
| .SH "PROGRAMMING WITH HISTORY FUNCTIONS" |
.SH "PROGRAMMING WITH HISTORY FUNCTIONS" |
| This section describes how to use the History library in other programs. |
This section describes how to use the History library in other programs. |
| .SS Introduction to History |
.SS Introduction to History |
| .PP | A programmer using the History library has available functions |
| The programmer using the History library has available functions | |
| for remembering lines on a history list, associating arbitrary data |
for remembering lines on a history list, associating arbitrary data |
| with a line, removing lines from the list, searching through the list |
with a line, removing lines from the list, searching through the list |
| for a line containing an arbitrary text string, and referencing any line |
for a line containing an arbitrary text string, and referencing any line |
|
Line 280 in new commands. The basic history manipulation comma
|
Line 291 in new commands. The basic history manipulation comma
|
| identical to |
identical to |
| the history substitution provided by \fBbash\fP. |
the history substitution provided by \fBbash\fP. |
| .PP |
.PP |
| If the programmer desires, he can use the Readline library, which | The programmer can also use the Readline library, which |
| includes some history manipulation by default, and has the added |
includes some history manipulation by default, and has the added |
| advantage of command line editing. |
advantage of command line editing. |
| .PP |
.PP |
|
Line 292 in any file that uses the
|
Line 303 in any file that uses the
|
| History library's features. It supplies extern declarations for all |
History library's features. It supplies extern declarations for all |
| of the library's public functions and variables, and declares all of |
of the library's public functions and variables, and declares all of |
| the public data structures. |
the public data structures. |
| |
|
| .SS History Storage |
.SS History Storage |
| .PP |
|
| The history list is an array of history entries. A history entry is |
The history list is an array of history entries. A history entry is |
| declared as follows: |
declared as follows: |
| .PP |
.PP |
|
Line 330 typedef struct _hist_state {
|
Line 339 typedef struct _hist_state {
|
| If the flags member includes \fBHS_STIFLED\fP, the history has been |
If the flags member includes \fBHS_STIFLED\fP, the history has been |
| stifled. |
stifled. |
| .SH "History Functions" |
.SH "History Functions" |
| .PP |
|
| This section describes the calling sequence for the various functions |
This section describes the calling sequence for the various functions |
| exported by the GNU History library. |
exported by the GNU History library. |
| .SS Initializing History and State Management |
.SS Initializing History and State Management |
|
Line 349 Return a structure describing the current state of the
|
Line 357 Return a structure describing the current state of the
|
| Set the state of the history list according to \fIstate\fP. |
Set the state of the history list according to \fIstate\fP. |
| |
|
| .SS History List Management |
.SS History List Management |
| |
|
| These functions manage individual entries on the history list, or set |
These functions manage individual entries on the history list, or set |
| parameters managing the list itself. |
parameters managing the list itself. |
| |
|
| .Fn1 void add_history "const char *string" |
.Fn1 void add_history "const char *string" |
| Place \fIstring\fP at the end of the history list. The associated data |
Place \fIstring\fP at the end of the history list. The associated data |
| field (if any) is set to \fBNULL\fP. |
field (if any) is set to \fBNULL\fP. |
| |
If the maximum number of history entries has been set using |
| |
\fBstifle_history()\fP, and the new number of history entries would exceed |
| |
that maximum, the oldest history entry is removed. |
| |
|
| .Fn1 void add_history_time "const char *string" |
.Fn1 void add_history_time "const char *string" |
| Change the time stamp associated with the most recent history entry to |
Change the time stamp associated with the most recent history entry to |
|
Line 382 Clear the history list by deleting all the entries.
|
Line 392 Clear the history list by deleting all the entries.
|
| |
|
| .Fn1 void stifle_history "int max" |
.Fn1 void stifle_history "int max" |
| Stifle the history list, remembering only the last \fImax\fP entries. |
Stifle the history list, remembering only the last \fImax\fP entries. |
| |
The history list will contain only \fImax\fP entries at a time. |
| |
|
| .Fn1 int unstifle_history "void" |
.Fn1 int unstifle_history "void" |
| Stop stifling the history. This returns the previously-set |
Stop stifling the history. This returns the previously-set |
|
Line 411 Return the history entry at the current position, as d
|
Line 422 Return the history entry at the current position, as d
|
| pointer. |
pointer. |
| |
|
| .Fn1 "HIST_ENTRY *" history_get "int offset" |
.Fn1 "HIST_ENTRY *" history_get "int offset" |
| Return the history entry at position \fIoffset\fP, starting from | Return the history entry at position \fIoffset\fP. |
| \fBhistory_base\fP. | The range of valid values of \fIoffset\fP starts at \fBhistory_base\fP |
| If there is no entry there, or if \fIoffset\fP | and ends at \fBhistory_length\fP \- 1. |
| is greater than the history length, return a \fBNULL\fP pointer. | If there is no entry there, or if \fIoffset\fP is outside the valid |
| | range, return a \fBNULL\fP pointer. |
| |
|
| .Fn1 "time_t" history_get_time "HIST_ENTRY *" |
.Fn1 "time_t" history_get_time "HIST_ENTRY *" |
| Return the time stamp associated with the history entry passed as the argument. |
Return the time stamp associated with the history entry passed as the argument. |
|
Line 441 return a pointer to that entry. If there is no previo
|
Line 453 return a pointer to that entry. If there is no previo
|
| a \fBNULL\fP pointer. |
a \fBNULL\fP pointer. |
| |
|
| .Fn1 "HIST_ENTRY *" next_history "void" |
.Fn1 "HIST_ENTRY *" next_history "void" |
| Move the current history offset forward to the next history entry, and | If the current history offset refers to a valid history entry, |
| return the a pointer to that entry. If there is no next entry, return | increment the current history offset. |
| a \fBNULL\fP pointer. | If the possibly-incremented history offset refers to a valid history |
| | entry, return a pointer to that entry; |
| | otherwise, return a \fBNULL\fP pointer. |
| |
|
| .SS Searching the History List |
.SS Searching the History List |
| |
|
|
Line 538 if the returned line should be displayed, but not exec
|
Line 552 if the returned line should be displayed, but not exec
|
| as with the \fB:p\fP modifier. |
as with the \fB:p\fP modifier. |
| .PD |
.PD |
| .RE |
.RE |
| If an error ocurred in expansion, then \fIoutput\fP contains a descriptive | If an error occurred in expansion, then \fIoutput\fP contains a descriptive |
| error message. |
error message. |
| |
|
| .Fn3 "char *" get_history_event "const char *string" "int *cindex" "int qchar" |
.Fn3 "char *" get_history_event "const char *string" "int *cindex" "int qchar" |
|
Line 576 The number of entries currently stored in the history
|
Line 590 The number of entries currently stored in the history
|
| The maximum number of history entries. This must be changed using |
The maximum number of history entries. This must be changed using |
| \fBstifle_history()\fP. |
\fBstifle_history()\fP. |
| |
|
| .Vb int history_wite_timestamps | .Vb int history_write_timestamps |
| If non-zero, timestamps are written to the history file, so they can be |
If non-zero, timestamps are written to the history file, so they can be |
| preserved between sessions. The default value is 0, meaning that |
preserved between sessions. The default value is 0, meaning that |
| timestamps are not saved. |
timestamps are not saved. |
|
Line 613 string, in addition to space, tab, \fI:\fP and \fI?\fP
|
Line 627 string, in addition to space, tab, \fI:\fP and \fI?\fP
|
| a substring search. The default is empty. |
a substring search. The default is empty. |
| |
|
| .Vb int history_quotes_inhibit_expansion |
.Vb int history_quotes_inhibit_expansion |
| If non-zero, single-quoted words are not scanned for the history expansion | If non-zero, double-quoted words are not scanned for the history expansion |
| character. The default value is 0. | character or the history comment character. The default value is 0. |
| |
|
| .Vb "rl_linebuf_func_t *" history_inhibit_expansion_function |
.Vb "rl_linebuf_func_t *" history_inhibit_expansion_function |
| This should be set to the address of a function that takes two arguments: |
This should be set to the address of a function that takes two arguments: |
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to history.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / readline / doc