1.\" $NetBSD: tip.1,v 1.34 2023/04/25 01:48:37 gutteridge 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 serial terminal emulator 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 \&~> 181Copy file from local to remote. 182.Nm 183prompts for the name of a local file to transmit. 184.It Ic \&~< 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 > '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 ``~>'' 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 229.Tn XMODEM . 230The child program will be run with the following 231arrangement of file descriptors: 232.Bl -column -offset indent 0 "<->" "remote tty in" 233.It 0 Ta <-> Ta remote tty in 234.It 1 Ta <-> Ta remote tty out 235.It 2 Ta <-> Ta local tty out 236.El 237.It Ic \&~+ 238Synonym for \&~C, provided for compatibility with other versions of 239.Nm cu . 240.It Ic \&~# 241Send a 242.Dv BREAK 243to the remote system. 244For systems which don't support the 245necessary 246.Ar ioctl 247call the break is simulated by a sequence of line speed changes 248and 249.Dv DEL 250characters. 251.It Ic \&~s 252Set a variable (see the discussion below). 253.It Ic \&~^Z 254Stop 255.Nm 256(only available with job control). 257.It Ic \&~^Y 258Stop only the ``local side'' of 259.Nm 260(only available with job control); 261the ``remote side'' of 262.Nm , 263the side that displays output from the remote host, is left running. 264.It Ic \&~? 265Get a summary of the tilde escapes 266.El 267.Pp 268.Nm 269uses the file 270.Pa /etc/remote 271to find how to reach a particular 272system and to find out how it should operate while talking 273to the system; 274refer to 275.Xr remote 5 276for a full description. 277Each system has a default baud rate with which to 278establish a connection. 279If this value is not suitable, the baud rate 280to be used may be specified on the command line, e.g. 281.Ql "tip -300 mds" . 282.Pp 283When 284.Nm 285establishes a connection it sends out a 286connection message to the remote system; the default value, if any, 287is defined in 288.Pa /etc/remote 289(see 290.Xr remote 5 ) . 291.Pp 292When 293.Nm 294prompts for an argument (e.g. during setup of 295a file transfer) the line typed may be edited with the standard 296erase and kill characters. 297A null line in response to a prompt, 298or an interrupt, will abort the dialogue and return you to the 299remote machine. 300.Pp 301.Nm 302guards against multiple users connecting to a remote system 303by opening modems and terminal lines with exclusive access, 304and by honoring the locking protocol used by 305.Xr uucico 8 . 306.Pp 307During file transfers 308.Nm 309provides a running count of the number of lines transferred. 310When using the ~> and ~< commands, the ``eofread'' and ``eofwrite'' 311variables are used to recognize end-of-file when reading, and 312specify end-of-file when writing (see below). 313File transfers normally depend on tandem mode for flow control. 314If the remote 315system does not support tandem mode, ``echocheck'' may be set 316to indicate 317.Nm 318should synchronize with the remote system on the echo of each 319transmitted character. 320.Pp 321When 322.Nm 323must dial a phone number to connect to a system it will print 324various messages indicating its actions. 325.Nm 326supports the 327.Tn DEC DN Ns -11 328and 329Racal-Vadic 831 auto-call-units; 330the 331.Tn DEC DF Ns \&02 332and 333.Tn DF Ns \&03 , 334Ventel 212+, Racal-Vadic 3451, and 335Bizcomp 1031 and 1032 integral call unit/modems. 336.Ss VARIABLES 337.Nm 338maintains a set of 339.Ar variables 340which control its operation. 341Some of these variables are read-only to normal users (root is allowed 342to change anything of interest). 343Variables may be displayed 344and set through the ``s'' escape. 345The syntax for variables is patterned 346after 347.Xr vi 1 348and 349.Xr mail 1 . 350Supplying ``all'' 351as an argument to the set command displays all variables readable by 352the user. 353Alternatively, the user may request display of a particular 354variable by attaching a `?' to the end. 355For example ``escape?'' displays 356the current escape character. 357.Pp 358Variables are numeric, string, character, or boolean values. 359Boolean 360variables are set merely by specifying their name; they may be reset 361by prepending a `!' to the name. 362Other variable types are set by 363concatenating an `=' and the value. 364The entire assignment must not 365have any blanks in it. 366A single set command may be used to interrogate 367as well as set a number of variables. 368Variables may be initialized at run time by placing set commands 369(without the ``~s'' prefix in a file 370.Pa .tiprc 371in one's home directory). 372The 373.Fl v 374option causes 375.Nm 376to display the sets as they are made. 377Certain common variables have abbreviations. 378The following is a list of common variables, 379their abbreviations, and their default values. 380.Bl -tag -width Ar 381.It Ar beautify 382(bool) Discard unprintable characters when a session is being scripted; 383abbreviated 384.Ar be . 385.It Ar baudrate 386(num) The baud rate at which the connection was established; 387abbreviated 388.Ar ba . 389.It Ar dialtimeout 390(num) When dialing a phone number, the time (in seconds) 391to wait for a connection to be established; abbreviated 392.Ar dial . 393.It Ar echocheck 394(bool) Synchronize with the remote host during file transfer by 395waiting for the echo of the last character transmitted; default is 396.Ar off . 397.It Ar eofread 398(str) The set of characters which signify an end-of-transmission 399during a ~< file transfer command; abbreviated 400.Ar eofr . 401.It Ar eofwrite 402(str) The string sent to indicate end-of-transmission during 403a ~> file transfer command; abbreviated 404.Ar eofw . 405.It Ar eol 406(str) The set of characters which indicate an end-of-line. 407.Nm 408will recognize escape characters only after an end-of-line. 409.It Ar escape 410(char) The command prefix (escape) character; abbreviated 411.Ar es ; 412default value is `~'. 413.It Ar exceptions 414(str) The set of characters which should not be discarded 415due to the beautification switch; abbreviated 416.Ar ex ; 417default value is ``\et\en\ef\eb''. 418.It Ar force 419(char) The character used to force literal data transmission; 420abbreviated 421.Ar fo ; 422default value is `^P'. 423.It Ar framesize 424(num) The amount of data (in bytes) to buffer between file system 425writes when receiving files; abbreviated 426.Ar fr . 427.It Ar host 428(str) The name of the host to which you are connected; abbreviated 429.Ar ho . 430.It Ar prompt 431(char) The character which indicates an end-of-line on the remote 432host; abbreviated 433.Ar pr ; 434default value is `\en'. 435This value is used to synchronize during 436data transfers. 437The count of lines transferred during a file transfer 438command is based on receipt of this character. 439.It Ar raise 440(bool) Upper case mapping mode; abbreviated 441.Ar ra ; 442default value is 443.Ar off . 444When this mode is enabled, all lower case letters will be mapped to 445upper case by 446.Nm 447for transmission to the remote machine. 448.It Ar raisechar 449(char) The input character used to toggle upper case mapping mode; 450abbreviated 451.Ar rc ; 452default value is `^A'. 453.It Ar record 454(str) The name of the file in which a session script is recorded; 455abbreviated 456.Ar rec ; 457default value is ``tip.record''. 458.It Ar script 459(bool) Session scripting mode; abbreviated 460.Ar sc ; 461default is 462.Ar off . 463When 464.Ar script 465is 466.Li true , 467.Nm 468will record everything transmitted by the remote machine in 469the script record file specified in 470.Ar record . 471If the 472.Ar beautify 473switch is on, only printable 474.Tn ASCII 475characters will be included in 476the script file (those characters between 040 and 0177). 477The 478variable 479.Ar exceptions 480is used to indicate characters which are an exception to the normal 481beautification rules. 482.It Ar tabexpand 483(bool) Expand tabs to spaces during file transfers; abbreviated 484.Ar tab ; 485default value is 486.Ar false . 487Each tab is expanded to 8 spaces. 488.It Ar tandem 489(bool) Use XON/XOFF flow control to throttle data from the remote host; 490abbreviated 491.Ar ta . 492The default value is 493.Ar true 494unless the 495.Ar nt 496capability has been specified in 497.Pa /etc/remote , 498in which case the default value is 499.Ar false . 500.It Ar verbose 501(bool) Verbose mode; abbreviated 502.Ar verb ; 503default is 504.Ar true . 505When verbose mode is enabled, 506.Nm 507prints messages while dialing, shows the current number 508of lines transferred during a file transfer operations, 509and more. 510.El 511.Sh ENVIRONMENT 512.Nm 513uses the following environment variables: 514.Bl -tag -width Fl 515.It Ev SHELL 516(str) The name of the shell to use for the ~! command; default 517value is ``/bin/sh'', or taken from the environment. 518.It Ev HOME 519(str) The home directory to use for the ~c command; default 520value is taken from the environment. 521.It Ev HOST 522Check for a default host if none specified. 523.El 524.Pp 525The variables 526.Ev ${REMOTE} 527and 528.Ev ${PHONES} 529are also exported. 530.Sh FILES 531.Bl -tag -width /var/spool/lock/LCK..* -compact 532.It Pa /etc/remote 533Global system descriptions. 534.It Pa /etc/phones 535Global phone number data base. 536.It ${REMOTE} 537Private system descriptions. 538.It ${PHONES} 539Private phone numbers. 540.It ~/.tiprc 541Initialization file. 542.It Pa tip.record 543Record file. 544.El 545.Sh DIAGNOSTICS 546Diagnostics are, hopefully, self explanatory. 547.Sh SEE ALSO 548.Xr phones 5 , 549.Xr remote 5 550.Sh HISTORY 551The 552.Nm 553command appeared in 554.Bx 4.2 . 555.Sh BUGS 556The full set of variables is undocumented and should, probably, be 557pared down. 558