xref: /dragonfly/usr.bin/tset/tset.1 (revision 10cbe914)
1.\" Copyright (c) 1985, 1990, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\" 3. All advertising materials mentioning features or use of this software
13.\"    must display the following acknowledgement:
14.\"	This product includes software developed by the University of
15.\"	California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\"    may be used to endorse or promote products derived from this software
18.\"    without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\"	@(#)tset.1	8.1 (Berkeley) 6/9/93
33.\" $FreeBSD: src/usr.bin/tset/tset.1,v 1.5.2.5 2003/02/24 22:37:42 trhodes Exp $
34.\" $DragonFly: src/usr.bin/tset/tset.1,v 1.4 2006/04/17 18:01:38 swildner Exp $
35.\"
36.Dd June 9, 1993
37.Dt TSET 1
38.Os
39.Sh NAME
40.Nm tset ,
41.Nm reset
42.Nd terminal initialization
43.Sh SYNOPSIS
44.Nm
45.Op Fl IQrSs
46.Op Fl
47.Op Fl e Ar ch
48.Op Fl i Ar ch
49.Op Fl k Ar ch
50.Op Fl m Ar mapping
51.Op Ar terminal
52.Nm reset
53.Op Fl IQrSs
54.Op Fl
55.Op Fl e Ar ch
56.Op Fl i Ar ch
57.Op Fl k Ar ch
58.Op Fl m Ar mapping
59.Op Ar terminal
60.Sh DESCRIPTION
61The
62.Nm
63utility initializes terminals.
64It first determines the type of terminal that you are using.
65This determination is done as follows, using the first terminal type found.
66.Pp
67.Bl -bullet -compact -offset indent
68.It
69The
70.Ar terminal
71argument specified on the command line.
72.It
73The value of the
74.Ev TERM
75environment variable.
76.It
77The terminal type associated with the standard error output device in the
78.Pa /etc/ttys
79file.
80.It
81The default terminal type, ``unknown''.
82.El
83.Pp
84If the terminal type was not specified on the command-line, the
85.Fl m
86option mappings are then applied (see below for more information).
87Then, if the terminal type begins with a question mark (``?''), the user is
88prompted for confirmation of the terminal type.
89An empty response confirms the type, or, another type can be entered to
90specify a new type.
91Once the terminal type has been determined, the termcap entry for the terminal
92is retrieved.
93If no termcap entry is found for the type, the user is prompted for another
94terminal type.
95.Pp
96Once the termcap entry is retrieved, the window size, backspace, interrupt
97and line kill characters (among many other things) are set and the terminal
98and tab initialization strings are sent to the standard error output.
99Finally, if the erase, interrupt and line kill characters have changed,
100or are not set to their default values, their values are displayed to the
101standard error output.
102.Pp
103When invoked as
104.Nm reset ,
105.Nm
106sets cooked and echo modes, turns off cbreak and raw modes, turns on
107newline translation and resets any unset special characters to their
108default values before doing the terminal initialization described above.
109This is useful after a program dies leaving a terminal in an abnormal state.
110Note, you may have to type
111.Dq Li <LF>reset<LF>
112(the line-feed character is normally control-J) to get the terminal
113to work, as carriage-return may no longer work in the abnormal state.
114Also, the terminal will often not echo the command.
115.Pp
116The options are as follows:
117.Bl -tag -width flag
118.It Fl
119The terminal type is displayed to the standard output, and the terminal is
120not initialized in any way.
121.It Fl e
122Set the erase character to
123.Ar ch .
124.It Fl I
125Do not send the terminal or tab initialization strings to the terminal.
126.It Fl i
127Set the interrupt character to
128.Ar ch .
129.It Fl k
130Set the line kill character to
131.Ar ch .
132.It Fl m
133Specify a mapping from a port type to a terminal.
134See below for more information.
135.It Fl Q
136Don't display any values for the erase, interrupt and line kill characters.
137.It Fl r
138Print the terminal type to the standard error output.
139.It Fl S
140Print the terminal type and the termcap entry to the standard output.
141See the section below on setting the environment for details.
142.It Fl s
143Print the sequence of shell commands to initialize the environment variables
144.Ev TERM
145and
146.Ev TERMCAP
147to the standard output.
148See the section below on setting the environment for details.
149.El
150.Pp
151The arguments for the
152.Fl e ,
153.Fl i
154and
155.Fl k
156options may either be entered as actual characters or by using the
157.Dq hat
158notation, i.e. control-h may be specified as
159.Dq Li ^H
160or
161.Dq Li ^h .
162.Sh SETTING THE ENVIRONMENT
163It is often desirable to enter the terminal type and information about
164the terminal's capabilities into the shell's environment.
165This is done using the
166.Fl S
167and
168.Fl s
169options.
170.Pp
171When the
172.Fl S
173option is specified, the terminal type and the termcap entry are written
174to the standard output, separated by a space and without a terminating
175newline.
176This can be assigned to an array by
177.Xr csh 1
178and
179.Xr ksh 1
180users and then used like any other shell array.
181.Pp
182When the
183.Fl s
184option is specified, the commands to enter the information into the
185shell's environment are written to the standard output.
186If the
187.Ev SHELL
188environment variable ends in ``csh'', the commands are for the
189.Xr csh 1 ,
190otherwise, they are for
191.Xr sh 1 .
192Note, the
193.Xr csh 1
194commands set and unset the shell variable
195.Dq noglob ,
196leaving it unset.
197The following line in the
198.Pa .login
199or
200.Pa .profile
201files will initialize the environment correctly:
202.Bd -literal -offset indent
203eval \`tset -s options ... \`
204.Ed
205.Pp
206To demonstrate a simple use of the
207.Fl S
208option, the following lines in the
209.Pa .login
210file have an equivalent effect:
211.Bd -literal -offset indent
212set noglob
213set term=(`tset -S options ...`)
214setenv TERM $term[1]
215setenv TERMCAP "$term[2]"
216unset term
217unset noglob
218.Ed
219.Sh TERMINAL TYPE MAPPING
220When the terminal is not hardwired into the system (or the current system
221information is incorrect) the terminal type derived from the
222.Pa /etc/ttys
223file or the
224.Ev TERM
225environment variable is often something generic like
226.Dq network ,
227.Dq dialup ,
228or
229.Dq unknown .
230When
231.Nm
232is used in a startup script
233.Pf ( Pa .profile
234for
235.Xr sh 1
236users or
237.Pa .login
238for
239.Xr csh 1
240users) it is often desirable to provide information about the type of
241terminal used on such ports.
242The purpose of the
243.Fl m
244option is to
245.Dq map
246from some set of conditions to a terminal type, that is, to
247tell
248.Nm
249``If I'm on this port at a particular speed, guess that I'm on that
250kind of terminal''.
251.Pp
252The argument to the
253.Fl m
254option consists of an optional port type, an optional operator, an optional
255baud rate specification, an optional colon (``:'') character and a terminal
256type.
257The port type is a string (delimited by either the operator or the colon
258character).
259The operator may be any combination of:
260.Dq Li \&> ,
261.Dq Li \&< ,
262.Dq Li \&@ ,
263and
264.Dq Li \&! ;
265.Dq Li \&>
266means greater than,
267.Dq Li \&<
268means less than,
269.Dq Li \&@
270means equal to
271and
272.Dq Li !\&
273inverts the sense of the test.
274The baud rate is specified as a number and is compared with the speed
275of the standard error output (which should be the control terminal).
276The terminal type is a string.
277.Pp
278If the terminal type is not specified on the command line, the
279.Fl m
280mappings are applied to the terminal type.
281If the port type and baud rate match the mapping, the terminal type specified
282in the mapping replaces the current type.
283If more than one mapping is specified, the first applicable mapping is used.
284.Pp
285For example, consider the following mapping:
286.Dq Li dialup>9600:vt100 .
287The port type is
288.Dq Li dialup ,
289the operator is
290.Dq Li > ,
291the baud rate specification is
292.Dq Li 9600 ,
293and the terminal type is
294.Dq Li vt100 .
295The result of this mapping is to specify that if the terminal type is
296.Dq Li dialup ,
297and the baud rate is greater than 9600 baud, a terminal type of
298.Dq Li vt100
299will be used.
300.Pp
301If no port type is specified, the terminal type will match any port type,
302for example,
303.Dq Li -m dialup:vt100 -m :?xterm
304will cause any dialup port, regardless of baud rate, to match the terminal
305type
306.Dq Li vt100 ,
307and any non-dialup port type to match the terminal type
308.Dq Li ?xterm .
309Note, because of the leading question mark, the user will be
310queried on a default port as to whether they are actually using an
311.Ar xterm
312terminal.
313.Pp
314No whitespace characters are permitted in the
315.Fl m
316option argument.
317Also, to avoid problems with metacharacters, it is suggested that the entire
318.Fl m
319option argument be placed within single quote characters, and that
320.Xr csh 1
321users insert a backslash character (``\e'') before any exclamation
322marks (``!'').
323.Sh ENVIRONMENT
324The
325.Nm
326command utilizes the
327.Ev SHELL
328and
329.Ev TERM
330environment variables.
331.Sh FILES
332.Bl -tag -width /usr/share/misc/termcap -compact
333.It Pa /etc/ttys
334system port name to terminal type mapping database
335.It Pa /usr/share/misc/termcap
336terminal capability database
337.El
338.Sh COMPATIBILITY
339The
340.Fl A ,
341.Fl E ,
342.Fl h ,
343.Fl u
344and
345.Fl v
346options have been deleted from the
347.Nm
348utility.
349None of them were documented in
350.Bx 4.3
351and all are of limited utility at
352best.
353The
354.Fl a ,
355.Fl d
356and
357.Fl p
358options are similarly not documented or useful, but were retained as they
359appear to be in widespread use.
360It is strongly recommended that any usage of these three options be
361changed to use the
362.Fl m
363option instead.
364The
365.Fl n
366option remains, but has no effect.
367It is still permissible to specify the
368.Fl e ,
369.Fl i
370and
371.Fl k
372options without arguments, although it is strongly recommended that such
373usage be fixed to explicitly specify the character.
374.Pp
375Executing
376.Nm
377as
378.Nm reset
379no longer implies the
380.Fl Q
381option.
382Also, the interaction between the
383.Fl
384option and the
385.Ar terminal
386argument in some historic implementations of
387.Nm
388has been removed.
389.Pp
390Finally, the
391.Nm
392implementation has been completely redone (as part of the addition to the
393system of a
394.St -p1003.1-88
395compliant terminal interface) and will no longer compile on systems with
396older terminal interfaces.
397.Sh SEE ALSO
398.Xr csh 1 ,
399.Xr sh 1 ,
400.Xr stty 1 ,
401.Xr tty 4 ,
402.Xr termcap 5 ,
403.Xr ttys 5 ,
404.Xr environ 7
405.Sh HISTORY
406The
407.Nm
408command appeared in
409.Bx 3.0 .
410