Commit | Line | Data |
---|---|---|
9255ee31 EZ |
1 | .\" |
2 | .\" MAN PAGE COMMENTS to | |
3 | .\" | |
4 | .\" Chet Ramey | |
5 | .\" Information Network Services | |
6 | .\" Case Western Reserve University | |
775e241e | 7 | .\" chet.ramey@case.edu |
9255ee31 | 8 | .\" |
b4f26d54 | 9 | .\" Last Change: Fri Jul 17 09:43:01 EDT 2020 |
9255ee31 | 10 | .\" |
b4f26d54 | 11 | .TH HISTORY 3 "2020 July 17" "GNU History 8.1" |
9255ee31 EZ |
12 | .\" |
13 | .\" File Name macro. This used to be `.PN', for Path Name, | |
14 | .\" but Sun doesn't seem to like that very much. | |
15 | .\" | |
16 | .de FN | |
17 | \fI\|\\$1\|\fP | |
18 | .. | |
19 | .ds lp \fR\|(\fP | |
20 | .ds rp \fR\|)\fP | |
21 | .\" FnN return-value fun-name N arguments | |
22 | .de Fn1 | |
23 | \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3\fP\\*(rp | |
24 | .br | |
25 | .. | |
26 | .de Fn2 | |
27 | .if t \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3,\|\\$4\fP\\*(rp | |
28 | .if n \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3, \\$4\fP\\*(rp | |
29 | .br | |
30 | .. | |
31 | .de Fn3 | |
32 | .if t \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3,\|\\$4,\|\\$5\fP\|\\*(rp | |
33 | .if n \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3, \\$4, \\$5\fP\\*(rp | |
34 | .br | |
35 | .. | |
36 | .de Vb | |
37 | \fI\\$1\fP \fB\\$2\fP | |
38 | .br | |
39 | .. | |
40 | .SH NAME | |
41 | history \- GNU History Library | |
42 | .SH COPYRIGHT | |
b4f26d54 TT |
43 | .if t The GNU History Library is Copyright \(co 1989-2020 by the Free Software Foundation, Inc. |
44 | .if n The GNU History Library is Copyright (C) 1989-2020 by the Free Software Foundation, Inc. | |
9255ee31 EZ |
45 | .SH DESCRIPTION |
46 | Many programs read input from the user a line at a time. The GNU | |
47 | History library is able to keep track of those lines, associate arbitrary | |
48 | data with each line, and utilize information from previous lines in | |
49 | composing new ones. | |
50 | .PP | |
51 | .SH "HISTORY EXPANSION" | |
9255ee31 EZ |
52 | The history library supports a history expansion feature that |
53 | is identical to the history expansion in | |
54 | .BR bash. | |
55 | This section describes what syntax features are available. | |
56 | .PP | |
57 | History expansions introduce words from the history list into | |
58 | the input stream, making it easy to repeat commands, insert the | |
59 | arguments to a previous command into the current input line, or | |
60 | fix errors in previous commands quickly. | |
61 | .PP | |
62 | History expansion is usually performed immediately after a complete line | |
63 | is read. | |
64 | It takes place in two parts. | |
65 | The first is to determine which line from the history list | |
66 | to use during substitution. | |
67 | The second is to select portions of that line for inclusion into | |
68 | the current one. | |
69 | The line selected from the history is the \fIevent\fP, | |
70 | and the portions of that line that are acted upon are \fIwords\fP. | |
71 | Various \fImodifiers\fP are available to manipulate the selected words. | |
72 | The line is broken into words in the same fashion as \fBbash\fP | |
73 | does when reading input, | |
74 | so that several words that would otherwise be separated | |
75 | are considered one word when surrounded by quotes (see the | |
76 | description of \fBhistory_tokenize()\fP below). | |
77 | History expansions are introduced by the appearance of the | |
78 | history expansion character, which is \^\fB!\fP\^ by default. | |
79 | Only backslash (\^\fB\e\fP\^) and single quotes can quote | |
80 | the history expansion character. | |
81 | .SS Event Designators | |
9255ee31 EZ |
82 | An event designator is a reference to a command line entry in the |
83 | history list. | |
cc88a640 JK |
84 | Unless the reference is absolute, events are relative to the current |
85 | position in the history list. | |
9255ee31 EZ |
86 | .PP |
87 | .PD 0 | |
88 | .TP | |
89 | .B ! | |
90 | Start a history substitution, except when followed by a | |
91 | .BR blank , | |
92 | newline, = or (. | |
93 | .TP | |
94 | .B !\fIn\fR | |
95 | Refer to command line | |
96 | .IR n . | |
97 | .TP | |
98 | .B !\-\fIn\fR | |
cc88a640 | 99 | Refer to the current command minus |
9255ee31 EZ |
100 | .IR n . |
101 | .TP | |
102 | .B !! | |
103 | Refer to the previous command. This is a synonym for `!\-1'. | |
104 | .TP | |
105 | .B !\fIstring\fR | |
cc88a640 JK |
106 | Refer to the most recent command |
107 | preceding the current position in the history list | |
108 | starting with | |
9255ee31 EZ |
109 | .IR string . |
110 | .TP | |
111 | .B !?\fIstring\fR\fB[?]\fR | |
cc88a640 | 112 | Refer to the most recent command |
775e241e | 113 | preceding the current position in the history list |
cc88a640 | 114 | containing |
9255ee31 EZ |
115 | .IR string . |
116 | The trailing \fB?\fP may be omitted if | |
117 | .I string | |
118 | is followed immediately by a newline. | |
b4f26d54 TT |
119 | If \fIstring\fP is missing, the string from the most recent search is used; |
120 | it is an error if there is no previous search string. | |
9255ee31 EZ |
121 | .TP |
122 | .B \d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u | |
123 | Quick substitution. Repeat the last command, replacing | |
124 | .I string1 | |
125 | with | |
126 | .IR string2 . | |
127 | Equivalent to | |
b4f26d54 | 128 | ``!!:s\d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u'' |
9255ee31 EZ |
129 | (see \fBModifiers\fP below). |
130 | .TP | |
131 | .B !# | |
132 | The entire command line typed so far. | |
133 | .PD | |
134 | .SS Word Designators | |
9255ee31 | 135 | Word designators are used to select desired words from the event. |
775e241e | 136 | A |
9255ee31 EZ |
137 | .B : |
138 | separates the event specification from the word designator. | |
139 | It may be omitted if the word designator begins with a | |
140 | .BR ^ , | |
141 | .BR $ , | |
142 | .BR * , | |
143 | .BR \- , | |
144 | or | |
145 | .BR % . | |
146 | Words are numbered from the beginning of the line, | |
147 | with the first word being denoted by 0 (zero). | |
148 | Words are inserted into the current line separated by single spaces. | |
149 | .PP | |
150 | .PD 0 | |
151 | .TP | |
152 | .B 0 (zero) | |
153 | The zeroth word. For the shell, this is the command | |
154 | word. | |
155 | .TP | |
156 | .I n | |
157 | The \fIn\fRth word. | |
158 | .TP | |
159 | .B ^ | |
160 | The first argument. That is, word 1. | |
161 | .TP | |
162 | .B $ | |
775e241e TT |
163 | The last word. This is usually the last argument, but will expand to the |
164 | zeroth word if there is only one word in the line. | |
9255ee31 EZ |
165 | .TP |
166 | .B % | |
b4f26d54 TT |
167 | The first word matched by the most recent `?\fIstring\fR?' search, |
168 | if the search string begins with a character that is part of a word. | |
9255ee31 EZ |
169 | .TP |
170 | .I x\fB\-\fPy | |
171 | A range of words; `\-\fIy\fR' abbreviates `0\-\fIy\fR'. | |
172 | .TP | |
173 | .B * | |
174 | All of the words but the zeroth. This is a synonym | |
175 | for `\fI1\-$\fP'. It is not an error to use | |
176 | .B * | |
177 | if there is just one | |
178 | word in the event; the empty string is returned in that case. | |
179 | .TP | |
180 | .B x* | |
181 | Abbreviates \fIx\-$\fP. | |
182 | .TP | |
183 | .B x\- | |
184 | Abbreviates \fIx\-$\fP like \fBx*\fP, but omits the last word. | |
b4f26d54 | 185 | If \fBx\fP is missing, it defaults to 0. |
9255ee31 EZ |
186 | .PD |
187 | .PP | |
188 | If a word designator is supplied without an event specification, the | |
189 | previous command is used as the event. | |
190 | .SS Modifiers | |
9255ee31 EZ |
191 | After the optional word designator, there may appear a sequence of |
192 | one or more of the following modifiers, each preceded by a `:'. | |
b4f26d54 | 193 | These modify, or edit, the word or words selected from the history event. |
9255ee31 EZ |
194 | .PP |
195 | .PD 0 | |
196 | .PP | |
197 | .TP | |
198 | .B h | |
199 | Remove a trailing file name component, leaving only the head. | |
200 | .TP | |
201 | .B t | |
202 | Remove all leading file name components, leaving the tail. | |
203 | .TP | |
204 | .B r | |
205 | Remove a trailing suffix of the form \fI.xxx\fP, leaving the | |
206 | basename. | |
207 | .TP | |
208 | .B e | |
209 | Remove all but the trailing suffix. | |
210 | .TP | |
211 | .B p | |
212 | Print the new command but do not execute it. | |
213 | .TP | |
214 | .B q | |
215 | Quote the substituted words, escaping further substitutions. | |
216 | .TP | |
217 | .B x | |
218 | Quote the substituted words as with | |
219 | .BR q , | |
220 | but break into words at | |
221 | .B blanks | |
222 | and newlines. | |
b4f26d54 TT |
223 | The \fBq\fP and \fBx\fP modifiers are mutually exclusive; the last one |
224 | supplied is used. | |
9255ee31 EZ |
225 | .TP |
226 | .B s/\fIold\fP/\fInew\fP/ | |
227 | Substitute | |
228 | .I new | |
229 | for the first occurrence of | |
230 | .I old | |
b4f26d54 TT |
231 | in the event line. |
232 | Any character may be used as the delimiter in place of /. | |
233 | The final delimiter is optional if it is the last character of the | |
234 | event line. | |
235 | The delimiter may be quoted in | |
9255ee31 EZ |
236 | .I old |
237 | and | |
238 | .I new | |
239 | with a single backslash. If & appears in | |
240 | .IR new , | |
241 | it is replaced by | |
242 | .IR old . | |
b4f26d54 TT |
243 | A single backslash will quote the &. |
244 | If | |
9255ee31 EZ |
245 | .I old |
246 | is null, it is set to the last | |
247 | .I old | |
248 | substituted, or, if no previous history substitutions took place, | |
249 | the last | |
250 | .I string | |
251 | in a | |
252 | .B !?\fIstring\fR\fB[?]\fR | |
253 | search. | |
b4f26d54 TT |
254 | If |
255 | .I new | |
256 | is null, each matching | |
257 | .I old | |
258 | is deleted. | |
9255ee31 EZ |
259 | .TP |
260 | .B & | |
261 | Repeat the previous substitution. | |
262 | .TP | |
263 | .B g | |
264 | Cause changes to be applied over the entire event line. This is | |
265 | used in conjunction with `\fB:s\fP' (e.g., `\fB:gs/\fIold\fP/\fInew\fP/\fR') | |
266 | or `\fB:&\fP'. If used with | |
267 | `\fB:s\fP', any delimiter can be used | |
268 | in place of /, and the final delimiter is optional | |
269 | if it is the last character of the event line. | |
5bdf8622 DJ |
270 | An \fBa\fP may be used as a synonym for \fBg\fP. |
271 | .TP | |
272 | .B G | |
b4f26d54 TT |
273 | Apply the following `\fBs\fP' or `\fB&\fP' modifier once to each word |
274 | in the event line. | |
9255ee31 EZ |
275 | .PD |
276 | .SH "PROGRAMMING WITH HISTORY FUNCTIONS" | |
277 | This section describes how to use the History library in other programs. | |
278 | .SS Introduction to History | |
b4f26d54 | 279 | A programmer using the History library has available functions |
9255ee31 EZ |
280 | for remembering lines on a history list, associating arbitrary data |
281 | with a line, removing lines from the list, searching through the list | |
282 | for a line containing an arbitrary text string, and referencing any line | |
283 | in the list directly. In addition, a history \fIexpansion\fP function | |
284 | is available which provides for a consistent user interface across | |
285 | different programs. | |
286 | .PP | |
287 | The user using programs written with the History library has the | |
288 | benefit of a consistent user interface with a set of well-known | |
289 | commands for manipulating the text of previous lines and using that text | |
290 | in new commands. The basic history manipulation commands are | |
291 | identical to | |
292 | the history substitution provided by \fBbash\fP. | |
293 | .PP | |
b4f26d54 | 294 | The programmer can also use the Readline library, which |
9255ee31 EZ |
295 | includes some history manipulation by default, and has the added |
296 | advantage of command line editing. | |
297 | .PP | |
298 | Before declaring any functions using any functionality the History | |
299 | library provides in other code, an application writer should include | |
300 | the file | |
301 | .FN <readline/history.h> | |
302 | in any file that uses the | |
303 | History library's features. It supplies extern declarations for all | |
304 | of the library's public functions and variables, and declares all of | |
305 | the public data structures. | |
9255ee31 | 306 | .SS History Storage |
9255ee31 EZ |
307 | The history list is an array of history entries. A history entry is |
308 | declared as follows: | |
309 | .PP | |
310 | .Vb "typedef void *" histdata_t; | |
311 | .PP | |
312 | .nf | |
313 | typedef struct _hist_entry { | |
314 | char *line; | |
5bdf8622 | 315 | char *timestamp; |
9255ee31 EZ |
316 | histdata_t data; |
317 | } HIST_ENTRY; | |
318 | .fi | |
319 | .PP | |
320 | The history list itself might therefore be declared as | |
321 | .PP | |
322 | .Vb "HIST_ENTRY **" the_history_list; | |
323 | .PP | |
324 | The state of the History library is encapsulated into a single structure: | |
325 | .PP | |
326 | .nf | |
327 | /* | |
328 | * A structure used to pass around the current state of the history. | |
329 | */ | |
330 | typedef struct _hist_state { | |
331 | HIST_ENTRY **entries; /* Pointer to the entries themselves. */ | |
332 | int offset; /* The location pointer within this array. */ | |
333 | int length; /* Number of elements within this array. */ | |
334 | int size; /* Number of slots allocated to this array. */ | |
335 | int flags; | |
336 | } HISTORY_STATE; | |
337 | .fi | |
338 | .PP | |
339 | If the flags member includes \fBHS_STIFLED\fP, the history has been | |
340 | stifled. | |
341 | .SH "History Functions" | |
9255ee31 EZ |
342 | This section describes the calling sequence for the various functions |
343 | exported by the GNU History library. | |
344 | .SS Initializing History and State Management | |
345 | This section describes functions used to initialize and manage | |
346 | the state of the History library when you want to use the history | |
347 | functions in your program. | |
348 | ||
349 | .Fn1 void using_history void | |
350 | Begin a session in which the history functions might be used. This | |
351 | initializes the interactive variables. | |
352 | ||
353 | .Fn1 "HISTORY_STATE *" history_get_history_state void | |
354 | Return a structure describing the current state of the input history. | |
355 | ||
356 | .Fn1 void history_set_history_state "HISTORY_STATE *state" | |
357 | Set the state of the history list according to \fIstate\fP. | |
358 | ||
359 | .SS History List Management | |
9255ee31 EZ |
360 | These functions manage individual entries on the history list, or set |
361 | parameters managing the list itself. | |
362 | ||
363 | .Fn1 void add_history "const char *string" | |
364 | Place \fIstring\fP at the end of the history list. The associated data | |
365 | field (if any) is set to \fBNULL\fP. | |
cb41b9e7 TT |
366 | If the maximum number of history entries has been set using |
367 | \fBstifle_history()\fP, and the new number of history entries would exceed | |
368 | that maximum, the oldest history entry is removed. | |
9255ee31 | 369 | |
5bdf8622 DJ |
370 | .Fn1 void add_history_time "const char *string" |
371 | Change the time stamp associated with the most recent history entry to | |
372 | \fIstring\fP. | |
373 | ||
9255ee31 EZ |
374 | .Fn1 "HIST_ENTRY *" remove_history "int which" |
375 | Remove history entry at offset \fIwhich\fP from the history. The | |
376 | removed element is returned so you can free the line, data, | |
377 | and containing structure. | |
378 | ||
5bdf8622 DJ |
379 | .Fn1 "histdata_t" free_history_entry "HIST_ENTRY *histent" |
380 | Free the history entry \fIhistent\fP and any history library private | |
381 | data associated with it. Returns the application-specific data | |
382 | so the caller can dispose of it. | |
383 | ||
9255ee31 EZ |
384 | .Fn3 "HIST_ENTRY *" replace_history_entry "int which" "const char *line" "histdata_t data" |
385 | Make the history entry at offset \fIwhich\fP have \fIline\fP and \fIdata\fP. | |
5bdf8622 DJ |
386 | This returns the old entry so the caller can dispose of any |
387 | application-specific data. In the case | |
9255ee31 EZ |
388 | of an invalid \fIwhich\fP, a \fBNULL\fP pointer is returned. |
389 | ||
390 | .Fn1 void clear_history "void" | |
391 | Clear the history list by deleting all the entries. | |
392 | ||
393 | .Fn1 void stifle_history "int max" | |
394 | Stifle the history list, remembering only the last \fImax\fP entries. | |
cb41b9e7 | 395 | The history list will contain only \fImax\fP entries at a time. |
9255ee31 EZ |
396 | |
397 | .Fn1 int unstifle_history "void" | |
398 | Stop stifling the history. This returns the previously-set | |
399 | maximum number of history entries (as set by \fBstifle_history()\fP). | |
400 | history was stifled. The value is positive if the history was | |
401 | stifled, negative if it wasn't. | |
402 | ||
403 | .Fn1 int history_is_stifled "void" | |
404 | Returns non-zero if the history is stifled, zero if it is not. | |
405 | ||
406 | .SS Information About the History List | |
407 | ||
408 | These functions return information about the entire history list or | |
409 | individual list entries. | |
410 | ||
411 | .Fn1 "HIST_ENTRY **" history_list "void" | |
412 | Return a \fBNULL\fP terminated array of \fIHIST_ENTRY *\fP which is the | |
413 | current input history. Element 0 of this list is the beginning of time. | |
414 | If there is no history, return \fBNULL\fP. | |
415 | ||
416 | .Fn1 int where_history "void" | |
417 | Returns the offset of the current history element. | |
418 | ||
419 | .Fn1 "HIST_ENTRY *" current_history "void" | |
420 | Return the history entry at the current position, as determined by | |
421 | \fBwhere_history()\fP. If there is no entry there, return a \fBNULL\fP | |
422 | pointer. | |
423 | ||
424 | .Fn1 "HIST_ENTRY *" history_get "int offset" | |
cb41b9e7 TT |
425 | Return the history entry at position \fIoffset\fP. |
426 | The range of valid values of \fIoffset\fP starts at \fBhistory_base\fP | |
427 | and ends at \fBhistory_length\fP \- 1. | |
428 | If there is no entry there, or if \fIoffset\fP is outside the valid | |
429 | range, return a \fBNULL\fP pointer. | |
9255ee31 | 430 | |
5bdf8622 DJ |
431 | .Fn1 "time_t" history_get_time "HIST_ENTRY *" |
432 | Return the time stamp associated with the history entry passed as the argument. | |
433 | ||
9255ee31 EZ |
434 | .Fn1 int history_total_bytes "void" |
435 | Return the number of bytes that the primary history entries are using. | |
436 | This function returns the sum of the lengths of all the lines in the | |
437 | history. | |
438 | ||
439 | .SS Moving Around the History List | |
440 | ||
441 | These functions allow the current index into the history list to be | |
442 | set or changed. | |
443 | ||
444 | .Fn1 int history_set_pos "int pos" | |
445 | Set the current history offset to \fIpos\fP, an absolute index | |
446 | into the list. | |
447 | Returns 1 on success, 0 if \fIpos\fP is less than zero or greater | |
448 | than the number of history entries. | |
449 | ||
450 | .Fn1 "HIST_ENTRY *" previous_history "void" | |
451 | Back up the current history offset to the previous history entry, and | |
452 | return a pointer to that entry. If there is no previous entry, return | |
453 | a \fBNULL\fP pointer. | |
454 | ||
455 | .Fn1 "HIST_ENTRY *" next_history "void" | |
775e241e TT |
456 | If the current history offset refers to a valid history entry, |
457 | increment the current history offset. | |
458 | If the possibly-incremented history offset refers to a valid history | |
459 | entry, return a pointer to that entry; | |
460 | otherwise, return a \fBNULL\fP pointer. | |
9255ee31 EZ |
461 | |
462 | .SS Searching the History List | |
463 | ||
464 | These functions allow searching of the history list for entries containing | |
465 | a specific string. Searching may be performed both forward and backward | |
466 | from the current history position. The search may be \fIanchored\fP, | |
467 | meaning that the string must match at the beginning of the history entry. | |
468 | ||
469 | .Fn2 int history_search "const char *string" "int direction" | |
470 | Search the history for \fIstring\fP, starting at the current history offset. | |
471 | If \fIdirection\fP is less than 0, then the search is through | |
472 | previous entries, otherwise through subsequent entries. | |
473 | If \fIstring\fP is found, then | |
474 | the current history index is set to that history entry, and the value | |
475 | returned is the offset in the line of the entry where | |
476 | \fIstring\fP was found. Otherwise, nothing is changed, and a -1 is | |
477 | returned. | |
478 | ||
479 | .Fn2 int history_search_prefix "const char *string" "int direction" | |
480 | Search the history for \fIstring\fP, starting at the current history | |
481 | offset. The search is anchored: matching lines must begin with | |
482 | \fIstring\fP. If \fIdirection\fP is less than 0, then the search is | |
483 | through previous entries, otherwise through subsequent entries. | |
484 | If \fIstring\fP is found, then the | |
485 | current history index is set to that entry, and the return value is 0. | |
486 | Otherwise, nothing is changed, and a -1 is returned. | |
487 | ||
488 | .Fn3 int history_search_pos "const char *string" "int direction" "int pos" | |
489 | Search for \fIstring\fP in the history list, starting at \fIpos\fP, an | |
490 | absolute index into the list. If \fIdirection\fP is negative, the search | |
491 | proceeds backward from \fIpos\fP, otherwise forward. Returns the absolute | |
492 | index of the history element where \fIstring\fP was found, or -1 otherwise. | |
493 | ||
494 | .SS Managing the History File | |
495 | The History library can read the history from and write it to a file. | |
496 | This section documents the functions for managing a history file. | |
497 | ||
498 | .Fn1 int read_history "const char *filename" | |
499 | Add the contents of \fIfilename\fP to the history list, a line at a time. | |
500 | If \fIfilename\fP is \fBNULL\fP, then read from \fI~/.history\fP. | |
501 | Returns 0 if successful, or \fBerrno\fP if not. | |
502 | ||
503 | .Fn3 int read_history_range "const char *filename" "int from" "int to" | |
504 | Read a range of lines from \fIfilename\fP, adding them to the history list. | |
505 | Start reading at line \fIfrom\fP and end at \fIto\fP. | |
506 | If \fIfrom\fP is zero, start at the beginning. If \fIto\fP is less than | |
507 | \fIfrom\fP, then read until the end of the file. If \fIfilename\fP is | |
508 | \fBNULL\fP, then read from \fI~/.history\fP. Returns 0 if successful, | |
509 | or \fBerrno\fP if not. | |
510 | ||
511 | .Fn1 int write_history "const char *filename" | |
512 | Write the current history to \fIfilename\fP, overwriting \fIfilename\fP | |
513 | if necessary. | |
514 | If \fIfilename\fP is \fBNULL\fP, then write the history list to \fI~/.history\fP. | |
515 | Returns 0 on success, or \fBerrno\fP on a read or write error. | |
516 | ||
517 | ||
518 | .Fn2 int append_history "int nelements" "const char *filename" | |
519 | Append the last \fInelements\fP of the history list to \fIfilename\fP. | |
520 | If \fIfilename\fP is \fBNULL\fP, then append to \fI~/.history\fP. | |
521 | Returns 0 on success, or \fBerrno\fP on a read or write error. | |
522 | ||
523 | .Fn2 int history_truncate_file "const char *filename" "int nlines" | |
524 | Truncate the history file \fIfilename\fP, leaving only the last | |
525 | \fInlines\fP lines. | |
526 | If \fIfilename\fP is \fBNULL\fP, then \fI~/.history\fP is truncated. | |
527 | Returns 0 on success, or \fBerrno\fP on failure. | |
528 | ||
529 | .SS History Expansion | |
530 | ||
531 | These functions implement history expansion. | |
532 | ||
533 | .Fn2 int history_expand "char *string" "char **output" | |
534 | Expand \fIstring\fP, placing the result into \fIoutput\fP, a pointer | |
535 | to a string. Returns: | |
536 | .RS | |
537 | .PD 0 | |
538 | .TP | |
539 | 0 | |
540 | If no expansions took place (or, if the only change in | |
541 | the text was the removal of escape characters preceding the history expansion | |
542 | character); | |
543 | .TP | |
544 | 1 | |
545 | if expansions did take place; | |
546 | .TP | |
547 | -1 | |
548 | if there was an error in expansion; | |
549 | .TP | |
550 | 2 | |
551 | if the returned line should be displayed, but not executed, | |
552 | as with the \fB:p\fP modifier. | |
553 | .PD | |
554 | .RE | |
b4f26d54 | 555 | If an error occurred in expansion, then \fIoutput\fP contains a descriptive |
9255ee31 EZ |
556 | error message. |
557 | ||
558 | .Fn3 "char *" get_history_event "const char *string" "int *cindex" "int qchar" | |
559 | Returns the text of the history event beginning at \fIstring\fP + | |
560 | \fI*cindex\fP. \fI*cindex\fP is modified to point to after the event | |
561 | specifier. At function entry, \fIcindex\fP points to the index into | |
562 | \fIstring\fP where the history event specification begins. \fIqchar\fP | |
563 | is a character that is allowed to end the event specification in addition | |
564 | to the ``normal'' terminating characters. | |
565 | ||
566 | .Fn1 "char **" history_tokenize "const char *string" | |
567 | Return an array of tokens parsed out of \fIstring\fP, much as the | |
568 | shell might. | |
569 | The tokens are split on the characters in the | |
570 | \fBhistory_word_delimiters\fP variable, | |
571 | and shell quoting conventions are obeyed. | |
572 | ||
573 | .Fn3 "char *" history_arg_extract "int first" "int last" "const char *string" | |
574 | Extract a string segment consisting of the \fIfirst\fP through \fIlast\fP | |
575 | arguments present in \fIstring\fP. Arguments are split using | |
576 | \fBhistory_tokenize()\fP. | |
577 | ||
578 | .SS History Variables | |
579 | ||
580 | This section describes the externally-visible variables exported by | |
581 | the GNU History Library. | |
582 | ||
583 | .Vb int history_base | |
584 | The logical offset of the first entry in the history list. | |
585 | ||
586 | .Vb int history_length | |
587 | The number of entries currently stored in the history list. | |
588 | ||
589 | .Vb int history_max_entries | |
590 | The maximum number of history entries. This must be changed using | |
591 | \fBstifle_history()\fP. | |
592 | ||
b4f26d54 | 593 | .Vb int history_write_timestamps |
5bdf8622 DJ |
594 | If non-zero, timestamps are written to the history file, so they can be |
595 | preserved between sessions. The default value is 0, meaning that | |
596 | timestamps are not saved. | |
cc88a640 JK |
597 | The current timestamp format uses the value of \fIhistory_comment_char\fP |
598 | to delimit timestamp entries in the history file. If that variable does | |
599 | not have a value (the default), timestamps will not be written. | |
5bdf8622 | 600 | |
9255ee31 EZ |
601 | .Vb char history_expansion_char |
602 | The character that introduces a history event. The default is \fB!\fP. | |
603 | Setting this to 0 inhibits history expansion. | |
604 | ||
605 | .Vb char history_subst_char | |
606 | The character that invokes word substitution if found at the start of | |
607 | a line. The default is \fB^\fP. | |
608 | ||
609 | .Vb char history_comment_char | |
610 | During tokenization, if this character is seen as the first character | |
611 | of a word, then it and all subsequent characters up to a newline are | |
612 | ignored, suppressing history expansion for the remainder of the line. | |
613 | This is disabled by default. | |
614 | ||
615 | .Vb "char *" history_word_delimiters | |
616 | The characters that separate tokens for \fBhistory_tokenize()\fP. | |
617 | The default value is \fB"\ \et\en()<>;&|"\fP. | |
618 | ||
619 | .Vb "char *" history_no_expand_chars | |
620 | The list of characters which inhibit history expansion if found immediately | |
621 | following \fBhistory_expansion_char\fP. The default is space, tab, newline, | |
622 | \fB\er\fP, and \fB=\fP. | |
623 | ||
624 | .Vb "char *" history_search_delimiter_chars | |
625 | The list of additional characters which can delimit a history search | |
626 | string, in addition to space, tab, \fI:\fP and \fI?\fP in the case of | |
627 | a substring search. The default is empty. | |
628 | ||
629 | .Vb int history_quotes_inhibit_expansion | |
775e241e TT |
630 | If non-zero, double-quoted words are not scanned for the history expansion |
631 | character or the history comment character. The default value is 0. | |
9255ee31 EZ |
632 | |
633 | .Vb "rl_linebuf_func_t *" history_inhibit_expansion_function | |
634 | This should be set to the address of a function that takes two arguments: | |
635 | a \fBchar *\fP (\fIstring\fP) | |
636 | and an \fBint\fP index into that string (\fIi\fP). | |
637 | It should return a non-zero value if the history expansion starting at | |
638 | \fIstring[i]\fP should not be performed; zero if the expansion should | |
639 | be done. | |
640 | It is intended for use by applications like \fBbash\fP that use the history | |
641 | expansion character for additional purposes. | |
642 | By default, this variable is set to \fBNULL\fP. | |
643 | .SH FILES | |
644 | .PD 0 | |
645 | .TP | |
646 | .FN ~/.history | |
647 | Default filename for reading and writing saved history | |
648 | .PD | |
649 | .SH "SEE ALSO" | |
650 | .PD 0 | |
651 | .TP | |
652 | \fIThe Gnu Readline Library\fP, Brian Fox and Chet Ramey | |
653 | .TP | |
654 | \fIThe Gnu History Library\fP, Brian Fox and Chet Ramey | |
655 | .TP | |
656 | \fIbash\fP(1) | |
657 | .TP | |
658 | \fIreadline\fP(3) | |
659 | .PD | |
660 | .SH AUTHORS | |
661 | Brian Fox, Free Software Foundation | |
662 | .br | |
663 | bfox@gnu.org | |
664 | .PP | |
665 | Chet Ramey, Case Western Reserve University | |
666 | .br | |
775e241e | 667 | chet.ramey@case.edu |
9255ee31 EZ |
668 | .SH BUG REPORTS |
669 | If you find a bug in the | |
670 | .B history | |
671 | library, you should report it. But first, you should | |
672 | make sure that it really is a bug, and that it appears in the latest | |
673 | version of the | |
674 | .B history | |
675 | library that you have. | |
676 | .PP | |
677 | Once you have determined that a bug actually exists, mail a | |
678 | bug report to \fIbug\-readline\fP@\fIgnu.org\fP. | |
679 | If you have a fix, you are welcome to mail that | |
680 | as well! Suggestions and `philosophical' bug reports may be mailed | |
681 | to \fPbug-readline\fP@\fIgnu.org\fP or posted to the Usenet | |
682 | newsgroup | |
683 | .BR gnu.bash.bug . | |
684 | .PP | |
685 | Comments and bug reports concerning | |
686 | this manual page should be directed to | |
775e241e | 687 | .IR chet.ramey@case.edu . |