Commit | Line | Data |
---|---|---|
9255ee31 EZ |
1 | |
2 | ||
3 | ||
4 | HISTORY(3) HISTORY(3) | |
5 | ||
6 | ||
7 | N\bNA\bAM\bME\bE | |
8 | history - GNU History Library | |
9 | ||
10 | C\bCO\bOP\bPY\bYR\bRI\bIG\bGH\bHT\bT | |
11 | The GNU History Library is Copyright (C) 1989-2002 by the | |
12 | Free Software Foundation, Inc. | |
13 | ||
14 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN | |
15 | Many programs read input from the user a line at a time. | |
16 | The GNU History library is able to keep track of those | |
17 | lines, associate arbitrary data with each line, and uti- | |
18 | lize information from previous lines in composing new | |
19 | ones. | |
20 | ||
21 | ||
22 | H\bHI\bIS\bST\bTO\bOR\bRY\bY E\bEX\bXP\bPA\bAN\bNS\bSI\bIO\bON\bN | |
23 | The history library supports a history expansion feature | |
24 | that is identical to the history expansion in b\bba\bas\bsh\bh.\b. This | |
25 | section describes what syntax features are available. | |
26 | ||
27 | History expansions introduce words from the history list | |
28 | into the input stream, making it easy to repeat commands, | |
29 | insert the arguments to a previous command into the cur- | |
30 | rent input line, or fix errors in previous commands | |
31 | quickly. | |
32 | ||
33 | History expansion is usually performed immediately after a | |
34 | complete line is read. It takes place in two parts. The | |
35 | first is to determine which line from the history list to | |
36 | use during substitution. The second is to select portions | |
37 | of that line for inclusion into the current one. The line | |
38 | selected from the history is the _\be_\bv_\be_\bn_\bt, and the portions | |
39 | of that line that are acted upon are _\bw_\bo_\br_\bd_\bs. Various _\bm_\bo_\bd_\bi_\b- | |
40 | _\bf_\bi_\be_\br_\bs are available to manipulate the selected words. The | |
41 | line is broken into words in the same fashion as b\bba\bas\bsh\bh does | |
42 | when reading input, so that several words that would oth- | |
43 | erwise be separated are considered one word when sur- | |
44 | rounded by quotes (see the description of h\bhi\bis\bst\bto\bor\bry\by_\b_t\bto\bok\bk-\b- | |
45 | e\ben\bni\biz\bze\be(\b()\b) below). History expansions are introduced by the | |
46 | appearance of the history expansion character, which is !\b! | |
47 | by default. Only backslash (\\b\) and single quotes can | |
48 | quote the history expansion character. | |
49 | ||
50 | E\bEv\bve\ben\bnt\bt D\bDe\bes\bsi\big\bgn\bna\bat\bto\bor\brs\bs | |
51 | An event designator is a reference to a command line entry | |
52 | in the history list. | |
53 | ||
54 | !\b! Start a history substitution, except when followed | |
55 | by a b\bbl\bla\ban\bnk\bk, newline, = or (. | |
56 | !\b!_\bn Refer to command line _\bn. | |
57 | !\b!-\b-_\bn Refer to the current command line minus _\bn. | |
58 | !\b!!\b! Refer to the previous command. This is a synonym | |
59 | for `!-1'. | |
60 | ||
61 | ||
62 | ||
63 | ||
64 | GNU History 4.3 2002 January 31 1 | |
65 | ||
66 | ||
67 | ||
68 | ||
69 | ||
70 | HISTORY(3) HISTORY(3) | |
71 | ||
72 | ||
73 | !\b!_\bs_\bt_\br_\bi_\bn_\bg | |
74 | Refer to the most recent command starting with | |
75 | _\bs_\bt_\br_\bi_\bn_\bg. | |
76 | !\b!?\b?_\bs_\bt_\br_\bi_\bn_\bg[\b[?\b?]\b] | |
77 | Refer to the most recent command containing _\bs_\bt_\br_\bi_\bn_\bg. | |
78 | The trailing ?\b? may be omitted if _\bs_\bt_\br_\bi_\bn_\bg is followed | |
79 | immediately by a newline. | |
80 | ^\b^_\bs_\bt_\br_\bi_\bn_\bg_\b1^\b^_\bs_\bt_\br_\bi_\bn_\bg_\b2^\b^ | |
81 | Quick substitution. Repeat the last command, | |
82 | replacing _\bs_\bt_\br_\bi_\bn_\bg_\b1 with _\bs_\bt_\br_\bi_\bn_\bg_\b2. Equivalent to | |
83 | ``!!:s/_\bs_\bt_\br_\bi_\bn_\bg_\b1/_\bs_\bt_\br_\bi_\bn_\bg_\b2/'' (see M\bMo\bod\bdi\bif\bfi\bie\ber\brs\bs below). | |
84 | !\b!#\b# The entire command line typed so far. | |
85 | ||
86 | W\bWo\bor\brd\bd D\bDe\bes\bsi\big\bgn\bna\bat\bto\bor\brs\bs | |
87 | Word designators are used to select desired words from the | |
88 | event. A :\b: separates the event specification from the | |
89 | word designator. It may be omitted if the word designator | |
90 | begins with a ^\b^, $\b$, *\b*, -\b-, or %\b%. Words are numbered from | |
91 | the beginning of the line, with the first word being | |
92 | denoted by 0 (zero). Words are inserted into the current | |
93 | line separated by single spaces. | |
94 | ||
95 | 0\b0 (\b(z\bze\ber\bro\bo)\b) | |
96 | The zeroth word. For the shell, this is the com- | |
97 | mand word. | |
98 | _\bn The _\bnth word. | |
99 | ^\b^ The first argument. That is, word 1. | |
100 | $\b$ The last argument. | |
101 | %\b% The word matched by the most recent `?_\bs_\bt_\br_\bi_\bn_\bg?' | |
102 | search. | |
103 | _\bx-\b-_\by A range of words; `-_\by' abbreviates `0-_\by'. | |
104 | *\b* All of the words but the zeroth. This is a synonym | |
105 | for `_\b1_\b-_\b$'. It is not an error to use *\b* if there is | |
106 | just one word in the event; the empty string is | |
107 | returned in that case. | |
108 | x\bx*\b* Abbreviates _\bx_\b-_\b$. | |
109 | x\bx-\b- Abbreviates _\bx_\b-_\b$ like x\bx*\b*, but omits the last word. | |
110 | ||
111 | If a word designator is supplied without an event specifi- | |
112 | cation, the previous command is used as the event. | |
113 | ||
114 | M\bMo\bod\bdi\bif\bfi\bie\ber\brs\bs | |
115 | After the optional word designator, there may appear a | |
116 | sequence of one or more of the following modifiers, each | |
117 | preceded by a `:'. | |
118 | ||
119 | h\bh Remove a trailing file name component, leaving only | |
120 | the head. | |
121 | t\bt Remove all leading file name components, leaving | |
122 | the tail. | |
123 | r\br Remove a trailing suffix of the form _\b._\bx_\bx_\bx, leaving | |
124 | the basename. | |
125 | e\be Remove all but the trailing suffix. | |
126 | p\bp Print the new command but do not execute it. | |
127 | ||
128 | ||
129 | ||
130 | GNU History 4.3 2002 January 31 2 | |
131 | ||
132 | ||
133 | ||
134 | ||
135 | ||
136 | HISTORY(3) HISTORY(3) | |
137 | ||
138 | ||
139 | q\bq Quote the substituted words, escaping further sub- | |
140 | stitutions. | |
141 | x\bx Quote the substituted words as with q\bq, but break | |
142 | into words at b\bbl\bla\ban\bnk\bks\bs and newlines. | |
143 | s\bs/\b/_\bo_\bl_\bd/\b/_\bn_\be_\bw/\b/ | |
144 | Substitute _\bn_\be_\bw for the first occurrence of _\bo_\bl_\bd in | |
145 | the event line. Any delimiter can be used in place | |
146 | of /. The final delimiter is optional if it is the | |
147 | last character of the event line. The delimiter | |
148 | may be quoted in _\bo_\bl_\bd and _\bn_\be_\bw with a single back- | |
149 | slash. If & appears in _\bn_\be_\bw, it is replaced by _\bo_\bl_\bd. | |
150 | A single backslash will quote the &. If _\bo_\bl_\bd is | |
151 | null, it is set to the last _\bo_\bl_\bd substituted, or, if | |
152 | no previous history substitutions took place, the | |
153 | last _\bs_\bt_\br_\bi_\bn_\bg in a !\b!?\b?_\bs_\bt_\br_\bi_\bn_\bg[\b[?\b?]\b] search. | |
154 | &\b& Repeat the previous substitution. | |
155 | g\bg Cause changes to be applied over the entire event | |
156 | line. This is used in conjunction with `:\b:s\bs' (e.g., | |
157 | `:\b:g\bgs\bs/\b/_\bo_\bl_\bd/\b/_\bn_\be_\bw/\b/') or `:\b:&\b&'. If used with `:\b:s\bs', any | |
158 | delimiter can be used in place of /, and the final | |
159 | delimiter is optional if it is the last character | |
160 | of the event line. | |
161 | ||
162 | 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 | |
163 | This section describes how to use the History library in | |
164 | other programs. | |
165 | ||
166 | I\bIn\bnt\btr\bro\bod\bdu\buc\bct\bti\bio\bon\bn t\bto\bo H\bHi\bis\bst\bto\bor\bry\by | |
167 | The programmer using the History library has available | |
168 | functions for remembering lines on a history list, associ- | |
169 | ating arbitrary data with a line, removing lines from the | |
170 | list, searching through the list for a line containing an | |
171 | arbitrary text string, and referencing any line in the | |
172 | list directly. In addition, a history _\be_\bx_\bp_\ba_\bn_\bs_\bi_\bo_\bn function | |
173 | is available which provides for a consistent user inter- | |
174 | face across different programs. | |
175 | ||
176 | The user using programs written with the History library | |
177 | has the benefit of a consistent user interface with a set | |
178 | of well-known commands for manipulating the text of previ- | |
179 | ous lines and using that text in new commands. The basic | |
180 | history manipulation commands are identical to the history | |
181 | substitution provided by b\bba\bas\bsh\bh. | |
182 | ||
183 | If the programmer desires, he can use the Readline | |
184 | library, which includes some history manipulation by | |
185 | default, and has the added advantage of command line edit- | |
186 | ing. | |
187 | ||
188 | Before declaring any functions using any functionality the | |
189 | History library provides in other code, an application | |
190 | writer should include the file _\b<_\br_\be_\ba_\bd_\bl_\bi_\bn_\be_\b/_\bh_\bi_\bs_\bt_\bo_\br_\by_\b._\bh_\b> in any | |
191 | file that uses the History library's features. It sup- | |
192 | plies extern declarations for all of the library's public | |
193 | ||
194 | ||
195 | ||
196 | GNU History 4.3 2002 January 31 3 | |
197 | ||
198 | ||
199 | ||
200 | ||
201 | ||
202 | HISTORY(3) HISTORY(3) | |
203 | ||
204 | ||
205 | functions and variables, and declares all of the public | |
206 | data structures. | |
207 | ||
208 | ||
209 | H\bHi\bis\bst\bto\bor\bry\by S\bSt\bto\bor\bra\bag\bge\be | |
210 | The history list is an array of history entries. A his- | |
211 | tory entry is declared as follows: | |
212 | ||
213 | _\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; | |
214 | ||
215 | typedef struct _hist_entry { | |
216 | char *line; | |
217 | histdata_t data; | |
218 | } HIST_ENTRY; | |
219 | ||
220 | The history list itself might therefore be declared as | |
221 | ||
222 | _\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; | |
223 | ||
224 | The state of the History library is encapsulated into a | |
225 | single structure: | |
226 | ||
227 | /* | |
228 | * A structure used to pass around the current state of the history. | |
229 | */ | |
230 | typedef struct _hist_state { | |
231 | HIST_ENTRY **entries; /* Pointer to the entries themselves. */ | |
232 | int offset; /* The location pointer within this array. */ | |
233 | int length; /* Number of elements within this array. */ | |
234 | int size; /* Number of slots allocated to this array. */ | |
235 | int flags; | |
236 | } HISTORY_STATE; | |
237 | ||
238 | If the flags member includes H\bHS\bS_\b_S\bST\bTI\bIF\bFL\bLE\bED\bD, the history has | |
239 | been stifled. | |
240 | ||
241 | H\bHi\bis\bst\bto\bor\bry\by F\bFu\bun\bnc\bct\bti\bio\bon\bns\bs | |
242 | This section describes the calling sequence for the vari- | |
243 | ous functions exported by the GNU History library. | |
244 | ||
245 | 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 | |
246 | This section describes functions used to initialize and | |
247 | manage the state of the History library when you want to | |
248 | use the history functions in your program. | |
249 | ||
250 | _\bv_\bo_\bi_\bd u\bus\bsi\bin\bng\bg_\b_h\bhi\bis\bst\bto\bor\bry\by (_\bv_\bo_\bi_\bd) | |
251 | Begin a session in which the history functions might be | |
252 | used. This initializes the interactive variables. | |
253 | ||
254 | _\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) | |
255 | Return a structure describing the current state of the | |
256 | input history. | |
257 | ||
258 | _\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) | |
259 | ||
260 | ||
261 | ||
262 | GNU History 4.3 2002 January 31 4 | |
263 | ||
264 | ||
265 | ||
266 | ||
267 | ||
268 | HISTORY(3) HISTORY(3) | |
269 | ||
270 | ||
271 | Set the state of the history list according to _\bs_\bt_\ba_\bt_\be. | |
272 | ||
273 | ||
274 | H\bHi\bis\bst\bto\bor\bry\by L\bLi\bis\bst\bt M\bMa\ban\bna\bag\bge\bem\bme\ben\bnt\bt | |
275 | These functions manage individual entries on the history | |
276 | list, or set parameters managing the list itself. | |
277 | ||
278 | _\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) | |
279 | Place _\bs_\bt_\br_\bi_\bn_\bg at the end of the history list. The associ- | |
280 | ated data field (if any) is set to N\bNU\bUL\bLL\bL. | |
281 | ||
282 | _\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) | |
283 | Remove history entry at offset _\bw_\bh_\bi_\bc_\bh from the history. | |
284 | The removed element is returned so you can free the line, | |
285 | data, and containing structure. | |
286 | ||
287 | _\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 | |
288 | _\b*_\bl_\bi_\bn_\be_\b, _\bh_\bi_\bs_\bt_\bd_\ba_\bt_\ba_\b__\bt _\bd_\ba_\bt_\ba) | |
289 | Make the history entry at offset _\bw_\bh_\bi_\bc_\bh have _\bl_\bi_\bn_\be and _\bd_\ba_\bt_\ba. | |
290 | This returns the old entry so you can dispose of the data. | |
291 | In the case of an invalid _\bw_\bh_\bi_\bc_\bh, a N\bNU\bUL\bLL\bL pointer is | |
292 | returned. | |
293 | ||
294 | _\bv_\bo_\bi_\bd c\bcl\ble\bea\bar\br_\b_h\bhi\bis\bst\bto\bor\bry\by (_\bv_\bo_\bi_\bd) | |
295 | Clear the history list by deleting all the entries. | |
296 | ||
297 | _\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) | |
298 | Stifle the history list, remembering only the last _\bm_\ba_\bx | |
299 | entries. | |
300 | ||
301 | _\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) | |
302 | Stop stifling the history. This returns the previously- | |
303 | set maximum number of history entries (as set by s\bst\bti\bi-\b- | |
304 | f\bfl\ble\be_\b_h\bhi\bis\bst\bto\bor\bry\by(\b()\b)). history was stifled. The value is posi- | |
305 | tive if the history was stifled, negative if it wasn't. | |
306 | ||
307 | _\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) | |
308 | Returns non-zero if the history is stifled, zero if it is | |
309 | not. | |
310 | ||
311 | ||
312 | 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 | |
313 | These functions return information about the entire his- | |
314 | tory list or individual list entries. | |
315 | ||
316 | _\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) | |
317 | Return a N\bNU\bUL\bLL\bL terminated array of _\bH_\bI_\bS_\bT_\b__\bE_\bN_\bT_\bR_\bY _\b* which is | |
318 | the current input history. Element 0 of this list is the | |
319 | beginning of time. If there is no history, return N\bNU\bUL\bLL\bL. | |
320 | ||
321 | _\bi_\bn_\bt w\bwh\bhe\ber\bre\be_\b_h\bhi\bis\bst\bto\bor\bry\by (_\bv_\bo_\bi_\bd) | |
322 | Returns the offset of the current history element. | |
323 | ||
324 | _\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) | |
325 | ||
326 | ||
327 | ||
328 | GNU History 4.3 2002 January 31 5 | |
329 | ||
330 | ||
331 | ||
332 | ||
333 | ||
334 | HISTORY(3) HISTORY(3) | |
335 | ||
336 | ||
337 | Return the history entry at the current position, as | |
338 | determined by w\bwh\bhe\ber\bre\be_\b_h\bhi\bis\bst\bto\bor\bry\by(\b()\b). If there is no entry | |
339 | there, return a N\bNU\bUL\bLL\bL pointer. | |
340 | ||
341 | _\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) | |
342 | Return the history entry at position _\bo_\bf_\bf_\bs_\be_\bt, starting from | |
343 | h\bhi\bis\bst\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 | |
344 | greater than the history length, return a N\bNU\bUL\bLL\bL pointer. | |
345 | ||
346 | _\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) | |
347 | Return the number of bytes that the primary history | |
348 | entries are using. This function returns the sum of the | |
349 | lengths of all the lines in the history. | |
350 | ||
351 | ||
352 | 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 | |
353 | These functions allow the current index into the history | |
354 | list to be set or changed. | |
355 | ||
356 | _\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) | |
357 | Set the current history offset to _\bp_\bo_\bs, an absolute index | |
358 | into the list. Returns 1 on success, 0 if _\bp_\bo_\bs is less | |
359 | than zero or greater than the number of history entries. | |
360 | ||
361 | _\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) | |
362 | Back up the current history offset to the previous history | |
363 | entry, and return a pointer to that entry. If there is no | |
364 | previous entry, return a N\bNU\bUL\bLL\bL pointer. | |
365 | ||
366 | _\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) | |
367 | Move the current history offset forward to the next his- | |
368 | tory entry, and return the a pointer to that entry. If | |
369 | there is no next entry, return a N\bNU\bUL\bLL\bL pointer. | |
370 | ||
371 | ||
372 | 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 | |
373 | These functions allow searching of the history list for | |
374 | entries containing a specific string. Searching may be | |
375 | performed both forward and backward from the current his- | |
376 | tory position. The search may be _\ba_\bn_\bc_\bh_\bo_\br_\be_\bd, meaning that | |
377 | the string must match at the beginning of the history | |
378 | entry. | |
379 | ||
380 | _\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) | |
381 | Search the history for _\bs_\bt_\br_\bi_\bn_\bg, starting at the current | |
382 | history offset. If _\bd_\bi_\br_\be_\bc_\bt_\bi_\bo_\bn is less than 0, then the | |
383 | search is through previous entries, otherwise through sub- | |
384 | sequent entries. If _\bs_\bt_\br_\bi_\bn_\bg is found, then the current | |
385 | history index is set to that history entry, and the value | |
386 | returned is the offset in the line of the entry where | |
387 | _\bs_\bt_\br_\bi_\bn_\bg was found. Otherwise, nothing is changed, and a -1 | |
388 | is returned. | |
389 | ||
390 | _\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 | |
391 | ||
392 | ||
393 | ||
394 | GNU History 4.3 2002 January 31 6 | |
395 | ||
396 | ||
397 | ||
398 | ||
399 | ||
400 | HISTORY(3) HISTORY(3) | |
401 | ||
402 | ||
403 | _\bd_\bi_\br_\be_\bc_\bt_\bi_\bo_\bn) | |
404 | Search the history for _\bs_\bt_\br_\bi_\bn_\bg, starting at the current | |
405 | history offset. The search is anchored: matching lines | |
406 | must begin with _\bs_\bt_\br_\bi_\bn_\bg. If _\bd_\bi_\br_\be_\bc_\bt_\bi_\bo_\bn is less than 0, then | |
407 | the search is through previous entries, otherwise through | |
408 | subsequent entries. If _\bs_\bt_\br_\bi_\bn_\bg is found, then the current | |
409 | history index is set to that entry, and the return value | |
410 | is 0. Otherwise, nothing is changed, and a -1 is | |
411 | returned. | |
412 | ||
413 | _\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, | |
414 | _\bi_\bn_\bt _\bp_\bo_\bs) | |
415 | Search for _\bs_\bt_\br_\bi_\bn_\bg in the history list, starting at _\bp_\bo_\bs, an | |
416 | absolute index into the list. If _\bd_\bi_\br_\be_\bc_\bt_\bi_\bo_\bn is negative, | |
417 | the search proceeds backward from _\bp_\bo_\bs, otherwise forward. | |
418 | Returns the absolute index of the history element where | |
419 | _\bs_\bt_\br_\bi_\bn_\bg was found, or -1 otherwise. | |
420 | ||
421 | ||
422 | 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 | |
423 | The History library can read the history from and write it | |
424 | to a file. This section documents the functions for man- | |
425 | aging a history file. | |
426 | ||
427 | _\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) | |
428 | Add the contents of _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be to the history list, a line | |
429 | at a time. If _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be is N\bNU\bUL\bLL\bL, then read from _\b~_\b/_\b._\bh_\bi_\bs_\b- | |
430 | _\bt_\bo_\br_\by. Returns 0 if successful, or e\ber\brr\brn\bno\bo if not. | |
431 | ||
432 | _\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, | |
433 | _\bi_\bn_\bt _\bt_\bo) | |
434 | Read a range of lines from _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be, adding them to the | |
435 | history list. Start reading at line _\bf_\br_\bo_\bm and end at _\bt_\bo. | |
436 | If _\bf_\br_\bo_\bm is zero, start at the beginning. If _\bt_\bo is less | |
437 | than _\bf_\br_\bo_\bm, then read until the end of the file. If _\bf_\bi_\bl_\be_\b- | |
438 | _\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 | |
439 | successful, or e\ber\brr\brn\bno\bo if not. | |
440 | ||
441 | _\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) | |
442 | Write the current history to _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be, overwriting _\bf_\bi_\bl_\be_\b- | |
443 | _\bn_\ba_\bm_\be if necessary. If _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be is N\bNU\bUL\bLL\bL, then write the | |
444 | history list to _\b~_\b/_\b._\bh_\bi_\bs_\bt_\bo_\br_\by. Returns 0 on success, or | |
445 | e\ber\brr\brn\bno\bo on a read or write error. | |
446 | ||
447 | ||
448 | _\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) | |
449 | 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. | |
450 | If _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be is N\bNU\bUL\bLL\bL, then append to _\b~_\b/_\b._\bh_\bi_\bs_\bt_\bo_\br_\by. Returns 0 | |
451 | on success, or e\ber\brr\brn\bno\bo on a read or write error. | |
452 | ||
453 | _\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 | |
454 | _\bn_\bl_\bi_\bn_\be_\bs) | |
455 | Truncate the history file _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be, leaving only the last | |
456 | _\bn_\bl_\bi_\bn_\be_\bs lines. 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 | |
457 | ||
458 | ||
459 | ||
460 | GNU History 4.3 2002 January 31 7 | |
461 | ||
462 | ||
463 | ||
464 | ||
465 | ||
466 | HISTORY(3) HISTORY(3) | |
467 | ||
468 | ||
469 | truncated. Returns 0 on success, or e\ber\brr\brn\bno\bo on failure. | |
470 | ||
471 | ||
472 | H\bHi\bis\bst\bto\bor\bry\by E\bEx\bxp\bpa\ban\bns\bsi\bio\bon\bn | |
473 | These functions implement history expansion. | |
474 | ||
475 | _\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) | |
476 | Expand _\bs_\bt_\br_\bi_\bn_\bg, placing the result into _\bo_\bu_\bt_\bp_\bu_\bt, a pointer | |
477 | to a string. Returns: | |
478 | 0 If no expansions took place (or, if the only | |
479 | change in the text was the removal of escape | |
480 | characters preceding the history expansion | |
481 | character); | |
482 | 1 if expansions did take place; | |
483 | -1 if there was an error in expansion; | |
484 | 2 if the returned line should be displayed, | |
485 | but not executed, as with the :\b:p\bp modifier. | |
486 | If an error ocurred in expansion, then _\bo_\bu_\bt_\bp_\bu_\bt contains a | |
487 | descriptive error message. | |
488 | ||
489 | _\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, | |
490 | _\bi_\bn_\bt _\bq_\bc_\bh_\ba_\br) | |
491 | Returns the text of the history event beginning at _\bs_\bt_\br_\bi_\bn_\bg | |
492 | + _\b*_\bc_\bi_\bn_\bd_\be_\bx. _\b*_\bc_\bi_\bn_\bd_\be_\bx is modified to point to after the | |
493 | event specifier. At function entry, _\bc_\bi_\bn_\bd_\be_\bx points to the | |
494 | index into _\bs_\bt_\br_\bi_\bn_\bg where the history event specification | |
495 | begins. _\bq_\bc_\bh_\ba_\br is a character that is allowed to end the | |
496 | event specification in addition to the ``normal'' termi- | |
497 | nating characters. | |
498 | ||
499 | _\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) | |
500 | Return an array of tokens parsed out of _\bs_\bt_\br_\bi_\bn_\bg, much as | |
501 | the shell might. The tokens are split on the characters | |
502 | in the 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 variable, and shell quoting | |
503 | conventions are obeyed. | |
504 | ||
505 | _\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 | |
506 | _\bc_\bh_\ba_\br _\b*_\bs_\bt_\br_\bi_\bn_\bg) | |
507 | Extract a string segment consisting of the _\bf_\bi_\br_\bs_\bt through | |
508 | _\bl_\ba_\bs_\bt arguments present in _\bs_\bt_\br_\bi_\bn_\bg. Arguments are split | |
509 | using h\bhi\bis\bst\bto\bor\bry\by_\b_t\bto\bok\bke\ben\bni\biz\bze\be(\b()\b). | |
510 | ||
511 | ||
512 | H\bHi\bis\bst\bto\bor\bry\by V\bVa\bar\bri\bia\bab\bbl\ble\bes\bs | |
513 | This section describes the externally-visible variables | |
514 | exported by the GNU History Library. | |
515 | ||
516 | _\bi_\bn_\bt h\bhi\bis\bst\bto\bor\bry\by_\b_b\bba\bas\bse\be | |
517 | The logical offset of the first entry in the history list. | |
518 | ||
519 | _\bi_\bn_\bt h\bhi\bis\bst\bto\bor\bry\by_\b_l\ble\ben\bng\bgt\bth\bh | |
520 | The number of entries currently stored in the history | |
521 | list. | |
522 | ||
523 | ||
524 | ||
525 | ||
526 | GNU History 4.3 2002 January 31 8 | |
527 | ||
528 | ||
529 | ||
530 | ||
531 | ||
532 | HISTORY(3) HISTORY(3) | |
533 | ||
534 | ||
535 | _\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 | |
536 | The maximum number of history entries. This must be | |
537 | changed using s\bst\bti\bif\bfl\ble\be_\b_h\bhi\bis\bst\bto\bor\bry\by(\b()\b). | |
538 | ||
539 | _\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 | |
540 | The character that introduces a history event. The | |
541 | default is !\b!. Setting this to 0 inhibits history expan- | |
542 | sion. | |
543 | ||
544 | _\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 | |
545 | The character that invokes word substitution if found at | |
546 | the start of a line. The default is ^\b^. | |
547 | ||
548 | _\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 | |
549 | During tokenization, if this character is seen as the | |
550 | first character of a word, then it and all subsequent | |
551 | characters up to a newline are ignored, suppressing his- | |
552 | tory expansion for the remainder of the line. This is | |
553 | disabled by default. | |
554 | ||
555 | _\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 | |
556 | The characters that separate tokens for h\bhi\bis\bst\bto\bor\bry\by_\b_t\bto\bok\bk-\b- | |
557 | e\ben\bni\biz\bze\be(\b()\b). The default value is "\b" \\b\t\bt\\b\n\bn(\b()\b)<\b<>\b>;\b;&\b&|\b|"\b". | |
558 | ||
559 | _\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 | |
560 | The list of characters which inhibit history expansion if | |
561 | found immediately 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 | |
562 | default is space, tab, newline, \\b\r\br, and =\b=. | |
563 | ||
564 | _\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 | |
565 | The list of additional characters which can delimit a his- | |
566 | tory search string, in addition to space, tab, _\b: and _\b? in | |
567 | the case of a substring search. The default is empty. | |
568 | ||
569 | _\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 | |
570 | If non-zero, single-quoted words are not scanned for the | |
571 | history expansion character. The default value is 0. | |
572 | ||
573 | _\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 | |
574 | This should be set to the address of a function that takes | |
575 | two arguments: a c\bch\bha\bar\br *\b* (_\bs_\bt_\br_\bi_\bn_\bg) and an i\bin\bnt\bt index into | |
576 | that string (_\bi). It should return a non-zero value if the | |
577 | history expansion starting at _\bs_\bt_\br_\bi_\bn_\bg_\b[_\bi_\b] should not be per- | |
578 | formed; zero if the expansion should be done. It is | |
579 | intended for use by applications like b\bba\bas\bsh\bh that use the | |
580 | history expansion character for additional purposes. By | |
581 | default, this variable is set to N\bNU\bUL\bLL\bL. | |
582 | ||
583 | F\bFI\bIL\bLE\bES\bS | |
584 | _\b~_\b/_\b._\bh_\bi_\bs_\bt_\bo_\br_\by | |
585 | Default filename for reading and writing saved his- | |
586 | tory | |
587 | ||
588 | ||
589 | ||
590 | ||
591 | ||
592 | GNU History 4.3 2002 January 31 9 | |
593 | ||
594 | ||
595 | ||
596 | ||
597 | ||
598 | HISTORY(3) HISTORY(3) | |
599 | ||
600 | ||
601 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO | |
602 | _\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 | |
603 | _\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 | |
604 | _\bb_\ba_\bs_\bh(1) | |
605 | _\br_\be_\ba_\bd_\bl_\bi_\bn_\be(3) | |
606 | ||
607 | A\bAU\bUT\bTH\bHO\bOR\bRS\bS | |
608 | Brian Fox, Free Software Foundation | |
609 | bfox@gnu.org | |
610 | ||
611 | Chet Ramey, Case Western Reserve University | |
612 | chet@ins.CWRU.Edu | |
613 | ||
614 | B\bBU\bUG\bG R\bRE\bEP\bPO\bOR\bRT\bTS\bS | |
615 | If you find a bug in the h\bhi\bis\bst\bto\bor\bry\by library, you should | |
616 | report it. But first, you should make sure that it really | |
617 | is a bug, and that it appears in the latest version of the | |
618 | h\bhi\bis\bst\bto\bor\bry\by library that you have. | |
619 | ||
620 | Once you have determined that a bug actually exists, mail | |
621 | a bug report 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, | |
622 | you are welcome to mail that as well! Suggestions and | |
623 | `philosophical' bug reports may be mailed to _\bb_\bu_\bg_\b-_\br_\be_\ba_\bd_\b- | |
624 | _\bl_\bi_\bn_\be@_\bg_\bn_\bu_\b._\bo_\br_\bg or posted to the Usenet newsgroup | |
625 | g\bgn\bnu\bu.\b.b\bba\bas\bsh\bh.\b.b\bbu\bug\bg. | |
626 | ||
627 | Comments and bug reports concerning this manual page | |
628 | should be directed to _\bc_\bh_\be_\bt_\b@_\bi_\bn_\bs_\b._\bC_\bW_\bR_\bU_\b._\bE_\bd_\bu. | |
629 | ||
630 | ||
631 | ||
632 | ||
633 | ||
634 | ||
635 | ||
636 | ||
637 | ||
638 | ||
639 | ||
640 | ||
641 | ||
642 | ||
643 | ||
644 | ||
645 | ||
646 | ||
647 | ||
648 | ||
649 | ||
650 | ||
651 | ||
652 | ||
653 | ||
654 | ||
655 | ||
656 | ||
657 | ||
658 | GNU History 4.3 2002 January 31 10 | |
659 | ||
660 |