usr.bin/tip/tip/tip.1

   1 .\"     $OpenBSD: tip.1,v 1.37 2006/06/07 06:35:59 mbalmer Exp $
   2 .\"     $NetBSD: tip.1,v 1.7 1994/12/08 09:31:05 jtc Exp $
   3 .\"
   4 .\" Copyright (c) 1980, 1990, 1993
   5 .\"     The Regents of the University of California.  All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. Neither the name of the University nor the names of its contributors
  16 .\"    may be used to endorse or promote products derived from this software
  17 .\"    without specific prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .\"     @(#)tip.1       8.4 (Berkeley) 4/18/94
  32 .\" $FreeBSD$
  33 .\"
  34 .Dd August 31, 2006
  35 .Dt TIP 1
  36 .Os
  37 .Sh NAME
  38 .Nm tip
  39 .Nd connect to a remote system
  40 .Sh SYNOPSIS
  41 .Nm
  42 .Op Fl nv
  43 .Op Fl Ar speed
  44 .Op Ar system-name
  45 .Sh DESCRIPTION
  46 The
  47 .Nm
  48 utility
  49 establishes a full-duplex connection to another machine, giving the
  50 appearance of being logged in directly on the remote CPU.
  51 It goes without saying that you must have a login on the machine (or
  52 equivalent) to which you wish to connect.
  53 .Pp
  54 The options are as follows:
  55 .Bl -tag -width indent
  56 .It Fl n
  57 No escape (disable tilde).
  58 .It Fl v
  59 Set verbose mode.
  60 .El
  61 .Pp
  62 If
  63 .Ar speed
  64 is specified, it will override any baudrate specified in the system
  65 description being used.
  66 .Pp
  67 If neither
  68 .Ar speed
  69 nor
  70 .Ar system-name
  71 are specified,
  72 .Ar system-name
  73 will be set to the value of the
  74 .Ev HOST
  75 environment variable.
  76 .Pp
  77 If
  78 .Ar speed
  79 is specified but
  80 .Ar system-name
  81 is not,
  82 .Ar system-name
  83 will be set to a value of
  84 .Dq Li tip
  85 with
  86 .Ar speed
  87 appended.
  88 For example,
  89 .Nm Fl 1200
  90 will set
  91 .Ar system-name
  92 to
  93 .Dq Li tip1200 .
  94 .Pp
  95 Typed characters are normally transmitted directly to the remote
  96 machine (which does the echoing as well).
  97 A tilde
  98 .Pq Ql ~
  99 appearing as the first character of a line is an escape signal; the
 100 following are recognized:
 101 .Bl -tag -width indent
 102 .It Ic ~^D No or Ic ~.
 103 Drop the connection and exit.
 104 Only the connection is dropped \(en the login session is not terminated.
 105 .It Ic ~c Op Ar name
 106 Change directory to
 107 .Ar name
 108 (no argument implies change to home directory).
 109 .It Ic ~!
 110 Escape to a shell (exiting the shell will return to
 111 .Nm ) .
 112 .It Ic ~>
 113 Copy file from local to remote.
 114 The
 115 .Nm
 116 utility
 117 prompts for the name of a local file to transmit.
 118 .It Ic ~<
 119 Copy file from remote to local.
 120 The
 121 .Nm
 122 utility
 123 prompts first for the name of the file to be sent, then for a command
 124 to be executed on the remote machine.
 125 .It Ic ~p Ar from Op Ar to
 126 Send a file to a remote
 127 .Ux
 128 host.
 129 This command causes the remote
 130 .Ux
 131 system to run the following command string,
 132 sending it the
 133 .Ar from
 134 file:
 135 .Pp
 136 .Dl "stty -echo; cat > 'to'; stty echo"
 137 .Pp
 138 If the
 139 .Ar to
 140 file is not specified, the
 141 .Ar from
 142 file name is used.
 143 This command is actually a
 144 .Ux
 145 specific version of the
 146 .Ic ~>
 147 command.
 148 .It Ic ~t Ar from Op Ar to
 149 Take a file from a remote
 150 .Ux
 151 host.
 152 As in the
 153 .Ic ~p
 154 command, the
 155 .Ar to
 156 file defaults to the
 157 .Ar from
 158 file name if it is not specified.
 159 The remote host executes the following command string
 160 to send the file to
 161 .Nm :
 162 .Pp
 163 .Dl "cat 'from'; echo '' | tr '\e012' '\e01'"
 164 .It Ic ~|
 165 Pipe the output from a remote command to a local
 166 .Ux
 167 process.
 168 The command string sent to the local
 169 .Ux
 170 system is processed by the shell.
 171 .It Ic ~$
 172 Pipe the output from a local
 173 .Ux
 174 process to the remote host.
 175 The command string sent to the local
 176 .Ux
 177 system is processed by the shell.
 178 .It Ic ~C
 179 Fork a child process on the local system to perform special protocols
 180 such as
 181 .Tn XMODEM .
 182 The child program will be run with the following arrangement of
 183 file descriptors:
 184 .Bd -literal -offset indent
 185 0 <-> remote tty in
 186 1 <-> remote tty out
 187 2 <-> local tty stderr
 188 .Ed
 189 .It Ic ~#
 190 Send a
 191 .Dv BREAK
 192 to the remote system.
 193 For systems which do not support the necessary
 194 .Fn ioctl
 195 call, the break is simulated by a sequence of line speed changes and
 196 .Dv DEL
 197 characters.
 198 .It Ic ~s
 199 Set a variable (see the discussion below).
 200 .It Ic ~v
 201 List all variables and their values (if set).
 202 .It Ic ~^Z
 203 Stop
 204 .Nm
 205 (only available with job control).
 206 .It Ic ~^Y
 207 Stop only the
 208 .Dq "local side"
 209 of
 210 .Nm
 211 (only available with job control); the
 212 .Dq "remote side"
 213 of
 214 .Nm ,
 215 the side that displays output from the remote host, is left running.
 216 .It Ic ~?
 217 Get a summary of the tilde escapes.
 218 .El
 219 .Pp
 220 To find the system description, and thus the operating characteristics
 221 of
 222 .Ar system-name ,
 223 .Nm
 224 searches for a system description with a name identical to
 225 .Ar system-name .
 226 The search order is as follows:
 227 .Bl -enum -offset indent
 228 .It
 229 If the environment variable
 230 .Ev REMOTE
 231 does not start with a
 232 .Ql /
 233 it is assumed to be a system description, and is considered first.
 234 .It
 235 If the environment variable
 236 .Ev REMOTE
 237 begins with a
 238 .Ql /
 239 it is assumed to be a path to a
 240 .Xr remote 5
 241 database, and the specified database is searched.
 242 .It
 243 The default
 244 .Xr remote 5
 245 database,
 246 .Pa /etc/remote ,
 247 is searched.
 248 .El
 249 .Pp
 250 See
 251 .Xr remote 5
 252 for full documentation on system descriptions.
 253 .Pp
 254 The
 255 .Va br
 256 capability is used in system descriptions to specify the baud rate
 257 with which to establish a connection.
 258 If the value specified is not suitable, the baud rate to be used may
 259 be given on the command line, e.g.\&
 260 .Dq Li "tip -300 mds" .
 261 .Pp
 262 When
 263 .Nm
 264 establishes a connection, it sends out the connection message
 265 specified in the
 266 .Va cm
 267 capability of the system description being used.
 268 .Pp
 269 When
 270 .Nm
 271 prompts for an argument, for example during setup of a file transfer, the
 272 line typed may be edited with the standard erase and kill characters.
 273 A null line in response to a prompt, or an interrupt, will abort the
 274 dialogue and return the user to the remote machine.
 275 .Pp
 276 The
 277 .Nm
 278 utility
 279 guards against multiple users connecting to a remote system by opening
 280 modems and terminal lines with exclusive access, and by honoring the
 281 locking protocol used by
 282 .Xr uucico 8 Pq Pa ports/net/freebsd-uucp .
 283 .Pp
 284 During file transfers
 285 .Nm
 286 provides a running count of the number of lines transferred.
 287 When using the
 288 .Ic ~>
 289 and
 290 .Ic ~<
 291 commands, the
 292 .Va eofread
 293 and
 294 .Va eofwrite
 295 variables are used to recognize end-of-file when reading, and specify
 296 end-of-file when writing (see below).
 297 File transfers normally depend on hardwareflow or tandem mode for flow control.
 298 If the remote system does not support hardwareflow or tandem mode,
 299 .Va echocheck
 300 may be set to indicate that
 301 .Nm
 302 should synchronize with the remote system on the echo of each
 303 transmitted character.
 304 .Pp
 305 When
 306 .Nm
 307 must dial a phone number to connect to a system, it will print various
 308 messages indicating its actions.
 309 The
 310 .Nm
 311 utility
 312 supports a variety of auto-call units and modems with the
 313 .Va at
 314 capability in system descriptions.
 315 .Pp
 316 Support for Ventel 212+ (ventel), Hayes AT-style (hayes),
 317 USRobotics Courier (courier), Telebit T3000 (t3000) and
 318 Racal-Vadic 831 (vadic) units is enabled by default.
 319 .Pp
 320 Support for Bizcomp 1031[fw] (biz31[fw]), Bizcomp 1022[fw]
 321 (biz22[fw]), DEC DF0[23]-AC (df0[23]), DEC DN-11 (dn11) and
 322 Racal-Vadic 3451 (v3451) units can be added by recompiling
 323 .Nm
 324 with the appropriate defines.
 325 .Pp
 326 Note that if support for both the Racal-Vadic 831 and 3451 is enabled,
 327 they are referred to as the v831 and v3451, respectively.
 328 If only one of the two is supported, it is referred to as vadic.
 329 .Ss Variables
 330 The
 331 .Nm
 332 utility
 333 maintains a set of variables which control its operation.
 334 Some of these variables are read-only to normal users (root is allowed
 335 to change anything of interest).
 336 Variables may be displayed and set through the
 337 .Ic ~s
 338 escape.
 339 The syntax for variables is patterned after
 340 .Xr vi 1
 341 and
 342 .Xr Mail 1 .
 343 Supplying
 344 .Dq Li all
 345 as an argument to the set command displays all variables readable by
 346 the user.
 347 Alternatively, the user may request display of a particular variable
 348 by attaching a
 349 .Ql \&?
 350 to the end.
 351 For example,
 352 .Dq Li escape?
 353 displays the current escape character.
 354 .Pp
 355 Variables are numeric, string, character, or boolean values.
 356 Boolean variables are set merely by specifying their name; they may be
 357 reset by prepending a
 358 .Ql \&!
 359 to the name.
 360 Other variable types are set by concatenating an
 361 .Ql =
 362 and the value.
 363 The entire assignment must not have any blanks in it.
 364 A single set command may be used to interrogate as well as set a
 365 number of variables.
 366 Variables may be initialized at run time by placing set commands
 367 (without the
 368 .Ic ~s
 369 prefix) in the initialization file
 370 .Pa ~/.tiprc ;
 371 the
 372 .Fl v
 373 option additionally causes
 374 .Nm
 375 to display the sets as they are made.
 376 Certain common variables have abbreviations.
 377 The following is a list of common variables, their abbreviations, and
 378 their default values:
 379 .Bl -tag -width indent
 380 .It Va baudrate
 381 .Pq Vt num
 382 The baud rate at which the connection was established;
 383 abbreviated
 384 .Va ba .
 385 .It Va beautify
 386 .Pq Vt bool
 387 Discard unprintable characters when a session is being
 388 scripted; abbreviated
 389 .Va be .
 390 .It Va dialtimeout
 391 .Pq Vt num
 392 When dialing a phone number, the time (in seconds) to wait for a
 393 connection to be established; abbreviated
 394 .Va dial .
 395 .It Va echocheck
 396 .Pq Vt bool
 397 Synchronize with the remote host during file transfer by
 398 waiting for the echo of the last character transmitted; default is
 399 .Cm off .
 400 .It Va eofread
 401 .Pq Vt str
 402 The set of characters which signify an end-of-transmission
 403 during a
 404 .Ic ~<
 405 file transfer command; abbreviated
 406 .Va eofr .
 407 .It Va eofwrite
 408 .Pq Vt str
 409 The string sent to indicate end-of-transmission during a
 410 .Ic ~>
 411 file transfer command; abbreviated
 412 .Va eofw .
 413 .It Va eol
 414 .Pq Vt str
 415 The set of characters which indicate an end-of-line.
 416 The
 417 .Nm
 418 utility
 419 will recognize escape characters only after an end-of-line.
 420 .It Va escape
 421 .Pq Vt char
 422 The command prefix (escape) character; abbreviated
 423 .Va es ;
 424 default value is
 425 .Ql ~ .
 426 .It Va exceptions
 427 .Pq Vt str
 428 The set of characters which should not be discarded due to the
 429 beautification switch; abbreviated
 430 .Va ex ;
 431 default value is
 432 .Dq Li \et\en\ef\eb .
 433 .It Va force
 434 .Pq Vt char
 435 The character used to force literal data transmission;
 436 abbreviated
 437 .Va fo ;
 438 default value is
 439 .Ql ^P .
 440 .It Va framesize
 441 .Pq Vt num
 442 The amount of data (in bytes) to buffer between file system
 443 writes when receiving files; abbreviated
 444 .Va fr .
 445 .It Va hardwareflow
 446 .Pq Vt bool
 447 Whether hardware flow control (CRTSCTS) is enabled for the
 448 connection; abbreviated
 449 .Va hf ;
 450 default value is
 451 .Cm off .
 452 .It Va host
 453 .Pq Vt str
 454 The name of the host to which you are connected; abbreviated
 455 .Va ho .
 456 .It Va linedisc
 457 .Pq Vt num
 458 The line discipline to use; abbreviated
 459 .Va ld .
 460 .It Va prompt
 461 .Pq Vt char
 462 The character which indicates an end-of-line on the remote
 463 host; abbreviated
 464 .Va pr ;
 465 default value is
 466 .Ql \en .
 467 This value is used to synchronize during data transfers.
 468 The count of lines transferred during a file transfer command is based
 469 on receipt of this character.
 470 .It Va raise
 471 .Pq Vt bool
 472 Upper case mapping mode; abbreviated
 473 .Va ra ;
 474 default value is
 475 .Cm off .
 476 When this mode is enabled, all lowercase letters will be mapped to
 477 uppercase by
 478 .Nm
 479 for transmission to the remote machine.
 480 .It Va raisechar
 481 .Pq Vt char
 482 The input character used to toggle uppercase mapping mode;
 483 abbreviated
 484 .Va rc ;
 485 not set by default.
 486 .It Va record
 487 .Pq Vt str
 488 The name of the file in which a session script is recorded;
 489 abbreviated
 490 .Va rec ;
 491 default value is
 492 .Pa tip.record .
 493 .It Va script
 494 .Pq Vt bool
 495 Session scripting mode; abbreviated
 496 .Va sc ;
 497 default is
 498 .Cm off .
 499 When
 500 .Va script
 501 is
 502 .Cm true ,
 503 .Nm
 504 will record everything transmitted by the remote machine in the script
 505 record file specified in
 506 .Va record .
 507 If the
 508 .Va beautify
 509 switch is on, only printable
 510 .Tn ASCII
 511 characters will be included in the script file (those characters
 512 between 040 and 0177).
 513 The variable
 514 .Va exceptions
 515 is used to indicate characters which are an exception to the normal
 516 beautification rules.
 517 .It Va tabexpand
 518 .Pq Vt bool
 519 Expand tabs to spaces during file transfers; abbreviated
 520 .Va tab ;
 521 default value is
 522 .Cm false .
 523 Each tab is expanded to 8 spaces.
 524 .It Va tandem
 525 .Pq Vt bool
 526 Use XON/XOFF flow control to throttle data from the remote host;
 527 abbreviated
 528 .Va ta .
 529 The default value is
 530 .Cm true
 531 unless the
 532 .Va nt
 533 capability has been specified in
 534 .Pa /etc/remote ,
 535 in which case the default value is
 536 .Cm false .
 537 .It Va verbose
 538 .Pq Vt bool
 539 Verbose mode; abbreviated
 540 .Va verb ;
 541 default is
 542 .Cm true .
 543 When verbose mode is enabled,
 544 .Nm
 545 prints messages while dialing, shows the current number of lines
 546 transferred during a file transfer operations, and more.
 547 .El
 548 .Sh ENVIRONMENT
 549 .Bl -tag -width indent
 550 .It Ev HOME
 551 The home directory to use for the
 552 .Ic ~c
 553 command.
 554 .It Ev HOST
 555 The default value for
 556 .Ar system-name
 557 if none is specified via the command line.
 558 .It Ev PHONES
 559 A path to a
 560 .Xr phones 5
 561 database.
 562 .It Ev REMOTE
 563 A system description, or an absolute path to a
 564 .Xr remote 5
 565 system description database.
 566 .It Ev SHELL
 567 The name of the shell to use for the
 568 .Ic ~!
 569 command; default value is
 570 .Dq Li /bin/sh .
 571 .El
 572 .Sh FILES
 573 .Bl -tag -width ".Pa /var/spool/lock/LCK..*" -compact
 574 .It Pa ~/.tiprc
 575 initialization file
 576 .It Pa tip.record
 577 record file
 578 .It Pa /etc/phones
 579 default
 580 .Xr phones 5
 581 file
 582 .It Pa /etc/remote
 583 global
 584 .Xr remote 5
 585 database
 586 .It Pa /var/log/aculog
 587 line access log
 588 .It Pa /var/spool/lock/LCK..*
 589 lock file to avoid conflicts with
 590 .Xr uucp 1 Pq Pa ports/net/freebsd-uucp
 591 .El
 592 .Sh SEE ALSO
 593 .Xr cu 1 ,
 594 .Xr phones 5 ,
 595 .Xr remote 5
 596 .Sh HISTORY
 597 The
 598 .Nm
 599 command appeared in
 600 .Bx 4.2 .
 601 .Sh BUGS
 602 The full set of variables is undocumented and should, probably, be
 603 pared down.