[BACK]Return to history.3 CVS log [TXT] [DIR] Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / readline / doc

Diff for /embedaddon/readline/doc/history.3 between versions 1.1 and 1.1.1.2

version 1.1, 2014/07/30 08:16:45 version 1.1.1.2, 2021/03/17 01:01:01
Line 6 Line 6
 .\"     Case Western Reserve University  .\"     Case Western Reserve University
 .\"     chet.ramey@case.edu  .\"     chet.ramey@case.edu
 .\"  .\"
.\"     Last Change: Thu Thu Jun 27 10:34:44 EDT 2013.\"     Last Change: Fri Jul 17 09:43:01 EDT 2020
 .\"  .\"
.TH HISTORY 3 "2013 June 27" "GNU History 6.3".TH HISTORY 3 "2020 July 17" "GNU History 8.1"
 .\"  .\"
 .\" File Name macro.  This used to be `.PN', for Path Name,  .\" File Name macro.  This used to be `.PN', for Path Name,
 .\" but Sun doesn't seem to like that very much.  .\" but Sun doesn't seem to like that very much.
Line 40 Line 40
 .SH NAME  .SH NAME
 history \- GNU History Library  history \- GNU History Library
 .SH COPYRIGHT  .SH COPYRIGHT
.if t The GNU History Library is Copyright \(co 1989-2011 by the Free Software Foundation, Inc..if t The GNU History Library is Copyright \(co 1989-2020 by the Free Software Foundation, Inc.
.if n The GNU History Library is Copyright (C) 1989-2011 by the Free Software Foundation, Inc..if n The GNU History Library is Copyright (C) 1989-2020 by the Free Software Foundation, Inc.
 .SH DESCRIPTION  .SH DESCRIPTION
 Many programs read input from the user a line at a time.  The GNU  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  History library is able to keep track of those lines, associate arbitrary
Line 49  data with each line, and utilize information from prev Line 49  data with each line, and utilize information from prev
 composing new ones.   composing new ones. 
 .PP  .PP
 .SH "HISTORY EXPANSION"  .SH "HISTORY EXPANSION"
 .PP  
 The history library supports a history expansion feature that  The history library supports a history expansion feature that
 is identical to the history expansion in  is identical to the history expansion in
 .BR bash.  .BR bash.
Line 80  history expansion character, which is \^\fB!\fP\^ by d Line 79  history expansion character, which is \^\fB!\fP\^ by d
 Only backslash (\^\fB\e\fP\^) and single quotes can quote  Only backslash (\^\fB\e\fP\^) and single quotes can quote
 the history expansion character.  the history expansion character.
 .SS Event Designators  .SS Event Designators
 .PP  
 An event designator is a reference to a command line entry in the  An event designator is a reference to a command line entry in the
 history list.  history list.
 Unless the reference is absolute, events are relative to the current  Unless the reference is absolute, events are relative to the current
Line 118  containing Line 116  containing
 The trailing \fB?\fP may be omitted if  The trailing \fB?\fP may be omitted if
 .I string  .I string
 is followed immediately by a newline.  is followed immediately by a newline.
   If \fIstring\fP is missing, the string from the most recent search is used;
   it is an error if there is no previous search string.
 .TP  .TP
 .B \d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u  .B \d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u
 Quick substitution.  Repeat the last command, replacing  Quick substitution.  Repeat the last command, replacing
Line 125  Quick substitution.  Repeat the last command, replacin Line 125  Quick substitution.  Repeat the last command, replacin
 with  with
 .IR string2 .  .IR string2 .
 Equivalent to  Equivalent to
``!!:s/\fIstring1\fP/\fIstring2\fP/''``!!:s\d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u''
 (see \fBModifiers\fP below).  (see \fBModifiers\fP below).
 .TP  .TP
 .B !#  .B !#
 The entire command line typed so far.  The entire command line typed so far.
 .PD  .PD
 .SS Word Designators  .SS Word Designators
 .PP  
 Word designators are used to select desired words from the event.  Word designators are used to select desired words from the event.
A A
 .B :  .B :
 separates the event specification from the word designator.  separates the event specification from the word designator.
 It may be omitted if the word designator begins with a  It may be omitted if the word designator begins with a
Line 165  The last word.  This is usually the last argument, but Line 164  The last word.  This is usually the last argument, but
 zeroth word if there is only one word in the line.  zeroth word if there is only one word in the line.
 .TP  .TP
 .B %  .B %
The word matched by the most recent `?\fIstring\fR?' search.The first word matched by the most recent `?\fIstring\fR?' search,
 if the search string begins with a character that is part of a word.
 .TP  .TP
 .I x\fB\-\fPy  .I x\fB\-\fPy
 A range of words; `\-\fIy\fR' abbreviates `0\-\fIy\fR'.  A range of words; `\-\fIy\fR' abbreviates `0\-\fIy\fR'.
Line 182  Abbreviates \fIx\-$\fP. Line 182  Abbreviates \fIx\-$\fP.
 .TP  .TP
 .B x\-  .B x\-
 Abbreviates \fIx\-$\fP like \fBx*\fP, but omits the last word.  Abbreviates \fIx\-$\fP like \fBx*\fP, but omits the last word.
   If \fBx\fP is missing, it defaults to 0.
 .PD  .PD
 .PP  .PP
 If a word designator is supplied without an event specification, the  If a word designator is supplied without an event specification, the
 previous command is used as the event.  previous command is used as the event.
 .SS Modifiers  .SS Modifiers
 .PP  
 After the optional word designator, there may appear a sequence of  After the optional word designator, there may appear a sequence of
 one or more of the following modifiers, each preceded by a `:'.  one or more of the following modifiers, each preceded by a `:'.
   These modify, or edit, the word or words selected from the history event.
 .PP  .PP
 .PD 0  .PD 0
 .PP  .PP
Line 219  Quote the substituted words as with Line 220  Quote the substituted words as with
 but break into words at  but break into words at
 .B blanks  .B blanks
 and newlines.  and newlines.
   The \fBq\fP and \fBx\fP modifiers are mutually exclusive; the last one
   supplied is used.
 .TP  .TP
 .B s/\fIold\fP/\fInew\fP/  .B s/\fIold\fP/\fInew\fP/
 Substitute  Substitute
 .I new  .I new
 for the first occurrence of  for the first occurrence of
 .I old  .I old
in the event line.  Any delimiter can be used in place of /.  Thein the event line.
final delimiter is optional if it is the last character of theAny character may be used as the delimiter in place of /.
event line.  The delimiter may be quoted inThe final delimiter is optional if it is the last character of the
 event line.
 The delimiter may be quoted in
 .I old  .I old
 and  and
 .I new  .I new
Line 235  with a single backslash.  If & appears in Line 240  with a single backslash.  If & appears in
 .IR new ,  .IR new ,
 it is replaced by  it is replaced by
 .IR old .  .IR old .
A single backslash will quote the &.  IfA single backslash will quote the &.
 If
 .I old  .I old
 is null, it is set to the last  is null, it is set to the last
 .I old  .I old
Line 245  the last Line 251  the last
 in a  in a
 .B !?\fIstring\fR\fB[?]\fR  .B !?\fIstring\fR\fB[?]\fR
 search.  search.
   If
   .I new
   is null, each matching
   .I old
   is deleted.
 .TP  .TP
 .B &  .B &
 Repeat the previous substitution.  Repeat the previous substitution.
Line 259  if it is the last character of the event line. Line 270  if it is the last character of the event line.
 An \fBa\fP may be used as a synonym for \fBg\fP.  An \fBa\fP may be used as a synonym for \fBg\fP.
 .TP  .TP
 .B G  .B G
Apply the following `\fBs\fP' modifier once to each word in the event line.Apply the following `\fBs\fP' or `\fB&\fP' modifier once to each word
 in the event line.
 .PD  .PD
 .SH "PROGRAMMING WITH HISTORY FUNCTIONS"  .SH "PROGRAMMING WITH HISTORY FUNCTIONS"
 This section describes how to use the History library in other programs.  This section describes how to use the History library in other programs.
 .SS Introduction to History  .SS Introduction to History
.PPA programmer using the History library has available functions
The programmer using the History library has available functions 
 for remembering lines on a history list, associating arbitrary data  for remembering lines on a history list, associating arbitrary data
 with a line, removing lines from the list, searching through the list  with a line, removing lines from the list, searching through the list
 for a line containing an arbitrary text string, and referencing any line  for a line containing an arbitrary text string, and referencing any line
Line 280  in new commands.  The basic history manipulation comma Line 291  in new commands.  The basic history manipulation comma
 identical to  identical to
 the history substitution provided by \fBbash\fP.  the history substitution provided by \fBbash\fP.
 .PP  .PP
If the programmer desires, he can use the Readline library, whichThe programmer can also use the Readline library, which
 includes some history manipulation by default, and has the added  includes some history manipulation by default, and has the added
 advantage of command line editing.  advantage of command line editing.
 .PP  .PP
Line 292  in any file that uses the Line 303  in any file that uses the
 History library's features.  It supplies extern declarations for all  History library's features.  It supplies extern declarations for all
 of the library's public functions and variables, and declares all of  of the library's public functions and variables, and declares all of
 the public data structures.  the public data structures.
   
 .SS History Storage  .SS History Storage
 .PP  
 The history list is an array of history entries.  A history entry is  The history list is an array of history entries.  A history entry is
 declared as follows:  declared as follows:
 .PP  .PP
Line 330  typedef struct _hist_state { Line 339  typedef struct _hist_state {
 If the flags member includes \fBHS_STIFLED\fP, the history has been  If the flags member includes \fBHS_STIFLED\fP, the history has been
 stifled.  stifled.
 .SH "History Functions"  .SH "History Functions"
 .PP  
 This section describes the calling sequence for the various functions  This section describes the calling sequence for the various functions
 exported by the GNU History library.  exported by the GNU History library.
 .SS Initializing History and State Management  .SS Initializing History and State Management
Line 349  Return a structure describing the current state of the Line 357  Return a structure describing the current state of the
 Set the state of the history list according to \fIstate\fP.  Set the state of the history list according to \fIstate\fP.
   
 .SS History List Management  .SS History List Management
   
 These functions manage individual entries on the history list, or set  These functions manage individual entries on the history list, or set
 parameters managing the list itself.  parameters managing the list itself.
   
 .Fn1 void add_history "const char *string"  .Fn1 void add_history "const char *string"
 Place \fIstring\fP at the end of the history list.  The associated data  Place \fIstring\fP at the end of the history list.  The associated data
 field (if any) is set to \fBNULL\fP.  field (if any) is set to \fBNULL\fP.
   If the maximum number of history entries has been set using
   \fBstifle_history()\fP, and the new number of history entries would exceed
   that maximum, the oldest history entry is removed.
   
 .Fn1 void add_history_time "const char *string"  .Fn1 void add_history_time "const char *string"
 Change the time stamp associated with the most recent history entry to  Change the time stamp associated with the most recent history entry to
Line 382  Clear the history list by deleting all the entries. Line 392  Clear the history list by deleting all the entries.
   
 .Fn1 void stifle_history "int max"  .Fn1 void stifle_history "int max"
 Stifle the history list, remembering only the last \fImax\fP entries.  Stifle the history list, remembering only the last \fImax\fP entries.
   The history list will contain only \fImax\fP entries at a time.
   
 .Fn1 int unstifle_history "void"  .Fn1 int unstifle_history "void"
 Stop stifling the history.  This returns the previously-set  Stop stifling the history.  This returns the previously-set
Line 411  Return the history entry at the current position, as d Line 422  Return the history entry at the current position, as d
 pointer.  pointer.
   
 .Fn1 "HIST_ENTRY *" history_get "int offset"  .Fn1 "HIST_ENTRY *" history_get "int offset"
Return the history entry at position \fIoffset\fP, starting fromReturn the history entry at position \fIoffset\fP.
\fBhistory_base\fP.The range of valid values of \fIoffset\fP starts at \fBhistory_base\fP
If there is no entry there, or if \fIoffset\fPand ends at \fBhistory_length\fP \- 1.
is greater than the history length, return a \fBNULL\fP pointer.If there is no entry there, or if \fIoffset\fP is outside the valid
 range, return a \fBNULL\fP pointer.
   
 .Fn1 "time_t" history_get_time "HIST_ENTRY *"  .Fn1 "time_t" history_get_time "HIST_ENTRY *"
 Return the time stamp associated with the history entry passed as the argument.  Return the time stamp associated with the history entry passed as the argument.
Line 441  return a pointer to that entry.  If there is no previo Line 453  return a pointer to that entry.  If there is no previo
 a \fBNULL\fP pointer.  a \fBNULL\fP pointer.
   
 .Fn1 "HIST_ENTRY *" next_history "void"  .Fn1 "HIST_ENTRY *" next_history "void"
Move the current history offset forward to the next history entry, andIf the current history offset refers to a valid history entry,
return the a pointer to that entry.  If there is no next entry, returnincrement the current history offset.
a \fBNULL\fP pointer.If the possibly-incremented history offset refers to a valid history
 entry, return a pointer to that entry;
 otherwise, return a \fBNULL\fP pointer.
   
 .SS Searching the History List  .SS Searching the History List
   
Line 538  if the returned line should be displayed, but not exec Line 552  if the returned line should be displayed, but not exec
 as with the \fB:p\fP modifier.  as with the \fB:p\fP modifier.
 .PD  .PD
 .RE  .RE
If an error ocurred in expansion, then \fIoutput\fP contains a descriptiveIf an error occurred in expansion, then \fIoutput\fP contains a descriptive
 error message.  error message.
   
 .Fn3 "char *" get_history_event "const char *string" "int *cindex" "int qchar"  .Fn3 "char *" get_history_event "const char *string" "int *cindex" "int qchar"
Line 576  The number of entries currently stored in the history  Line 590  The number of entries currently stored in the history 
 The maximum number of history entries.  This must be changed using  The maximum number of history entries.  This must be changed using
 \fBstifle_history()\fP.  \fBstifle_history()\fP.
   
.Vb int history_wite_timestamps.Vb int history_write_timestamps
 If non-zero, timestamps are written to the history file, so they can be  If non-zero, timestamps are written to the history file, so they can be
 preserved between sessions.  The default value is 0, meaning that  preserved between sessions.  The default value is 0, meaning that
 timestamps are not saved.  timestamps are not saved.
Line 613  string, in addition to space, tab, \fI:\fP and \fI?\fP Line 627  string, in addition to space, tab, \fI:\fP and \fI?\fP
 a substring search.  The default is empty.  a substring search.  The default is empty.
   
 .Vb int history_quotes_inhibit_expansion  .Vb int history_quotes_inhibit_expansion
If non-zero, single-quoted words are not scanned for the history expansionIf non-zero, double-quoted words are not scanned for the history expansion
character.  The default value is 0.character or the history comment character.  The default value is 0.
   
 .Vb "rl_linebuf_func_t *" history_inhibit_expansion_function  .Vb "rl_linebuf_func_t *" history_inhibit_expansion_function
 This should be set to the address of a function that takes two arguments:  This should be set to the address of a function that takes two arguments:
Removed from v.1.1  
changed lines
  Added in v.1.1.1.2

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>