HISTORY(3)                 Library Functions Manual                 HISTORY(3)



[1mNAME[0m
       history - GNU History Library

[1mCOPYRIGHT[0m
       The GNU History Library is Copyright (C) 1989-2014 by the Free Software
       Foundation, Inc.

[1mDESCRIPTION[0m
       Many programs read input from the user a line at a time.  The GNU  His-
       tory  library is able to keep track of those lines, associate arbitrary
       data with each line, and utilize information  from  previous  lines  in
       composing new ones.

[1mHISTORY EXPANSION[0m
       The  history library supports a history expansion feature that is iden-
       tical to the history expansion in [1mbash.  [22mThis  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 current 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  sec-
       ond  is  to select portions of that line for inclusion into the current
       one.  The line selected from the history is the [4mevent[24m, and the portions
       of  that  line  that  are  acted upon are [4mwords[24m.  Various [4mmodifiers[24m are
       available to manipulate the selected words.  The line  is  broken  into
       words in the same fashion as [1mbash [22mdoes when reading input, so that sev-
       eral words that would otherwise be separated are  considered  one  word
       when  surrounded  by  quotes (see the description of [1mhistory_tokenize()[0m
       below).  History expansions are introduced by  the  appearance  of  the
       history expansion character, which is [1m! [22mby default.  Only backslash ([1m\[22m)
       and single quotes can quote the history expansion character.

   [1mEvent Designators[0m
       An event designator is a reference to a command line entry in the  his-
       tory  list.   Unless  the reference is absolute, events are relative to
       the current position in the history list.

       [1m!      [22mStart a history substitution, except when followed by  a  [1mblank[22m,
              newline, = or (.
       [1m![4m[22mn[24m     Refer to command line [4mn[24m.
       [1m!-[4m[22mn[24m    Refer to the current command minus [4mn[24m.
       [1m!!     [22mRefer to the previous command.  This is a synonym for `!-1'.
       [1m![4m[22mstring[0m
              Refer  to the most recent command preceding the current position
              in the history list starting with [4mstring[24m.
       [1m!?[4m[22mstring[24m[1m[?][0m
              Refer to the most recent command preceding the current  position
              in  the  history  list containing [4mstring[24m.  The trailing [1m? [22mmay be
              omitted if [4mstring[24m is followed immediately by a newline.
       [1m^[4m[22mstring1[24m[1m^[4m[22mstring2[24m[1m^[0m
              Quick substitution.  Repeat the last command, replacing  [4mstring1[0m
              with [4mstring2[24m.  Equivalent to ``!!:s/[4mstring1[24m/[4mstring2[24m/'' (see [1mMod-[0m
              [1mifiers [22mbelow).
       [1m!#     [22mThe entire command line typed so far.

   [1mWord Designators[0m
       Word designators are used to select desired words from the event.  A  [1m:[0m
       separates  the event specification from the word designator.  It may be
       omitted if the word designator begins with a [1m^[22m, [1m$[22m, [1m*[22m, [1m-[22m, or  [1m%[22m.   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  sepa-
       rated by single spaces.

       [1m0 (zero)[0m
              The zeroth word.  For the shell, this is the command word.
       [4mn[24m      The [4mn[24mth word.
       [1m^      [22mThe first argument.  That is, word 1.
       [1m$      [22mThe  last  word.   This  is  usually the last argument, but will
              expand to the zeroth word if there is only one word in the line.
       [1m%      [22mThe word matched by the most recent `?[4mstring[24m?' search.
       [4mx[24m[1m-[4m[22my[24m    A range of words; `-[4my[24m' abbreviates `0-[4my[24m'.
       [1m*      [22mAll of the words but the zeroth.  This is a synonym  for  `[4m1-$[24m'.
              It  is  not  an  error to use [1m* [22mif there is just one word in the
              event; the empty string is returned in that case.
       [1mx*     [22mAbbreviates [4mx-$[24m.
       [1mx-     [22mAbbreviates [4mx-$[24m like [1mx*[22m, but omits the last word.

       If a word designator is supplied without an  event  specification,  the
       previous command is used as the event.

   [1mModifiers[0m
       After  the optional word designator, there may appear a sequence of one
       or more of the following modifiers, each preceded by a `:'.

       [1mh      [22mRemove a trailing file name component, leaving only the head.
       [1mt      [22mRemove all leading file name components, leaving the tail.
       [1mr      [22mRemove a trailing suffix of the form [4m.xxx[24m, leaving the basename.
       [1me      [22mRemove all but the trailing suffix.
       [1mp      [22mPrint the new command but do not execute it.
       [1mq      [22mQuote the substituted words, escaping further substitutions.
       [1mx      [22mQuote the substituted words as with [1mq[22m, but break into  words  at
              [1mblanks [22mand newlines.
       [1ms/[4m[22mold[24m[1m/[4m[22mnew[24m[1m/[0m
              Substitute  [4mnew[24m  for  the  first  occurrence of [4mold[24m 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 [4mold[24m and [4mnew[24m with a  single
              backslash.   If & appears in [4mnew[24m, it is replaced by [4mold[24m.  A sin-
              gle backslash will quote the &.  If [4mold[24m is null, it  is  set  to
              the  last  [4mold[24m substituted, or, if no previous history substitu-
              tions took place, the last [4mstring[24m in a [1m!?[4m[22mstring[24m[1m[?]  [22msearch.
       [1m&      [22mRepeat the previous substitution.
       [1mg      [22mCause changes to be applied over the entire event line.  This is
              used  in  conjunction  with `[1m:s[22m' (e.g., `[1m:gs/[4m[22mold[24m[1m/[4m[22mnew[24m[1m/[22m') or `[1m:&[22m'.
              If used with `[1m:s[22m', any delimiter can be used in place of /,  and
              the  final  delimiter is optional if it is the last character of
              the event line.  An [1ma [22mmay be used as a synonym for [1mg[22m.
       [1mG      [22mApply the following `[1ms[22m' modifier once to each word in the  event
              line.

[1mPROGRAMMING WITH HISTORY FUNCTIONS[0m
       This  section  describes  how  to use the History library in other pro-
       grams.

   [1mIntroduction to History[0m
       The programmer using the History library has  available  functions  for
       remembering  lines on a history list, associating 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 [4mexpansion[24m function is avail-
       able  which  provides  for a consistent user interface across different
       programs.

       The user using programs written with the History library has the  bene-
       fit  of  a  consistent user interface with a set of well-known commands
       for manipulating the text of previous lines and using that text in  new
       commands.  The basic history manipulation commands are identical to the
       history substitution provided by [1mbash[22m.

       If the programmer desires, he  can  use  the  Readline  library,  which
       includes some history manipulation by default, and has the added advan-
       tage of command line editing.

       Before declaring any functions  using  any  functionality  the  History
       library  provides  in  other code, an application writer should include
       the file  [4m<readline/history.h>[24m  in  any  file  that  uses  the  History
       library's  features.   It  supplies  extern declarations for all of the
       library's public functions and variables, and declares all of the  pub-
       lic data structures.


   [1mHistory Storage[0m
       The  history  list  is an array of history entries.  A history entry is
       declared as follows:

       [4mtypedef[24m [4mvoid[24m [4m*[24m [1mhistdata_t;[0m

       typedef struct _hist_entry {
         char *line;
         char *timestamp;
         histdata_t data;
       } HIST_ENTRY;

       The history list itself might therefore be declared as

       [4mHIST_ENTRY[24m [4m**[24m [1mthe_history_list;[0m

       The state of the History library is encapsulated into a  single  struc-
       ture:

       /*
        * 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 [1mHS_STIFLED[22m, the history has been stifled.

[1mHistory Functions[0m
       This  section  describes the calling sequence for the various functions
       exported by the GNU History library.

   [1mInitializing History and State Management[0m
       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.

       [4mvoid[24m [1musing_history [22m([4mvoid[24m)
       Begin a session in which the history functions  might  be  used.   This
       initializes the interactive variables.

       [4mHISTORY_STATE[24m [4m*[24m [1mhistory_get_history_state [22m([4mvoid[24m)
       Return a structure describing the current state of the input history.

       [4mvoid[24m [1mhistory_set_history_state [22m([4mHISTORY_STATE[24m [4m*state[24m)
       Set the state of the history list according to [4mstate[24m.


   [1mHistory List Management[0m
       These  functions  manage individual entries on the history list, or set
       parameters managing the list itself.

       [4mvoid[24m [1madd_history [22m([4mconst[24m [4mchar[24m [4m*string[24m)
       Place [4mstring[24m at the end of the history list.  The associated data field
       (if any) is set to [1mNULL[22m.

       [4mvoid[24m [1madd_history_time [22m([4mconst[24m [4mchar[24m [4m*string[24m)
       Change  the time stamp associated with the most recent history entry to
       [4mstring[24m.

       [4mHIST_ENTRY[24m [4m*[24m [1mremove_history [22m([4mint[24m [4mwhich[24m)
       Remove history entry at offset [4mwhich[24m from  the  history.   The  removed
       element  is  returned  so  you  can free the line, data, and containing
       structure.

       [4mhistdata_t[24m [1mfree_history_entry [22m([4mHIST_ENTRY[24m [4m*histent[24m)
       Free the history entry [4mhistent[24m and any  history  library  private  data
       associated with it.  Returns the application-specific data so the call-
       er can dispose of it.

       [4mHIST_ENTRY[24m [4m*[24m [1mreplace_history_entry [22m([4mint[24m [4mwhich,[24m [4mconst[24m [4mchar[24m [4m*line,[24m  [4mhist-[0m
       [4mdata_t[24m [4mdata[24m)
       Make  the  history  entry  at  offset  [4mwhich[24m  have [4mline[24m and [4mdata[24m.  This
       returns the old entry so the caller can dispose of any application-spe-
       cific  data.   In  the  case  of  an  invalid  [4mwhich[24m, a [1mNULL [22mpointer is
       returned.

       [4mvoid[24m [1mclear_history [22m([4mvoid[24m)
       Clear the history list by deleting all the entries.

       [4mvoid[24m [1mstifle_history [22m([4mint[24m [4mmax[24m)
       Stifle the history list, remembering only the last [4mmax[24m entries.

       [4mint[24m [1munstifle_history [22m([4mvoid[24m)
       Stop stifling the history.  This  returns  the  previously-set  maximum
       number  of  history  entries (as set by [1mstifle_history()[22m).  history was
       stifled.  The value is positive if the history was stifled, negative if
       it wasn't.

       [4mint[24m [1mhistory_is_stifled [22m([4mvoid[24m)
       Returns non-zero if the history is stifled, zero if it is not.


   [1mInformation About the History List[0m
       These  functions  return  information  about the entire history list or
       individual list entries.

       [4mHIST_ENTRY[24m [4m**[24m [1mhistory_list [22m([4mvoid[24m)
       Return a [1mNULL [22mterminated array of [4mHIST_ENTRY[24m [4m*[24m  which  is  the  current
       input  history.   Element  0 of this list is the beginning of time.  If
       there is no history, return [1mNULL[22m.

       [4mint[24m [1mwhere_history [22m([4mvoid[24m)
       Returns the offset of the current history element.

       [4mHIST_ENTRY[24m [4m*[24m [1mcurrent_history [22m([4mvoid[24m)
       Return the history entry at the  current  position,  as  determined  by
       [1mwhere_history()[22m.  If there is no entry there, return a [1mNULL [22mpointer.

       [4mHIST_ENTRY[24m [4m*[24m [1mhistory_get [22m([4mint[24m [4moffset[24m)
       Return  the  history  entry  at  position  [4moffset[24m,  starting  from [1mhis-[0m
       [1mtory_base[22m.  If there is no entry there, or if [4moffset[24m  is  greater  than
       the history length, return a [1mNULL [22mpointer.

       [4mtime_t[24m [1mhistory_get_time [22m([4mHIST_ENTRY[24m [4m*[24m)
       Return  the  time stamp associated with the history entry passed as the
       argument.

       [4mint[24m [1mhistory_total_bytes [22m([4mvoid[24m)
       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.


   [1mMoving Around the History List[0m
       These functions allow the current index into the history list to be set
       or changed.

       [4mint[24m [1mhistory_set_pos [22m([4mint[24m [4mpos[24m)
       Set the current history offset to [4mpos[24m, an absolute index into the list.
       Returns 1 on success, 0 if [4mpos[24m is less than zero or  greater  than  the
       number of history entries.

       [4mHIST_ENTRY[24m [4m*[24m [1mprevious_history [22m([4mvoid[24m)
       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 [1mNULL [22mpointer.

       [4mHIST_ENTRY[24m [4m*[24m [1mnext_history [22m([4mvoid[24m)
       If  the  current history offset refers to a valid history entry, incre-
       ment the current history offset.  If the  possibly-incremented  history
       offset refers to a valid history entry, return a pointer to that entry;
       otherwise, return a [1mNULL [22mpointer.


   [1mSearching the History List[0m
       These functions allow searching of the history list  for  entries  con-
       taining a specific string.  Searching may be performed both forward and
       backward  from  the  current  history  position.   The  search  may  be
       [4manchored[24m,  meaning  that  the string must match at the beginning of the
       history entry.

       [4mint[24m [1mhistory_search [22m([4mconst[24m [4mchar[24m [4m*string,[24m [4mint[24m [4mdirection[24m)
       Search the history for [4mstring[24m, starting at the current history  offset.
       If  [4mdirection[24m  is  less  than  0,  then  the search is through previous
       entries, otherwise through subsequent entries.   If  [4mstring[24m  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 [4mstring[24m  was
       found.  Otherwise, nothing is changed, and a -1 is returned.

       [4mint[24m [1mhistory_search_prefix [22m([4mconst[24m [4mchar[24m [4m*string,[24m [4mint[24m [4mdirection[24m)
       Search  the history for [4mstring[24m, starting at the current history offset.
       The search is anchored: matching lines  must  begin  with  [4mstring[24m.   If
       [4mdirection[24m  is less than 0, then the search is through previous entries,
       otherwise through subsequent entries.  If [4mstring[24m  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.

       [4mint[24m [1mhistory_search_pos [22m([4mconst[24m [4mchar[24m [4m*string,[24m [4mint[24m [4mdirection,[24m [4mint[24m [4mpos[24m)
       Search for [4mstring[24m in the history list, starting  at  [4mpos[24m,  an  absolute
       index  into  the  list.   If [4mdirection[24m is negative, the search proceeds
       backward from [4mpos[24m, otherwise forward.  Returns the  absolute  index  of
       the history element where [4mstring[24m was found, or -1 otherwise.


   [1mManaging the History File[0m
       The  History  library can read the history from and write it to a file.
       This section documents the functions for managing a history file.

       [4mint[24m [1mread_history [22m([4mconst[24m [4mchar[24m [4m*filename[24m)
       Add the contents of [4mfilename[24m to the history list, a line at a time.  If
       [4mfilename[24m  is [1mNULL[22m, then read from [4m~/.history[24m.  Returns 0 if successful,
       or [1merrno [22mif not.

       [4mint[24m [1mread_history_range [22m([4mconst[24m [4mchar[24m [4m*filename,[24m [4mint[24m [4mfrom,[24m [4mint[24m [4mto[24m)
       Read a range of lines from [4mfilename[24m, adding them to the  history  list.
       Start  reading  at  line [4mfrom[24m and end at [4mto[24m.  If [4mfrom[24m is zero, start at
       the beginning.  If [4mto[24m is less than [4mfrom[24m, then read until the end of the
       file.   If  [4mfilename[24m  is [1mNULL[22m, then read from [4m~/.history[24m.  Returns 0 if
       successful, or [1merrno [22mif not.

       [4mint[24m [1mwrite_history [22m([4mconst[24m [4mchar[24m [4m*filename[24m)
       Write the current history to [4mfilename[24m, overwriting [4mfilename[24m  if  neces-
       sary.   If [4mfilename[24m is [1mNULL[22m, then write the history list to [4m~/.history[24m.
       Returns 0 on success, or [1merrno [22mon a read or write error.


       [4mint[24m [1mappend_history [22m([4mint[24m [4mnelements,[24m [4mconst[24m [4mchar[24m [4m*filename[24m)
       Append the last [4mnelements[24m of the history list to [4mfilename[24m.  If [4mfilename[0m
       is  [1mNULL[22m, then append to [4m~/.history[24m.  Returns 0 on success, or [1merrno [22mon
       a read or write error.

       [4mint[24m [1mhistory_truncate_file [22m([4mconst[24m [4mchar[24m [4m*filename,[24m [4mint[24m [4mnlines[24m)
       Truncate the history file [4mfilename[24m, leaving only the last [4mnlines[24m lines.
       If  [4mfilename[24m  is [1mNULL[22m, then [4m~/.history[24m is truncated.  Returns 0 on suc-
       cess, or [1merrno [22mon failure.


   [1mHistory Expansion[0m
       These functions implement history expansion.

       [4mint[24m [1mhistory_expand [22m([4mchar[24m [4m*string,[24m [4mchar[24m [4m**output[24m)
       Expand [4mstring[24m, placing the result into [4moutput[24m, 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 exe-
                     cuted, as with the [1m:p [22mmodifier.
       If an error ocurred in expansion, then [4moutput[24m  contains  a  descriptive
       error message.

       [4mchar[24m [4m*[24m [1mget_history_event [22m([4mconst[24m [4mchar[24m [4m*string,[24m [4mint[24m [4m*cindex,[24m [4mint[24m [4mqchar[24m)
       Returns  the  text  of the history event beginning at [4mstring[24m + [4m*cindex[24m.
       [4m*cindex[24m is modified to point to after the event specifier.  At function
       entry,  [4mcindex[24m  points to the index into [4mstring[24m where the history event
       specification begins.  [4mqchar[24m is a character that is allowed to end  the
       event  specification  in addition to the ``normal'' terminating charac-
       ters.

       [4mchar[24m [4m**[24m [1mhistory_tokenize [22m([4mconst[24m [4mchar[24m [4m*string[24m)
       Return an array of tokens parsed out  of  [4mstring[24m,  much  as  the  shell
       might.    The   tokens   are  split  on  the  characters  in  the  [1mhis-[0m
       [1mtory_word_delimiters  [22mvariable,  and  shell  quoting  conventions   are
       obeyed.

       [4mchar[24m [4m*[24m [1mhistory_arg_extract [22m([4mint[24m [4mfirst,[24m [4mint[24m [4mlast,[24m [4mconst[24m [4mchar[24m [4m*string[24m)
       Extract a string segment consisting of the [4mfirst[24m through [4mlast[24m arguments
       present in [4mstring[24m.  Arguments are split using [1mhistory_tokenize()[22m.


   [1mHistory Variables[0m
       This section describes the externally-visible variables exported by the
       GNU History Library.

       [4mint[24m [1mhistory_base[0m
       The logical offset of the first entry in the history list.

       [4mint[24m [1mhistory_length[0m
       The number of entries currently stored in the history list.

       [4mint[24m [1mhistory_max_entries[0m
       The maximum number of history entries.  This must be changed using [1msti-[0m
       [1mfle_history()[22m.

       [4mint[24m [1mhistory_wite_timestamps[0m
       If non-zero, timestamps are written to the history file, so they can be
       preserved between sessions.  The default value is 0, meaning that time-
       stamps are not saved.  The current timestamp format uses the  value  of
       [4mhistory_comment_char[24m  to delimit timestamp entries in the history file.
       If that variable does not have a value (the default),  timestamps  will
       not be written.

       [4mchar[24m [1mhistory_expansion_char[0m
       The character that introduces a history event.  The default is [1m![22m.  Set-
       ting this to 0 inhibits history expansion.

       [4mchar[24m [1mhistory_subst_char[0m
       The character that invokes word substitution if found at the start of a
       line.  The default is [1m^[22m.

       [4mchar[24m [1mhistory_comment_char[0m
       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  history expansion for the remainder of the line.
       This is disabled by default.

       [4mchar[24m [4m*[24m [1mhistory_word_delimiters[0m
       The  characters  that  separate  tokens  for  [1mhistory_tokenize()[22m.   The
       default value is [1m" \t\n()<>;&|"[22m.

       [4mchar[24m [4m*[24m [1mhistory_no_expand_chars[0m
       The list of characters which inhibit history expansion if found immedi-
       ately following [1mhistory_expansion_char[22m.  The  default  is  space,  tab,
       newline, [1m\r[22m, and [1m=[22m.

       [4mchar[24m [4m*[24m [1mhistory_search_delimiter_chars[0m
       The  list  of  additional characters which can delimit a history search
       string, in addition to space, tab, [4m:[24m and [4m?[24m in the case of  a  substring
       search.  The default is empty.

       [4mint[24m [1mhistory_quotes_inhibit_expansion[0m
       If non-zero, double-quoted words are not scanned for the history expan-
       sion character or the history comment character.  The default value  is
       0.

       [4mrl_linebuf_func_t[24m [4m*[24m [1mhistory_inhibit_expansion_function[0m
       This  should  be  set to the address of a function that takes two argu-
       ments: a [1mchar * [22m([4mstring[24m) and an [1mint [22mindex into  that  string  ([4mi[24m).   It
       should  return  a  non-zero  value if the history expansion starting at
       [4mstring[i][24m should not be performed; zero  if  the  expansion  should  be
       done.   It  is  intended for use by applications like [1mbash [22mthat use the
       history expansion character for additional purposes.  By default,  this
       variable is set to [1mNULL[22m.

[1mFILES[0m
       [4m~/.history[0m
              Default filename for reading and writing saved history

[1mSEE ALSO[0m
       [4mThe[24m [4mGnu[24m [4mReadline[24m [4mLibrary[24m, Brian Fox and Chet Ramey
       [4mThe[24m [4mGnu[24m [4mHistory[24m [4mLibrary[24m, Brian Fox and Chet Ramey
       [4mbash[24m(1)
       [4mreadline[24m(3)

[1mAUTHORS[0m
       Brian Fox, Free Software Foundation
       bfox@gnu.org

       Chet Ramey, Case Western Reserve University
       chet.ramey@case.edu

[1mBUG REPORTS[0m
       If  you  find  a bug in the [1mhistory [22mlibrary, 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 [1mhistory [22mlibrary that you have.

       Once  you have determined that a bug actually exists, mail a bug report
       to [4mbug-readline[24m@[4mgnu.org[24m.  If you have a fix, you are  welcome  to  mail
       that  as  well!   Suggestions  and  `philosophical'  bug reports may be
       mailed to  [4mbug-readline[24m@[4mgnu.org[24m  or  posted  to  the  Usenet  newsgroup
       [1mgnu.bash.bug[22m.

       Comments and bug reports concerning this manual page should be directed
       to [4mchet.ramey@case.edu[24m.



GNU History 6.3                   2015 May 24                       HISTORY(3)
