# man > history(3readline)

---
type: CommandReference
command: history
mode: man
section: 3
source: man-pages
---
## Quick Reference
- `!!` — repeat the previous command
- `!$` — last argument of the previous command
- `!string` — most recent command starting with `string`
- `^old^new^` — quick substitution: replace `old` with `new` in last command
- `history_search("string", -1)` — search backward for `string` in history
- `read_history(NULL)` — load history from the default file (~/.history)
- `write_history(NULL)` — save history to the default file
- `add_history("line")` — append a line to the history list

## Name
history - GNU History Library

## Synopsis
The GNU History library provides functions to manage a list of previously entered command lines, support history expansion, and associate arbitrary data with each entry. It is typically used together with the Readline library.

## Functions

### Initialization & State
- `using_history()` — initialize the history library for use
- `history_get_history_state()` — return a `HISTORY_STATE` structure describing the current history list
- `history_set_history_state(HISTORY_STATE *state)` — restore the history list to the given state

### List Management
- `add_history(const char *string)` — add `string` to the end of the history list; if the list is stifled to a maximum size, the oldest entry is removed
- `add_history_time(const char *string)` — change the timestamp of the most recent history entry to `string`
- `remove_history(int which)` — remove the entry at offset `which`; returns the removed `HIST_ENTRY` so the caller can free it
- `free_history_entry(HIST_ENTRY *histent)` — free a history entry and its private data; returns the application‑specific data pointer
- `replace_history_entry(int which, const char *line, histdata_t data)` — replace the line and data of the entry at `which`; returns the old entry
- `clear_history()` — delete all history entries
- `stifle_history(int max)` — limit the history list to the most recent `max` entries
- `unstifle_history()` — remove the stifling limit; returns the previous maximum (positive if stifled, negative if not)
- `history_is_stifled()` — returns non‑zero if the history is stifled

### Information Retrieval
- `history_list()` — return a `NULL`-terminated array of `HIST_ENTRY *` for the entire history; element 0 is the oldest
- `where_history()` — return the offset of the “current” history element
- `current_history()` — return the `HIST_ENTRY` at the current offset
- `history_get(int offset)` — return the entry at absolute `offset` (range `history_base` … `history_length-1`), or `NULL`
- `history_get_time(HIST_ENTRY *)` — return the timestamp of the given entry
- `history_total_bytes()` — return the total number of bytes used by all history lines

### Moving the Current Position
- `history_set_pos(int pos)` — set the current history offset to `pos`; returns 1 on success, 0 if `pos` is out of range
- `previous_history()` — move to the previous entry and return it, or `NULL` if none
- `next_history()` — move to the next entry and return it, or `NULL` if none

### Searching
- `history_search(const char *string, int direction)` — search for `string` starting from the current offset; `direction` < 0 searches backward, ≥ 0 forward. Returns the offset within the line where the string was found, or -1.
- `history_search_prefix(const char *string, int direction)` — anchored search: the line must start with `string`. Returns 0 on success, -1 otherwise.
- `history_search_pos(const char *string, int direction, int pos)` — search starting at absolute index `pos`; returns the index of the matching entry, or -1.

### History File I/O
- `read_history(const char *filename)` — read lines from `filename` (or `~/.history` if `NULL`) and append them to the history list. Returns 0 on success, or `errno`.
- `read_history_range(const char *filename, int from, int to)` — read lines `from` through `to` from the file; if `to` < `from` read to end. Returns 0 or `errno`.
- `write_history(const char *filename)` — overwrite `filename` with the current history list; default file is `~/.history`. Returns 0 or `errno`.
- `append_history(int nelements, const char *filename)` — append the last `nelements` entries to `filename`. Returns 0 or `errno`.
- `history_truncate_file(const char *filename, int nlines)` — keep only the last `nlines` lines in the file. Returns 0 or `errno`.

### History Expansion
- `history_expand(char *string, char **output)` — perform history expansion on `string`; result placed in `output`. Returns:
  - 0 – no expansions (or only escape removal)
  - 1 – expansions took place
  - -1 – error (output contains error message)
  - 2 – line should be displayed but not executed (`:p` modifier)
- `get_history_event(const char *string, int *cindex, int qchar)` — extract the text of a history event specification starting at `string + *cindex`; updates `*cindex` to point after the event specifier. `qchar` is an extra delimiter to end the event.
- `history_tokenize(const char *string)` — split `string` into tokens using the characters in `history_word_delimiters` and obeying shell quoting; returns a `NULL`-terminated array of strings.
- `history_arg_extract(int first, int last, const char *string)` — extract a substring containing arguments `first` through `last` from `string` (split as by `history_tokenize()`).

### History Variables
- `int history_base` — logical offset of the first entry in the history list
- `int history_length` — number of entries currently stored
- `int history_max_entries` — maximum number of entries (set via `stifle_history()`)
- `int history_write_timestamps` — if non‑zero, timestamps are written to the history file (default 0)
- `char history_expansion_char` — character that introduces a history event (default `!`; set to 0 to disable expansion)
- `char history_subst_char` — character that triggers word substitution at the start of a line (default `^`)
- `char history_comment_char` — if seen as the first character of a word, that word and the rest of the line are ignored for expansion (disabled by default)
- `char *history_word_delimiters` — characters that separate tokens for `history_tokenize()` (default `" \t\n()<>;&|"`)
- `char *history_no_expand_chars` — characters that inhibit history expansion if they immediately follow `history_expansion_char` (default space, tab, newline, `\r`, `=`)
- `char *history_search_delimiter_chars` — extra characters that can delimit a history search string (default empty)
- `int history_quotes_inhibit_expansion` — if non‑zero, double‑quoted words are not scanned for expansion (default 0)
- `rl_linebuf_func_t *history_inhibit_expansion_function` — pointer to a function `int func(char *, int)` that returns non‑zero to suppress expansion at a given index (default `NULL`)

## History Expansion Syntax

### Event Designators
- `!` — start history substitution (unless followed by blank, newline, `=`, or `(`)
- `!n` — command line number `n`
- `!-n` — the `n`-th previous command
- `!!` — previous command (synonym for `!-1`)
- `!string` — most recent command starting with `string`
- `!?string[?]` — most recent command containing `string`; trailing `?` optional if followed by newline
- `^string1^string2^` — quick substitution: repeat last command, replace `string1` with `string2`
- `!#` — the entire command line typed so far

### Word Designators
Separated from the event by `:` (the colon may be omitted if the designator is `^`, `$`, `*`, `-`, or `%`).
- `0` — zeroth word (command name)
- `n` — `n`-th word
- `^` — first argument (word 1)
- `$` — last word
- `%` — first word matched by the most recent `?string?` search
- `x-y` — range of words; `-y` abbreviates `0-y`
- `*` — all words except the zeroth (`1-$`)
- `x*` — abbreviates `x-$`
- `x-` — abbreviates `x-$` but omits the last word; `x` missing defaults to 0

### Modifiers
Each modifier follows a `:`.
- `h` — remove trailing file name component (head)
- `t` — remove leading file name components (tail)
- `r` — remove a trailing `.xxx` suffix
- `e` — keep only the suffix
- `p` — print the expanded command but do not execute
- `q` — quote the substituted words, escaping further substitutions
- `x` — like `q` but break into words at blanks and newlines; mutually exclusive with `q`
- `s/old/new/` — substitute `new` for the first occurrence of `old`; any delimiter can be used in place of `/`; `&` in `new` is replaced by `old`
- `&` — repeat the previous substitution
- `g` — apply the `s` or `&` modifier globally to the whole event line; `a` is a synonym for `g`
- `G` — apply the following `s` or `&` modifier once to each word in the event line

## Examples
shell
# Repeat last command
!!

# Run last command starting with "ls"
!ls

# Quick substitution: fix typo in last command
^mroe^more^

# Reuse last argument of previous command
echo !$

# In C code:
#include <readline/history.h>
add_history("my command");
HIST_ENTRY *entry = history_get(history_length - 1);
## See Also
- [bash(1)](http://localhost/phpMan.php/man/bash/1/markdown)
- [readline(3)](http://localhost/phpMan.php/man/readline/3/markdown)
- The GNU Readline Library
- The GNU History Library