summaryrefslogtreecommitdiff
path: root/doc/history.0
diff options
context:
space:
mode:
Diffstat (limited to 'doc/history.0')
-rw-r--r--doc/history.0196
1 files changed, 101 insertions, 95 deletions
diff --git a/doc/history.0 b/doc/history.0
index 9133300..3c1a794 100644
--- a/doc/history.0
+++ b/doc/history.0
@@ -6,7 +6,7 @@ HISTORY(3) Library Functions Manual HISTORY(3)
history - GNU History Library
COPYRIGHT
- The GNU History Library is Copyright (C) 1989-2017 by the Free Software
+ The GNU History Library is Copyright (C) 1989-2020 by the Free Software
Foundation, Inc.
DESCRIPTION
@@ -55,10 +55,12 @@ HISTORY(3) Library Functions Manual HISTORY(3)
!?string[?]
Refer to the most recent command preceding the current position
in the history list containing string. The trailing ? may be
- omitted if string is followed immediately by a newline.
+ omitted if string is followed immediately by a newline. If
+ string is missing, the string from the most recent search is
+ used; it is an error if there is no previous search string.
^string1^string2^
Quick substitution. Repeat the last command, replacing string1
- with string2. Equivalent to ``!!:s/string1/string2/'' (see Mod-
+ with string2. Equivalent to ``!!:s^string1^string2^'' (see Mod-
ifiers below).
!# The entire command line typed so far.
@@ -74,22 +76,26 @@ HISTORY(3) Library Functions Manual HISTORY(3)
The zeroth word. For the shell, this is the command word.
n The nth word.
^ The first argument. That is, word 1.
- $ 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.
- % The word matched by the most recent `?string?' search.
+ $ The last word. This is usually the last argument, but will ex-
+ pand to the zeroth word if there is only one word in the line.
+ % The first word matched by the most recent `?string?' search, if
+ the search string begins with a character that is part of a
+ word.
x-y A range of words; `-y' abbreviates `0-y'.
* All of the words but the zeroth. This is a synonym for `1-$'.
It is not an error to use * if there is just one word in the
event; the empty string is returned in that case.
x* Abbreviates x-$.
- x- Abbreviates x-$ like x*, but omits the last word.
+ x- Abbreviates x-$ like x*, but omits the last word. If x is miss-
+ ing, it defaults to 0.
- 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.
Modifiers
- After the optional word designator, there may appear a sequence of one
- or more of the following modifiers, each preceded by a `:'.
+ After the optional word designator, there may appear a sequence of one
+ or more of the following modifiers, each preceded by a `:'. These mod-
+ ify, or edit, the word or words selected from the history event.
h Remove a trailing file name component, leaving only the head.
t Remove all leading file name components, leaving the tail.
@@ -98,32 +104,34 @@ HISTORY(3) Library Functions Manual HISTORY(3)
p Print the new command but do not execute it.
q Quote the substituted words, escaping further substitutions.
x Quote the substituted words as with q, but break into words at
- blanks and newlines.
+ blanks and newlines. The q and x modifiers are mutually exclu-
+ sive; the last one supplied is used.
s/old/new/
- Substitute new for the first occurrence of old 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 old and new with a single
- backslash. If & appears in new, it is replaced by old. A sin-
- gle backslash will quote the &. If old is null, it is set to
- the last old substituted, or, if no previous history substitu-
- tions took place, the last string in a !?string[?] search.
+ Substitute new for the first occurrence of old in the event
+ line. Any character may be used as the delimiter in place of /.
+ The final delimiter is optional if it is the last character of
+ the event line. The delimiter may be quoted in old and new with
+ a single backslash. If & appears in new, it is replaced by old.
+ A single backslash will quote the &. If old is null, it is set
+ to the last old substituted, or, if no previous history substi-
+ tutions took place, the last string in a !?string[?] search.
+ If new is null, each matching old is deleted.
& Repeat the previous substitution.
g Cause changes to be applied over the entire event line. This is
used in conjunction with `:s' (e.g., `:gs/old/new/') or `:&'.
If used with `:s', 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 a may be used as a synonym for g.
- G Apply the following `s' modifier once to each word in the event
- line.
+ G Apply the following `s' or `&' modifier once to each word in the
+ event line.
PROGRAMMING WITH HISTORY FUNCTIONS
This section describes how to use the History library in other pro-
grams.
Introduction to History
- The programmer using the History library has available functions for
- remembering lines on a history list, associating arbitrary data with a
+ A programmer using the History library has available functions for re-
+ membering 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 expansion function is avail-
@@ -136,17 +144,16 @@ HISTORY(3) Library Functions Manual HISTORY(3)
commands. The basic history manipulation commands are identical to the
history substitution provided by bash.
- If the programmer desires, he can use the Readline library, which
- includes some history manipulation by default, and has the added advan-
- tage of command line editing.
-
- Before declaring any functions using any functionality the History
- library provides in other code, an application writer should include
- the file <readline/history.h> 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 pub-
- lic data structures.
+ The programmer can also use the Readline library, which includes some
+ history manipulation by default, and has the added advantage of command
+ line editing.
+ Before declaring any functions using any functionality the History li-
+ brary provides in other code, an application writer should include the
+ file <readline/history.h> 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.
History Storage
The history list is an array of history entries. A history entry is
@@ -215,21 +222,21 @@ HISTORY(3) Library Functions Manual HISTORY(3)
string.
HIST_ENTRY * remove_history (int which)
- Remove history entry at offset which from the history. The removed
- element is returned so you can free the line, data, and containing
- structure.
+ Remove history entry at offset which from the history. The removed el-
+ ement is returned so you can free the line, data, and containing struc-
+ ture.
histdata_t free_history_entry (HIST_ENTRY *histent)
- Free the history entry histent and any history library private data
- associated with it. Returns the application-specific data so the call-
- er can dispose of it.
+ Free the history entry histent and any history library private data as-
+ sociated with it. Returns the application-specific data so the caller
+ can dispose of it.
HIST_ENTRY * replace_history_entry (int which, const char *line, hist-
data_t data)
- Make the history entry at offset which have line and data. This
- returns the old entry so the caller can dispose of any application-spe-
- cific data. In the case of an invalid which, a NULL pointer is
- returned.
+ Make the history entry at offset which have line and data. This re-
+ turns the old entry so the caller can dispose of any application-spe-
+ cific data. In the case of an invalid which, a NULL pointer is re-
+ turned.
void clear_history (void)
Clear the history list by deleting all the entries.
@@ -249,12 +256,12 @@ HISTORY(3) Library Functions Manual HISTORY(3)
Information About the History List
- These functions return information about the entire history list or
- individual list entries.
+ These functions return information about the entire history list or in-
+ dividual list entries.
HIST_ENTRY ** history_list (void)
- Return a NULL terminated array of HIST_ENTRY * which is the current
- input history. Element 0 of this list is the beginning of time. If
+ Return a NULL terminated array of HIST_ENTRY * which is the current in-
+ put history. Element 0 of this list is the beginning of time. If
there is no history, return NULL.
int where_history (void)
@@ -267,8 +274,8 @@ HISTORY(3) Library Functions Manual HISTORY(3)
HIST_ENTRY * history_get (int offset)
Return the history entry at position offset. The range of valid values
of offset starts at history_base and ends at history_length - 1. If
- there is no entry there, or if offset is outside the valid range,
- return a NULL pointer.
+ there is no entry there, or if offset is outside the valid range, re-
+ turn a NULL pointer.
time_t history_get_time (HIST_ENTRY *)
Return the time stamp associated with the history entry passed as the
@@ -304,31 +311,31 @@ HISTORY(3) Library Functions Manual HISTORY(3)
Searching the History List
These functions allow searching of the history list for entries con-
taining a specific string. Searching may be performed both forward and
- backward from the current history position. The search may be
- anchored, meaning that the string must match at the beginning of the
- history entry.
+ backward from the current history position. The search may be an-
+ chored, meaning that the string must match at the beginning of the his-
+ tory entry.
int history_search (const char *string, int direction)
Search the history for string, starting at the current history offset.
- If direction is less than 0, then the search is through previous
- entries, otherwise through subsequent entries. If string 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 string was
- found. Otherwise, nothing is changed, and a -1 is returned.
+ If direction is less than 0, then the search is through previous en-
+ tries, otherwise through subsequent entries. If string 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 string was found.
+ Otherwise, nothing is changed, and a -1 is returned.
int history_search_prefix (const char *string, int direction)
Search the history for string, starting at the current history offset.
- The search is anchored: matching lines must begin with string. If
- direction is less than 0, then the search is through previous entries,
+ The search is anchored: matching lines must begin with string. If di-
+ rection is less than 0, then the search is through previous entries,
otherwise through subsequent entries. If string 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.
int history_search_pos (const char *string, int direction, int pos)
- Search for string in the history list, starting at pos, an absolute
- index into the list. If direction is negative, the search proceeds
- backward from pos, otherwise forward. Returns the absolute index of
- the history element where string was found, or -1 otherwise.
+ Search for string in the history list, starting at pos, an absolute in-
+ dex into the list. If direction is negative, the search proceeds back-
+ ward from pos, otherwise forward. Returns the absolute index of the
+ history element where string was found, or -1 otherwise.
Managing the History File
@@ -377,7 +384,7 @@ HISTORY(3) Library Functions Manual HISTORY(3)
-1 if there was an error in expansion;
2 if the returned line should be displayed, but not exe-
cuted, as with the :p modifier.
- If an error ocurred in expansion, then output contains a descriptive
+ If an error occurred in expansion, then output contains a descriptive
error message.
char * get_history_event (const char *string, int *cindex, int qchar)
@@ -390,9 +397,8 @@ HISTORY(3) Library Functions Manual HISTORY(3)
char ** history_tokenize (const char *string)
Return an array of tokens parsed out of string, much as the shell
- might. The tokens are split on the characters in the his-
- tory_word_delimiters variable, and shell quoting conventions are
- obeyed.
+ might. The tokens are split on the characters in the history_word_de-
+ limiters variable, and shell quoting conventions are obeyed.
char * history_arg_extract (int first, int last, const char *string)
Extract a string segment consisting of the first through last arguments
@@ -413,12 +419,12 @@ HISTORY(3) Library Functions Manual HISTORY(3)
The maximum number of history entries. This must be changed using sti-
fle_history().
- int history_wite_timestamps
+ int history_write_timestamps
If non-zero, timestamps are written to the history file, so they can be
preserved between sessions. The default value is 0, meaning that time-
- stamps are not saved. The current timestamp format uses the value of
- history_comment_char to delimit timestamp entries in the history file.
- If that variable does not have a value (the default), timestamps will
+ stamps are not saved. The current timestamp format uses the value of
+ history_comment_char to delimit timestamp entries in the history file.
+ If that variable does not have a value (the default), timestamps will
not be written.
char history_expansion_char
@@ -430,37 +436,37 @@ HISTORY(3) Library Functions Manual HISTORY(3)
line. The default is ^.
char history_comment_char
- 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.
+ 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.
char * history_word_delimiters
- The characters that separate tokens for history_tokenize(). The
- default value is " \t\n()<>;&|".
+ The characters that separate tokens for history_tokenize(). The de-
+ fault value is " \t\n()<>;&|".
char * history_no_expand_chars
The list of characters which inhibit history expansion if found immedi-
- ately following history_expansion_char. The default is space, tab,
+ ately following history_expansion_char. The default is space, tab,
newline, \r, and =.
char * history_search_delimiter_chars
- The list of additional characters which can delimit a history search
- string, in addition to space, tab, : and ? in the case of a substring
+ The list of additional characters which can delimit a history search
+ string, in addition to space, tab, : and ? in the case of a substring
search. The default is empty.
int history_quotes_inhibit_expansion
If non-zero, double-quoted words are not scanned for the history expan-
- sion character or the history comment character. The default value is
+ sion character or the history comment character. The default value is
0.
rl_linebuf_func_t * history_inhibit_expansion_function
- This should be set to the address of a function that takes two argu-
- ments: a char * (string) and an int index into that string (i). It
- should return a non-zero value if the history expansion starting at
- string[i] 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
+ This should be set to the address of a function that takes two argu-
+ ments: a char * (string) and an int index into that string (i). It
+ should return a non-zero value if the history expansion starting at
+ string[i] 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 NULL.
FILES
@@ -481,14 +487,14 @@ HISTORY(3) Library Functions Manual HISTORY(3)
chet.ramey@case.edu
BUG REPORTS
- If you find a bug in the history 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 history library that you have.
-
- Once you have determined that a bug actually exists, mail a bug report
- to bug-readline@gnu.org. If you have a fix, you are welcome to mail
- that as well! Suggestions and `philosophical' bug reports may be
- mailed to bug-readline@gnu.org or posted to the Usenet newsgroup
+ If you find a bug in the history library, you should report it. But
+ first, you should make sure that it really is a bug, and that it ap-
+ pears in the latest version of the history library that you have.
+
+ Once you have determined that a bug actually exists, mail a bug report
+ to bug-readline@gnu.org. If you have a fix, you are welcome to mail
+ that as well! Suggestions and `philosophical' bug reports may be
+ mailed to bug-readline@gnu.org or posted to the Usenet newsgroup
gnu.bash.bug.
Comments and bug reports concerning this manual page should be directed
@@ -496,4 +502,4 @@ HISTORY(3) Library Functions Manual HISTORY(3)
-GNU History 6.3 2017 October 8 HISTORY(3)
+GNU History 8.1 2020 July 17 HISTORY(3)
generated by cgit v1.2.3-70-g09d2 (git 2.46.0) at 2024-10-22 22:17:36 +0000