|
1 --- readline-5.2/doc/history.3.orig Mon Apr 4 00:12:21 2011 |
|
2 +++ readline-5.2/doc/history.3 Mon Apr 4 00:13:09 2011 |
|
3 @@ -19,16 +19,16 @@ |
|
4 .ds lp \fR\|(\fP |
|
5 .ds rp \fR\|)\fP |
|
6 .\" FnN return-value fun-name N arguments |
|
7 -.de Fn1 |
|
8 +.de F1 |
|
9 \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3\fP\\*(rp |
|
10 .br |
|
11 .. |
|
12 -.de Fn2 |
|
13 +.de F2 |
|
14 .if t \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3,\|\\$4\fP\\*(rp |
|
15 .if n \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3, \\$4\fP\\*(rp |
|
16 .br |
|
17 .. |
|
18 -.de Fn3 |
|
19 +.de F3 |
|
20 .if t \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3,\|\\$4,\|\\$5\fP\|\\*(rp |
|
21 .if n \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3, \\$4, \\$5\fP\\*(rp |
|
22 .br |
|
23 @@ -331,14 +331,14 @@ |
|
24 the state of the History library when you want to use the history |
|
25 functions in your program. |
|
26 |
|
27 -.Fn1 void using_history void |
|
28 +.F1 void using_history void |
|
29 Begin a session in which the history functions might be used. This |
|
30 initializes the interactive variables. |
|
31 |
|
32 -.Fn1 "HISTORY_STATE *" history_get_history_state void |
|
33 +.F1 "HISTORY_STATE *" history_get_history_state void |
|
34 Return a structure describing the current state of the input history. |
|
35 |
|
36 -.Fn1 void history_set_history_state "HISTORY_STATE *state" |
|
37 +.F1 void history_set_history_state "HISTORY_STATE *state" |
|
38 Set the state of the history list according to \fIstate\fP. |
|
39 |
|
40 .SS History List Management |
|
41 @@ -346,43 +346,43 @@ |
|
42 These functions manage individual entries on the history list, or set |
|
43 parameters managing the list itself. |
|
44 |
|
45 -.Fn1 void add_history "const char *string" |
|
46 +.F1 void add_history "const char *string" |
|
47 Place \fIstring\fP at the end of the history list. The associated data |
|
48 field (if any) is set to \fBNULL\fP. |
|
49 |
|
50 -.Fn1 void add_history_time "const char *string" |
|
51 +.F1 void add_history_time "const char *string" |
|
52 Change the time stamp associated with the most recent history entry to |
|
53 \fIstring\fP. |
|
54 |
|
55 -.Fn1 "HIST_ENTRY *" remove_history "int which" |
|
56 +.F1 "HIST_ENTRY *" remove_history "int which" |
|
57 Remove history entry at offset \fIwhich\fP from the history. The |
|
58 removed element is returned so you can free the line, data, |
|
59 and containing structure. |
|
60 |
|
61 -.Fn1 "histdata_t" free_history_entry "HIST_ENTRY *histent" |
|
62 +.F1 "histdata_t" free_history_entry "HIST_ENTRY *histent" |
|
63 Free the history entry \fIhistent\fP and any history library private |
|
64 data associated with it. Returns the application-specific data |
|
65 so the caller can dispose of it. |
|
66 |
|
67 -.Fn3 "HIST_ENTRY *" replace_history_entry "int which" "const char *line" "histdata_t data" |
|
68 +.F3 "HIST_ENTRY *" replace_history_entry "int which" "const char *line" "histdata_t data" |
|
69 Make the history entry at offset \fIwhich\fP have \fIline\fP and \fIdata\fP. |
|
70 This returns the old entry so the caller can dispose of any |
|
71 application-specific data. In the case |
|
72 of an invalid \fIwhich\fP, a \fBNULL\fP pointer is returned. |
|
73 |
|
74 -.Fn1 void clear_history "void" |
|
75 +.F1 void clear_history "void" |
|
76 Clear the history list by deleting all the entries. |
|
77 |
|
78 -.Fn1 void stifle_history "int max" |
|
79 +.F1 void stifle_history "int max" |
|
80 Stifle the history list, remembering only the last \fImax\fP entries. |
|
81 |
|
82 -.Fn1 int unstifle_history "void" |
|
83 +.F1 int unstifle_history "void" |
|
84 Stop stifling the history. This returns the previously-set |
|
85 maximum number of history entries (as set by \fBstifle_history()\fP). |
|
86 history was stifled. The value is positive if the history was |
|
87 stifled, negative if it wasn't. |
|
88 |
|
89 -.Fn1 int history_is_stifled "void" |
|
90 +.F1 int history_is_stifled "void" |
|
91 Returns non-zero if the history is stifled, zero if it is not. |
|
92 |
|
93 .SS Information About the History List |
|
94 @@ -390,29 +390,29 @@ |
|
95 These functions return information about the entire history list or |
|
96 individual list entries. |
|
97 |
|
98 -.Fn1 "HIST_ENTRY **" history_list "void" |
|
99 +.F1 "HIST_ENTRY **" history_list "void" |
|
100 Return a \fBNULL\fP terminated array of \fIHIST_ENTRY *\fP which is the |
|
101 current input history. Element 0 of this list is the beginning of time. |
|
102 If there is no history, return \fBNULL\fP. |
|
103 |
|
104 -.Fn1 int where_history "void" |
|
105 +.F1 int where_history "void" |
|
106 Returns the offset of the current history element. |
|
107 |
|
108 -.Fn1 "HIST_ENTRY *" current_history "void" |
|
109 +.F1 "HIST_ENTRY *" current_history "void" |
|
110 Return the history entry at the current position, as determined by |
|
111 \fBwhere_history()\fP. If there is no entry there, return a \fBNULL\fP |
|
112 pointer. |
|
113 |
|
114 -.Fn1 "HIST_ENTRY *" history_get "int offset" |
|
115 +.F1 "HIST_ENTRY *" history_get "int offset" |
|
116 Return the history entry at position \fIoffset\fP, starting from |
|
117 \fBhistory_base\fP. |
|
118 If there is no entry there, or if \fIoffset\fP |
|
119 is greater than the history length, return a \fBNULL\fP pointer. |
|
120 |
|
121 -.Fn1 "time_t" history_get_time "HIST_ENTRY *" |
|
122 +.F1 "time_t" history_get_time "HIST_ENTRY *" |
|
123 Return the time stamp associated with the history entry passed as the argument. |
|
124 |
|
125 -.Fn1 int history_total_bytes "void" |
|
126 +.F1 int history_total_bytes "void" |
|
127 Return the number of bytes that the primary history entries are using. |
|
128 This function returns the sum of the lengths of all the lines in the |
|
129 history. |
|
130 @@ -422,18 +422,18 @@ |
|
131 These functions allow the current index into the history list to be |
|
132 set or changed. |
|
133 |
|
134 -.Fn1 int history_set_pos "int pos" |
|
135 +.F1 int history_set_pos "int pos" |
|
136 Set the current history offset to \fIpos\fP, an absolute index |
|
137 into the list. |
|
138 Returns 1 on success, 0 if \fIpos\fP is less than zero or greater |
|
139 than the number of history entries. |
|
140 |
|
141 -.Fn1 "HIST_ENTRY *" previous_history "void" |
|
142 +.F1 "HIST_ENTRY *" previous_history "void" |
|
143 Back up the current history offset to the previous history entry, and |
|
144 return a pointer to that entry. If there is no previous entry, return |
|
145 a \fBNULL\fP pointer. |
|
146 |
|
147 -.Fn1 "HIST_ENTRY *" next_history "void" |
|
148 +.F1 "HIST_ENTRY *" next_history "void" |
|
149 Move the current history offset forward to the next history entry, and |
|
150 return the a pointer to that entry. If there is no next entry, return |
|
151 a \fBNULL\fP pointer. |
|
152 @@ -445,7 +445,7 @@ |
|
153 from the current history position. The search may be \fIanchored\fP, |
|
154 meaning that the string must match at the beginning of the history entry. |
|
155 |
|
156 -.Fn2 int history_search "const char *string" "int direction" |
|
157 +.F2 int history_search "const char *string" "int direction" |
|
158 Search the history for \fIstring\fP, starting at the current history offset. |
|
159 If \fIdirection\fP is less than 0, then the search is through |
|
160 previous entries, otherwise through subsequent entries. |
|
161 @@ -455,7 +455,7 @@ |
|
162 \fIstring\fP was found. Otherwise, nothing is changed, and a -1 is |
|
163 returned. |
|
164 |
|
165 -.Fn2 int history_search_prefix "const char *string" "int direction" |
|
166 +.F2 int history_search_prefix "const char *string" "int direction" |
|
167 Search the history for \fIstring\fP, starting at the current history |
|
168 offset. The search is anchored: matching lines must begin with |
|
169 \fIstring\fP. If \fIdirection\fP is less than 0, then the search is |
|
170 @@ -464,7 +464,7 @@ |
|
171 current history index is set to that entry, and the return value is 0. |
|
172 Otherwise, nothing is changed, and a -1 is returned. |
|
173 |
|
174 -.Fn3 int history_search_pos "const char *string" "int direction" "int pos" |
|
175 +.F3 int history_search_pos "const char *string" "int direction" "int pos" |
|
176 Search for \fIstring\fP in the history list, starting at \fIpos\fP, an |
|
177 absolute index into the list. If \fIdirection\fP is negative, the search |
|
178 proceeds backward from \fIpos\fP, otherwise forward. Returns the absolute |
|
179 @@ -474,12 +474,12 @@ |
|
180 The History library can read the history from and write it to a file. |
|
181 This section documents the functions for managing a history file. |
|
182 |
|
183 -.Fn1 int read_history "const char *filename" |
|
184 +.F1 int read_history "const char *filename" |
|
185 Add the contents of \fIfilename\fP to the history list, a line at a time. |
|
186 If \fIfilename\fP is \fBNULL\fP, then read from \fI~/.history\fP. |
|
187 Returns 0 if successful, or \fBerrno\fP if not. |
|
188 |
|
189 -.Fn3 int read_history_range "const char *filename" "int from" "int to" |
|
190 +.F3 int read_history_range "const char *filename" "int from" "int to" |
|
191 Read a range of lines from \fIfilename\fP, adding them to the history list. |
|
192 Start reading at line \fIfrom\fP and end at \fIto\fP. |
|
193 If \fIfrom\fP is zero, start at the beginning. If \fIto\fP is less than |
|
194 @@ -487,7 +487,7 @@ |
|
195 \fBNULL\fP, then read from \fI~/.history\fP. Returns 0 if successful, |
|
196 or \fBerrno\fP if not. |
|
197 |
|
198 -.Fn1 int write_history "const char *filename" |
|
199 +.F1 int write_history "const char *filename" |
|
200 Write the current history to \fIfilename\fP, overwriting \fIfilename\fP |
|
201 if necessary. |
|
202 If \fIfilename\fP is \fBNULL\fP, then write the history list to \fI~/.history\fP. |
|
203 @@ -494,12 +494,12 @@ |
|
204 Returns 0 on success, or \fBerrno\fP on a read or write error. |
|
205 |
|
206 |
|
207 -.Fn2 int append_history "int nelements" "const char *filename" |
|
208 +.F2 int append_history "int nelements" "const char *filename" |
|
209 Append the last \fInelements\fP of the history list to \fIfilename\fP. |
|
210 If \fIfilename\fP is \fBNULL\fP, then append to \fI~/.history\fP. |
|
211 Returns 0 on success, or \fBerrno\fP on a read or write error. |
|
212 |
|
213 -.Fn2 int history_truncate_file "const char *filename" "int nlines" |
|
214 +.F2 int history_truncate_file "const char *filename" "int nlines" |
|
215 Truncate the history file \fIfilename\fP, leaving only the last |
|
216 \fInlines\fP lines. |
|
217 If \fIfilename\fP is \fBNULL\fP, then \fI~/.history\fP is truncated. |
|
218 @@ -509,7 +509,7 @@ |
|
219 |
|
220 These functions implement history expansion. |
|
221 |
|
222 -.Fn2 int history_expand "char *string" "char **output" |
|
223 +.F2 int history_expand "char *string" "char **output" |
|
224 Expand \fIstring\fP, placing the result into \fIoutput\fP, a pointer |
|
225 to a string. Returns: |
|
226 .RS |
|
227 @@ -534,7 +534,7 @@ |
|
228 If an error ocurred in expansion, then \fIoutput\fP contains a descriptive |
|
229 error message. |
|
230 |
|
231 -.Fn3 "char *" get_history_event "const char *string" "int *cindex" "int qchar" |
|
232 +.F3 "char *" get_history_event "const char *string" "int *cindex" "int qchar" |
|
233 Returns the text of the history event beginning at \fIstring\fP + |
|
234 \fI*cindex\fP. \fI*cindex\fP is modified to point to after the event |
|
235 specifier. At function entry, \fIcindex\fP points to the index into |
|
236 @@ -542,7 +542,7 @@ |
|
237 is a character that is allowed to end the event specification in addition |
|
238 to the ``normal'' terminating characters. |
|
239 |
|
240 -.Fn1 "char **" history_tokenize "const char *string" |
|
241 +.F1 "char **" history_tokenize "const char *string" |
|
242 Return an array of tokens parsed out of \fIstring\fP, much as the |
|
243 shell might. |
|
244 The tokens are split on the characters in the |
|
245 @@ -549,7 +549,7 @@ |
|
246 \fBhistory_word_delimiters\fP variable, |
|
247 and shell quoting conventions are obeyed. |
|
248 |
|
249 -.Fn3 "char *" history_arg_extract "int first" "int last" "const char *string" |
|
250 +.F3 "char *" history_arg_extract "int first" "int last" "const char *string" |
|
251 Extract a string segment consisting of the \fIfirst\fP through \fIlast\fP |
|
252 arguments present in \fIstring\fP. Arguments are split using |
|
253 \fBhistory_tokenize()\fP. |