summaryrefslogtreecommitdiff
path: root/doc/history.0
diff options
context:
space:
mode:
Diffstat (limited to 'doc/history.0')
-rw-r--r--doc/history.0593
1 files changed, 302 insertions, 291 deletions
diff --git a/doc/history.0 b/doc/history.0
index 2bf3b1a..7abcb7d 100644
--- a/doc/history.0
+++ b/doc/history.0
@@ -1,23 +1,21 @@
-HISTORY(3) Library Functions Manual HISTORY(3)
+_H_I_S_T_O_R_Y(3) Library Functions Manual _H_I_S_T_O_R_Y(3)
-
-
-NAME
+NNAAMMEE
history - GNU History Library
-COPYRIGHT
- The GNU History Library is Copyright (C) 1989-2020 by the Free Software
+CCOOPPYYRRIIGGHHTT
+ The GNU History Library is Copyright (C) 1989-2024 by the Free Software
Foundation, Inc.
-DESCRIPTION
- Many programs read input from the user a line at a time. The GNU His-
- tory library is able to keep track of those lines, associate arbitrary
- data with each line, and utilize information from previous lines in
+DDEESSCCRRIIPPTTIIOONN
+ Many programs read input from the user a line at a time. The GNU His-
+ tory 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.
-HISTORY EXPANSION
- The history library supports a history expansion feature that is iden-
- tical to the history expansion in bash. This section describes what
+HHIISSTTOORRYY EEXXPPAANNSSIIOONN
+ The history library supports a history expansion feature that is iden-
+ tical to the history expansion in bbaasshh. This section describes what
syntax features are available.
History expansions introduce words from the history list into the input
@@ -25,141 +23,151 @@ HISTORY(3) Library Functions Manual HISTORY(3)
previous command into the current input line, or fix errors in previous
commands quickly.
- 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 sec-
- ond is to select portions of that line for inclusion into the current
- one. The line selected from the history is the event, and the portions
- of that line that are acted upon are words. Various modifiers are
+ 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 sec-
+ ond is to select portions of that line for inclusion into the current
+ one. The line selected from the history is the _e_v_e_n_t, and the portions
+ of that line that are acted upon are _w_o_r_d_s. Various _m_o_d_i_f_i_e_r_s are
available to manipulate the selected words. The line is broken into
- words in the same fashion as bash does when reading input, so that sev-
- eral words that would otherwise be separated are considered one word
- when surrounded by quotes (see the description of history_tokenize()
- below). History expansions are introduced by the appearance of the
- history expansion character, which is ! by default. Only backslash (\)
- and single quotes can quote the history expansion character.
-
- Event Designators
+ words in the same fashion as bbaasshh does when reading input, so that sev-
+ eral words that would otherwise be separated are considered one word
+ when surrounded by quotes (see the description of hhiissttoorryy__ttookkeenniizzee(())
+ below).
+
+ History expansions are introduced by the appearance of the history ex-
+ pansion character, which is !! by default. Only backslash (\\) and sin-
+ gle quotes can quote the history expansion character.
+
+ There is a special abbreviation for substitution, active when the _q_u_i_c_k
+ _s_u_b_s_t_i_t_u_t_i_o_n character (default ^^) is the first character on the line.
+ It selects the previous history list entry, using an event designator
+ equivalent to !!!!, and substitutes one string for another in that line.
+ It is described below under EEvveenntt DDeessiiggnnaattoorrss. This is the only his-
+ tory expansion that does not begin with the history expansion charac-
+ ter.
+
+ EEvveenntt DDeessiiggnnaattoorrss
An event designator is a reference to a command line entry in the his-
tory list. Unless the reference is absolute, events are relative to
the current position in the history list.
- ! Start a history substitution, except when followed by a blank,
+ !! Start a history substitution, except when followed by a bbllaannkk,
newline, = or (.
- !n Refer to command line n.
- !-n Refer to the current command minus n.
- !! Refer to the previous command. This is a synonym for `!-1'.
- !string
+ !!_n Refer to command line _n.
+ !!--_n Refer to the current command minus _n.
+ !!!! Refer to the previous command. This is a synonym for "!-1".
+ !!_s_t_r_i_n_g
Refer to the most recent command preceding the current position
- in the history list starting with string.
- !?string[?]
+ in the history list starting with _s_t_r_i_n_g.
+ !!??_s_t_r_i_n_g[[??]]
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. If
- string is missing, the string from the most recent search is
+ in the history list containing _s_t_r_i_n_g. The trailing ?? may be
+ omitted if _s_t_r_i_n_g is followed immediately by a newline. If
+ _s_t_r_i_n_g 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-
- ifiers below).
- !# The entire command line typed so far.
-
- Word Designators
- Word designators are used to select desired words from the event. A :
+ ^^_s_t_r_i_n_g_1^^_s_t_r_i_n_g_2^^
+ Quick substitution. Repeat the last command, replacing _s_t_r_i_n_g_1
+ with _s_t_r_i_n_g_2. Equivalent to "!!:s^_s_t_r_i_n_g_1^_s_t_r_i_n_g_2^" (see MMooddii--
+ ffiieerrss below).
+ !!## The entire command line typed so far.
+
+ WWoorrdd DDeessiiggnnaattoorrss
+ Word designators are used to select desired words from the event. A ::
separates the event specification from the word designator. It may be
- omitted if the word designator begins with a ^, $, *, -, or %. Words
+ omitted if the word designator begins with a ^^, $$, **, --, or %%. 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 sepa-
rated by single spaces.
- 0 (zero)
+ 00 ((zzeerroo))
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 ex-
+ _n The _nth word.
+ ^^ The first argument. That is, word 1.
+ $$ 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
+ %% The first word matched by the most recent "?_s_t_r_i_n_g?" 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
+ _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. If x is miss-
+ xx** Abbreviates _x_-_$.
+ xx-- Abbreviates _x_-_$ like xx**, but omits the last word. If xx is miss-
ing, it defaults to 0.
If a word designator is supplied without an event specification, the
previous command is used as the event.
- Modifiers
+ MMooddiiffiieerrss
After the optional word designator, there may appear a sequence of one
- or more of the following modifiers, each preceded by a `:'. These mod-
+ 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.
- r Remove a trailing suffix of the form .xxx, leaving the basename.
- e Remove all but the trailing suffix.
- 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. The q and x modifiers are mutually exclu-
+ hh Remove a trailing file name component, leaving only the head.
+ tt Remove all leading file name components, leaving the tail.
+ rr Remove a trailing suffix of the form _._x_x_x, leaving the basename.
+ ee Remove all but the trailing suffix.
+ pp Print the new command but do not execute it.
+ qq Quote the substituted words, escaping further substitutions.
+ xx Quote the substituted words as with qq, but break into words at
+ bbllaannkkss and newlines. The qq and xx 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
+ ss//_o_l_d//_n_e_w//
+ Substitute _n_e_w for the first occurrence of _o_l_d 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' or `&' modifier once to each word in the
+ the event line. The delimiter may be quoted in _o_l_d and _n_e_w with
+ a single backslash. If & appears in _n_e_w, it is replaced by _o_l_d.
+ A single backslash will quote the &. If _o_l_d is null, it is set
+ to the last _o_l_d substituted, or, if no previous history substi-
+ tutions took place, the last _s_t_r_i_n_g in a !!??_s_t_r_i_n_g[[??]] search.
+ If _n_e_w is null, each matching _o_l_d is deleted.
+ && Repeat the previous substitution.
+ gg Cause changes to be applied over the entire event line. This is
+ used in conjunction with "::ss" (e.g., "::ggss//_o_l_d//_n_e_w//") or "::&&".
+ If used with "::ss", 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 aa may be used as a synonym for gg.
+ GG Apply the following "ss" or "&&" modifier once to each word in the
event line.
-PROGRAMMING WITH HISTORY FUNCTIONS
+PPRROOGGRRAAMMMMIINNGG WWIITTHH HHIISSTTOORRYY FFUUNNCCTTIIOONNSS
This section describes how to use the History library in other pro-
grams.
- Introduction to History
+ IInnttrroodduuccttiioonn ttoo HHiissttoorryy
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-
- able which provides for a consistent user interface across different
+ the list directly. In addition, a history _e_x_p_a_n_s_i_o_n function is avail-
+ able which provides for a consistent user interface across different
programs.
- The user using programs written with the History library has the bene-
- fit 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
+ The user using programs written with the History library has the bene-
+ fit 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 bash.
+ history substitution provided by bbaasshh.
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
+ Before declaring any functions using any functionality the History li-
+ brary provides in other code, an application writer should include the
+ file _<_r_e_a_d_l_i_n_e_/_h_i_s_t_o_r_y_._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
+ HHiissttoorryy SSttoorraaggee
+ The history list is an array of history entries. A history entry is
declared as follows:
- typedef void * histdata_t;
+ _t_y_p_e_d_e_f _v_o_i_d _* hhiissttddaattaa__tt;;
typedef struct _hist_entry {
char *line;
@@ -169,213 +177,206 @@ HISTORY(3) Library Functions Manual HISTORY(3)
The history list itself might therefore be declared as
- HIST_ENTRY ** the_history_list;
+ _H_I_S_T___E_N_T_R_Y _*_* tthhee__hhiissttoorryy__lliisstt;;
- The state of the History library is encapsulated into a single struc-
+ The state of the History library is encapsulated into a single struc-
ture:
/*
* 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. */
+ HIST_ENTRY **entries; /* Pointer to entry records. */
+ int offset; /* The current record. */
+ int length; /* Number of records in list. */
+ int size; /* Number of records allocated. */
int flags;
} HISTORY_STATE;
- If the flags member includes HS_STIFLED, the history has been stifled.
+ If the flags member includes HHSS__SSTTIIFFLLEEDD, the history has been stifled.
-History Functions
- This section describes the calling sequence for the various functions
+HHiissttoorryy FFuunnccttiioonnss
+ This section describes the calling sequence for the various functions
exported by the GNU History library.
- Initializing History and State Management
- This section describes functions used to initialize and manage the
+ IInniittiiaalliizziinngg HHiissttoorryy aanndd SSttaattee MMaannaaggeemmeenntt
+ 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.
- void using_history (void)
+ _v_o_i_d uussiinngg__hhiissttoorryy (_v_o_i_d)
Begin a session in which the history functions might be used. This
initializes the interactive variables.
- HISTORY_STATE * history_get_history_state (void)
+ _H_I_S_T_O_R_Y___S_T_A_T_E _* hhiissttoorryy__ggeett__hhiissttoorryy__ssttaattee (_v_o_i_d)
Return a structure describing the current state of the input history.
- void history_set_history_state (HISTORY_STATE *state)
- Set the state of the history list according to state.
+ _v_o_i_d hhiissttoorryy__sseett__hhiissttoorryy__ssttaattee (_H_I_S_T_O_R_Y___S_T_A_T_E _*_s_t_a_t_e)
+ Set the state of the history list according to _s_t_a_t_e.
-
- History List Management
+ HHiissttoorryy LLiisstt MMaannaaggeemmeenntt
These functions manage individual entries on the history list, or set
parameters managing the list itself.
- void add_history (const char *string)
- Place string at the end of the history list. The associated data field
- (if any) is set to NULL. If the maximum number of history entries has
- been set using stifle_history(), and the new number of history entries
+ _v_o_i_d aadddd__hhiissttoorryy (_c_o_n_s_t _c_h_a_r _*_s_t_r_i_n_g)
+ Place _s_t_r_i_n_g at the end of the history list. The associated data field
+ (if any) is set to NNUULLLL. If the maximum number of history entries has
+ been set using ssttiiffllee__hhiissttoorryy(()), and the new number of history entries
would exceed that maximum, the oldest history entry is removed.
- void add_history_time (const char *string)
- Change the time stamp associated with the most recent history entry to
- string.
+ _v_o_i_d aadddd__hhiissttoorryy__ttiimmee (_c_o_n_s_t _c_h_a_r _*_s_t_r_i_n_g)
+ Change the time stamp associated with the most recent history entry to
+ _s_t_r_i_n_g.
- HIST_ENTRY * remove_history (int which)
- Remove history entry at offset which from the history. The removed el-
+ _H_I_S_T___E_N_T_R_Y _* rreemmoovvee__hhiissttoorryy (_i_n_t _w_h_i_c_h)
+ Remove history entry at offset _w_h_i_c_h 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 as-
+ _h_i_s_t_d_a_t_a___t ffrreeee__hhiissttoorryy__eennttrryy (_H_I_S_T___E_N_T_R_Y _*_h_i_s_t_e_n_t)
+ Free the history entry _h_i_s_t_e_n_t 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 re-
+ _H_I_S_T___E_N_T_R_Y _* rreeppllaaccee__hhiissttoorryy__eennttrryy (_i_n_t _w_h_i_c_h_, _c_o_n_s_t _c_h_a_r _*_l_i_n_e_, _h_i_s_t_-
+ _d_a_t_a___t _d_a_t_a)
+ Make the history entry at offset _w_h_i_c_h have _l_i_n_e and _d_a_t_a. 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-
+ cific data. In the case of an invalid _w_h_i_c_h, a NNUULLLL pointer is re-
turned.
- void clear_history (void)
+ _v_o_i_d cclleeaarr__hhiissttoorryy (_v_o_i_d)
Clear the history list by deleting all the entries.
- void stifle_history (int max)
- Stifle the history list, remembering only the last max entries. The
- history list will contain only max entries at a time.
+ _v_o_i_d ssttiiffllee__hhiissttoorryy (_i_n_t _m_a_x)
+ Stifle the history list, remembering only the last _m_a_x entries. The
+ history list will contain only _m_a_x entries at a time.
- int unstifle_history (void)
+ _i_n_t uunnssttiiffllee__hhiissttoorryy (_v_o_i_d)
Stop stifling the history. This returns the previously-set maximum
- number of history entries (as set by stifle_history()). history was
+ number of history entries (as set by ssttiiffllee__hhiissttoorryy(())). history was
stifled. The value is positive if the history was stifled, negative if
it wasn't.
- int history_is_stifled (void)
+ _i_n_t hhiissttoorryy__iiss__ssttiifflleedd (_v_o_i_d)
Returns non-zero if the history is stifled, zero if it is not.
-
- Information About the History List
+ IInnffoorrmmaattiioonn AAbboouutt tthhee HHiissttoorryy LLiisstt
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 in-
- put history. Element 0 of this list is the beginning of time. If
- there is no history, return NULL.
+ _H_I_S_T___E_N_T_R_Y _*_* hhiissttoorryy__lliisstt (_v_o_i_d)
+ Return a NNUULLLL terminated array of _H_I_S_T___E_N_T_R_Y _* which is the current in-
+ put history. Element 0 of this list is the beginning of time. If
+ there is no history, return NNUULLLL.
- int where_history (void)
+ _i_n_t wwhheerree__hhiissttoorryy (_v_o_i_d)
Returns the offset of the current history element.
- HIST_ENTRY * current_history (void)
- Return the history entry at the current position, as determined by
- where_history(). If there is no entry there, return a NULL pointer.
+ _H_I_S_T___E_N_T_R_Y _* ccuurrrreenntt__hhiissttoorryy (_v_o_i_d)
+ Return the history entry at the current position, as determined by
+ wwhheerree__hhiissttoorryy(()). If there is no entry there, return a NNUULLLL pointer.
- 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, re-
- turn a NULL pointer.
+ _H_I_S_T___E_N_T_R_Y _* hhiissttoorryy__ggeett (_i_n_t _o_f_f_s_e_t)
+ Return the history entry at position _o_f_f_s_e_t. The range of valid values
+ of _o_f_f_s_e_t starts at hhiissttoorryy__bbaassee and ends at hhiissttoorryy__lleennggtthh - 1. If
+ there is no entry there, or if _o_f_f_s_e_t is outside the valid range, re-
+ turn a NNUULLLL pointer.
- time_t history_get_time (HIST_ENTRY *)
+ _t_i_m_e___t hhiissttoorryy__ggeett__ttiimmee (_H_I_S_T___E_N_T_R_Y _*)
Return the time stamp associated with the history entry passed as the
argument.
- int history_total_bytes (void)
+ _i_n_t hhiissttoorryy__ttoottaall__bbyytteess (_v_o_i_d)
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.
-
- Moving Around the History List
+ MMoovviinngg AArroouunndd tthhee HHiissttoorryy LLiisstt
These functions allow the current index into the history list to be set
or changed.
- int history_set_pos (int pos)
- Set the current history offset to pos, an absolute index into the list.
- Returns 1 on success, 0 if pos is less than zero or greater than the
+ _i_n_t hhiissttoorryy__sseett__ppooss (_i_n_t _p_o_s)
+ Set the current history offset to _p_o_s, an absolute index into the list.
+ Returns 1 on success, 0 if _p_o_s is less than zero or greater than the
number of history entries.
- HIST_ENTRY * previous_history (void)
+ _H_I_S_T___E_N_T_R_Y _* pprreevviioouuss__hhiissttoorryy (_v_o_i_d)
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 NULL pointer.
+ a NNUULLLL pointer.
- HIST_ENTRY * next_history (void)
+ _H_I_S_T___E_N_T_R_Y _* nneexxtt__hhiissttoorryy (_v_o_i_d)
If the current history offset refers to a valid history entry, incre-
ment 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 NULL pointer.
-
+ otherwise, return a NNUULLLL pointer.
- Searching the History List
- These functions allow searching of the history list for entries con-
+ SSeeaarrcchhiinngg tthhee HHiissttoorryy LLiisstt
+ 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 an-
- chored, meaning that the string must match at the beginning of the his-
+ backward from the current history position. The search may be _a_n_-
+ _c_h_o_r_e_d, 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 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 di-
- rection is less than 0, then the search is through previous entries,
- otherwise through subsequent entries. If string is found, then the
+ _i_n_t hhiissttoorryy__sseeaarrcchh (_c_o_n_s_t _c_h_a_r _*_s_t_r_i_n_g_, _i_n_t _d_i_r_e_c_t_i_o_n)
+ Search the history for _s_t_r_i_n_g, starting at the current history offset.
+ If _d_i_r_e_c_t_i_o_n is less than 0, then the search is through previous en-
+ tries, otherwise through subsequent entries. If _s_t_r_i_n_g 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 _s_t_r_i_n_g was found.
+ Otherwise, nothing is changed, and the function returns -1.
+
+ _i_n_t hhiissttoorryy__sseeaarrcchh__pprreeffiixx (_c_o_n_s_t _c_h_a_r _*_s_t_r_i_n_g_, _i_n_t _d_i_r_e_c_t_i_o_n)
+ Search the history for _s_t_r_i_n_g, starting at the current history offset.
+ The search is anchored: matching lines must begin with _s_t_r_i_n_g. If _d_i_-
+ _r_e_c_t_i_o_n is less than 0, then the search is through previous entries,
+ otherwise through subsequent entries. If _s_t_r_i_n_g 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.
+ Otherwise, nothing is changed, and the function returns -1.
- int history_search_pos (const char *string, int direction, int pos)
- 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.
+ _i_n_t hhiissttoorryy__sseeaarrcchh__ppooss (_c_o_n_s_t _c_h_a_r _*_s_t_r_i_n_g_, _i_n_t _d_i_r_e_c_t_i_o_n_, _i_n_t _p_o_s)
+ Search for _s_t_r_i_n_g in the history list, starting at _p_o_s, an absolute in-
+ dex into the list. If _d_i_r_e_c_t_i_o_n is negative, the search proceeds back-
+ ward from _p_o_s, otherwise forward. Returns the absolute index of the
+ history element where _s_t_r_i_n_g was found, or -1 otherwise.
-
- Managing the History File
+ MMaannaaggiinngg tthhee HHiissttoorryy FFiillee
The History library can read the history from and write it to a file.
This section documents the functions for managing a history file.
- int read_history (const char *filename)
- Add the contents of filename to the history list, a line at a time. If
- filename is NULL, then read from ~/.history. Returns 0 if successful,
- or errno if not.
-
- int read_history_range (const char *filename, int from, int to)
- Read a range of lines from filename, adding them to the history list.
- Start reading at line from and end at to. If from is zero, start at
- the beginning. If to is less than from, then read until the end of the
- file. If filename is NULL, then read from ~/.history. Returns 0 if
- successful, or errno if not.
-
- int write_history (const char *filename)
- Write the current history to filename, overwriting filename if neces-
- sary. If filename is NULL, then write the history list to ~/.history.
- Returns 0 on success, or errno on a read or write error.
-
-
- int append_history (int nelements, const char *filename)
- Append the last nelements of the history list to filename. If filename
- is NULL, then append to ~/.history. Returns 0 on success, or errno on
+ _i_n_t rreeaadd__hhiissttoorryy (_c_o_n_s_t _c_h_a_r _*_f_i_l_e_n_a_m_e)
+ Add the contents of _f_i_l_e_n_a_m_e to the history list, a line at a time. If
+ _f_i_l_e_n_a_m_e is NNUULLLL, then read from _~_/_._h_i_s_t_o_r_y. Returns 0 if successful,
+ or eerrrrnnoo if not.
+
+ _i_n_t rreeaadd__hhiissttoorryy__rraannggee (_c_o_n_s_t _c_h_a_r _*_f_i_l_e_n_a_m_e_, _i_n_t _f_r_o_m_, _i_n_t _t_o)
+ Read a range of lines from _f_i_l_e_n_a_m_e, adding them to the history list.
+ Start reading at line _f_r_o_m and end at _t_o. If _f_r_o_m is zero, start at
+ the beginning. If _t_o is less than _f_r_o_m, then read until the end of the
+ file. If _f_i_l_e_n_a_m_e is NNUULLLL, then read from _~_/_._h_i_s_t_o_r_y. Returns 0 if
+ successful, or eerrrrnnoo if not.
+
+ _i_n_t wwrriittee__hhiissttoorryy (_c_o_n_s_t _c_h_a_r _*_f_i_l_e_n_a_m_e)
+ Write the current history to _f_i_l_e_n_a_m_e, overwriting _f_i_l_e_n_a_m_e if neces-
+ sary. If _f_i_l_e_n_a_m_e is NNUULLLL, then write the history list to _~_/_._h_i_s_t_o_r_y.
+ Returns 0 on success, or eerrrrnnoo on a read or write error.
+
+ _i_n_t aappppeenndd__hhiissttoorryy (_i_n_t _n_e_l_e_m_e_n_t_s_, _c_o_n_s_t _c_h_a_r _*_f_i_l_e_n_a_m_e)
+ Append the last _n_e_l_e_m_e_n_t_s of the history list to _f_i_l_e_n_a_m_e. If _f_i_l_e_n_a_m_e
+ is NNUULLLL, then append to _~_/_._h_i_s_t_o_r_y. Returns 0 on success, or eerrrrnnoo on
a read or write error.
- int history_truncate_file (const char *filename, int nlines)
- Truncate the history file filename, leaving only the last nlines lines.
- If filename is NULL, then ~/.history is truncated. Returns 0 on suc-
- cess, or errno on failure.
-
+ _i_n_t hhiissttoorryy__ttrruunnccaattee__ffiillee (_c_o_n_s_t _c_h_a_r _*_f_i_l_e_n_a_m_e_, _i_n_t _n_l_i_n_e_s)
+ Truncate the history file _f_i_l_e_n_a_m_e, leaving only the last _n_l_i_n_e_s lines.
+ If _f_i_l_e_n_a_m_e is NNUULLLL, then _~_/_._h_i_s_t_o_r_y is truncated. Returns 0 on suc-
+ cess, or eerrrrnnoo on failure.
- History Expansion
+ HHiissttoorryy EExxppaannssiioonn
These functions implement history expansion.
- int history_expand (char *string, char **output)
- Expand string, placing the result into output, a pointer to a string.
+ _i_n_t hhiissttoorryy__eexxppaanndd (_c_o_n_s_t _c_h_a_r _*_s_t_r_i_n_g_, _c_h_a_r _*_*_o_u_t_p_u_t)
+ Expand _s_t_r_i_n_g, placing the result into _o_u_t_p_u_t, a pointer to a string.
Returns:
0 If no expansions took place (or, if the only change in
the text was the removal of escape characters preceding
@@ -383,123 +384,133 @@ HISTORY(3) Library Functions Manual HISTORY(3)
1 if expansions did take place;
-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 occurred in expansion, then output contains a descriptive
+ cuted, as with the ::pp modifier.
+ If an error occurred in expansion, then _o_u_t_p_u_t contains a descriptive
error message.
- char * get_history_event (const char *string, int *cindex, int qchar)
- Returns the text of the history event beginning at string + *cindex.
- *cindex is modified to point to after the event specifier. At function
- entry, cindex points to the index into string where the history event
- specification begins. qchar is a character that is allowed to end the
- event specification in addition to the ``normal'' terminating charac-
+ _c_h_a_r _* ggeett__hhiissttoorryy__eevveenntt (_c_o_n_s_t _c_h_a_r _*_s_t_r_i_n_g_, _i_n_t _*_c_i_n_d_e_x_, _i_n_t _q_c_h_a_r)
+ Returns the text of the history event beginning at _s_t_r_i_n_g + _*_c_i_n_d_e_x.
+ _*_c_i_n_d_e_x is modified to point to after the event specifier. At function
+ entry, _c_i_n_d_e_x points to the index into _s_t_r_i_n_g where the history event
+ specification begins. _q_c_h_a_r is a character that is allowed to end the
+ event specification in addition to the ``normal'' terminating charac-
ters.
- 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 history_word_de-
- limiters variable, and shell quoting conventions are obeyed.
+ _c_h_a_r _*_* hhiissttoorryy__ttookkeenniizzee (_c_o_n_s_t _c_h_a_r _*_s_t_r_i_n_g)
+ Return an array of tokens parsed out of _s_t_r_i_n_g, much as the shell
+ might. The tokens are split on the characters in the hhiissttoorryy__wwoorrdd__ddee--
+ lliimmiitteerrss 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
- present in string. Arguments are split using history_tokenize().
+ _c_h_a_r _* hhiissttoorryy__aarrgg__eexxttrraacctt (_i_n_t _f_i_r_s_t_, _i_n_t _l_a_s_t_, _c_o_n_s_t _c_h_a_r _*_s_t_r_i_n_g)
+ Extract a string segment consisting of the _f_i_r_s_t through _l_a_s_t arguments
+ present in _s_t_r_i_n_g. Arguments are split using hhiissttoorryy__ttookkeenniizzee(()).
-
- History Variables
+ HHiissttoorryy VVaarriiaabblleess
This section describes the externally-visible variables exported by the
GNU History Library.
- int history_base
+ _i_n_t hhiissttoorryy__bbaassee
The logical offset of the first entry in the history list.
- int history_length
+ _i_n_t hhiissttoorryy__lleennggtthh
The number of entries currently stored in the history list.
- int history_max_entries
- The maximum number of history entries. This must be changed using sti-
- fle_history().
+ _i_n_t hhiissttoorryy__mmaaxx__eennttrriieess
+ The maximum number of history entries. This must be changed using ssttii--
+ ffllee__hhiissttoorryy(()).
- int history_write_timestamps
+ _i_n_t hhiissttoorryy__wwrriittee__ttiimmeessttaammppss
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.
+ _h_i_s_t_o_r_y___c_o_m_m_e_n_t___c_h_a_r 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
- The character that introduces a history event. The default is !. Set-
+ _c_h_a_r hhiissttoorryy__eexxppaannssiioonn__cchhaarr
+ The character that introduces a history event. The default is !!. Set-
ting this to 0 inhibits history expansion.
- char history_subst_char
+ _c_h_a_r hhiissttoorryy__ssuubbsstt__cchhaarr
The character that invokes word substitution if found at the start of a
- line. The default is ^.
+ line. The default is ^^.
- char history_comment_char
+ _c_h_a_r hhiissttoorryy__ccoommmmeenntt__cchhaarr
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 de-
- fault value is " \t\n()<>;&|".
+ _c_h_a_r _* hhiissttoorryy__wwoorrdd__ddeelliimmiitteerrss
+ The characters that separate tokens for hhiissttoorryy__ttookkeenniizzee(()). The de-
+ fault value is "" \\tt\\nn(())<<>>;;&&||"".
- char * history_no_expand_chars
+ _c_h_a_r _* hhiissttoorryy__nnoo__eexxppaanndd__cchhaarrss
The list of characters which inhibit history expansion if found immedi-
- ately following history_expansion_char. The default is space, tab,
- newline, \r, and =.
+ ately following hhiissttoorryy__eexxppaannssiioonn__cchhaarr. The default is space, tab,
+ newline, \\rr, 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
+ _c_h_a_r _* hhiissttoorryy__sseeaarrcchh__ddeelliimmiitteerr__cchhaarrss
+ 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
- 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
- variable is set to NULL.
-
-FILES
- ~/.history
+ _i_n_t hhiissttoorryy__qquuootteess__iinnhhiibbiitt__eexxppaannssiioonn
+ If non-zero, the history expansion code implements shell-like quoting:
+ single-quoted words are not scanned for the history expansion character
+ or the history comment character, and double-quoted words may have his-
+ tory expansion performed, since single quotes are not special within
+ double quotes. The default value is 0.
+
+ _i_n_t hhiissttoorryy__qquuoottiinngg__ssttaattee
+ An application may set this variable to indicate that the current line
+ being expanded is subject to existing quoting. If set to _', the history
+ expansion function will assume that the line is single-quoted and in-
+ hibit expansion until it reads an unquoted closing single quote; if set
+ to _", history expansion will assume the line is double quoted until it
+ reads an unquoted closing double quote. If set to zero, the default,
+ the history expansion function will assume the line is not quoted and
+ treat quote characters within the line as described above. This is
+ only effective if hhiissttoorryy__qquuootteess__iinnhhiibbiitt__eexxppaannssiioonn is set.
+
+ _r_l___l_i_n_e_b_u_f___f_u_n_c___t _* hhiissttoorryy__iinnhhiibbiitt__eexxppaannssiioonn__ffuunnccttiioonn
+ This should be set to the address of a function that takes two argu-
+ ments: a cchhaarr ** (_s_t_r_i_n_g) and an iinntt index into that string (_i). It
+ should return a non-zero value if the history expansion starting at
+ _s_t_r_i_n_g_[_i_] should not be performed; zero if the expansion should be
+ done. It is intended for use by applications like bbaasshh that use the
+ history expansion character for additional purposes. By default, this
+ variable is set to NNUULLLL.
+
+FFIILLEESS
+ _~_/_._h_i_s_t_o_r_y
Default filename for reading and writing saved history
-SEE ALSO
- The Gnu Readline Library, Brian Fox and Chet Ramey
- The Gnu History Library, Brian Fox and Chet Ramey
- bash(1)
- readline(3)
+SSEEEE AALLSSOO
+ _T_h_e _G_n_u _R_e_a_d_l_i_n_e _L_i_b_r_a_r_y, Brian Fox and Chet Ramey
+ _T_h_e _G_n_u _H_i_s_t_o_r_y _L_i_b_r_a_r_y, Brian Fox and Chet Ramey
+ _b_a_s_h(1)
+ _r_e_a_d_l_i_n_e(3)
-AUTHORS
+AAUUTTHHOORRSS
Brian Fox, Free Software Foundation
bfox@gnu.org
Chet Ramey, Case Western Reserve University
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 ap-
- pears in the latest version of the history library that you have.
+BBUUGG RREEPPOORRTTSS
+ If you find a bug in the hhiissttoorryy 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 hhiissttoorryy 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.
+ Once you have determined that a bug actually exists, mail a bug report
+ to _b_u_g_-_r_e_a_d_l_i_n_e@_g_n_u_._o_r_g. If you have a fix, you are welcome to mail
+ that as well! Suggestions and `philosophical' bug reports may be
+ mailed to _b_u_g_-_r_e_a_d_l_i_n_e@_g_n_u_._o_r_g or posted to the Usenet newsgroup
+ ggnnuu..bbaasshh..bbuugg.
Comments and bug reports concerning this manual page should be directed
- to chet.ramey@case.edu.
-
-
+ to _c_h_e_t_._r_a_m_e_y_@_c_a_s_e_._e_d_u.
-GNU History 8.1 2020 July 17 HISTORY(3)
+GNU History 8.3 2024 March 29 _H_I_S_T_O_R_Y(3)
generated by cgit v1.2.3-70-g09d2 (git 2.46.0) at 2024-10-22 20:53:50 +0000