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