8 history - GNU History Library
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.
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
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.
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
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.
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
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
64 GNU History 4.3 2002 January 31 1
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.
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.
95 0
\b0 (
\b(z
\bze
\ber
\bro
\bo)
\b)
96 The zeroth word. For the shell, this is the com-
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?'
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.
111 If a word designator is supplied without an event specifi-
112 cation, the previous command is used as the event.
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
119 h
\bh Remove a trailing file name component, leaving only
121 t
\bt Remove all leading file name components, leaving
123 r
\br Remove a trailing suffix of the form _
\b._
\bx_
\bx_
\bx, leaving
125 e
\be Remove all but the trailing suffix.
126 p
\bp Print the new command but do not execute it.
130 GNU History 4.3 2002 January 31 2
136 HISTORY(3) HISTORY(3)
139 q
\bq Quote the substituted words, escaping further sub-
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
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
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.
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.
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-
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
196 GNU History 4.3 2002 January 31 3
202 HISTORY(3) HISTORY(3)
205 functions and variables, and declares all of the public
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:
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;
215 typedef struct _hist_entry {
220 The history list itself might therefore be declared as
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;
224 The state of the History library is encapsulated into a
228 * A structure used to pass around the current state of the history.
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. */
238 If the flags member includes H
\bHS
\bS_
\b_S
\bST
\bTI
\bIF
\bFL
\bLE
\bED
\bD, the history has
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.
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.
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.
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
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)
262 GNU History 4.3 2002 January 31 4
268 HISTORY(3) HISTORY(3)
271 Set the state of the history list according to _
\bs_
\bt_
\ba_
\bt_
\be.
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.
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.
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.
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
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.
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
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.
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
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.
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.
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.
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)
328 GNU History 4.3 2002 January 31 5
334 HISTORY(3) HISTORY(3)
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.
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.
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.
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.
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.
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.
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.
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
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
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
394 GNU History 4.3 2002 January 31 6
400 HISTORY(3) HISTORY(3)
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
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.
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.
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.
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.
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.
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.
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
460 GNU History 4.3 2002 January 31 7
466 HISTORY(3) HISTORY(3)
469 truncated. Returns 0 on success, or e
\ber
\brr
\brn
\bno
\bo on failure.
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.
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
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.
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-
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.
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).
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.
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.
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
526 GNU History 4.3 2002 January 31 8
532 HISTORY(3) HISTORY(3)
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).
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-
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^.
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
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".
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=.
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.
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.
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.
584 _
\b~_
\b/_
\b._
\bh_
\bi_
\bs_
\bt_
\bo_
\br_
\by
585 Default filename for reading and writing saved his-
592 GNU History 4.3 2002 January 31 9
598 HISTORY(3) HISTORY(3)
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
605 _
\br_
\be_
\ba_
\bd_
\bl_
\bi_
\bn_
\be(3)
607 A
\bAU
\bUT
\bTH
\bHO
\bOR
\bRS
\bS
608 Brian Fox, Free Software Foundation
611 Chet Ramey, Case Western Reserve University
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.
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.
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.
658 GNU History 4.3 2002 January 31 10