.\" Chet Ramey
.\" Information Network Services
.\" Case Western Reserve University
-.\" chet@ins.CWRU.Edu
+.\" chet.ramey@case.edu
.\"
-.\" Last Change: Thu Jan 31 16:08:07 EST 2002
+.\" Last Change: Sun May 24 18:01:17 EDT 2015
.\"
-.TH HISTORY 3 "2002 January 31" "GNU History 4.3"
+.TH HISTORY 3 "2015 May 24" "GNU History 6.3"
.\"
.\" File Name macro. This used to be `.PN', for Path Name,
.\" but Sun doesn't seem to like that very much.
.SH NAME
history \- GNU History Library
.SH COPYRIGHT
-.if t The GNU History Library is Copyright \(co 1989-2002 by the Free Software Foundation, Inc.
-.if n The GNU History Library is Copyright (C) 1989-2002 by the Free Software Foundation, Inc.
+.if t The GNU History Library is Copyright \(co 1989-2014 by the Free Software Foundation, Inc.
+.if n The GNU History Library is Copyright (C) 1989-2014 by the Free Software Foundation, Inc.
.SH DESCRIPTION
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
.PP
An event designator is a reference to a command line entry in the
history list.
+Unless the reference is absolute, events are relative to the current
+position in the history list.
.PP
.PD 0
.TP
.IR n .
.TP
.B !\-\fIn\fR
-Refer to the current command line minus
+Refer to the current command minus
.IR n .
.TP
.B !!
Refer to the previous command. This is a synonym for `!\-1'.
.TP
.B !\fIstring\fR
-Refer to the most recent command starting with
+Refer to the most recent command
+preceding the current position in the history list
+starting with
.IR string .
.TP
.B !?\fIstring\fR\fB[?]\fR
-Refer to the most recent command containing
+Refer to the most recent command
+preceding the current position in the history list
+containing
.IR string .
The trailing \fB?\fP may be omitted if
.I string
.SS Word Designators
.PP
Word designators are used to select desired words from the event.
-A
+A
.B :
separates the event specification from the word designator.
It may be omitted if the word designator begins with a
The first argument. That is, word 1.
.TP
.B $
-The last argument.
+The last word. This is usually the last argument, but will expand to the
+zeroth word if there is only one word in the line.
.TP
.B %
The word matched by the most recent `?\fIstring\fR?' search.
`\fB:s\fP', 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 \fBa\fP may be used as a synonym for \fBg\fP.
+.TP
+.B G
+Apply the following `\fBs\fP' modifier once to each word in the event line.
.PD
.SH "PROGRAMMING WITH HISTORY FUNCTIONS"
This section describes how to use the History library in other programs.
.nf
typedef struct _hist_entry {
char *line;
+ char *timestamp;
histdata_t data;
} HIST_ENTRY;
.fi
Place \fIstring\fP at the end of the history list. The associated data
field (if any) is set to \fBNULL\fP.
+.Fn1 void add_history_time "const char *string"
+Change the time stamp associated with the most recent history entry to
+\fIstring\fP.
+
.Fn1 "HIST_ENTRY *" remove_history "int which"
Remove history entry at offset \fIwhich\fP from the history. The
removed element is returned so you can free the line, data,
and containing structure.
+.Fn1 "histdata_t" free_history_entry "HIST_ENTRY *histent"
+Free the history entry \fIhistent\fP and any history library private
+data associated with it. Returns the application-specific data
+so the caller can dispose of it.
+
.Fn3 "HIST_ENTRY *" replace_history_entry "int which" "const char *line" "histdata_t data"
Make the history entry at offset \fIwhich\fP have \fIline\fP and \fIdata\fP.
-This returns the old entry so you can dispose of the data. In the case
+This returns the old entry so the caller can dispose of any
+application-specific data. In the case
of an invalid \fIwhich\fP, a \fBNULL\fP pointer is returned.
.Fn1 void clear_history "void"
If there is no entry there, or if \fIoffset\fP
is greater than the history length, return a \fBNULL\fP pointer.
+.Fn1 "time_t" history_get_time "HIST_ENTRY *"
+Return the time stamp associated with the history entry passed as the argument.
+
.Fn1 int history_total_bytes "void"
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
a \fBNULL\fP pointer.
.Fn1 "HIST_ENTRY *" next_history "void"
-Move the current history offset forward to the next history entry, and
-return the a pointer to that entry. If there is no next entry, return
-a \fBNULL\fP pointer.
+If the current history offset refers to a valid history entry,
+increment 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 \fBNULL\fP pointer.
.SS Searching the History List
The maximum number of history entries. This must be changed using
\fBstifle_history()\fP.
+.Vb int history_wite_timestamps
+If non-zero, timestamps are written to the history file, so they can be
+preserved between sessions. The default value is 0, meaning that
+timestamps are not saved.
+The current timestamp format uses the value of \fIhistory_comment_char\fP
+to delimit timestamp entries in the history file. If that variable does
+not have a value (the default), timestamps will not be written.
+
.Vb char history_expansion_char
The character that introduces a history event. The default is \fB!\fP.
Setting this to 0 inhibits history expansion.
a substring search. The default is empty.
.Vb int history_quotes_inhibit_expansion
-If non-zero, single-quoted words are not scanned for the history expansion
-character. The default value is 0.
+If non-zero, double-quoted words are not scanned for the history expansion
+character or the history comment character. The default value is 0.
.Vb "rl_linebuf_func_t *" history_inhibit_expansion_function
This should be set to the address of a function that takes two arguments:
.PP
Chet Ramey, Case Western Reserve University
.br
-chet@ins.CWRU.Edu
+chet.ramey@case.edu
.SH BUG REPORTS
If you find a bug in the
.B history
.PP
Comments and bug reports concerning
this manual page should be directed to
-.IR chet@ins.CWRU.Edu .
+.IR chet.ramey@case.edu .
projects / deliverable / binutils-gdb.git / blobdiff