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