--- /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 / thirdparty / binutils-gdb.git / blobdiff