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