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