Set the state of the history list according to STATE.
File: history.info, Node: History List Management, Next: Information About the History List, Prev: Initializing History and State Management, Up: History Functions
History List Management
-----------------------
These functions manage individual entries on the history list, or set
parameters managing the list itself.
- Function: void add_history (char *string)
Place STRING at the end of the history list. The associated data
Make the history entry at offset WHICH have LINE and DATA. This
returns the old entry so you can dispose of the data. In the case
of an invalid WHICH, a `NULL' pointer is returned.
- Function: void stifle_history (int max)
Stifle the history list, remembering only the last MAX entries.
- Function: int unstifle_history ()
Stop stifling the history. This returns the previous amount the
history was stifled. The value is positive if the history was
stifled, negative if it wasn't.
- Function: int history_is_stifled ()
Returns non-zero if the history is stifled, zero if it is not.
File: history.info, Node: Information About the History List, Next: Moving Around the History List, Prev: History List Management, Up: History Functions
Information About the History List
----------------------------------
These functions return information about the entire history list or
individual list entries.
- Function: HIST_ENTRY ** history_list ()
Return a `NULL' terminated array of `HIST_ENTRY' which is the
current input history. Element 0 of this list is the beginning of
time. If there is no history, return `NULL'.
- Function: int where_history ()
Returns the offset of the current history element.
- Function: HIST_ENTRY * current_history ()
Return the history entry at the current position, as determined by
`where_history ()'. If there is no entry there, return a `NULL'
pointer.
- Function: HIST_ENTRY * history_get (int offset)
Return the history entry at position OFFSET, starting from
`history_base'. If there is no entry there, or if OFFSET is
greater than the history length, return a `NULL' pointer.
- Function: int history_total_bytes ()
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.
File: history.info, Node: Moving Around the History List, Next: Searching the History List, Prev: Information About the History List, Up: History Functions
Moving Around the History List
------------------------------
These functions allow the current index into the history list to be
set or changed.
- Function: int history_set_pos (int pos)
Set the position in the history list to POS, an absolute index
into the list.
- Function: HIST_ENTRY * previous_history ()
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 `NULL' pointer.
- Function: HIST_ENTRY * next_history ()
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 `NULL' pointer.
File: history.info, Node: Searching the History List, Next: Managing the History File, Prev: Moving Around the History List, Up: History Functions
Searching the History List
--------------------------
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 history position. The search may be
"anchored", meaning that the string must match at the beginning of the
history entry.
- Function: int history_search (char *string, int direction)
Search the history for STRING, starting at the current history
offset. If DIRECTION < 0, then the search is through previous
entries, else through subsequent. If STRING 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 STRING was
found. Otherwise, nothing is changed, and a -1 is returned.
- Function: int history_search_prefix (char *string, int direction)
Search the history for STRING, starting at the current history
offset. The search is anchored: matching lines must begin with
STRING. If DIRECTION < 0, then the search is through previous
entries, else through subsequent. If STRING 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.
- Function: int history_search_pos (char *string, int direction, int
pos)
Search for STRING in the history list, starting at POS, an
absolute index into the list. If DIRECTION is negative, the search
proceeds backward from POS, otherwise forward. Returns the
absolute index of the history element where STRING was found, or
-1 otherwise.
File: history.info, Node: Managing the History File, Next: History Expansion, Prev: Searching the History List, Up: History Functions
Managing the History File
-------------------------
The History library can read the history from and write it to a file.
This section documents the functions for managing a history file.
- Function: int read_history (char *filename)
Add the contents of FILENAME to the history list, a line at a
time. If FILENAME is `NULL', then read from `~/.history'.
Returns 0 if successful, or errno if not.
- Function: int read_history_range (char *filename, int from, int to)
Read a range of lines from FILENAME, adding them to the history
list. Start reading at line FROM and end at TO. If FROM is zero,
start at the beginning. If TO is less than FROM, then read until
the end of the file. If FILENAME is `NULL', then read from
`~/.history'. Returns 0 if successful, or `errno' if not.
- Function: int write_history (char *filename)
Write the current history to FILENAME, overwriting FILENAME if
necessary. If FILENAME is `NULL', then write the history list to
`~/.history'. Values returned are as in `read_history ()'.
- Function: int append_history (int nelements, char *filename)
Append the last NELEMENTS of the history list to FILENAME.
- Function: int history_truncate_file (char *filename, int nlines)
Truncate the history file FILENAME, leaving only the last NLINES
lines.
File: history.info, Node: History Expansion, Prev: Managing the History File, Up: History Functions
History Expansion
-----------------
These functions implement `csh'-like history expansion.
- Function: int history_expand (char *string, char **output)
Expand STRING, placing the result into OUTPUT, a pointer to a
string (*note History Interaction::.). Returns:
`0'
If no expansions took place (or, if the only change in the
text was the de-slashifying of the history expansion
character);
`1'
if expansions did take place;
`-1'
if there was an error in expansion;
`2'
if the returned line should only be displayed, but not
executed, as with the `:p' modifier (*note Modifiers::.).
If an error ocurred in expansion, then OUTPUT contains a
descriptive error message.
- Function: char * history_arg_extract (int first, int last, char
*string)
Extract a string segment consisting of the FIRST through LAST
arguments present in STRING. Arguments are broken up as in Bash.
- Function: char * get_history_event (char *string, int *cindex, int
qchar)
Returns the text of the history event beginning at STRING +
*CINDEX. *CINDEX is modified to point to after the event
specifier. At function entry, CINDEX points to the index into
STRING where the history event specification begins. QCHAR is a
character that is allowed to end the event specification in
