Commit | Line | Data |
---|---|---|
b585a9fa | 1 | HISTORY(3) HISTORY(3) |
84041b4c EZ |
2 | |
3 | ||
4 | ||
84041b4c EZ |
5 | N\bNA\bAM\bME\bE |
6 | history - GNU History Library | |
7 | ||
8 | C\bCO\bOP\bPY\bYR\bRI\bIG\bGH\bHT\bT | |
b585a9fa EZ |
9 | The GNU History Library is Copyright (C) 1989-2002 by the Free Software |
10 | Foundation, Inc. | |
84041b4c EZ |
11 | |
12 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN | |
b585a9fa EZ |
13 | Many programs read input from the user a line at a time. The GNU His- |
14 | tory library is able to keep track of those lines, associate arbitrary | |
15 | data with each line, and utilize information from previous lines in | |
16 | composing new ones. | |
84041b4c EZ |
17 | |
18 | ||
19 | H\bHI\bIS\bST\bTO\bOR\bRY\bY E\bEX\bXP\bPA\bAN\bNS\bSI\bIO\bON\bN | |
b585a9fa EZ |
20 | The history library supports a history expansion feature that is iden- |
21 | tical to the history expansion in b\bba\bas\bsh\bh.\b. This section describes what | |
22 | syntax features are available. | |
23 | ||
24 | History expansions introduce words from the history list into the input | |
25 | stream, making it easy to repeat commands, insert the arguments to a | |
26 | previous command into the current input line, or fix errors in previous | |
27 | commands quickly. | |
28 | ||
29 | History expansion is usually performed immediately after a complete | |
30 | line is read. It takes place in two parts. The first is to determine | |
31 | which line from the history list to use during substitution. The sec- | |
32 | ond is to select portions of that line for inclusion into the current | |
33 | one. The line selected from the history is the _\be_\bv_\be_\bn_\bt, and the portions | |
34 | of that line that are acted upon are _\bw_\bo_\br_\bd_\bs. Various _\bm_\bo_\bd_\bi_\bf_\bi_\be_\br_\bs are | |
35 | available to manipulate the selected words. The line is broken into | |
36 | words in the same fashion as b\bba\bas\bsh\bh does when reading input, so that sev- | |
37 | eral words that would otherwise be separated are considered one word | |
38 | when surrounded by quotes (see the description of h\bhi\bis\bst\bto\bor\bry\by_\b_t\bto\bok\bke\ben\bni\biz\bze\be(\b()\b) | |
39 | below). History expansions are introduced by the appearance of the | |
40 | history expansion character, which is !\b! by default. Only backslash (\\b\) | |
41 | and single quotes can quote the history expansion character. | |
84041b4c EZ |
42 | |
43 | E\bEv\bve\ben\bnt\bt D\bDe\bes\bsi\big\bgn\bna\bat\bto\bor\brs\bs | |
b585a9fa EZ |
44 | An event designator is a reference to a command line entry in the his- |
45 | tory list. | |
84041b4c | 46 | |
b585a9fa EZ |
47 | !\b! Start a history substitution, except when followed by a b\bbl\bla\ban\bnk\bk, |
48 | newline, = or (. | |
84041b4c EZ |
49 | !\b!_\bn Refer to command line _\bn. |
50 | !\b!-\b-_\bn Refer to the current command line minus _\bn. | |
b585a9fa | 51 | !\b!!\b! Refer to the previous command. This is a synonym for `!-1'. |
84041b4c | 52 | !\b!_\bs_\bt_\br_\bi_\bn_\bg |
b585a9fa | 53 | Refer to the most recent command starting with _\bs_\bt_\br_\bi_\bn_\bg. |
84041b4c | 54 | !\b!?\b?_\bs_\bt_\br_\bi_\bn_\bg[\b[?\b?]\b] |
b585a9fa EZ |
55 | Refer to the most recent command containing _\bs_\bt_\br_\bi_\bn_\bg. The trail- |
56 | ing ?\b? may be omitted if _\bs_\bt_\br_\bi_\bn_\bg is followed immediately by a new- | |
57 | line. | |
84041b4c | 58 | ^\b^_\bs_\bt_\br_\bi_\bn_\bg_\b1^\b^_\bs_\bt_\br_\bi_\bn_\bg_\b2^\b^ |
b585a9fa EZ |
59 | Quick substitution. Repeat the last command, replacing _\bs_\bt_\br_\bi_\bn_\bg_\b1 |
60 | with _\bs_\bt_\br_\bi_\bn_\bg_\b2. Equivalent to ``!!:s/_\bs_\bt_\br_\bi_\bn_\bg_\b1/_\bs_\bt_\br_\bi_\bn_\bg_\b2/'' (see M\bMo\bod\bd-\b- | |
61 | i\bif\bfi\bie\ber\brs\bs below). | |
84041b4c EZ |
62 | !\b!#\b# The entire command line typed so far. |
63 | ||
64 | W\bWo\bor\brd\bd D\bDe\bes\bsi\big\bgn\bna\bat\bto\bor\brs\bs | |
b585a9fa EZ |
65 | Word designators are used to select desired words from the event. A :\b: |
66 | separates the event specification from the word designator. It may be | |
67 | omitted if the word designator begins with a ^\b^, $\b$, *\b*, -\b-, or %\b%. Words | |
68 | are numbered from the beginning of the line, with the first word being | |
69 | denoted by 0 (zero). Words are inserted into the current line sepa- | |
70 | rated by single spaces. | |
84041b4c EZ |
71 | |
72 | 0\b0 (\b(z\bze\ber\bro\bo)\b) | |
b585a9fa | 73 | The zeroth word. For the shell, this is the command word. |
84041b4c EZ |
74 | _\bn The _\bnth word. |
75 | ^\b^ The first argument. That is, word 1. | |
76 | $\b$ The last argument. | |
b585a9fa | 77 | %\b% The word matched by the most recent `?_\bs_\bt_\br_\bi_\bn_\bg?' search. |
84041b4c | 78 | _\bx-\b-_\by A range of words; `-_\by' abbreviates `0-_\by'. |
b585a9fa EZ |
79 | *\b* All of the words but the zeroth. This is a synonym for `_\b1_\b-_\b$'. |
80 | It is not an error to use *\b* if there is just one word in the | |
81 | event; the empty string is returned in that case. | |
84041b4c EZ |
82 | x\bx*\b* Abbreviates _\bx_\b-_\b$. |
83 | x\bx-\b- Abbreviates _\bx_\b-_\b$ like x\bx*\b*, but omits the last word. | |
84 | ||
b585a9fa EZ |
85 | If a word designator is supplied without an event specification, the |
86 | previous command is used as the event. | |
84041b4c EZ |
87 | |
88 | M\bMo\bod\bdi\bif\bfi\bie\ber\brs\bs | |
b585a9fa EZ |
89 | After the optional word designator, there may appear a sequence of one |
90 | or more of the following modifiers, each preceded by a `:'. | |
91 | ||
92 | h\bh Remove a trailing file name component, leaving only the head. | |
93 | t\bt Remove all leading file name components, leaving the tail. | |
94 | r\br Remove a trailing suffix of the form _\b._\bx_\bx_\bx, leaving the basename. | |
84041b4c EZ |
95 | e\be Remove all but the trailing suffix. |
96 | p\bp Print the new command but do not execute it. | |
b585a9fa EZ |
97 | q\bq Quote the substituted words, escaping further substitutions. |
98 | x\bx Quote the substituted words as with q\bq, but break into words at | |
99 | b\bbl\bla\ban\bnk\bks\bs and newlines. | |
84041b4c | 100 | s\bs/\b/_\bo_\bl_\bd/\b/_\bn_\be_\bw/\b/ |
b585a9fa EZ |
101 | Substitute _\bn_\be_\bw for the first occurrence of _\bo_\bl_\bd in the event |
102 | line. Any delimiter can be used in place of /. The final | |
103 | delimiter is optional if it is the last character of the event | |
104 | line. The delimiter may be quoted in _\bo_\bl_\bd and _\bn_\be_\bw with a single | |
105 | backslash. If & appears in _\bn_\be_\bw, it is replaced by _\bo_\bl_\bd. A sin- | |
106 | gle backslash will quote the &. If _\bo_\bl_\bd is null, it is set to | |
107 | the last _\bo_\bl_\bd substituted, or, if no previous history substitu- | |
108 | tions took place, the last _\bs_\bt_\br_\bi_\bn_\bg in a !\b!?\b?_\bs_\bt_\br_\bi_\bn_\bg[\b[?\b?]\b] search. | |
84041b4c | 109 | &\b& Repeat the previous substitution. |
b585a9fa EZ |
110 | g\bg Cause changes to be applied over the entire event line. This is |
111 | used in conjunction with `:\b:s\bs' (e.g., `:\b:g\bgs\bs/\b/_\bo_\bl_\bd/\b/_\bn_\be_\bw/\b/') or `:\b:&\b&'. | |
112 | If used with `:\b:s\bs', any delimiter can be used in place of /, and | |
113 | the final delimiter is optional if it is the last character of | |
114 | the event line. An a\ba may be used as a synonym for g\bg. | |
115 | G\bG Apply the following `s\bs' modifier once to each word in the event | |
116 | line. | |
84041b4c EZ |
117 | |
118 | P\bPR\bRO\bOG\bGR\bRA\bAM\bMM\bMI\bIN\bNG\bG W\bWI\bIT\bTH\bH H\bHI\bIS\bST\bTO\bOR\bRY\bY F\bFU\bUN\bNC\bCT\bTI\bIO\bON\bNS\bS | |
b585a9fa EZ |
119 | This section describes how to use the History library in other pro- |
120 | grams. | |
84041b4c EZ |
121 | |
122 | I\bIn\bnt\btr\bro\bod\bdu\buc\bct\bti\bio\bon\bn t\bto\bo H\bHi\bis\bst\bto\bor\bry\by | |
b585a9fa EZ |
123 | The programmer using the History library has available functions for |
124 | remembering lines on a history list, associating arbitrary data with a | |
125 | line, removing lines from the list, searching through the list for a | |
126 | line containing an arbitrary text string, and referencing any line in | |
127 | the list directly. In addition, a history _\be_\bx_\bp_\ba_\bn_\bs_\bi_\bo_\bn function is avail- | |
128 | able which provides for a consistent user interface across different | |
129 | programs. | |
130 | ||
131 | The user using programs written with the History library has the bene- | |
132 | fit of a consistent user interface with a set of well-known commands | |
133 | for manipulating the text of previous lines and using that text in new | |
134 | commands. The basic history manipulation commands are identical to the | |
135 | history substitution provided by b\bba\bas\bsh\bh. | |
136 | ||
137 | If the programmer desires, he can use the Readline library, which | |
138 | includes some history manipulation by default, and has the added advan- | |
139 | tage of command line editing. | |
140 | ||
141 | Before declaring any functions using any functionality the History | |
142 | library provides in other code, an application writer should include | |
143 | the file _\b<_\br_\be_\ba_\bd_\bl_\bi_\bn_\be_\b/_\bh_\bi_\bs_\bt_\bo_\br_\by_\b._\bh_\b> in any file that uses the History | |
144 | library's features. It supplies extern declarations for all of the | |
145 | library's public functions and variables, and declares all of the pub- | |
146 | lic data structures. | |
84041b4c EZ |
147 | |
148 | ||
149 | H\bHi\bis\bst\bto\bor\bry\by S\bSt\bto\bor\bra\bag\bge\be | |
b585a9fa EZ |
150 | The history list is an array of history entries. A history entry is |
151 | declared as follows: | |
84041b4c EZ |
152 | |
153 | _\bt_\by_\bp_\be_\bd_\be_\bf _\bv_\bo_\bi_\bd _\b* h\bhi\bis\bst\btd\bda\bat\bta\ba_\b_t\bt;\b; | |
154 | ||
155 | typedef struct _hist_entry { | |
156 | char *line; | |
b585a9fa | 157 | char *timestamp; |
84041b4c EZ |
158 | histdata_t data; |
159 | } HIST_ENTRY; | |
160 | ||
161 | The history list itself might therefore be declared as | |
162 | ||
163 | _\bH_\bI_\bS_\bT_\b__\bE_\bN_\bT_\bR_\bY _\b*_\b* t\bth\bhe\be_\b_h\bhi\bis\bst\bto\bor\bry\by_\b_l\bli\bis\bst\bt;\b; | |
164 | ||
b585a9fa EZ |
165 | The state of the History library is encapsulated into a single struc- |
166 | ture: | |
84041b4c EZ |
167 | |
168 | /* | |
169 | * A structure used to pass around the current state of the history. | |
170 | */ | |
171 | typedef struct _hist_state { | |
172 | HIST_ENTRY **entries; /* Pointer to the entries themselves. */ | |
173 | int offset; /* The location pointer within this array. */ | |
174 | int length; /* Number of elements within this array. */ | |
175 | int size; /* Number of slots allocated to this array. */ | |
176 | int flags; | |
177 | } HISTORY_STATE; | |
178 | ||
b585a9fa | 179 | If the flags member includes H\bHS\bS_\b_S\bST\bTI\bIF\bFL\bLE\bED\bD, the history has been stifled. |
84041b4c EZ |
180 | |
181 | H\bHi\bis\bst\bto\bor\bry\by F\bFu\bun\bnc\bct\bti\bio\bon\bns\bs | |
b585a9fa EZ |
182 | This section describes the calling sequence for the various functions |
183 | exported by the GNU History library. | |
84041b4c EZ |
184 | |
185 | I\bIn\bni\bit\bti\bia\bal\bli\biz\bzi\bin\bng\bg H\bHi\bis\bst\bto\bor\bry\by a\ban\bnd\bd S\bSt\bta\bat\bte\be M\bMa\ban\bna\bag\bge\bem\bme\ben\bnt\bt | |
b585a9fa EZ |
186 | This section describes functions used to initialize and manage the |
187 | state of the History library when you want to use the history functions | |
188 | in your program. | |
84041b4c EZ |
189 | |
190 | _\bv_\bo_\bi_\bd u\bus\bsi\bin\bng\bg_\b_h\bhi\bis\bst\bto\bor\bry\by (_\bv_\bo_\bi_\bd) | |
b585a9fa EZ |
191 | Begin a session in which the history functions might be used. This |
192 | initializes the interactive variables. | |
84041b4c EZ |
193 | |
194 | _\bH_\bI_\bS_\bT_\bO_\bR_\bY_\b__\bS_\bT_\bA_\bT_\bE _\b* h\bhi\bis\bst\bto\bor\bry\by_\b_g\bge\bet\bt_\b_h\bhi\bis\bst\bto\bor\bry\by_\b_s\bst\bta\bat\bte\be (_\bv_\bo_\bi_\bd) | |
b585a9fa | 195 | Return a structure describing the current state of the input history. |
84041b4c EZ |
196 | |
197 | _\bv_\bo_\bi_\bd h\bhi\bis\bst\bto\bor\bry\by_\b_s\bse\bet\bt_\b_h\bhi\bis\bst\bto\bor\bry\by_\b_s\bst\bta\bat\bte\be (_\bH_\bI_\bS_\bT_\bO_\bR_\bY_\b__\bS_\bT_\bA_\bT_\bE _\b*_\bs_\bt_\ba_\bt_\be) | |
84041b4c EZ |
198 | Set the state of the history list according to _\bs_\bt_\ba_\bt_\be. |
199 | ||
200 | ||
201 | H\bHi\bis\bst\bto\bor\bry\by L\bLi\bis\bst\bt M\bMa\ban\bna\bag\bge\bem\bme\ben\bnt\bt | |
b585a9fa EZ |
202 | These functions manage individual entries on the history list, or set |
203 | parameters managing the list itself. | |
84041b4c EZ |
204 | |
205 | _\bv_\bo_\bi_\bd a\bad\bdd\bd_\b_h\bhi\bis\bst\bto\bor\bry\by (_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bs_\bt_\br_\bi_\bn_\bg) | |
b585a9fa EZ |
206 | Place _\bs_\bt_\br_\bi_\bn_\bg at the end of the history list. The associated data field |
207 | (if any) is set to N\bNU\bUL\bLL\bL. | |
208 | ||
209 | _\bv_\bo_\bi_\bd a\bad\bdd\bd_\b_h\bhi\bis\bst\bto\bor\bry\by_\b_t\bti\bim\bme\be (_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bs_\bt_\br_\bi_\bn_\bg) | |
210 | Change the time stamp associated with the most recent history entry to | |
211 | _\bs_\bt_\br_\bi_\bn_\bg. | |
84041b4c EZ |
212 | |
213 | _\bH_\bI_\bS_\bT_\b__\bE_\bN_\bT_\bR_\bY _\b* r\bre\bem\bmo\bov\bve\be_\b_h\bhi\bis\bst\bto\bor\bry\by (_\bi_\bn_\bt _\bw_\bh_\bi_\bc_\bh) | |
b585a9fa EZ |
214 | Remove history entry at offset _\bw_\bh_\bi_\bc_\bh from the history. The removed |
215 | element is returned so you can free the line, data, and containing | |
216 | structure. | |
217 | ||
218 | _\bh_\bi_\bs_\bt_\bd_\ba_\bt_\ba_\b__\bt f\bfr\bre\bee\be_\b_h\bhi\bis\bst\bto\bor\bry\by_\b_e\ben\bnt\btr\bry\by (_\bH_\bI_\bS_\bT_\b__\bE_\bN_\bT_\bR_\bY _\b*_\bh_\bi_\bs_\bt_\be_\bn_\bt) | |
219 | Free the history entry _\bh_\bi_\bs_\bt_\be_\bn_\bt and any history library private data | |
220 | associated with it. Returns the application-specific data so the | |
221 | caller can dispose of it. | |
222 | ||
223 | _\bH_\bI_\bS_\bT_\b__\bE_\bN_\bT_\bR_\bY _\b* r\bre\bep\bpl\bla\bac\bce\be_\b_h\bhi\bis\bst\bto\bor\bry\by_\b_e\ben\bnt\btr\bry\by (_\bi_\bn_\bt _\bw_\bh_\bi_\bc_\bh_\b, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bl_\bi_\bn_\be_\b, _\bh_\bi_\bs_\bt_\b- | |
224 | _\bd_\ba_\bt_\ba_\b__\bt _\bd_\ba_\bt_\ba) | |
225 | Make the history entry at offset _\bw_\bh_\bi_\bc_\bh have _\bl_\bi_\bn_\be and _\bd_\ba_\bt_\ba. This | |
226 | returns the old entry so the caller can dispose of any application-spe- | |
227 | cific data. In the case of an invalid _\bw_\bh_\bi_\bc_\bh, a N\bNU\bUL\bLL\bL pointer is | |
84041b4c EZ |
228 | returned. |
229 | ||
230 | _\bv_\bo_\bi_\bd c\bcl\ble\bea\bar\br_\b_h\bhi\bis\bst\bto\bor\bry\by (_\bv_\bo_\bi_\bd) | |
231 | Clear the history list by deleting all the entries. | |
232 | ||
233 | _\bv_\bo_\bi_\bd s\bst\bti\bif\bfl\ble\be_\b_h\bhi\bis\bst\bto\bor\bry\by (_\bi_\bn_\bt _\bm_\ba_\bx) | |
b585a9fa | 234 | Stifle the history list, remembering only the last _\bm_\ba_\bx entries. |
84041b4c EZ |
235 | |
236 | _\bi_\bn_\bt u\bun\bns\bst\bti\bif\bfl\ble\be_\b_h\bhi\bis\bst\bto\bor\bry\by (_\bv_\bo_\bi_\bd) | |
b585a9fa EZ |
237 | Stop stifling the history. This returns the previously-set maximum |
238 | number of history entries (as set by s\bst\bti\bif\bfl\ble\be_\b_h\bhi\bis\bst\bto\bor\bry\by(\b()\b)). history was | |
239 | stifled. The value is positive if the history was stifled, negative if | |
240 | it wasn't. | |
84041b4c EZ |
241 | |
242 | _\bi_\bn_\bt h\bhi\bis\bst\bto\bor\bry\by_\b_i\bis\bs_\b_s\bst\bti\bif\bfl\ble\bed\bd (_\bv_\bo_\bi_\bd) | |
b585a9fa | 243 | Returns non-zero if the history is stifled, zero if it is not. |
84041b4c EZ |
244 | |
245 | ||
246 | I\bIn\bnf\bfo\bor\brm\bma\bat\bti\bio\bon\bn A\bAb\bbo\bou\but\bt t\bth\bhe\be H\bHi\bis\bst\bto\bor\bry\by L\bLi\bis\bst\bt | |
b585a9fa EZ |
247 | These functions return information about the entire history list or |
248 | individual list entries. | |
84041b4c EZ |
249 | |
250 | _\bH_\bI_\bS_\bT_\b__\bE_\bN_\bT_\bR_\bY _\b*_\b* h\bhi\bis\bst\bto\bor\bry\by_\b_l\bli\bis\bst\bt (_\bv_\bo_\bi_\bd) | |
b585a9fa EZ |
251 | Return a N\bNU\bUL\bLL\bL terminated array of _\bH_\bI_\bS_\bT_\b__\bE_\bN_\bT_\bR_\bY _\b* which is the current |
252 | input history. Element 0 of this list is the beginning of time. If | |
253 | there is no history, return N\bNU\bUL\bLL\bL. | |
84041b4c EZ |
254 | |
255 | _\bi_\bn_\bt w\bwh\bhe\ber\bre\be_\b_h\bhi\bis\bst\bto\bor\bry\by (_\bv_\bo_\bi_\bd) | |
256 | Returns the offset of the current history element. | |
257 | ||
258 | _\bH_\bI_\bS_\bT_\b__\bE_\bN_\bT_\bR_\bY _\b* c\bcu\bur\brr\bre\ben\bnt\bt_\b_h\bhi\bis\bst\bto\bor\bry\by (_\bv_\bo_\bi_\bd) | |
b585a9fa EZ |
259 | Return the history entry at the current position, as determined by |
260 | w\bwh\bhe\ber\bre\be_\b_h\bhi\bis\bst\bto\bor\bry\by(\b()\b). If there is no entry there, return a N\bNU\bUL\bLL\bL pointer. | |
84041b4c EZ |
261 | |
262 | _\bH_\bI_\bS_\bT_\b__\bE_\bN_\bT_\bR_\bY _\b* h\bhi\bis\bst\bto\bor\bry\by_\b_g\bge\bet\bt (_\bi_\bn_\bt _\bo_\bf_\bf_\bs_\be_\bt) | |
b585a9fa EZ |
263 | Return the history entry at position _\bo_\bf_\bf_\bs_\be_\bt, starting from h\bhi\bis\bs-\b- |
264 | t\bto\bor\bry\by_\b_b\bba\bas\bse\be. If there is no entry there, or if _\bo_\bf_\bf_\bs_\be_\bt is greater than | |
265 | the history length, return a N\bNU\bUL\bLL\bL pointer. | |
266 | ||
267 | _\bt_\bi_\bm_\be_\b__\bt h\bhi\bis\bst\bto\bor\bry\by_\b_g\bge\bet\bt_\b_t\bti\bim\bme\be (_\bH_\bI_\bS_\bT_\b__\bE_\bN_\bT_\bR_\bY _\b*) | |
268 | Return the time stamp associated with the history entry passed as the | |
269 | argument. | |
84041b4c EZ |
270 | |
271 | _\bi_\bn_\bt h\bhi\bis\bst\bto\bor\bry\by_\b_t\bto\bot\bta\bal\bl_\b_b\bby\byt\bte\bes\bs (_\bv_\bo_\bi_\bd) | |
b585a9fa EZ |
272 | Return the number of bytes that the primary history entries are using. |
273 | This function returns the sum of the lengths of all the lines in the | |
274 | history. | |
84041b4c EZ |
275 | |
276 | ||
277 | M\bMo\bov\bvi\bin\bng\bg A\bAr\bro\bou\bun\bnd\bd t\bth\bhe\be H\bHi\bis\bst\bto\bor\bry\by L\bLi\bis\bst\bt | |
b585a9fa EZ |
278 | These functions allow the current index into the history list to be set |
279 | or changed. | |
84041b4c EZ |
280 | |
281 | _\bi_\bn_\bt h\bhi\bis\bst\bto\bor\bry\by_\b_s\bse\bet\bt_\b_p\bpo\bos\bs (_\bi_\bn_\bt _\bp_\bo_\bs) | |
b585a9fa EZ |
282 | Set the current history offset to _\bp_\bo_\bs, an absolute index into the list. |
283 | Returns 1 on success, 0 if _\bp_\bo_\bs is less than zero or greater than the | |
284 | number of history entries. | |
84041b4c EZ |
285 | |
286 | _\bH_\bI_\bS_\bT_\b__\bE_\bN_\bT_\bR_\bY _\b* p\bpr\bre\bev\bvi\bio\bou\bus\bs_\b_h\bhi\bis\bst\bto\bor\bry\by (_\bv_\bo_\bi_\bd) | |
b585a9fa EZ |
287 | Back up the current history offset to the previous history entry, and |
288 | return a pointer to that entry. If there is no previous entry, return | |
289 | a N\bNU\bUL\bLL\bL pointer. | |
84041b4c EZ |
290 | |
291 | _\bH_\bI_\bS_\bT_\b__\bE_\bN_\bT_\bR_\bY _\b* n\bne\bex\bxt\bt_\b_h\bhi\bis\bst\bto\bor\bry\by (_\bv_\bo_\bi_\bd) | |
b585a9fa EZ |
292 | Move the current history offset forward to the next history entry, and |
293 | return the a pointer to that entry. If there is no next entry, return | |
294 | a N\bNU\bUL\bLL\bL pointer. | |
84041b4c EZ |
295 | |
296 | ||
297 | S\bSe\bea\bar\brc\bch\bhi\bin\bng\bg t\bth\bhe\be H\bHi\bis\bst\bto\bor\bry\by L\bLi\bis\bst\bt | |
b585a9fa EZ |
298 | These functions allow searching of the history list for entries con- |
299 | taining a specific string. Searching may be performed both forward and | |
300 | backward from the current history position. The search may be | |
301 | _\ba_\bn_\bc_\bh_\bo_\br_\be_\bd, meaning that the string must match at the beginning of the | |
302 | history entry. | |
84041b4c EZ |
303 | |
304 | _\bi_\bn_\bt h\bhi\bis\bst\bto\bor\bry\by_\b_s\bse\bea\bar\brc\bch\bh (_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bs_\bt_\br_\bi_\bn_\bg_\b, _\bi_\bn_\bt _\bd_\bi_\br_\be_\bc_\bt_\bi_\bo_\bn) | |
b585a9fa EZ |
305 | Search the history for _\bs_\bt_\br_\bi_\bn_\bg, starting at the current history offset. |
306 | If _\bd_\bi_\br_\be_\bc_\bt_\bi_\bo_\bn is less than 0, then the search is through previous | |
307 | entries, otherwise through subsequent entries. If _\bs_\bt_\br_\bi_\bn_\bg is found, | |
308 | then the current history index is set to that history entry, and the | |
309 | value returned is the offset in the line of the entry where _\bs_\bt_\br_\bi_\bn_\bg was | |
310 | found. Otherwise, nothing is changed, and a -1 is returned. | |
311 | ||
312 | _\bi_\bn_\bt h\bhi\bis\bst\bto\bor\bry\by_\b_s\bse\bea\bar\brc\bch\bh_\b_p\bpr\bre\bef\bfi\bix\bx (_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bs_\bt_\br_\bi_\bn_\bg_\b, _\bi_\bn_\bt _\bd_\bi_\br_\be_\bc_\bt_\bi_\bo_\bn) | |
313 | Search the history for _\bs_\bt_\br_\bi_\bn_\bg, starting at the current history offset. | |
314 | The search is anchored: matching lines must begin with _\bs_\bt_\br_\bi_\bn_\bg. If | |
315 | _\bd_\bi_\br_\be_\bc_\bt_\bi_\bo_\bn is less than 0, then the search is through previous entries, | |
316 | otherwise through subsequent entries. If _\bs_\bt_\br_\bi_\bn_\bg is found, then the | |
317 | current history index is set to that entry, and the return value is 0. | |
318 | Otherwise, nothing is changed, and a -1 is returned. | |
319 | ||
320 | _\bi_\bn_\bt h\bhi\bis\bst\bto\bor\bry\by_\b_s\bse\bea\bar\brc\bch\bh_\b_p\bpo\bos\bs (_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bs_\bt_\br_\bi_\bn_\bg_\b, _\bi_\bn_\bt _\bd_\bi_\br_\be_\bc_\bt_\bi_\bo_\bn_\b, _\bi_\bn_\bt _\bp_\bo_\bs) | |
321 | Search for _\bs_\bt_\br_\bi_\bn_\bg in the history list, starting at _\bp_\bo_\bs, an absolute | |
322 | index into the list. If _\bd_\bi_\br_\be_\bc_\bt_\bi_\bo_\bn is negative, the search proceeds | |
323 | backward from _\bp_\bo_\bs, otherwise forward. Returns the absolute index of | |
324 | the history element where _\bs_\bt_\br_\bi_\bn_\bg was found, or -1 otherwise. | |
84041b4c EZ |
325 | |
326 | ||
327 | M\bMa\ban\bna\bag\bgi\bin\bng\bg t\bth\bhe\be H\bHi\bis\bst\bto\bor\bry\by F\bFi\bil\ble\be | |
b585a9fa EZ |
328 | The History library can read the history from and write it to a file. |
329 | This section documents the functions for managing a history file. | |
84041b4c EZ |
330 | |
331 | _\bi_\bn_\bt r\bre\bea\bad\bd_\b_h\bhi\bis\bst\bto\bor\bry\by (_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\bi_\bl_\be_\bn_\ba_\bm_\be) | |
b585a9fa EZ |
332 | Add the contents of _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be to the history list, a line at a time. If |
333 | _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be is N\bNU\bUL\bLL\bL, then read from _\b~_\b/_\b._\bh_\bi_\bs_\bt_\bo_\br_\by. Returns 0 if successful, | |
334 | or e\ber\brr\brn\bno\bo if not. | |
335 | ||
336 | _\bi_\bn_\bt r\bre\bea\bad\bd_\b_h\bhi\bis\bst\bto\bor\bry\by_\b_r\bra\ban\bng\bge\be (_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\bi_\bl_\be_\bn_\ba_\bm_\be_\b, _\bi_\bn_\bt _\bf_\br_\bo_\bm_\b, _\bi_\bn_\bt _\bt_\bo) | |
337 | Read a range of lines from _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be, adding them to the history list. | |
338 | Start reading at line _\bf_\br_\bo_\bm and end at _\bt_\bo. If _\bf_\br_\bo_\bm is zero, start at | |
339 | the beginning. If _\bt_\bo is less than _\bf_\br_\bo_\bm, then read until the end of the | |
340 | file. If _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be is N\bNU\bUL\bLL\bL, then read from _\b~_\b/_\b._\bh_\bi_\bs_\bt_\bo_\br_\by. Returns 0 if | |
84041b4c EZ |
341 | successful, or e\ber\brr\brn\bno\bo if not. |
342 | ||
343 | _\bi_\bn_\bt w\bwr\bri\bit\bte\be_\b_h\bhi\bis\bst\bto\bor\bry\by (_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\bi_\bl_\be_\bn_\ba_\bm_\be) | |
b585a9fa EZ |
344 | Write the current history to _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be, overwriting _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be if neces- |
345 | sary. If _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be is N\bNU\bUL\bLL\bL, then write the history list to _\b~_\b/_\b._\bh_\bi_\bs_\bt_\bo_\br_\by. | |
346 | Returns 0 on success, or e\ber\brr\brn\bno\bo on a read or write error. | |
84041b4c EZ |
347 | |
348 | ||
349 | _\bi_\bn_\bt a\bap\bpp\bpe\ben\bnd\bd_\b_h\bhi\bis\bst\bto\bor\bry\by (_\bi_\bn_\bt _\bn_\be_\bl_\be_\bm_\be_\bn_\bt_\bs_\b, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\bi_\bl_\be_\bn_\ba_\bm_\be) | |
b585a9fa EZ |
350 | Append the last _\bn_\be_\bl_\be_\bm_\be_\bn_\bt_\bs of the history list to _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be. If _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be |
351 | is N\bNU\bUL\bLL\bL, then append to _\b~_\b/_\b._\bh_\bi_\bs_\bt_\bo_\br_\by. Returns 0 on success, or e\ber\brr\brn\bno\bo on | |
352 | a read or write error. | |
84041b4c | 353 | |
b585a9fa EZ |
354 | _\bi_\bn_\bt h\bhi\bis\bst\bto\bor\bry\by_\b_t\btr\bru\bun\bnc\bca\bat\bte\be_\b_f\bfi\bil\ble\be (_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\bi_\bl_\be_\bn_\ba_\bm_\be_\b, _\bi_\bn_\bt _\bn_\bl_\bi_\bn_\be_\bs) |
355 | Truncate the history file _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be, leaving only the last _\bn_\bl_\bi_\bn_\be_\bs lines. | |
356 | If _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be is N\bNU\bUL\bLL\bL, then _\b~_\b/_\b._\bh_\bi_\bs_\bt_\bo_\br_\by is truncated. Returns 0 on suc- | |
357 | cess, or e\ber\brr\brn\bno\bo on failure. | |
84041b4c EZ |
358 | |
359 | ||
360 | H\bHi\bis\bst\bto\bor\bry\by E\bEx\bxp\bpa\ban\bns\bsi\bio\bon\bn | |
361 | These functions implement history expansion. | |
362 | ||
363 | _\bi_\bn_\bt h\bhi\bis\bst\bto\bor\bry\by_\b_e\bex\bxp\bpa\ban\bnd\bd (_\bc_\bh_\ba_\br _\b*_\bs_\bt_\br_\bi_\bn_\bg_\b, _\bc_\bh_\ba_\br _\b*_\b*_\bo_\bu_\bt_\bp_\bu_\bt) | |
b585a9fa EZ |
364 | Expand _\bs_\bt_\br_\bi_\bn_\bg, placing the result into _\bo_\bu_\bt_\bp_\bu_\bt, a pointer to a string. |
365 | Returns: | |
366 | 0 If no expansions took place (or, if the only change in | |
367 | the text was the removal of escape characters preceding | |
368 | the history expansion character); | |
84041b4c EZ |
369 | 1 if expansions did take place; |
370 | -1 if there was an error in expansion; | |
b585a9fa EZ |
371 | 2 if the returned line should be displayed, but not exe- |
372 | cuted, as with the :\b:p\bp modifier. | |
373 | If an error ocurred in expansion, then _\bo_\bu_\bt_\bp_\bu_\bt contains a descriptive | |
374 | error message. | |
375 | ||
376 | _\bc_\bh_\ba_\br _\b* g\bge\bet\bt_\b_h\bhi\bis\bst\bto\bor\bry\by_\b_e\bev\bve\ben\bnt\bt (_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bs_\bt_\br_\bi_\bn_\bg_\b, _\bi_\bn_\bt _\b*_\bc_\bi_\bn_\bd_\be_\bx_\b, _\bi_\bn_\bt _\bq_\bc_\bh_\ba_\br) | |
377 | Returns the text of the history event beginning at _\bs_\bt_\br_\bi_\bn_\bg + _\b*_\bc_\bi_\bn_\bd_\be_\bx. | |
378 | _\b*_\bc_\bi_\bn_\bd_\be_\bx is modified to point to after the event specifier. At function | |
379 | entry, _\bc_\bi_\bn_\bd_\be_\bx points to the index into _\bs_\bt_\br_\bi_\bn_\bg where the history event | |
380 | specification begins. _\bq_\bc_\bh_\ba_\br is a character that is allowed to end the | |
381 | event specification in addition to the ``normal'' terminating charac- | |
382 | ters. | |
84041b4c EZ |
383 | |
384 | _\bc_\bh_\ba_\br _\b*_\b* h\bhi\bis\bst\bto\bor\bry\by_\b_t\bto\bok\bke\ben\bni\biz\bze\be (_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bs_\bt_\br_\bi_\bn_\bg) | |
b585a9fa EZ |
385 | Return an array of tokens parsed out of _\bs_\bt_\br_\bi_\bn_\bg, much as the shell |
386 | might. The tokens are split on the characters in the h\bhi\bis\bs-\b- | |
387 | t\bto\bor\bry\by_\b_w\bwo\bor\brd\bd_\b_d\bde\bel\bli\bim\bmi\bit\bte\ber\brs\bs variable, and shell quoting conventions are | |
388 | obeyed. | |
84041b4c | 389 | |
b585a9fa EZ |
390 | _\bc_\bh_\ba_\br _\b* h\bhi\bis\bst\bto\bor\bry\by_\b_a\bar\brg\bg_\b_e\bex\bxt\btr\bra\bac\bct\bt (_\bi_\bn_\bt _\bf_\bi_\br_\bs_\bt_\b, _\bi_\bn_\bt _\bl_\ba_\bs_\bt_\b, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bs_\bt_\br_\bi_\bn_\bg) |
391 | Extract a string segment consisting of the _\bf_\bi_\br_\bs_\bt through _\bl_\ba_\bs_\bt arguments | |
392 | present in _\bs_\bt_\br_\bi_\bn_\bg. Arguments are split using h\bhi\bis\bst\bto\bor\bry\by_\b_t\bto\bok\bke\ben\bni\biz\bze\be(\b()\b). | |
84041b4c EZ |
393 | |
394 | ||
395 | H\bHi\bis\bst\bto\bor\bry\by V\bVa\bar\bri\bia\bab\bbl\ble\bes\bs | |
b585a9fa EZ |
396 | This section describes the externally-visible variables exported by the |
397 | GNU History Library. | |
84041b4c EZ |
398 | |
399 | _\bi_\bn_\bt h\bhi\bis\bst\bto\bor\bry\by_\b_b\bba\bas\bse\be | |
400 | The logical offset of the first entry in the history list. | |
401 | ||
402 | _\bi_\bn_\bt h\bhi\bis\bst\bto\bor\bry\by_\b_l\ble\ben\bng\bgt\bth\bh | |
b585a9fa | 403 | The number of entries currently stored in the history list. |
84041b4c EZ |
404 | |
405 | _\bi_\bn_\bt h\bhi\bis\bst\bto\bor\bry\by_\b_m\bma\bax\bx_\b_e\ben\bnt\btr\bri\bie\bes\bs | |
b585a9fa EZ |
406 | The maximum number of history entries. This must be changed using s\bst\bti\bi-\b- |
407 | f\bfl\ble\be_\b_h\bhi\bis\bst\bto\bor\bry\by(\b()\b). | |
408 | ||
409 | _\bi_\bn_\bt h\bhi\bis\bst\bto\bor\bry\by_\b_w\bwr\bri\bit\bte\be_\b_t\bti\bim\bme\bes\bst\bta\bam\bmp\bps\bs | |
410 | If non-zero, timestamps are written to the history file, so they can be | |
411 | preserved between sessions. The default value is 0, meaning that | |
412 | timestamps are not saved. | |
84041b4c EZ |
413 | |
414 | _\bc_\bh_\ba_\br h\bhi\bis\bst\bto\bor\bry\by_\b_e\bex\bxp\bpa\ban\bns\bsi\bio\bon\bn_\b_c\bch\bha\bar\br | |
b585a9fa EZ |
415 | The character that introduces a history event. The default is !\b!. Set- |
416 | ting this to 0 inhibits history expansion. | |
84041b4c EZ |
417 | |
418 | _\bc_\bh_\ba_\br h\bhi\bis\bst\bto\bor\bry\by_\b_s\bsu\bub\bbs\bst\bt_\b_c\bch\bha\bar\br | |
b585a9fa EZ |
419 | The character that invokes word substitution if found at the start of a |
420 | line. The default is ^\b^. | |
84041b4c EZ |
421 | |
422 | _\bc_\bh_\ba_\br h\bhi\bis\bst\bto\bor\bry\by_\b_c\bco\bom\bmm\bme\ben\bnt\bt_\b_c\bch\bha\bar\br | |
b585a9fa EZ |
423 | During tokenization, if this character is seen as the first character |
424 | of a word, then it and all subsequent characters up to a newline are | |
425 | ignored, suppressing history expansion for the remainder of the line. | |
426 | This is disabled by default. | |
84041b4c EZ |
427 | |
428 | _\bc_\bh_\ba_\br _\b* h\bhi\bis\bst\bto\bor\bry\by_\b_w\bwo\bor\brd\bd_\b_d\bde\bel\bli\bim\bmi\bit\bte\ber\brs\bs | |
b585a9fa EZ |
429 | The characters that separate tokens for h\bhi\bis\bst\bto\bor\bry\by_\b_t\bto\bok\bke\ben\bni\biz\bze\be(\b()\b). The |
430 | default value is "\b" \\b\t\bt\\b\n\bn(\b()\b)<\b<>\b>;\b;&\b&|\b|"\b". | |
84041b4c EZ |
431 | |
432 | _\bc_\bh_\ba_\br _\b* h\bhi\bis\bst\bto\bor\bry\by_\b_n\bno\bo_\b_e\bex\bxp\bpa\ban\bnd\bd_\b_c\bch\bha\bar\brs\bs | |
b585a9fa EZ |
433 | The list of characters which inhibit history expansion if found immedi- |
434 | ately following h\bhi\bis\bst\bto\bor\bry\by_\b_e\bex\bxp\bpa\ban\bns\bsi\bio\bon\bn_\b_c\bch\bha\bar\br. The default is space, tab, | |
435 | newline, \\b\r\br, and =\b=. | |
84041b4c EZ |
436 | |
437 | _\bc_\bh_\ba_\br _\b* h\bhi\bis\bst\bto\bor\bry\by_\b_s\bse\bea\bar\brc\bch\bh_\b_d\bde\bel\bli\bim\bmi\bit\bte\ber\br_\b_c\bch\bha\bar\brs\bs | |
b585a9fa EZ |
438 | The list of additional characters which can delimit a history search |
439 | string, in addition to space, tab, _\b: and _\b? in the case of a substring | |
440 | search. The default is empty. | |
84041b4c EZ |
441 | |
442 | _\bi_\bn_\bt h\bhi\bis\bst\bto\bor\bry\by_\b_q\bqu\buo\bot\bte\bes\bs_\b_i\bin\bnh\bhi\bib\bbi\bit\bt_\b_e\bex\bxp\bpa\ban\bns\bsi\bio\bon\bn | |
b585a9fa EZ |
443 | If non-zero, single-quoted words are not scanned for the history expan- |
444 | sion character. The default value is 0. | |
84041b4c EZ |
445 | |
446 | _\br_\bl_\b__\bl_\bi_\bn_\be_\bb_\bu_\bf_\b__\bf_\bu_\bn_\bc_\b__\bt _\b* h\bhi\bis\bst\bto\bor\bry\by_\b_i\bin\bnh\bhi\bib\bbi\bit\bt_\b_e\bex\bxp\bpa\ban\bns\bsi\bio\bon\bn_\b_f\bfu\bun\bnc\bct\bti\bio\bon\bn | |
b585a9fa EZ |
447 | This should be set to the address of a function that takes two argu- |
448 | ments: a c\bch\bha\bar\br *\b* (_\bs_\bt_\br_\bi_\bn_\bg) and an i\bin\bnt\bt index into that string (_\bi). It | |
449 | should return a non-zero value if the history expansion starting at | |
450 | _\bs_\bt_\br_\bi_\bn_\bg_\b[_\bi_\b] should not be performed; zero if the expansion should be | |
451 | done. It is intended for use by applications like b\bba\bas\bsh\bh that use the | |
452 | history expansion character for additional purposes. By default, this | |
453 | variable is set to N\bNU\bUL\bLL\bL. | |
84041b4c EZ |
454 | |
455 | F\bFI\bIL\bLE\bES\bS | |
456 | _\b~_\b/_\b._\bh_\bi_\bs_\bt_\bo_\br_\by | |
b585a9fa | 457 | Default filename for reading and writing saved history |
84041b4c EZ |
458 | |
459 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO | |
460 | _\bT_\bh_\be _\bG_\bn_\bu _\bR_\be_\ba_\bd_\bl_\bi_\bn_\be _\bL_\bi_\bb_\br_\ba_\br_\by, Brian Fox and Chet Ramey | |
461 | _\bT_\bh_\be _\bG_\bn_\bu _\bH_\bi_\bs_\bt_\bo_\br_\by _\bL_\bi_\bb_\br_\ba_\br_\by, Brian Fox and Chet Ramey | |
462 | _\bb_\ba_\bs_\bh(1) | |
463 | _\br_\be_\ba_\bd_\bl_\bi_\bn_\be(3) | |
464 | ||
465 | A\bAU\bUT\bTH\bHO\bOR\bRS\bS | |
466 | Brian Fox, Free Software Foundation | |
467 | bfox@gnu.org | |
468 | ||
469 | Chet Ramey, Case Western Reserve University | |
470 | chet@ins.CWRU.Edu | |
471 | ||
472 | B\bBU\bUG\bG R\bRE\bEP\bPO\bOR\bRT\bTS\bS | |
b585a9fa EZ |
473 | If you find a bug in the h\bhi\bis\bst\bto\bor\bry\by library, you should report it. But |
474 | first, you should make sure that it really is a bug, and that it | |
475 | appears in the latest version of the h\bhi\bis\bst\bto\bor\bry\by library that you have. | |
476 | ||
477 | Once you have determined that a bug actually exists, mail a bug report | |
478 | to _\bb_\bu_\bg_\b-_\br_\be_\ba_\bd_\bl_\bi_\bn_\be@_\bg_\bn_\bu_\b._\bo_\br_\bg. If you have a fix, you are welcome to mail | |
479 | that as well! Suggestions and `philosophical' bug reports may be | |
480 | mailed to _\bb_\bu_\bg_\b-_\br_\be_\ba_\bd_\bl_\bi_\bn_\be@_\bg_\bn_\bu_\b._\bo_\br_\bg or posted to the Usenet newsgroup | |
84041b4c EZ |
481 | g\bgn\bnu\bu.\b.b\bba\bas\bsh\bh.\b.b\bbu\bug\bg. |
482 | ||
b585a9fa EZ |
483 | Comments and bug reports concerning this manual page should be directed |
484 | to _\bc_\bh_\be_\bt_\b@_\bi_\bn_\bs_\b._\bC_\bW_\bR_\bU_\b._\bE_\bd_\bu. | |
84041b4c | 485 | |
84041b4c EZ |
486 | |
487 | ||
b585a9fa | 488 | GNU History 5.0 2003 July 31 HISTORY(3) |