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