diff options
Diffstat (limited to 'doc/history.0')
| -rw-r--r-- | doc/history.0 | 754 |
1 files changed, 291 insertions, 463 deletions
diff --git a/doc/history.0 b/doc/history.0 index 324c363..3362294 100644 --- a/doc/history.0 +++ b/doc/history.0 @@ -1,219 +1,160 @@ +HISTORY(3) HISTORY(3) -HISTORY(3) HISTORY(3) - - NNAAMMEE history - GNU History Library CCOOPPYYRRIIGGHHTT - The GNU History Library is Copyright (C) 1989-2002 by the - Free Software Foundation, Inc. + The GNU History Library is Copyright (C) 1989-2002 by the Free Software + Foundation, Inc. DDEESSCCRRIIPPTTIIOONN - Many programs read input from the user a line at a time. - The GNU History library is able to keep track of those - lines, associate arbitrary data with each line, and uti- - lize information from previous lines in composing new - ones. + 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 - The history library supports a history expansion feature - that is identical 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 stream, making it easy to repeat commands, - insert the arguments to a previous command into the cur- - rent 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 second 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 bbaasshh does - when reading input, so that several words that would oth- - erwise be separated are considered one word when sur- - rounded by quotes (see the description of hhiissttoorryy__ttookk-- - eenniizzee(()) 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. + 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 + stream, making it easy to repeat commands, insert the arguments to a + previous command into the current input line, or fix errors in previous + commands quickly. + + 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 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 expansion character, which is !! by default. Only backslash (\\) + and single quotes can quote the history expansion character. EEvveenntt DDeessiiggnnaattoorrss - An event designator is a reference to a command line entry - in the history list. + An event designator is a reference to a command line entry in the his- + tory list. - !! Start a history substitution, except when followed - by a bbllaannkk, newline, = or (. + !! Start a history substitution, except when followed by a bbllaannkk, + newline, = or (. !!_n Refer to command line _n. !!--_n Refer to the current command line minus _n. - !!!! Refer to the previous command. This is a synonym - for `!-1'. - - - - -GNU History 4.3 2002 January 31 1 - - - - - -HISTORY(3) HISTORY(3) - - + !!!! Refer to the previous command. This is a synonym for `!-1'. !!_s_t_r_i_n_g - Refer to the most recent command starting with - _s_t_r_i_n_g. + Refer to the most recent command starting with _s_t_r_i_n_g. !!??_s_t_r_i_n_g[[??]] - Refer to the most recent command 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. + Refer to the most recent command containing _s_t_r_i_n_g. The trail- + ing ?? may be omitted if _s_t_r_i_n_g is followed immediately by a new- + line. ^^_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 MMooddiiffiieerrss below). + 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. 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 are numbered from - the beginning of the line, with the first word being - denoted by 0 (zero). Words are inserted into the current - line separated by single spaces. + 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 + 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)) - The zeroth word. For the shell, this is the com- - mand word. + The zeroth word. For the shell, this is the command word. _n The _nth word. ^^ The first argument. That is, word 1. $$ The last argument. - %% The word matched by the most recent `?_s_t_r_i_n_g?' - search. + %% 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 event; the empty string is - returned in that case. + ** 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. - If a word designator is supplied without an event specifi- - cation, the previous command is used as the event. + If a word designator is supplied without an event specification, the + previous command is used as the event. MMooddiiffiieerrss - After the optional word designator, there may appear a - sequence of one or more of the following modifiers, each - preceded by a `:'. - - 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. + After the optional word designator, there may appear a sequence of one + or more of the following modifiers, each preceded by a `:'. + + 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. - - - -GNU History 4.3 2002 January 31 2 - - - - - -HISTORY(3) HISTORY(3) - - - qq Quote the substituted words, escaping further sub- - stitutions. - xx Quote the substituted words as with qq, but break - into words at bbllaannkkss and newlines. + 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 back- - slash. 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 substitutions took place, the - last _s_t_r_i_n_g in a !!??_s_t_r_i_n_g[[??]] search. + 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 the final - delimiter is optional if it is the last character - of the event line. + 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' modifier once to each word in the event + line. PPRROOGGRRAAMMMMIINNGG WWIITTHH HHIISSTTOORRYY FFUUNNCCTTIIOONNSS - This section describes how to use the History library in - other programs. + 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, associ- - ating 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 available which provides for a consistent user inter- - face across different programs. - - The user using programs written with the History library - has the benefit of a consistent user interface with a set - of well-known commands for manipulating the text of previ- - ous lines and using that text in new commands. The basic - history manipulation commands are identical to the history - substitution provided by bbaasshh. - - If the programmer desires, he can use the Readline - library, which includes some history manipulation by - default, and has the added advantage of command line edit- - ing. - - 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 sup- - plies extern declarations for all of the library's public - - - -GNU History 4.3 2002 January 31 3 - - - - - -HISTORY(3) HISTORY(3) - - - functions and variables, and declares all of the public - data structures. + The programmer using the History library has available functions for + remembering lines on a history list, associating arbitrary data with a + line, removing lines from the list, searching through the list for a + line containing an arbitrary text string, and referencing any line in + the list directly. In addition, a history _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 + commands. The basic history manipulation commands are identical to the + history substitution provided by bbaasshh. + + 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 _<_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. HHiissttoorryy SSttoorraaggee - The history list is an array of history entries. A his- - tory entry is declared as follows: + 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 struct _hist_entry { char *line; + char *timestamp; histdata_t data; } HIST_ENTRY; @@ -221,8 +162,8 @@ HISTORY(3) HISTORY(3) _H_I_S_T___E_N_T_R_Y _*_* tthhee__hhiissttoorryy__lliisstt;; - The state of the History library is encapsulated into a - single structure: + 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. @@ -235,368 +176,285 @@ HISTORY(3) HISTORY(3) int flags; } HISTORY_STATE; - If the flags member includes HHSS__SSTTIIFFLLEEDD, the history has - been stifled. + If the flags member includes HHSS__SSTTIIFFLLEEDD, the history has been stifled. HHiissttoorryy FFuunnccttiioonnss - This section describes the calling sequence for the vari- - ous functions exported by the GNU History library. + 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 state of the History library when you want to - use the history functions in your program. + 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 initializes the interactive variables. + 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) - Return a structure describing the current state of the - input history. + 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) - - - -GNU History 4.3 2002 January 31 4 - - - - - -HISTORY(3) HISTORY(3) - - Set the state of the history list according to _s_t_a_t_e. HHiissttoorryy LLiisstt MMaannaaggeemmeenntt - These functions manage individual entries on the history - list, or set parameters managing the list itself. + 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 associ- - ated data field (if any) is set to NNUULLLL. + Place _s_t_r_i_n_g at the end of the history list. The associated data field + (if any) is set to NNUULLLL. + + _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. _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. - - _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 you can dispose of the data. - In the case of an invalid _w_h_i_c_h, a NNUULLLL pointer is + 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. + + _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. + + _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. _v_o_i_d cclleeaarr__hhiissttoorryy (_v_o_i_d) 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. + Stifle the history list, remembering only the last _m_a_x entries. _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 ssttii-- - ffllee__hhiissttoorryy(())). history was stifled. The value is posi- - tive if the history was stifled, negative if it wasn't. + Stop stifling the history. This returns the previously-set maximum + 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. _i_n_t hhiissttoorryy__iiss__ssttiifflleedd (_v_o_i_d) - Returns non-zero if the history is stifled, zero if it is - not. + 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 his- - tory list or individual list entries. + These functions return information about the entire history list or + individual 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. + 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. _i_n_t wwhheerree__hhiissttoorryy (_v_o_i_d) Returns the offset of the current history element. _H_I_S_T___E_N_T_R_Y _* ccuurrrreenntt__hhiissttoorryy (_v_o_i_d) - - - -GNU History 4.3 2002 January 31 5 - - - - - -HISTORY(3) HISTORY(3) - - - Return the history entry at the current position, as - determined by wwhheerree__hhiissttoorryy(()). If there is no entry - there, return a NNUULLLL pointer. + Return the history entry at the current position, as determined by + wwhheerree__hhiissttoorryy(()). If there is no entry there, return a NNUULLLL 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 - hhiissttoorryy__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. + 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. + + _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. _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. + 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 - These functions allow the current index into the history - list to be set or changed. + 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 number of history entries. + 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. _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. + 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. _H_I_S_T___E_N_T_R_Y _* nneexxtt__hhiissttoorryy (_v_o_i_d) - Move the current history offset forward to the next his- - tory entry, and return the a pointer to that entry. If - there is no next entry, return a NNUULLLL pointer. + 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. SSeeaarrcchhiinngg tthhee HHiissttoorryy LLiisstt - These functions allow searching of the history list for - entries containing a specific string. Searching may be - performed both forward and backward from the current his- - tory 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. + 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. _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 sub- - sequent 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. - - _i_n_t hhiissttoorryy__sseeaarrcchh__pprreeffiixx (_c_o_n_s_t _c_h_a_r _*_s_t_r_i_n_g_, _i_n_t - - - -GNU History 4.3 2002 January 31 6 - - - - - -HISTORY(3) HISTORY(3) - - - _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. - - _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. + 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. + + _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. + + _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. MMaannaaggiinngg tthhee HHiissttoorryy FFiillee - The History library can read the history from and write it - to a file. This section documents the functions for man- - aging a 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. - - _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 + 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 necessary. 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. + 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. - - _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 - - + 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. -GNU History 4.3 2002 January 31 7 - - - - - -HISTORY(3) HISTORY(3) - - - truncated. Returns 0 on success, or eerrrrnnoo 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. HHiissttoorryy EExxppaannssiioonn 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. Returns: - 0 If no expansions took place (or, if the only - change in the text was the removal of escape - characters preceding the history expansion - character); + 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 + the history expansion character); 1 if expansions did take place; -1 if there was an error in expansion; - 2 if the returned line should be displayed, - but not executed, as with the ::pp modifier. - If an error ocurred in expansion, then _o_u_t_p_u_t 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 - event specification in addition to the ``normal'' termi- - nating characters. + 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 + 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 + 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 hhiissttoorryy__wwoorrdd__ddeelliimmiitteerrss variable, and shell quoting - conventions are obeyed. + 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. - _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(()). + _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(()). HHiissttoorryy VVaarriiaabblleess - This section describes the externally-visible variables - exported by the GNU History Library. + This section describes the externally-visible variables exported by the + GNU History Library. _i_n_t hhiissttoorryy__bbaassee The logical offset of the first entry in the history list. _i_n_t hhiissttoorryy__lleennggtthh - The number of entries currently stored in the history - list. - - - - -GNU History 4.3 2002 January 31 8 - - - - - -HISTORY(3) HISTORY(3) - + 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 ssttiiffllee__hhiissttoorryy(()). + The maximum number of history entries. This must be changed using ssttii-- + ffllee__hhiissttoorryy(()). + + _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 + timestamps are not saved. _c_h_a_r hhiissttoorryy__eexxppaannssiioonn__cchhaarr - The character that introduces a history event. The - default is !!. Setting this to 0 inhibits history expan- - sion. + 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 - The character that invokes word substitution if found at - the start of a line. The default is ^^. + The character that invokes word substitution if found at the start of a + 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 his- - tory expansion for the remainder of the line. This is - disabled by default. + 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__ttookk-- - eenniizzee(()). The default value is "" \\tt\\nn(())<<>>;;&&||"". + The characters that separate tokens for hhiissttoorryy__ttookkeenniizzee(()). The + default value is "" \\tt\\nn(())<<>>;;&&||"". _c_h_a_r _* hhiissttoorryy__nnoo__eexxppaanndd__cchhaarrss - The list of characters which inhibit history expansion if - found immediately following hhiissttoorryy__eexxppaannssiioonn__cchhaarr. The - default is space, tab, newline, \\rr, and ==. + The list of characters which inhibit history expansion if found immedi- + ately following hhiissttoorryy__eexxppaannssiioonn__cchhaarr. The default is space, tab, + newline, \\rr, and ==. _c_h_a_r _* hhiissttoorryy__sseeaarrcchh__ddeelliimmiitteerr__cchhaarrss - The list of additional characters which can delimit a his- - tory search string, in addition to space, tab, _: and _? in - the case of a substring search. The default is empty. + 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 expansion character. The default value is 0. + If non-zero, single-quoted words are not scanned for the history expan- + sion character. The default value is 0. _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 arguments: 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 per- - formed; 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. + 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 his- - tory - - - - - -GNU History 4.3 2002 January 31 9 - - - - - -HISTORY(3) HISTORY(3) - + 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 @@ -612,49 +470,19 @@ AAUUTTHHOORRSS chet@ins.CWRU.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. - - 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 + 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. + + 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 _c_h_e_t_@_i_n_s_._C_W_R_U_._E_d_u. - - - - - - - - - - - - - - - - - - - - - - - - - - - - + Comments and bug reports concerning this manual page should be directed + to _c_h_e_t_@_i_n_s_._C_W_R_U_._E_d_u. -GNU History 4.3 2002 January 31 10 +GNU History 5.0 2003 July 31 HISTORY(3) |