| blob | 5e06e6bbcc8d9d4f540cf08d02b22fdb701b06e3 |
1 .\" $OpenBSD: editrc.5,v 1.32 2016/05/22 22:08:42 schwarze Exp $
2 .\" $NetBSD: editrc.5,v 1.31 2016/04/28 15:50:34 christos Exp $
3 .\"
4 .\" Copyright (c) 1997-2000 The NetBSD Foundation, Inc.
5 .\" All rights reserved.
6 .\"
7 .\" This file was contributed to The NetBSD Foundation by Luke Mewburn.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28 .\" POSSIBILITY OF SUCH DAMAGE.
29 .\"
30 .Dd $Mdocdate: May 22 2016 $
31 .Dt EDITRC 5
32 .Os
33 .Sh NAME
34 .Nm editrc
35 .Nd configuration file for editline library
36 .Sh DESCRIPTION
37 The
38 .Nm
39 file defines various settings to be used by the
40 .Xr editline 3
41 library.
42 .Pp
43 The format of each line is:
44 .Pp
45 .Dl [prog:]command [arg ...]
46 .Pp
47 .Ar command
48 is one of the
49 .Xr editline 3
50 builtin commands.
51 Refer to
52 .Sx BUILTIN COMMANDS
53 for more information.
54 .Pp
55 .Ar prog
56 is the program name string that a program defines when it calls
57 .Xr el_init 3
58 to set up
59 .Xr editline 3 ,
60 which is usually
61 .Va argv[0] .
62 .Ar command
63 will be executed for any program which matches
64 .Ar prog .
65 .Pp
66 .Ar prog
67 may also be a
68 .Xr regex 3
69 style
70 regular expression, in which case
71 .Ar command
72 will be executed for any program that matches the regular expression.
73 .Pp
74 If
75 .Ar prog
76 is absent,
77 .Ar command
78 is executed for all programs.
79 .Sh BUILTIN COMMANDS
80 The
81 .Nm editline
82 library has some builtin commands, which affect the way
83 that the line editing and history functions operate.
84 These are based on similar named builtins present in the tcsh shell.
85 .Pp
86 The following builtin commands are available:
87 .Bl -tag -width 4n
88 .It Ic bind Oo Fl aeklrsv Oc Op Ar key Op Ar command
89 Without options and arguments, list all bound keys and macros, and
90 the editor command or input string to which each one is bound.
91 If only
92 .Ar key
93 is supplied, show the binding for that key or macro.
94 If
95 .Ar key command
96 is supplied, bind the editor
97 .Ar command
98 to that key or macro.
99 .Pp
100 The options are as follows:
101 .Bl -tag -width 4n
102 .It Fl a
103 List or change key bindings in the
104 .Xr vi 1
105 mode alternate (command mode) key map.
106 .It Fl e
107 Bind all keys to the standard GNU Emacs-like bindings.
108 .It Fl k
109 .Ar key
110 is interpreted as a symbolic arrow key name, which may be one of
111 .Sq up ,
112 .Sq down ,
113 .Sq left
114 or
115 .Sq right .
116 .It Fl l
117 List all editor commands and a short description of each.
118 .It Fl r
119 Remove the binding of the key or macro
120 .Ar key .
121 .It Fl s
122 Define a keyboard macro rather than a key binding or command macro:
123 .Ar command
124 is taken as a literal string and appended to the input queue whenever
125 .Ar key
126 is typed.
127 Bound keys and macros in
128 .Ar command
129 are themselves reinterpreted, and this continues for ten levels of
130 interpretation.
131 .It Fl v
132 Bind all keys to the standard
133 .Xr vi 1 Ns -like
134 bindings.
135 .El
136 .Pp
137 The
138 .Xr editline 7
139 manual documents all editor commands and contains more information
140 about macros and the input queue.
141 .Pp
142 .Ar key
143 and
144 .Ar command
145 can contain control characters of the form
146 .Sm off
147 .Sq No ^ Ar character
148 .Sm on
149 .Po
150 e.g.\&
151 .Sq ^A
152 .Pc ,
153 and the following backslashed escape sequences:
154 .Pp
155 .Bl -tag -compact -offset indent -width 4n
156 .It Ic \ea
157 Bell
158 .It Ic \eb
159 Backspace
160 .It Ic \ee
161 Escape
162 .It Ic \ef
163 Formfeed
164 .It Ic \en
165 Newline
166 .It Ic \er
167 Carriage return
168 .It Ic \et
169 Horizontal tab
170 .It Ic \ev
171 Vertical tab
172 .Sm off
173 .It Sy \e Ar nnn
174 .Sm on
175 The ASCII character corresponding to the octal number
176 .Ar nnn .
177 .El
178 .Pp
179 .Sq \e
180 nullifies the special meaning of the following character,
181 if it has any, notably
182 .Sq \e
183 and
184 .Sq ^ .
185 .It Ic echotc Oo Fl sv Oc Ar arg Ar ...
186 Exercise terminal capabilities given in
187 .Ar arg ... .
188 If
189 .Ar arg
190 is
191 .Sq baud ,
192 .Sq cols ,
193 .Sq lines ,
194 .Sq rows ,
195 .Sq meta ,
196 or
197 .Sq tabs ,
198 the value of that capability is printed, with
199 .Dq yes
200 or
201 .Dq no
202 indicating that the terminal does or does not have that capability.
203 .Pp
204 .Fl s
205 returns an empty string for non-existent capabilities, rather than
206 causing an error.
207 .Fl v
208 causes messages to be verbose.
209 .It Ic edit Op Li on | Li off
210 Enable or disable the
211 .Nm editline
212 functionality in a program.
213 .It Ic history Ar list | Ar size Dv n | Ar unique Dv n
214 The
215 .Ar list
216 command lists all entries in the history.
217 The
218 .Ar size
219 command sets the history size to
220 .Dv n
221 entries.
222 The
223 .Ar unique
224 command controls if history should keep duplicate entries.
225 If
226 .Dv n
227 is non zero, only keep unique history entries.
228 If
229 .Dv n
230 is zero, then keep all entries (the default).
231 .It Ic settc Ar cap Ar val
232 Set the terminal capability
233 .Ar cap
234 to
235 .Ar val ,
236 as defined in
237 .Xr termcap 5 .
238 No sanity checking is done.
239 .It Ic setty Xo
240 .Op Fl adqx
241 .Op Ar +mode
242 .Op Ar -mode
243 .Op Ar mode
244 .Op Ar char=c
245 .Xc
246 Control which tty modes that
247 .Nm
248 won't allow the user to change.
249 .Fl d ,
250 .Fl q
251 or
252 .Fl x
253 tells
254 .Ic setty
255 to act on the
256 .Sq edit ,
257 .Sq quote
258 or
259 .Sq execute
260 set of tty modes respectively; defaulting to
261 .Fl x .
262 .Pp
263 Without other arguments,
264 .Ic setty
265 lists the modes in the chosen set which are fixed on
266 .Po
267 .Sq +mode
268 .Pc
269 or off
270 .Po
271 .Sq -mode
272 .Pc .
273 .Fl a
274 lists all tty modes in the chosen set regardless of the setting.
275 With
276 .Ar +mode ,
277 .Ar -mode
278 or
279 .Ar mode ,
280 fixes
281 .Ar mode
282 on or off or removes control of
283 .Ar mode
284 in the chosen set.
285 .Pp
286 .Ic Setty
287 can also be used to set tty characters to particular values using
288 .Ar char=value .
289 If
290 .Ar value
291 is empty
292 then the character is set to
293 .Dv _POSIX_VDISABLE .
294 .It Ic telltc
295 List the values of all the terminal capabilities (see
296 .Xr termcap 5 ) .
297 .El
298 .Sh FILES
299 .Bl -tag -width "~/.editrcXXX"
300 .It Pa ~/.editrc
301 User configuration file for the
302 .Xr editline 3
303 library.
304 .El
305 .Sh SEE ALSO
306 .Xr editline 3 ,
307 .Xr regex 3 ,
308 .Xr termcap 5 ,
309 .Xr editline 7
310 .Sh AUTHORS
311 .An -nosplit
312 The
313 .Nm editline
314 library was written by
315 .An Christos Zoulas ,
316 and this manual was written by
317 .An Luke Mewburn ,
318 with some sections inspired by tcsh.