181N/A .\" FnN return-value fun-name N arguments
181N/A \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3\fP\\*(rp
181N/A .if t \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3,\|\\$4\fP\\*(rp
181N/A .if n \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3, \\$4\fP\\*(rp
181N/A .if t \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3,\|\\$4,\|\\$5\fP\|\\*(rp
181N/A .if n \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3, \\$4, \\$5\fP\\*(rp
181N/A the state of the History library when you want to use the history
181N/A functions in your program.
181N/A+.F1 void using_history void
181N/A Begin a session in which the history functions might be used. This
181N/A initializes the interactive variables.
181N/A-.Fn1 "HISTORY_STATE *" history_get_history_state void
181N/A+.F1 "HISTORY_STATE *" history_get_history_state void
181N/A Return a structure describing the current state of the input history.
181N/A-.Fn1 void history_set_history_state "HISTORY_STATE *state"
181N/A+.F1 void history_set_history_state "HISTORY_STATE *state"
181N/A Set the state of the history list according to \fIstate\fP.
181N/A .SS History List Management
181N/A These functions manage individual entries on the history list, or set
181N/A parameters managing the list itself.
181N/A+.F1 void add_history "const char *string"
181N/A Place \fIstring\fP at the end of the history list. The associated data
181N/A field (if any) is set to \fBNULL\fP.
181N/A+.F1 void add_history_time "const char *string"
181N/A Change the time stamp associated with the most recent history entry to
181N/A+.F1 "HIST_ENTRY *" remove_history "int which"
181N/A Remove history entry at offset \fIwhich\fP from the history. The
181N/A removed element is returned so you can free the line, data,
181N/A and containing structure.
181N/A-.Fn1 "histdata_t" free_history_entry "HIST_ENTRY *histent"
181N/A+.F1 "histdata_t" free_history_entry "HIST_ENTRY *histent"
181N/A Free the history entry \fIhistent\fP and any history library private
181N/A data associated with it. Returns the application-specific data
181N/A so the caller can dispose of it.
181N/A-.Fn3 "HIST_ENTRY *" replace_history_entry "int which" "const char *line" "histdata_t data"
181N/A+.F3 "HIST_ENTRY *" replace_history_entry "int which" "const char *line" "histdata_t data"
181N/A Make the history entry at offset \fIwhich\fP have \fIline\fP and \fIdata\fP.
181N/A This returns the old entry so the caller can dispose of any
181N/A application-specific data. In the case
181N/A of an invalid \fIwhich\fP, a \fBNULL\fP pointer is returned.
181N/A+.F1 void clear_history "void"
181N/A Clear the history list by deleting all the entries.
181N/A+.F1 void stifle_history "int max"
181N/A Stifle the history list, remembering only the last \fImax\fP entries.
181N/A+.F1 int unstifle_history "void"
181N/A Stop stifling the history. This returns the previously-set
181N/A maximum number of history entries (as set by \fBstifle_history()\fP).
181N/A history was stifled. The value is positive if the history was
181N/A stifled, negative if it wasn't.
181N/A+.F1 int history_is_stifled "void"
181N/A Returns non-zero if the history is stifled, zero if it is not.
181N/A .SS Information About the History List
181N/A These functions return information about the entire history list or
181N/A individual list entries.
181N/A+.F1 "HIST_ENTRY **" history_list "void"
181N/A Return a \fBNULL\fP terminated array of \fIHIST_ENTRY *\fP which is the
181N/A current input history. Element 0 of this list is the beginning of time.
181N/A If there is no history, return \fBNULL\fP.
181N/A+.F1 int where_history "void"
181N/A Returns the offset of the current history element.
181N/A+.F1 "HIST_ENTRY *" current_history "void"
181N/A Return the history entry at the current position, as determined by
181N/A \fBwhere_history()\fP. If there is no entry there, return a \fBNULL\fP
181N/A+.F1 "HIST_ENTRY *" history_get "int offset"
181N/A Return the history entry at position \fIoffset\fP, starting from
181N/A If there is no entry there, or if \fIoffset\fP
181N/A is greater than the history length, return a \fBNULL\fP pointer.
181N/A+.F1 "time_t" history_get_time "HIST_ENTRY *"
181N/A Return the time stamp associated with the history entry passed as the argument.
181N/A+.F1 int history_total_bytes "void"
181N/A Return the number of bytes that the primary history entries are using.
181N/A This function returns the sum of the lengths of all the lines in the
181N/A These functions allow the current index into the history list to be
181N/A+.F1 int history_set_pos "int pos"
181N/A Set the current history offset to \fIpos\fP, an absolute index
181N/A Returns 1 on success, 0 if \fIpos\fP is less than zero or greater
181N/A than the number of history entries.
181N/A+.F1 "HIST_ENTRY *" previous_history "void"
181N/A Back up the current history offset to the previous history entry, and
181N/A return a pointer to that entry. If there is no previous entry, return
181N/A+.F1 "HIST_ENTRY *" next_history "void"
181N/A Move the current history offset forward to the next history entry, and
181N/A return the a pointer to that entry. If there is no next entry, return
181N/A from the current history position. The search may be \fIanchored\fP,
181N/A meaning that the string must match at the beginning of the history entry.
181N/A-.Fn2 int history_search "const char *string" "int direction"
181N/A+.F2 int history_search "const char *string" "int direction"
181N/A Search the history for \fIstring\fP, starting at the current history offset.
181N/A If \fIdirection\fP is less than 0, then the search is through
181N/A previous entries, otherwise through subsequent entries.
181N/A \fIstring\fP was found. Otherwise, nothing is changed, and a -1 is
181N/A-.Fn2 int history_search_prefix "const char *string" "int direction"
181N/A+.F2 int history_search_prefix "const char *string" "int direction"
181N/A Search the history for \fIstring\fP, starting at the current history
181N/A offset. The search is anchored: matching lines must begin with
181N/A \fIstring\fP. If \fIdirection\fP is less than 0, then the search is
181N/A current history index is set to that entry, and the return value is 0.
181N/A Otherwise, nothing is changed, and a -1 is returned.
181N/A-.Fn3 int history_search_pos "const char *string" "int direction" "int pos"
181N/A+.F3 int history_search_pos "const char *string" "int direction" "int pos"
181N/A Search for \fIstring\fP in the history list, starting at \fIpos\fP, an
181N/A absolute index into the list. If \fIdirection\fP is negative, the search
181N/A proceeds backward from \fIpos\fP, otherwise forward. Returns the absolute
181N/A The History library can read the history from and write it to a file.
181N/A This section documents the functions for managing a history file.
181N/A+.F1 int read_history "const char *filename"
181N/A Add the contents of \fIfilename\fP to the history list, a line at a time.
181N/A If \fIfilename\fP is \fBNULL\fP, then read from \fI~/.history\fP.
181N/A Returns 0 if successful, or \fBerrno\fP if not.
181N/A-.Fn3 int read_history_range "const char *filename" "int from" "int to"
181N/A+.F3 int read_history_range "const char *filename" "int from" "int to"
181N/A Read a range of lines from \fIfilename\fP, adding them to the history list.
181N/A Start reading at line \fIfrom\fP and end at \fIto\fP.
181N/A If \fIfrom\fP is zero, start at the beginning. If \fIto\fP is less than
181N/A \fBNULL\fP, then read from \fI~/.history\fP. Returns 0 if successful,
181N/A+.F1 int write_history "const char *filename"
181N/A Write the current history to \fIfilename\fP, overwriting \fIfilename\fP
181N/A If \fIfilename\fP is \fBNULL\fP, then write the history list to \fI~/.history\fP.
181N/A Returns 0 on success, or \fBerrno\fP on a read or write error.
181N/A-.Fn2 int append_history "int nelements" "const char *filename"
181N/A+.F2 int append_history "int nelements" "const char *filename"
181N/A Append the last \fInelements\fP of the history list to \fIfilename\fP.
181N/A If \fIfilename\fP is \fBNULL\fP, then append to \fI~/.history\fP.
181N/A Returns 0 on success, or \fBerrno\fP on a read or write error.
181N/A-.Fn2 int history_truncate_file "const char *filename" "int nlines"
181N/A+.F2 int history_truncate_file "const char *filename" "int nlines"
181N/A Truncate the history file \fIfilename\fP, leaving only the last
181N/A If \fIfilename\fP is \fBNULL\fP, then \fI~/.history\fP is truncated.
181N/A These functions implement history expansion.
181N/A-.Fn2 int history_expand "char *string" "char **output"
181N/A+.F2 int history_expand "char *string" "char **output"
181N/A Expand \fIstring\fP, placing the result into \fIoutput\fP, a pointer
181N/A If an error ocurred in expansion, then \fIoutput\fP contains a descriptive
181N/A-.Fn3 "char *" get_history_event "const char *string" "int *cindex" "int qchar"
181N/A+.F3 "char *" get_history_event "const char *string" "int *cindex" "int qchar"
181N/A Returns the text of the history event beginning at \fIstring\fP +
181N/A \fI*cindex\fP. \fI*cindex\fP is modified to point to after the event
181N/A specifier. At function entry, \fIcindex\fP points to the index into
181N/A is a character that is allowed to end the event specification in addition
181N/A to the ``normal'' terminating characters.
181N/A-.Fn1 "char **" history_tokenize "const char *string"
181N/A+.F1 "char **" history_tokenize "const char *string"
181N/A Return an array of tokens parsed out of \fIstring\fP, much as the
181N/A The tokens are split on the characters in the
181N/A \fBhistory_word_delimiters\fP variable,
181N/A and shell quoting conventions are obeyed.
181N/A-.Fn3 "char *" history_arg_extract "int first" "int last" "const char *string"
181N/A+.F3 "char *" history_arg_extract "int first" "int last" "const char *string"
181N/A Extract a string segment consisting of the \fIfirst\fP through \fIlast\fP
181N/A arguments present in \fIstring\fP. Arguments are split using
181N/A \fBhistory_tokenize()\fP.