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