+++ /dev/null
-
-
-
-HISTORY(3) HISTORY(3)
-
-
-N\bNA\bAM\bME\bE
- history - GNU History Library
-
-C\bCO\bOP\bPY\bYR\bRI\bIG\bGH\bHT\bT
- The GNU History Library is Copyright (C) 1989-2002 by the
- Free Software Foundation, Inc.
-
-D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
- Many programs read input from the user a line at a time.
- The GNU History library is able to keep track of those
- lines, associate arbitrary data with each line, and uti-
- lize information from previous lines in composing new
- ones.
-
-
-H\bHI\bIS\bST\bTO\bOR\bRY\bY E\bEX\bXP\bPA\bAN\bNS\bSI\bIO\bON\bN
- The history library supports a history expansion feature
- that is identical to the history expansion in b\bba\bas\bsh\bh.\b. This
- section describes what syntax features are available.
-
- History expansions introduce words from the history list
- into the input stream, making it easy to repeat commands,
- insert the arguments to a previous command into the cur-
- rent input line, or fix errors in previous commands
- quickly.
-
- History expansion is usually performed immediately after a
- complete line is read. It takes place in two parts. The
- first is to determine which line from the history list to
- use during substitution. The second is to select portions
- of that line for inclusion into the current one. The line
- selected from the history is the _\be_\bv_\be_\bn_\bt, and the portions
- of that line that are acted upon are _\bw_\bo_\br_\bd_\bs. Various _\bm_\bo_\bd_\bi_\b-
- _\bf_\bi_\be_\br_\bs are available to manipulate the selected words. The
- line is broken into words in the same fashion as b\bba\bas\bsh\bh does
- when reading input, so that several words that would oth-
- erwise be separated are considered one word when sur-
- rounded by quotes (see the description of h\bhi\bis\bst\bto\bor\bry\by_\b_t\bto\bok\bk-\b-
- e\ben\bni\biz\bze\be(\b()\b) below). History expansions are introduced by the
- appearance of the history expansion character, which is !\b!
- by default. Only backslash (\\b\) and single quotes can
- quote the history expansion character.
-
- E\bEv\bve\ben\bnt\bt D\bDe\bes\bsi\big\bgn\bna\bat\bto\bor\brs\bs
- An event designator is a reference to a command line entry
- in the history list.
-
- !\b! Start a history substitution, except when followed
- by a b\bbl\bla\ban\bnk\bk, newline, = or (.
- !\b!_\bn Refer to command line _\bn.
- !\b!-\b-_\bn Refer to the current command line minus _\bn.
- !\b!!\b! Refer to the previous command. This is a synonym
- for `!-1'.
-
-
-
-
-GNU History 4.3 2002 January 31 1
-
-
-
-
-
-HISTORY(3) HISTORY(3)
-
-
- !\b!_\bs_\bt_\br_\bi_\bn_\bg
- Refer to the most recent command starting with
- _\bs_\bt_\br_\bi_\bn_\bg.
- !\b!?\b?_\bs_\bt_\br_\bi_\bn_\bg[\b[?\b?]\b]
- Refer to the most recent command containing _\bs_\bt_\br_\bi_\bn_\bg.
- The trailing ?\b? may be omitted if _\bs_\bt_\br_\bi_\bn_\bg is followed
- immediately by a newline.
- ^\b^_\bs_\bt_\br_\bi_\bn_\bg_\b1^\b^_\bs_\bt_\br_\bi_\bn_\bg_\b2^\b^
- Quick substitution. Repeat the last command,
- replacing _\bs_\bt_\br_\bi_\bn_\bg_\b1 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\bdi\bif\bfi\bie\ber\brs\bs below).
- !\b!#\b# The entire command line typed so far.
-
- W\bWo\bor\brd\bd D\bDe\bes\bsi\big\bgn\bna\bat\bto\bor\brs\bs
- Word designators are used to select desired words from the
- event. A :\b: separates the event specification from the
- word designator. It may be omitted if the word designator
- begins with a ^\b^, $\b$, *\b*, -\b-, or %\b%. Words are numbered from
- the beginning of the line, with the first word being
- denoted by 0 (zero). Words are inserted into the current
- line separated by single spaces.
-
- 0\b0 (\b(z\bze\ber\bro\bo)\b)
- The zeroth word. For the shell, this is the com-
- mand word.
- _\bn The _\bnth word.
- ^\b^ The first argument. That is, word 1.
- $\b$ The last argument.
- %\b% The word matched by the most recent `?_\bs_\bt_\br_\bi_\bn_\bg?'
- search.
- _\bx-\b-_\by A range of words; `-_\by' abbreviates `0-_\by'.
- *\b* All of the words but the zeroth. This is a synonym
- for `_\b1_\b-_\b$'. It is not an error to use *\b* if there is
- just one word in the event; the empty string is
- returned in that case.
- x\bx*\b* Abbreviates _\bx_\b-_\b$.
- x\bx-\b- Abbreviates _\bx_\b-_\b$ like x\bx*\b*, but omits the last word.
-
- If a word designator is supplied without an event specifi-
- cation, the previous command is used as the event.
-
- M\bMo\bod\bdi\bif\bfi\bie\ber\brs\bs
- After the optional word designator, there may appear a
- sequence of one or more of the following modifiers, each
- preceded by a `:'.
-
- h\bh Remove a trailing file name component, leaving only
- the head.
- t\bt Remove all leading file name components, leaving
- the tail.
- r\br Remove a trailing suffix of the form _\b._\bx_\bx_\bx, leaving
- the basename.
- e\be Remove all but the trailing suffix.
- p\bp Print the new command but do not execute it.
-
-
-
-GNU History 4.3 2002 January 31 2
-
-
-
-
-
-HISTORY(3) HISTORY(3)
-
-
- q\bq Quote the substituted words, escaping further sub-
- stitutions.
- x\bx Quote the substituted words as with q\bq, but break
- into words at b\bbl\bla\ban\bnk\bks\bs and newlines.
- s\bs/\b/_\bo_\bl_\bd/\b/_\bn_\be_\bw/\b/
- Substitute _\bn_\be_\bw for the first occurrence of _\bo_\bl_\bd in
- the event line. Any delimiter can be used in place
- of /. The final delimiter is optional if it is the
- last character of the event line. The delimiter
- may be quoted in _\bo_\bl_\bd and _\bn_\be_\bw with a single back-
- slash. If & appears in _\bn_\be_\bw, it is replaced by _\bo_\bl_\bd.
- A single backslash will quote the &. If _\bo_\bl_\bd is
- null, it is set to the last _\bo_\bl_\bd substituted, or, if
- no previous history substitutions took place, the
- last _\bs_\bt_\br_\bi_\bn_\bg in a !\b!?\b?_\bs_\bt_\br_\bi_\bn_\bg[\b[?\b?]\b] search.
- &\b& Repeat the previous substitution.
- g\bg Cause changes to be applied over the entire event
- line. This is 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&'. If used with `:\b:s\bs', any
- delimiter can be used in place of /, and the final
- delimiter is optional if it is the last character
- of the event line.
-
-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
- This section describes how to use the History library in
- other programs.
-
- I\bIn\bnt\btr\bro\bod\bdu\buc\bct\bti\bio\bon\bn t\bto\bo H\bHi\bis\bst\bto\bor\bry\by
- The programmer using the History library has available
- functions for remembering lines on a history list, associ-
- ating arbitrary data with a line, removing lines from the
- list, searching through the list for a line containing an
- arbitrary text string, and referencing any line in the
- list directly. In addition, a history _\be_\bx_\bp_\ba_\bn_\bs_\bi_\bo_\bn function
- is available which provides for a consistent user inter-
- face across different programs.
-
- The user using programs written with the History library
- has the benefit of a consistent user interface with a set
- of well-known commands for manipulating the text of previ-
- ous lines and using that text in new commands. The basic
- history manipulation commands are identical to the history
- substitution provided by b\bba\bas\bsh\bh.
-
- If the programmer desires, he can use the Readline
- library, which includes some history manipulation by
- default, and has the added advantage of command line edit-
- ing.
-
- Before declaring any functions using any functionality the
- History library provides in other code, an application
- 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
- file that uses the History library's features. It sup-
- plies extern declarations for all of the library's public
-
-
-
-GNU History 4.3 2002 January 31 3
-
-
-
-
-
-HISTORY(3) HISTORY(3)
-
-
- functions and variables, and declares all of the public
- data structures.
-
-
- H\bHi\bis\bst\bto\bor\bry\by S\bSt\bto\bor\bra\bag\bge\be
- The history list is an array of history entries. A his-
- tory entry is declared as follows:
-
- _\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;
-
- typedef struct _hist_entry {
- char *line;
- histdata_t data;
- } HIST_ENTRY;
-
- The history list itself might therefore be declared as
-
- _\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;
-
- The state of the History library is encapsulated into a
- single structure:
-
- /*
- * A structure used to pass around the current state of the history.
- */
- typedef struct _hist_state {
- HIST_ENTRY **entries; /* Pointer to the entries themselves. */
- int offset; /* The location pointer within this array. */
- int length; /* Number of elements within this array. */
- int size; /* Number of slots allocated to this array. */
- int flags;
- } HISTORY_STATE;
-
- If the flags member includes H\bHS\bS_\b_S\bST\bTI\bIF\bFL\bLE\bED\bD, the history has
- been stifled.
-
-H\bHi\bis\bst\bto\bor\bry\by F\bFu\bun\bnc\bct\bti\bio\bon\bns\bs
- This section describes the calling sequence for the vari-
- ous functions exported by the GNU History library.
-
- 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
- This section describes functions used to initialize and
- manage the state of the History library when you want to
- use the history functions in your program.
-
- _\bv_\bo_\bi_\bd u\bus\bsi\bin\bng\bg_\b_h\bhi\bis\bst\bto\bor\bry\by (_\bv_\bo_\bi_\bd)
- Begin a session in which the history functions might be
- used. This initializes the interactive variables.
-
- _\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)
- Return a structure describing the current state of the
- input history.
-
- _\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)
-
-
-
-GNU History 4.3 2002 January 31 4
-
-
-
-
-
-HISTORY(3) HISTORY(3)
-
-
- Set the state of the history list according to _\bs_\bt_\ba_\bt_\be.
-
-
- H\bHi\bis\bst\bto\bor\bry\by L\bLi\bis\bst\bt M\bMa\ban\bna\bag\bge\bem\bme\ben\bnt\bt
- These functions manage individual entries on the history
- list, or set parameters managing the list itself.
-
- _\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)
- Place _\bs_\bt_\br_\bi_\bn_\bg at the end of the history list. The associ-
- ated data field (if any) is set to N\bNU\bUL\bLL\bL.
-
- _\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)
- Remove history entry at offset _\bw_\bh_\bi_\bc_\bh from the history.
- The removed element is returned so you can free the line,
- data, and containing structure.
-
- _\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_\bd_\ba_\bt_\ba_\b__\bt _\bd_\ba_\bt_\ba)
- Make the history entry at offset _\bw_\bh_\bi_\bc_\bh have _\bl_\bi_\bn_\be and _\bd_\ba_\bt_\ba.
- This returns the old entry so you can dispose of the data.
- In the case of an invalid _\bw_\bh_\bi_\bc_\bh, a N\bNU\bUL\bLL\bL pointer is
- returned.
-
- _\bv_\bo_\bi_\bd c\bcl\ble\bea\bar\br_\b_h\bhi\bis\bst\bto\bor\bry\by (_\bv_\bo_\bi_\bd)
- Clear the history list by deleting all the entries.
-
- _\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)
- Stifle the history list, remembering only the last _\bm_\ba_\bx
- entries.
-
- _\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)
- Stop stifling the history. This returns the previously-
- set maximum number of history entries (as set by s\bst\bti\bi-\b-
- f\bfl\ble\be_\b_h\bhi\bis\bst\bto\bor\bry\by(\b()\b)). history was stifled. The value is posi-
- tive if the history was stifled, negative if it wasn't.
-
- _\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)
- Returns non-zero if the history is stifled, zero if it is
- not.
-
-
- 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
- These functions return information about the entire his-
- tory list or individual list entries.
-
- _\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)
- 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 input history. Element 0 of this list is the
- beginning of time. If there is no history, return N\bNU\bUL\bLL\bL.
-
- _\bi_\bn_\bt w\bwh\bhe\ber\bre\be_\b_h\bhi\bis\bst\bto\bor\bry\by (_\bv_\bo_\bi_\bd)
- Returns the offset of the current history element.
-
- _\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)
-
-
-
-GNU History 4.3 2002 January 31 5
-
-
-
-
-
-HISTORY(3) HISTORY(3)
-
-
- Return the history entry at the current position, as
- determined by 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.
-
- _\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)
- Return the history entry at position _\bo_\bf_\bf_\bs_\be_\bt, starting from
- 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
- greater than the history length, return a N\bNU\bUL\bLL\bL pointer.
-
- _\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)
- Return the number of bytes that the primary history
- entries are using. This function returns the sum of the
- lengths of all the lines in the history.
-
-
- 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
- These functions allow the current index into the history
- list to be set or changed.
-
- _\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)
- Set the current history offset to _\bp_\bo_\bs, an absolute index
- into the list. Returns 1 on success, 0 if _\bp_\bo_\bs is less
- than zero or greater than the number of history entries.
-
- _\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)
- Back up the current history offset to the previous history
- entry, and return a pointer to that entry. If there is no
- previous entry, return a N\bNU\bUL\bLL\bL pointer.
-
- _\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)
- Move the current history offset forward to the next his-
- tory entry, and return the a pointer to that entry. If
- there is no next entry, return a N\bNU\bUL\bLL\bL pointer.
-
-
- 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
- These functions allow searching of the history list for
- entries containing a specific string. Searching may be
- performed both forward and backward from the current his-
- tory position. The search may be _\ba_\bn_\bc_\bh_\bo_\br_\be_\bd, meaning that
- the string must match at the beginning of the history
- entry.
-
- _\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)
- Search the history for _\bs_\bt_\br_\bi_\bn_\bg, starting at the current
- history offset. If _\bd_\bi_\br_\be_\bc_\bt_\bi_\bo_\bn is less than 0, then the
- search is through previous entries, otherwise through sub-
- sequent entries. If _\bs_\bt_\br_\bi_\bn_\bg is found, then the current
- history index is set to that history entry, and the value
- returned is the offset in the line of the entry where
- _\bs_\bt_\br_\bi_\bn_\bg was found. Otherwise, nothing is changed, and a -1
- is returned.
-
- _\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
-
-
-
-GNU History 4.3 2002 January 31 6
-
-
-
-
-
-HISTORY(3) HISTORY(3)
-
-
- _\bd_\bi_\br_\be_\bc_\bt_\bi_\bo_\bn)
- Search the history for _\bs_\bt_\br_\bi_\bn_\bg, starting at the current
- history offset. The search is anchored: matching lines
- must begin with _\bs_\bt_\br_\bi_\bn_\bg. If _\bd_\bi_\br_\be_\bc_\bt_\bi_\bo_\bn is less than 0, then
- the search is through previous entries, otherwise through
- subsequent entries. If _\bs_\bt_\br_\bi_\bn_\bg is found, then the current
- history index is set to that entry, and the return value
- is 0. Otherwise, nothing is changed, and a -1 is
- returned.
-
- _\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)
- Search for _\bs_\bt_\br_\bi_\bn_\bg in the history list, starting at _\bp_\bo_\bs, an
- absolute index into the list. If _\bd_\bi_\br_\be_\bc_\bt_\bi_\bo_\bn is negative,
- the search proceeds backward from _\bp_\bo_\bs, otherwise forward.
- Returns the absolute index of the history element where
- _\bs_\bt_\br_\bi_\bn_\bg was found, or -1 otherwise.
-
-
- 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
- The History library can read the history from and write it
- to a file. This section documents the functions for man-
- aging a history file.
-
- _\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)
- Add the contents of _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be to the history list, a line
- 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-
- _\bt_\bo_\br_\by. Returns 0 if successful, or e\ber\brr\brn\bno\bo if not.
-
- _\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)
- Read a range of lines from _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be, adding them to the
- history list. Start reading at line _\bf_\br_\bo_\bm and end at _\bt_\bo.
- If _\bf_\br_\bo_\bm is zero, start at the beginning. If _\bt_\bo is less
- than _\bf_\br_\bo_\bm, then read until the end of the file. If _\bf_\bi_\bl_\be_\b-
- _\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, or e\ber\brr\brn\bno\bo if not.
-
- _\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)
- Write the current history to _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be, overwriting _\bf_\bi_\bl_\be_\b-
- _\bn_\ba_\bm_\be if necessary. 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. Returns 0 on success, or
- e\ber\brr\brn\bno\bo on a read or write error.
-
-
- _\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)
- 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 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 a read or write error.
-
- _\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)
- Truncate the history file _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be, leaving only the last
- _\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
-
-
-
-GNU History 4.3 2002 January 31 7
-
-
-
-
-
-HISTORY(3) HISTORY(3)
-
-
- truncated. Returns 0 on success, or e\ber\brr\brn\bno\bo on failure.
-
-
- H\bHi\bis\bst\bto\bor\bry\by E\bEx\bxp\bpa\ban\bns\bsi\bio\bon\bn
- These functions implement history expansion.
-
- _\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)
- Expand _\bs_\bt_\br_\bi_\bn_\bg, placing the result into _\bo_\bu_\bt_\bp_\bu_\bt, a pointer
- to a string. Returns:
- 0 If no expansions took place (or, if the only
- change in the text was the removal of escape
- characters preceding the history expansion
- character);
- 1 if expansions did take place;
- -1 if there was an error in expansion;
- 2 if the returned line should be displayed,
- but not executed, as with the :\b:p\bp modifier.
- If an error ocurred in expansion, then _\bo_\bu_\bt_\bp_\bu_\bt contains a
- descriptive error message.
-
- _\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)
- Returns the text of the history event beginning at _\bs_\bt_\br_\bi_\bn_\bg
- + _\b*_\bc_\bi_\bn_\bd_\be_\bx. _\b*_\bc_\bi_\bn_\bd_\be_\bx is modified to point to after the
- event specifier. At function entry, _\bc_\bi_\bn_\bd_\be_\bx points to the
- index into _\bs_\bt_\br_\bi_\bn_\bg where the history event specification
- begins. _\bq_\bc_\bh_\ba_\br is a character that is allowed to end the
- event specification in addition to the ``normal'' termi-
- nating characters.
-
- _\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)
- Return an array of tokens parsed out of _\bs_\bt_\br_\bi_\bn_\bg, much as
- the shell might. The tokens are split on the characters
- 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
- conventions are obeyed.
-
- _\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)
- Extract a string segment consisting of the _\bf_\bi_\br_\bs_\bt through
- _\bl_\ba_\bs_\bt arguments 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).
-
-
- H\bHi\bis\bst\bto\bor\bry\by V\bVa\bar\bri\bia\bab\bbl\ble\bes\bs
- This section describes the externally-visible variables
- exported by the GNU History Library.
-
- _\bi_\bn_\bt h\bhi\bis\bst\bto\bor\bry\by_\b_b\bba\bas\bse\be
- The logical offset of the first entry in the history list.
-
- _\bi_\bn_\bt h\bhi\bis\bst\bto\bor\bry\by_\b_l\ble\ben\bng\bgt\bth\bh
- The number of entries currently stored in the history
- list.
-
-
-
-
-GNU History 4.3 2002 January 31 8
-
-
-
-
-
-HISTORY(3) HISTORY(3)
-
-
- _\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
- The maximum number of history entries. This must be
- changed using s\bst\bti\bif\bfl\ble\be_\b_h\bhi\bis\bst\bto\bor\bry\by(\b()\b).
-
- _\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
- The character that introduces a history event. The
- default is !\b!. Setting this to 0 inhibits history expan-
- sion.
-
- _\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
- The character that invokes word substitution if found at
- the start of a line. The default is ^\b^.
-
- _\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
- During tokenization, if this character is seen as the
- first character of a word, then it and all subsequent
- characters up to a newline are ignored, suppressing his-
- tory expansion for the remainder of the line. This is
- disabled by default.
-
- _\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
- The characters that separate tokens for h\bhi\bis\bst\bto\bor\bry\by_\b_t\bto\bok\bk-\b-
- 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".
-
- _\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
- The list of characters which inhibit history expansion if
- 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
- default is space, tab, newline, \\b\r\br, and =\b=.
-
- _\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
- The list of additional characters which can delimit a his-
- tory search string, in addition to space, tab, _\b: and _\b? in
- the case of a substring search. The default is empty.
-
- _\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
- If non-zero, single-quoted words are not scanned for the
- history expansion character. The default value is 0.
-
- _\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
- This should be set to the address of a function that takes
- two arguments: 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 should return a non-zero value if the
- history expansion starting at _\bs_\bt_\br_\bi_\bn_\bg_\b[_\bi_\b] should not be per-
- formed; zero if the expansion should be done. It is
- intended for use by applications like b\bba\bas\bsh\bh that use the
- history expansion character for additional purposes. By
- default, this variable is set to N\bNU\bUL\bLL\bL.
-
-F\bFI\bIL\bLE\bES\bS
- _\b~_\b/_\b._\bh_\bi_\bs_\bt_\bo_\br_\by
- Default filename for reading and writing saved his-
- tory
-
-
-
-
-
-GNU History 4.3 2002 January 31 9
-
-
-
-
-
-HISTORY(3) HISTORY(3)
-
-
-S\bSE\bEE\bE A\bAL\bLS\bSO\bO
- _\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
- _\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
- _\bb_\ba_\bs_\bh(1)
- _\br_\be_\ba_\bd_\bl_\bi_\bn_\be(3)
-
-A\bAU\bUT\bTH\bHO\bOR\bRS\bS
- Brian Fox, Free Software Foundation
- bfox@gnu.org
-
- Chet Ramey, Case Western Reserve University
- chet@ins.CWRU.Edu
-
-B\bBU\bUG\bG R\bRE\bEP\bPO\bOR\bRT\bTS\bS
- If you find a bug in the h\bhi\bis\bst\bto\bor\bry\by library, you should
- report it. But first, you should make sure that it really
- is a bug, and that it appears in the latest version of the
- h\bhi\bis\bst\bto\bor\bry\by library that you have.
-
- Once you have determined that a bug actually exists, mail
- 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,
- you are welcome to mail that as well! Suggestions and
- `philosophical' bug reports may be mailed to _\bb_\bu_\bg_\b-_\br_\be_\ba_\bd_\b-
- _\bl_\bi_\bn_\be@_\bg_\bn_\bu_\b._\bo_\br_\bg or posted to the Usenet newsgroup
- g\bgn\bnu\bu.\b.b\bba\bas\bsh\bh.\b.b\bbu\bug\bg.
-
- Comments and bug reports concerning this manual page
- should be directed to _\bc_\bh_\be_\bt_\b@_\bi_\bn_\bs_\b._\bC_\bW_\bR_\bU_\b._\bE_\bd_\bu.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-GNU History 4.3 2002 January 31 10
-
-
projects / binutils-gdb.git / commitdiff