usr.bin/tip/tip/cu.1

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