Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/man/man3/history.3 @ 68:5028fdace37b

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