--- embedaddon/readline/doc/history.0 2014/07/30 08:16:46 1.1.1.1 +++ embedaddon/readline/doc/history.0 2021/03/17 01:01:01 1.1.1.2 @@ -1,24 +1,23 @@ -HISTORY(3) HISTORY(3) +HISTORY(3) Library Functions Manual HISTORY(3) -NNAAMMEE +NAME history - GNU History Library -CCOOPPYYRRIIGGHHTT - The GNU History Library is Copyright (C) 1989-2011 by the Free Software +COPYRIGHT + The GNU History Library is Copyright (C) 1989-2020 by the Free Software Foundation, Inc. -DDEESSCCRRIIPPTTIIOONN +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 composing new ones. - -HHIISSTTOORRYY EEXXPPAANNSSIIOONN +HISTORY EXPANSION The history library supports a history expansion feature that is iden- - tical to the history expansion in bbaasshh.. This section describes what + tical to the history expansion in bash. This section describes what syntax features are available. History expansions introduce words from the history list into the input @@ -30,104 +29,112 @@ HHIISSTTOORRYY EEXXPPAANNSSIIOONN 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 + 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 available to manipulate the selected words. The line is broken into - words in the same fashion as bbaasshh does when reading input, so that sev- + 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 hhiissttoorryy__ttookkeenniizzee(()) + 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 (\\) + history expansion character, which is ! by default. Only backslash (\) and single quotes can quote the history expansion character. - EEvveenntt DDeessiiggnnaattoorrss + Event Designators 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 bbllaannkk, + ! Start a history substitution, except when followed by a blank, 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'. - !!_s_t_r_i_n_g + !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 Refer to the most recent command preceding the current position - in the history list starting with _s_t_r_i_n_g. - !!??_s_t_r_i_n_g[[??]] + in the history list starting with string. + !?string[?] Refer to the most recent command preceding the current position - 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. - ^^_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 MMoodd-- - iiffiieerrss below). - !!## The entire command line typed so far. + 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 + 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. - WWoorrdd DDeessiiggnnaattoorrss - Word designators are used to select desired words from the event. A :: + Word Designators + 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. - 00 ((zzeerroo)) + 0 (zero) 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 `?_s_t_r_i_n_g?' search. - _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 + 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 + 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. - xx** Abbreviates _x_-_$. - xx-- Abbreviates _x_-_$ like xx**, but omits the last word. + x* Abbreviates x-$. + 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 previous command is used as the event. - MMooddiiffiieerrss + Modifiers After the optional word designator, there may appear a sequence of one - or more of the following modifiers, each preceded by a `:'. + or more of the following modifiers, each preceded by a `:'. These mod- + ify, or edit, the word or words selected from the history event. - 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. - ss//_o_l_d//_n_e_w// - Substitute _n_e_w for the first occurrence of _o_l_d 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 _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 sin- - gle 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 substitu- - tions took place, the last _s_t_r_i_n_g in a !!??_s_t_r_i_n_g[[??]] search. - && 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 + 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- + sive; the last one supplied is used. + s/old/new/ + 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 aa may be used as a synonym for gg. - GG Apply the following `ss' modifier once to each word in the event - line. + 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 + event line. -PPRROOGGRRAAMMMMIINNGG WWIITTHH HHIISSTTOORRYY FFUUNNCCTTIIOONNSS +PROGRAMMING WITH HISTORY FUNCTIONS This section describes how to use the History library in other pro- grams. - IInnttrroodduuccttiioonn ttoo HHiissttoorryy - The programmer using the History library has available functions for - remembering lines on a history list, associating arbitrary data with a + Introduction to History + 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 _e_x_p_a_n_s_i_o_n function is avail- + the list directly. In addition, a history expansion function is avail- able which provides for a consistent user interface across different programs. @@ -135,25 +142,24 @@ PPRROOGGRRAAMMMMIINNGG WWIITTHH HHIIS 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 bbaasshh. + 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. + 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 - library 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 pub- - lic data structures. + Before declaring any functions using any functionality the History li- + brary provides in other code, an application writer should include the + file  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. - - HHiissttoorryy SSttoorraaggee + History Storage The history list is an array of history entries. A history entry is declared as follows: - _t_y_p_e_d_e_f _v_o_i_d _* hhiissttddaattaa__tt;; + typedef void * histdata_t; typedef struct _hist_entry { char *line; @@ -163,7 +169,7 @@ PPRROOGGRRAAMMMMIINNGG WWIITTHH HHIIS The history list itself might therefore be declared as - _H_I_S_T___E_N_T_R_Y _*_* tthhee__hhiissttoorryy__lliisstt;; + HIST_ENTRY ** the_history_list; The state of the History library is encapsulated into a single struc- ture: @@ -179,192 +185,197 @@ PPRROOGGRRAAMMMMIINNGG WWIITTHH HHIIS int flags; } HISTORY_STATE; - If the flags member includes HHSS__SSTTIIFFLLEEDD, the history has been stifled. + If the flags member includes HS_STIFLED, the history has been stifled. -HHiissttoorryy FFuunnccttiioonnss - This section describes the calling sequence for the various functions +History Functions + This section describes the calling sequence for the various functions exported by the GNU History library. - IInniittiiaalliizziinngg HHiissttoorryy aanndd SSttaattee MMaannaaggeemmeenntt - This section describes functions used to initialize and manage the + Initializing History and State Management + 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. - _v_o_i_d uussiinngg__hhiissttoorryy (_v_o_i_d) - Begin a session in which the history functions might be used. This + void using_history (void) + Begin a session in which the history functions might be used. This initializes the interactive variables. - _H_I_S_T_O_R_Y___S_T_A_T_E _* hhiissttoorryy__ggeett__hhiissttoorryy__ssttaattee (_v_o_i_d) + HISTORY_STATE * history_get_history_state (void) Return a structure describing the current state of the input history. - _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. + void history_set_history_state (HISTORY_STATE *state) + Set the state of the history list according to state. - HHiissttoorryy LLiisstt MMaannaaggeemmeenntt - These functions manage individual entries on the history list, or set + History List Management + These functions manage individual entries on the history list, or set parameters managing the list itself. - _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. + 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 + would exceed that maximum, the oldest history entry is removed. - _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. + void add_history_time (const char *string) + Change the time stamp associated with the most recent history entry to + string. - _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 - element is returned so you can free the line, data, and containing - structure. + HIST_ENTRY * remove_history (int which) + 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. - _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 - associated with it. Returns the application-specific data so the - caller can dispose of it. + histdata_t free_history_entry (HIST_ENTRY *histent) + 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. - _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 - returns the old entry so the caller can dispose of any application-spe- - cific data. In the case of an invalid _w_h_i_c_h, a NNUULLLL pointer is - returned. + 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- + 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. - _v_o_i_d cclleeaarr__hhiissttoorryy (_v_o_i_d) + void clear_history (void) Clear the history list by deleting all the entries. - _v_o_i_d ssttiiffllee__hhiissttoorryy (_i_n_t _m_a_x) - Stifle the history list, remembering only the last _m_a_x 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. - _i_n_t uunnssttiiffllee__hhiissttoorryy (_v_o_i_d) + int unstifle_history (void) Stop stifling the history. This returns the previously-set maximum - number of history entries (as set by ssttiiffllee__hhiissttoorryy(())). history was + number of history entries (as set by stifle_history()). history was stifled. The value is positive if the history was stifled, negative if it wasn't. - _i_n_t hhiissttoorryy__iiss__ssttiifflleedd (_v_o_i_d) + int history_is_stifled (void) Returns non-zero if the history is stifled, zero if it is not. - IInnffoorrmmaattiioonn AAbboouutt tthhee HHiissttoorryy LLiisstt - These functions return information about the entire history list or - individual list entries. + Information About the History List + These functions return information about the entire history list or in- + dividual list entries. - _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 - input history. Element 0 of this list is the beginning of time. If - there is no history, return NNUULLLL. + 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. - _i_n_t wwhheerree__hhiissttoorryy (_v_o_i_d) + int where_history (void) Returns the offset of the current history element. - _H_I_S_T___E_N_T_R_Y _* ccuurrrreenntt__hhiissttoorryy (_v_o_i_d) + HIST_ENTRY * current_history (void) Return the history entry at the current position, as determined by - wwhheerree__hhiissttoorryy(()). If there is no entry there, return a NNUULLLL pointer. + where_history(). If there is no entry there, return 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, starting from hhiiss-- - ttoorryy__bbaassee. If there is no entry there, or if _o_f_f_s_e_t is greater than - the history length, 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. - _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 + time_t history_get_time (HIST_ENTRY *) + Return the time stamp associated with the history entry passed as the argument. - _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 + int history_total_bytes (void) + 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. - MMoovviinngg AArroouunndd tthhee HHiissttoorryy LLiisstt + Moving Around the History List These functions allow the current index into the history list to be set or changed. - _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 + 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 number of history entries. - _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 NNUULLLL pointer. + HIST_ENTRY * previous_history (void) + 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. - _H_I_S_T___E_N_T_R_Y _* nneexxtt__hhiissttoorryy (_v_o_i_d) - Move the current history offset forward to the next history entry, and - return the a pointer to that entry. If there is no next entry, return - a NNUULLLL pointer. + HIST_ENTRY * next_history (void) + 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. - SSeeaarrcchhiinngg tthhee HHiissttoorryy LLiisstt + 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 - _a_n_c_h_o_r_e_d, 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. - _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 - entries, 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 a -1 is returned. + 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. - _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 + 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 current history index is set to that entry, and the return value is 0. Otherwise, nothing is changed, and a -1 is returned. - _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 - index into the list. If _d_i_r_e_c_t_i_o_n is negative, the search proceeds - backward 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. + 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. - MMaannaaggiinngg tthhee HHiissttoorryy FFiillee + Managing the History File The History library can read the history from and write it to a file. This section documents the functions for managing a history file. - _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. + 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. - _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. + 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. - _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. + 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. - _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 + 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 a read or write error. - _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. + 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. - HHiissttoorryy EExxppaannssiioonn + History Expansion These functions implement history expansion. - _i_n_t hhiissttoorryy__eexxppaanndd (_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. + int history_expand (char *string, char **output) + Expand string, placing the result into output, 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 @@ -372,123 +383,123 @@ HHiissttoorryy FFuunnccttiioonnss 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 ::pp modifier. - If an error ocurred in expansion, then _o_u_t_p_u_t contains a descriptive + cuted, as with the :p modifier. + If an error occurred in expansion, then output contains a descriptive error message. - _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 + 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- ters. - _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 hhiiss-- - ttoorryy__wwoorrdd__ddeelliimmiitteerrss variable, and shell quoting conventions are - obeyed. + 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__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(()). + 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(). - HHiissttoorryy VVaarriiaabblleess + History Variables This section describes the externally-visible variables exported by the GNU History Library. - _i_n_t hhiissttoorryy__bbaassee + int history_base The logical offset of the first entry in the history list. - _i_n_t hhiissttoorryy__lleennggtthh + int history_length The number of entries currently stored in the history list. - _i_n_t hhiissttoorryy__mmaaxx__eennttrriieess - The maximum number of history entries. This must be changed using ssttii-- - ffllee__hhiissttoorryy(()). + int history_max_entries + The maximum number of history entries. This must be changed using sti- + fle_history(). - _i_n_t hhiissttoorryy__wwiittee__ttiimmeessttaammppss + 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 - _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 + 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. - _c_h_a_r hhiissttoorryy__eexxppaannssiioonn__cchhaarr - The character that introduces a history event. The default is !!. Set- + char history_expansion_char + The character that introduces a history event. The default is !. Set- ting this to 0 inhibits history expansion. - _c_h_a_r hhiissttoorryy__ssuubbsstt__cchhaarr + char history_subst_char The character that invokes word substitution if found at the start of a - line. The default is ^^. + line. The default is ^. - _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. + 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. This is disabled by default. - _c_h_a_r _* hhiissttoorryy__wwoorrdd__ddeelliimmiitteerrss - The characters that separate tokens for hhiissttoorryy__ttookkeenniizzee(()). The - default value is "" \\tt\\nn(())<<>>;;&&||"". + char * history_word_delimiters + The characters that separate tokens for history_tokenize(). The de- + fault value is " \t\n()<>;&|". - _c_h_a_r _* hhiissttoorryy__nnoo__eexxppaanndd__cchhaarrss + char * history_no_expand_chars The list of characters which inhibit history expansion if found immedi- - ately following hhiissttoorryy__eexxppaannssiioonn__cchhaarr. The default is space, tab, - newline, \\rr, and ==. + ately following history_expansion_char. The default is space, tab, + newline, \r, and =. - _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 + 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 search. The default is empty. - _i_n_t hhiissttoorryy__qquuootteess__iinnhhiibbiitt__eexxppaannssiioonn - If non-zero, single-quoted words are not scanned for the history expan- - sion character. The default value is 0. + 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. - _r_l___l_i_n_e_b_u_f___f_u_n_c___t _* hhiissttoorryy__iinnhhiibbiitt__eexxppaannssiioonn__ffuunnccttiioonn + rl_linebuf_func_t * history_inhibit_expansion_function 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 + 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 - _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 + 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 NNUULLLL. + variable is set to NULL. -FFIILLEESS - _~_/_._h_i_s_t_o_r_y +FILES + ~/.history Default filename for reading and writing saved history -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) +SEE ALSO + The Gnu Readline Library, Brian Fox and Chet Ramey + The Gnu History Library, Brian Fox and Chet Ramey + bash(1) + readline(3) -AAUUTTHHOORRSS +AUTHORS Brian Fox, Free Software Foundation bfox@gnu.org Chet Ramey, Case Western Reserve University chet.ramey@case.edu -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 - appears in the latest version of the hhiissttoorryy library that you have. +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. 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 + 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 _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. + 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 - to _c_h_e_t_._r_a_m_e_y_@_c_a_s_e_._e_d_u. + to chet.ramey@case.edu. -GNU History 6.3 2013 June 27 HISTORY(3) +GNU History 8.1 2020 July 17 HISTORY(3)