diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 14:51:56 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 14:51:56 +0000 |
commit | c77311c90aa045796b3adcd021e69901022f4649 (patch) | |
tree | 3a6c4cc9271c6f7f7c24feff0d1aea286eed0a06 /doc/history.0 | |
parent | Initial commit. (diff) | |
download | readline-c77311c90aa045796b3adcd021e69901022f4649.tar.xz readline-c77311c90aa045796b3adcd021e69901022f4649.zip |
Adding upstream version 8.2.upstream/8.2upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r-- | doc/history.0 | 505 |
1 files changed, 505 insertions, 0 deletions
diff --git a/doc/history.0 b/doc/history.0 new file mode 100644 index 0000000..2bf3b1a --- /dev/null +++ b/doc/history.0 @@ -0,0 +1,505 @@ +HISTORY(3) Library Functions Manual HISTORY(3) + + + +[1mNAME[0m + history - GNU History Library + +[1mCOPYRIGHT[0m + The GNU History Library is Copyright (C) 1989-2020 by the Free Software + Foundation, Inc. + +[1mDESCRIPTION[0m + Many programs read input from the user a line at a time. The GNU His- + tory library is able to keep track of those lines, associate arbitrary + data with each line, and utilize information from previous lines in + composing new ones. + +[1mHISTORY EXPANSION[0m + The history library supports a history expansion feature that is iden- + tical to the history expansion in [1mbash. [22mThis section describes what + syntax features are available. + + History expansions introduce words from the history list into the input + stream, making it easy to repeat commands, insert the arguments to a + previous command into the current input line, or fix errors in previous + commands quickly. + + History expansion is usually performed immediately after a complete + line is read. It takes place in two parts. The first is to determine + which line from the history list to use during substitution. The sec- + ond is to select portions of that line for inclusion into the current + one. The line selected from the history is the [4mevent[24m, and the portions + of that line that are acted upon are [4mwords[24m. Various [4mmodifiers[24m are + available to manipulate the selected words. The line is broken into + words in the same fashion as [1mbash [22mdoes when reading input, so that sev- + eral words that would otherwise be separated are considered one word + when surrounded by quotes (see the description of [1mhistory_tokenize()[0m + below). History expansions are introduced by the appearance of the + history expansion character, which is [1m! [22mby default. Only backslash ([1m\[22m) + and single quotes can quote the history expansion character. + + [1mEvent Designators[0m + An event designator is a reference to a command line entry in the his- + tory list. Unless the reference is absolute, events are relative to + the current position in the history list. + + [1m! [22mStart a history substitution, except when followed by a [1mblank[22m, + newline, = or (. + [1m![4m[22mn[24m Refer to command line [4mn[24m. + [1m!-[4m[22mn[24m Refer to the current command minus [4mn[24m. + [1m!! [22mRefer to the previous command. This is a synonym for `!-1'. + [1m![4m[22mstring[0m + Refer to the most recent command preceding the current position + in the history list starting with [4mstring[24m. + [1m!?[4m[22mstring[24m[1m[?][0m + Refer to the most recent command preceding the current position + in the history list containing [4mstring[24m. The trailing [1m? [22mmay be + omitted if [4mstring[24m is followed immediately by a newline. If + [4mstring[24m is missing, the string from the most recent search is + used; it is an error if there is no previous search string. + [1m^[4m[22mstring1[24m[1m^[4m[22mstring2[24m[1m^[0m + Quick substitution. Repeat the last command, replacing [4mstring1[0m + with [4mstring2[24m. Equivalent to ``!!:s^[4mstring1[24m^[4mstring2[24m^'' (see [1mMod-[0m + [1mifiers [22mbelow). + [1m!# [22mThe entire command line typed so far. + + [1mWord Designators[0m + Word designators are used to select desired words from the event. A [1m:[0m + separates the event specification from the word designator. It may be + omitted if the word designator begins with a [1m^[22m, [1m$[22m, [1m*[22m, [1m-[22m, or [1m%[22m. Words + are numbered from the beginning of the line, with the first word being + denoted by 0 (zero). Words are inserted into the current line sepa- + rated by single spaces. + + [1m0 (zero)[0m + The zeroth word. For the shell, this is the command word. + [4mn[24m The [4mn[24mth word. + [1m^ [22mThe first argument. That is, word 1. + [1m$ [22mThe last word. This is usually the last argument, but will ex- + pand to the zeroth word if there is only one word in the line. + [1m% [22mThe first word matched by the most recent `?[4mstring[24m?' search, if + the search string begins with a character that is part of a + word. + [4mx[24m[1m-[4m[22my[24m A range of words; `-[4my[24m' abbreviates `0-[4my[24m'. + [1m* [22mAll of the words but the zeroth. This is a synonym for `[4m1-$[24m'. + It is not an error to use [1m* [22mif there is just one word in the + event; the empty string is returned in that case. + [1mx* [22mAbbreviates [4mx-$[24m. + [1mx- [22mAbbreviates [4mx-$[24m like [1mx*[22m, but omits the last word. If [1mx [22mis miss- + ing, it defaults to 0. + + If a word designator is supplied without an event specification, the + previous command is used as the event. + + [1mModifiers[0m + After the optional word designator, there may appear a sequence of one + or more of the following modifiers, each preceded by a `:'. These mod- + ify, or edit, the word or words selected from the history event. + + [1mh [22mRemove a trailing file name component, leaving only the head. + [1mt [22mRemove all leading file name components, leaving the tail. + [1mr [22mRemove a trailing suffix of the form [4m.xxx[24m, leaving the basename. + [1me [22mRemove all but the trailing suffix. + [1mp [22mPrint the new command but do not execute it. + [1mq [22mQuote the substituted words, escaping further substitutions. + [1mx [22mQuote the substituted words as with [1mq[22m, but break into words at + [1mblanks [22mand newlines. The [1mq [22mand [1mx [22mmodifiers are mutually exclu- + sive; the last one supplied is used. + [1ms/[4m[22mold[24m[1m/[4m[22mnew[24m[1m/[0m + Substitute [4mnew[24m for the first occurrence of [4mold[24m in the event + line. Any character may be used as the delimiter in place of /. + The final delimiter is optional if it is the last character of + the event line. The delimiter may be quoted in [4mold[24m and [4mnew[24m with + a single backslash. If & appears in [4mnew[24m, it is replaced by [4mold[24m. + A single backslash will quote the &. If [4mold[24m is null, it is set + to the last [4mold[24m substituted, or, if no previous history substi- + tutions took place, the last [4mstring[24m in a [1m!?[4m[22mstring[24m[1m[?] [22msearch. + If [4mnew[24m is null, each matching [4mold[24m is deleted. + [1m& [22mRepeat the previous substitution. + [1mg [22mCause changes to be applied over the entire event line. This is + used in conjunction with `[1m:s[22m' (e.g., `[1m:gs/[4m[22mold[24m[1m/[4m[22mnew[24m[1m/[22m') or `[1m:&[22m'. + If used with `[1m:s[22m', 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 [1ma [22mmay be used as a synonym for [1mg[22m. + [1mG [22mApply the following `[1ms[22m' or `[1m&[22m' modifier once to each word in the + event line. + +[1mPROGRAMMING WITH HISTORY FUNCTIONS[0m + This section describes how to use the History library in other pro- + grams. + + [1mIntroduction to History[0m + A programmer using the History library has available functions for re- + membering lines on a history list, associating arbitrary data with a + line, removing lines from the list, searching through the list for a + line containing an arbitrary text string, and referencing any line in + the list directly. In addition, a history [4mexpansion[24m function is avail- + able which provides for a consistent user interface across different + programs. + + The user using programs written with the History library has the bene- + fit of a consistent user interface with a set of well-known commands + for manipulating the text of previous lines and using that text in new + commands. The basic history manipulation commands are identical to the + history substitution provided by [1mbash[22m. + + The programmer can also use the readline library, which includes some + history manipulation by default, and has the added advantage of command + line editing. + + Before declaring any functions using any functionality the History li- + brary provides in other code, an application writer should include the + file [4m<readline/history.h>[24m in any file that uses the History library's + features. It supplies extern declarations for all of the library's + public functions and variables, and declares all of the public data + structures. + + [1mHistory Storage[0m + The history list is an array of history entries. A history entry is + declared as follows: + + [4mtypedef[24m [4mvoid[24m [4m*[24m [1mhistdata_t;[0m + + typedef struct _hist_entry { + char *line; + char *timestamp; + histdata_t data; + } HIST_ENTRY; + + The history list itself might therefore be declared as + + [4mHIST_ENTRY[24m [4m**[24m [1mthe_history_list;[0m + + The state of the History library is encapsulated into a single struc- + ture: + + /* + * A structure used to pass around the current state of the history. + */ + typedef struct _hist_state { + HIST_ENTRY **entries; /* Pointer to the entries themselves. */ + int offset; /* The location pointer within this array. */ + int length; /* Number of elements within this array. */ + int size; /* Number of slots allocated to this array. */ + int flags; + } HISTORY_STATE; + + If the flags member includes [1mHS_STIFLED[22m, the history has been stifled. + +[1mHistory Functions[0m + This section describes the calling sequence for the various functions + exported by the GNU History library. + + [1mInitializing History and State Management[0m + This section describes functions used to initialize and manage the + state of the History library when you want to use the history functions + in your program. + + [4mvoid[24m [1musing_history [22m([4mvoid[24m) + Begin a session in which the history functions might be used. This + initializes the interactive variables. + + [4mHISTORY_STATE[24m [4m*[24m [1mhistory_get_history_state [22m([4mvoid[24m) + Return a structure describing the current state of the input history. + + [4mvoid[24m [1mhistory_set_history_state [22m([4mHISTORY_STATE[24m [4m*state[24m) + Set the state of the history list according to [4mstate[24m. + + + [1mHistory List Management[0m + These functions manage individual entries on the history list, or set + parameters managing the list itself. + + [4mvoid[24m [1madd_history [22m([4mconst[24m [4mchar[24m [4m*string[24m) + Place [4mstring[24m at the end of the history list. The associated data field + (if any) is set to [1mNULL[22m. If the maximum number of history entries has + been set using [1mstifle_history()[22m, and the new number of history entries + would exceed that maximum, the oldest history entry is removed. + + [4mvoid[24m [1madd_history_time [22m([4mconst[24m [4mchar[24m [4m*string[24m) + Change the time stamp associated with the most recent history entry to + [4mstring[24m. + + [4mHIST_ENTRY[24m [4m*[24m [1mremove_history [22m([4mint[24m [4mwhich[24m) + Remove history entry at offset [4mwhich[24m from the history. The removed el- + ement is returned so you can free the line, data, and containing struc- + ture. + + [4mhistdata_t[24m [1mfree_history_entry [22m([4mHIST_ENTRY[24m [4m*histent[24m) + Free the history entry [4mhistent[24m and any history library private data as- + sociated with it. Returns the application-specific data so the caller + can dispose of it. + + [4mHIST_ENTRY[24m [4m*[24m [1mreplace_history_entry [22m([4mint[24m [4mwhich,[24m [4mconst[24m [4mchar[24m [4m*line,[24m [4mhist-[0m + [4mdata_t[24m [4mdata[24m) + Make the history entry at offset [4mwhich[24m have [4mline[24m and [4mdata[24m. This re- + turns the old entry so the caller can dispose of any application-spe- + cific data. In the case of an invalid [4mwhich[24m, a [1mNULL [22mpointer is re- + turned. + + [4mvoid[24m [1mclear_history [22m([4mvoid[24m) + Clear the history list by deleting all the entries. + + [4mvoid[24m [1mstifle_history [22m([4mint[24m [4mmax[24m) + Stifle the history list, remembering only the last [4mmax[24m entries. The + history list will contain only [4mmax[24m entries at a time. + + [4mint[24m [1munstifle_history [22m([4mvoid[24m) + Stop stifling the history. This returns the previously-set maximum + number of history entries (as set by [1mstifle_history()[22m). history was + stifled. The value is positive if the history was stifled, negative if + it wasn't. + + [4mint[24m [1mhistory_is_stifled [22m([4mvoid[24m) + Returns non-zero if the history is stifled, zero if it is not. + + + [1mInformation About the History List[0m + These functions return information about the entire history list or in- + dividual list entries. + + [4mHIST_ENTRY[24m [4m**[24m [1mhistory_list [22m([4mvoid[24m) + Return a [1mNULL [22mterminated array of [4mHIST_ENTRY[24m [4m*[24m which is the current in- + put history. Element 0 of this list is the beginning of time. If + there is no history, return [1mNULL[22m. + + [4mint[24m [1mwhere_history [22m([4mvoid[24m) + Returns the offset of the current history element. + + [4mHIST_ENTRY[24m [4m*[24m [1mcurrent_history [22m([4mvoid[24m) + Return the history entry at the current position, as determined by + [1mwhere_history()[22m. If there is no entry there, return a [1mNULL [22mpointer. + + [4mHIST_ENTRY[24m [4m*[24m [1mhistory_get [22m([4mint[24m [4moffset[24m) + Return the history entry at position [4moffset[24m. The range of valid values + of [4moffset[24m starts at [1mhistory_base [22mand ends at [1mhistory_length [22m- 1. If + there is no entry there, or if [4moffset[24m is outside the valid range, re- + turn a [1mNULL [22mpointer. + + [4mtime_t[24m [1mhistory_get_time [22m([4mHIST_ENTRY[24m [4m*[24m) + Return the time stamp associated with the history entry passed as the + argument. + + [4mint[24m [1mhistory_total_bytes [22m([4mvoid[24m) + 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. + + + [1mMoving Around the History List[0m + These functions allow the current index into the history list to be set + or changed. + + [4mint[24m [1mhistory_set_pos [22m([4mint[24m [4mpos[24m) + Set the current history offset to [4mpos[24m, an absolute index into the list. + Returns 1 on success, 0 if [4mpos[24m is less than zero or greater than the + number of history entries. + + [4mHIST_ENTRY[24m [4m*[24m [1mprevious_history [22m([4mvoid[24m) + 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 [1mNULL [22mpointer. + + [4mHIST_ENTRY[24m [4m*[24m [1mnext_history [22m([4mvoid[24m) + If the current history offset refers to a valid history entry, incre- + ment 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 [1mNULL [22mpointer. + + + [1mSearching the History List[0m + These functions allow searching of the history list for entries con- + taining a specific string. Searching may be performed both forward and + backward from the current history position. The search may be [4man-[0m + [4mchored[24m, meaning that the string must match at the beginning of the his- + tory entry. + + [4mint[24m [1mhistory_search [22m([4mconst[24m [4mchar[24m [4m*string,[24m [4mint[24m [4mdirection[24m) + Search the history for [4mstring[24m, starting at the current history offset. + If [4mdirection[24m is less than 0, then the search is through previous en- + tries, otherwise through subsequent entries. If [4mstring[24m 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 [4mstring[24m was found. + Otherwise, nothing is changed, and a -1 is returned. + + [4mint[24m [1mhistory_search_prefix [22m([4mconst[24m [4mchar[24m [4m*string,[24m [4mint[24m [4mdirection[24m) + Search the history for [4mstring[24m, starting at the current history offset. + The search is anchored: matching lines must begin with [4mstring[24m. If [4mdi-[0m + [4mrection[24m is less than 0, then the search is through previous entries, + otherwise through subsequent entries. If [4mstring[24m 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. + + [4mint[24m [1mhistory_search_pos [22m([4mconst[24m [4mchar[24m [4m*string,[24m [4mint[24m [4mdirection,[24m [4mint[24m [4mpos[24m) + Search for [4mstring[24m in the history list, starting at [4mpos[24m, an absolute in- + dex into the list. If [4mdirection[24m is negative, the search proceeds back- + ward from [4mpos[24m, otherwise forward. Returns the absolute index of the + history element where [4mstring[24m was found, or -1 otherwise. + + + [1mManaging the History File[0m + The History library can read the history from and write it to a file. + This section documents the functions for managing a history file. + + [4mint[24m [1mread_history [22m([4mconst[24m [4mchar[24m [4m*filename[24m) + Add the contents of [4mfilename[24m to the history list, a line at a time. If + [4mfilename[24m is [1mNULL[22m, then read from [4m~/.history[24m. Returns 0 if successful, + or [1merrno [22mif not. + + [4mint[24m [1mread_history_range [22m([4mconst[24m [4mchar[24m [4m*filename,[24m [4mint[24m [4mfrom,[24m [4mint[24m [4mto[24m) + Read a range of lines from [4mfilename[24m, adding them to the history list. + Start reading at line [4mfrom[24m and end at [4mto[24m. If [4mfrom[24m is zero, start at + the beginning. If [4mto[24m is less than [4mfrom[24m, then read until the end of the + file. If [4mfilename[24m is [1mNULL[22m, then read from [4m~/.history[24m. Returns 0 if + successful, or [1merrno [22mif not. + + [4mint[24m [1mwrite_history [22m([4mconst[24m [4mchar[24m [4m*filename[24m) + Write the current history to [4mfilename[24m, overwriting [4mfilename[24m if neces- + sary. If [4mfilename[24m is [1mNULL[22m, then write the history list to [4m~/.history[24m. + Returns 0 on success, or [1merrno [22mon a read or write error. + + + [4mint[24m [1mappend_history [22m([4mint[24m [4mnelements,[24m [4mconst[24m [4mchar[24m [4m*filename[24m) + Append the last [4mnelements[24m of the history list to [4mfilename[24m. If [4mfilename[0m + is [1mNULL[22m, then append to [4m~/.history[24m. Returns 0 on success, or [1merrno [22mon + a read or write error. + + [4mint[24m [1mhistory_truncate_file [22m([4mconst[24m [4mchar[24m [4m*filename,[24m [4mint[24m [4mnlines[24m) + Truncate the history file [4mfilename[24m, leaving only the last [4mnlines[24m lines. + If [4mfilename[24m is [1mNULL[22m, then [4m~/.history[24m is truncated. Returns 0 on suc- + cess, or [1merrno [22mon failure. + + + [1mHistory Expansion[0m + These functions implement history expansion. + + [4mint[24m [1mhistory_expand [22m([4mchar[24m [4m*string,[24m [4mchar[24m [4m**output[24m) + Expand [4mstring[24m, placing the result into [4moutput[24m, a pointer to a string. + Returns: + 0 If no expansions took place (or, if the only change in + the text was the removal of escape characters preceding + the history expansion character); + 1 if expansions did take place; + -1 if there was an error in expansion; + 2 if the returned line should be displayed, but not exe- + cuted, as with the [1m:p [22mmodifier. + If an error occurred in expansion, then [4moutput[24m contains a descriptive + error message. + + [4mchar[24m [4m*[24m [1mget_history_event [22m([4mconst[24m [4mchar[24m [4m*string,[24m [4mint[24m [4m*cindex,[24m [4mint[24m [4mqchar[24m) + Returns the text of the history event beginning at [4mstring[24m + [4m*cindex[24m. + [4m*cindex[24m is modified to point to after the event specifier. At function + entry, [4mcindex[24m points to the index into [4mstring[24m where the history event + specification begins. [4mqchar[24m is a character that is allowed to end the + event specification in addition to the ``normal'' terminating charac- + ters. + + [4mchar[24m [4m**[24m [1mhistory_tokenize [22m([4mconst[24m [4mchar[24m [4m*string[24m) + Return an array of tokens parsed out of [4mstring[24m, much as the shell + might. The tokens are split on the characters in the [1mhistory_word_de-[0m + [1mlimiters [22mvariable, and shell quoting conventions are obeyed. + + [4mchar[24m [4m*[24m [1mhistory_arg_extract [22m([4mint[24m [4mfirst,[24m [4mint[24m [4mlast,[24m [4mconst[24m [4mchar[24m [4m*string[24m) + Extract a string segment consisting of the [4mfirst[24m through [4mlast[24m arguments + present in [4mstring[24m. Arguments are split using [1mhistory_tokenize()[22m. + + + [1mHistory Variables[0m + This section describes the externally-visible variables exported by the + GNU History Library. + + [4mint[24m [1mhistory_base[0m + The logical offset of the first entry in the history list. + + [4mint[24m [1mhistory_length[0m + The number of entries currently stored in the history list. + + [4mint[24m [1mhistory_max_entries[0m + The maximum number of history entries. This must be changed using [1msti-[0m + [1mfle_history()[22m. + + [4mint[24m [1mhistory_write_timestamps[0m + If non-zero, timestamps are written to the history file, so they can be + preserved between sessions. The default value is 0, meaning that time- + stamps are not saved. The current timestamp format uses the value of + [4mhistory_comment_char[24m to delimit timestamp entries in the history file. + If that variable does not have a value (the default), timestamps will + not be written. + + [4mchar[24m [1mhistory_expansion_char[0m + The character that introduces a history event. The default is [1m![22m. Set- + ting this to 0 inhibits history expansion. + + [4mchar[24m [1mhistory_subst_char[0m + The character that invokes word substitution if found at the start of a + line. The default is [1m^[22m. + + [4mchar[24m [1mhistory_comment_char[0m + During tokenization, if this character is seen as the first character + of a word, then it and all subsequent characters up to a newline are + ignored, suppressing history expansion for the remainder of the line. + This is disabled by default. + + [4mchar[24m [4m*[24m [1mhistory_word_delimiters[0m + The characters that separate tokens for [1mhistory_tokenize()[22m. The de- + fault value is [1m" \t\n()<>;&|"[22m. + + [4mchar[24m [4m*[24m [1mhistory_no_expand_chars[0m + The list of characters which inhibit history expansion if found immedi- + ately following [1mhistory_expansion_char[22m. The default is space, tab, + newline, [1m\r[22m, and [1m=[22m. + + [4mchar[24m [4m*[24m [1mhistory_search_delimiter_chars[0m + The list of additional characters which can delimit a history search + string, in addition to space, tab, [4m:[24m and [4m?[24m in the case of a substring + search. The default is empty. + + [4mint[24m [1mhistory_quotes_inhibit_expansion[0m + If non-zero, double-quoted words are not scanned for the history expan- + sion character or the history comment character. The default value is + 0. + + [4mrl_linebuf_func_t[24m [4m*[24m [1mhistory_inhibit_expansion_function[0m + This should be set to the address of a function that takes two argu- + ments: a [1mchar * [22m([4mstring[24m) and an [1mint [22mindex into that string ([4mi[24m). It + should return a non-zero value if the history expansion starting at + [4mstring[i][24m should not be performed; zero if the expansion should be + done. It is intended for use by applications like [1mbash [22mthat use the + history expansion character for additional purposes. By default, this + variable is set to [1mNULL[22m. + +[1mFILES[0m + [4m~/.history[0m + Default filename for reading and writing saved history + +[1mSEE ALSO[0m + [4mThe[24m [4mGnu[24m [4mReadline[24m [4mLibrary[24m, Brian Fox and Chet Ramey + [4mThe[24m [4mGnu[24m [4mHistory[24m [4mLibrary[24m, Brian Fox and Chet Ramey + [4mbash[24m(1) + [4mreadline[24m(3) + +[1mAUTHORS[0m + Brian Fox, Free Software Foundation + bfox@gnu.org + + Chet Ramey, Case Western Reserve University + chet.ramey@case.edu + +[1mBUG REPORTS[0m + If you find a bug in the [1mhistory [22mlibrary, you should report it. But + first, you should make sure that it really is a bug, and that it ap- + pears in the latest version of the [1mhistory [22mlibrary that you have. + + Once you have determined that a bug actually exists, mail a bug report + to [4mbug-readline[24m@[4mgnu.org[24m. If you have a fix, you are welcome to mail + that as well! Suggestions and `philosophical' bug reports may be + mailed to [4mbug-readline[24m@[4mgnu.org[24m or posted to the Usenet newsgroup + [1mgnu.bash.bug[22m. + + Comments and bug reports concerning this manual page should be directed + to [4mchet.ramey@case.edu[24m. + + + +GNU History 8.1 2020 July 17 HISTORY(3) |