usr.bin/tset/tset.1

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