path: root/usr/src/man/man1c/cu.1c

.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions and the original IEEE and The Open Group
.\" Standard, the original IEEE and The Open Group Standard is the referee
.\" document.  The original Standard can be obtained online at
.\" http://www.opengroup.org/unix/online.html.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright 1989 AT&T
.\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
.\" Copyright (c) 2001, Sun Microsystems, Inc.  All Rights Reserved.
.\"
.TH CU 1C "May 11, 2001"
.SH NAME
cu \- call another UNIX system
.SH SYNOPSIS
.LP
.nf
\fBcu\fR [\fB-c\fR \fIdevice\fR | \fB-l\fR \fIline\fR] [\fB-s\fR \fIspeed\fR] [\fB-b\fR \fIbits\fR] [\fB-h\fR] [\fB-n\fR]
     [\fB-t\fR] [\fB-d\fR] [\fB-o\fR | \fB-e\fR] [\fB-L\fR] [\fB-C\fR] [\fB-H\fR] \fI telno\fR | \fIsystemname\fR
     [\fIlocal-cmd\fR]
.fi

.SH DESCRIPTION
.sp
.LP
The command \fBcu\fR calls up another UNIX system, a terminal, or possibly a
non-UNIX system. It manages an interactive conversation with possible transfers
of files. It is convenient to think of \fBcu\fR as operating in two phases. The
first phase is the connection phase in which the connection is established.
\fBcu\fR then enters the conversation phase. The \fB-d\fR option is the only
one that applies to both phases.
.SH OPTIONS
.sp
.LP
\fBcu\fR accepts many options. The \fB-c\fR, \fB-l\fR, and \fB-s\fR options
play a part in selecting the medium. The remaining options are used in
configuring the line.
.sp
.ne 2
.na
\fB\fB-b\fR \fIbits\fR\fR
.ad
.RS 13n
Forces \fIbits\fR to be the number of bits processed on the line. \fIbits\fR is
either  \fB7\fR or \fB8\fR. This allows connection between systems with
different character sizes.  By default, the character size of the line is set
to the same value as the current local terminal, but the character size setting
is affected by \fBLC_CTYPE\fR also.
.RE

.sp
.ne 2
.na
\fB\fB-c\fR \fIdevice\fR\fR
.ad
.RS 13n
Forces \fBcu\fR to use only entries in the "Type" field (the first field in the
\fB/etc/uucp/Devices\fR file) that match the user specified \fIdevice\fR,
usually the name of a local area network.
.RE

.sp
.ne 2
.na
\fB\fB-C\fR\fR
.ad
.RS 13n
Runs the \fIlocal-cmd\fR specified at the end of the command line instead of
entering interactive mode. The \fBstdin\fR and \fBstdout\fR of the command that
is run refer to the remote connection.
.RE

.sp
.ne 2
.na
\fB\fB-d\fR\fR
.ad
.RS 13n
Prints diagnostic traces.
.RE

.sp
.ne 2
.na
\fB\fB-e\fR\fR
.ad
.RS 13n
Sets an EVEN data parity.  This option designates that EVEN parity is to be
generated for data sent to the remote system.
.RE

.sp
.ne 2
.na
\fB\fB-h\fR\fR
.ad
.RS 13n
Sets communication mode to half-duplex.  This option emulates local echo in
order to support calls to other computer systems that expect terminals to be
set to half-duplex mode.
.RE

.sp
.ne 2
.na
\fB\fB-H\fR\fR
.ad
.RS 13n
Ignores one hangup. This allows the user to remain in \fBcu\fR while the remote
machine disconnects and places a call back to the local machine.  This option
should be used when connecting to systems with callback or dialback modems.
Once the callback occurs subsequent hangups will cause \fBcu\fR to terminate.
This option can be specified more than once. For more information about
dialback configuration, see \fBremote\fR(4) and \fISystem Administration Guide:
IP Services\fR
.RE

.sp
.ne 2
.na
\fB\fB-l\fR \fIline\fR\fR
.ad
.RS 13n
Specifies a device name to use as the communication line. This can be used to
override the search that would otherwise take place for the first available
line having the right speed. When the \fB-l\fR option is used without the
\fB-s\fR option, the speed of a line is taken from the  \fB/etc/uucp/Devices\fR
file record in which \fIline\fR matches the second field (the Line field). When
the \fB-l\fR and \fB-s\fR options are both used together, \fBcu\fR will search
the \fB/etc/uucp/Devices\fR file to check if the requested speed for the
requested line is available. If so, the connection will be made at the
requested speed, otherwise, an error message will be printed and the call will
not be made.  In the general case where a specified device is a directly
connected asynchronous line (for instance, \fB/dev/term/a\fR), a telephone
number  (\fItelno\fR) is not required. The specified device need not be in the
\fB/dev\fR directory. If the specified device is associated with an auto
dialer, a telephone number must be  provided.
.RE

.sp
.ne 2
.na
\fB\fB-L\fR\fR
.ad
.RS 13n
Goes through the login chat sequence specified in the \fB/etc/uucp/Systems\fR
file. For more information about the chat sequence, see \fISystem
Administration Guide: IP Services\fR
.RE

.sp
.ne 2
.na
\fB\fB-n\fR\fR
.ad
.RS 13n
Requests user prompt for telephone number.  For added security, this option
will prompt the user to provide the telephone number to be dialed, rather than
taking it from the command line.
.RE

.sp
.ne 2
.na
\fB\fB-o\fR\fR
.ad
.RS 13n
Sets an ODD data parity.  This option designates that ODD parity is to be
generated for data sent to the remote system.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR \fIspeed\fR\fR
.ad
.RS 13n
Specifies the transmission speed (\fB300\fR, \fB1200\fR, \fB2400\fR,
\fB4800\fR, \fB9600\fR, \fB19200\fR, \fB38400\fR). The default value is "Any"
speed which will depend on the order of the lines in the
\fB/etc/uucp/Devices\fR file.
.RE

.sp
.ne 2
.na
\fB\fB-t\fR\fR
.ad
.RS 13n
Dials a terminal which has been set to auto answer. Appropriate mapping of
carriage-return to carriage-return-line-feed pairs is set.
.RE

.SH OPERANDS
.sp
.LP
The following operands are supported:
.sp
.ne 2
.na
\fB\fItelno\fR\fR
.ad
.RS 14n
When using an automatic dialler, specifies the telephone number with equal
signs for secondary dial tone or minus signs placed appropriately for delays of
4 seconds.
.RE

.sp
.ne 2
.na
\fB\fIsystemname\fR\fR
.ad
.RS 14n
Specifies a \fBuucp\fR system name, which can be used rather than a telephone
number; in this case, \fBcu\fR will obtain an appropriate direct line or
telephone number from a system file.
.RE

.SH USAGE
.SS "Connection Phase"
.sp
.LP
\fBcu\fR uses the same mechanism that \fBuucp\fR(1C) does to establish a
connection. This means that it will use the \fBuucp\fR control files
\fB/etc/uucp/Devices\fR and \fB/etc/uucp/Systems\fR. This gives \fBcu\fR the
ability to choose from several different media to establish the connection. The
possible media include telephone lines, direct connections, and local area
networks (\fBLAN\fR). The \fB/etc/uucp/Devices\fR file contains a list of media
that are available on your system. The \fB/etc/uucp/Systems\fR file contains
information for connecting to remote systems, but it is not generally readable.
.sp
.LP
\fBNote:\fR \fBcu\fR determines which \fB/etc/uucp/Systems\fR and
\fB/etc/uucp/Devices\fR files to use based upon the name used to invoke
\fBcu\fR. In the simple case, this name will be "\fBcu\fR", but you could also
have created a link to \fBcu\fR with another name, such as "\fBpppcu\fR", in
which case \fBcu\fR would then look for a "service=pppcu" entry in the
\fB/etc/uucp/Sysfiles\fR file to determine which \fB/etc/uucp/Systems\fR file
to use.
.sp
.LP
The \fItelno\fR or \fIsystemname\fR parameter from the command line is used to
tell \fBcu\fR what system you wish to connect to. This parameter can be blank,
a telephone number, a system name, or a \fBLAN\fR specific address.
.sp
.ne 2
.na
\fBtelephone number\fR
.ad
.RS 20n
A telephone number is a string consisting of the tone dial characters (the
digits  \fB0\fR through \fB9\fR, \fB*\fR, and \fB#\fR) plus the special
characters \fB=\fR and \fB\(mi\fR\&. The equal sign designates a secondary dial
tone and the minus sign creates a  \fB4\fR second delay.
.RE

.sp
.ne 2
.na
\fBsystem name\fR
.ad
.RS 20n
A system name is the name of any computer that \fBuucp\fR can call; the
\fBuuname\fR(1C) command prints a list of these names.
.RE

.sp
.ne 2
.na
\fBLAN address\fR
.ad
.RS 20n
The documentation for your  \fBLAN\fR will show the form of the \fBLAN\fR
specific address.
.RE

.sp
.LP
If \fBcu\fR's default behavior is invoked (not using the \fB-c\fR or \fB-l\fR
options), \fBcu\fR will use the \fItelno\fR or \fIsystemname\fR parameter to
determine which medium to use. If a telephone number is specified, \fBcu\fR
will assume that you wish to use a telephone line and it will select an
automatic call unit (\fBACU\fR). Otherwise, \fBcu\fR will assume that it is a
system name. \fBcu\fR will follow the \fBuucp\fR calling mechanism and use the
\fB/etc/uucp/Systems\fR and \fB/etc/uucp/Devices\fR files to obtain the best
available connection. Since \fBcu\fR will choose a speed that is appropriate
for the medium that it selects, you may not use the \fB-s\fR option when this
parameter is a system name.
.sp
.LP
The \fB-c\fR and \fB-l\fR options modify this default behavior. \fB-c\fR is
most often used to select a  \fBLAN\fR by specifying a Type field from the
\fB/etc/uucp/Devices\fR file. You must include either a \fItelno\fR or
\fIsystemname\fR value when using the \fB-c\fR option. If the connection to
\fIsystemname\fR fails, a connection will be attempted using \fIsystemname\fR
as a  \fBLAN\fR specific address. The \fB-l\fR option is used to specify a
device associated with a direct connection. If the connection is truly a direct
connection to the remote machine, then there is no need to specify a
\fIsystemname\fR. This is the only case where a \fItelno\fR or \fIsystemname\fR
parameter is unnecessary. On the other hand, there may be cases in which the
specified device connects to a dialer, so it is valid to specify a telephone
number. The \fB-c\fR and \fB-l\fR options should not be specified on the same
command line.
.SS "Conversation Phase"
.sp
.LP
After making the connection, \fBcu\fR runs as two processes. The \fBtransmit\fR
process reads data from the standard input and, except for lines beginning with
\fB~\fR, passes it to the remote system. The \fBreceive\fR process accepts data
from the remote system and, except for lines beginning with \fB~\fR, passes it
to the standard output. Normally, an automatic DC3/DC1 protocol is used to
control input from the remote so the buffer is not overrun. Lines beginning
with \fB~\fR have special meanings.
.SS "Commands"
.sp
.LP
The \fBtransmit\fR process interprets the following user initiated commands:
.sp
.ne 2
.na
\fB\fB~.\fR\fR
.ad
.RS 27n
Terminates the conversation.
.RE

.sp
.ne 2
.na
\fB\fB~!\fR\fR
.ad
.RS 27n
Escapes to an interactive shell on the local system.
.RE

.sp
.ne 2
.na
\fB\fB~!\fR\fIcmd\|.\|.\|.\fR\fR
.ad
.RS 27n
Runs \fIcmd\fR on the local system (via \fBsh \fR\fB-c\fR).
.RE

.sp
.ne 2
.na
\fB\fB~$\fR\fIcmd\|.\|.\|.\fR\fR
.ad
.RS 27n
Runs \fIcmd\fR locally and send its output to the remote system.
.RE

.sp
.ne 2
.na
\fB\fB~%cd\fR\fR
.ad
.RS 27n
Changes the directory on the local system. Note: \fB~!cd\fR will cause the
command to be run by a sub-shell, probably not what was intended.
.RE

.sp
.ne 2
.na
\fB\fB~%take\fR \fIfrom\fR \|[\fI\|to\fR\|]\fR
.ad
.RS 27n
Copies file \fIfrom\fR (on the remote system) to file \fIto\fR on the local
system. If \fIto\fR is omitted, the \fIfrom\fR argument is used in both places.
.RE

.sp
.ne 2
.na
\fB\fB~%put\fR \fI\|from\fR \|[\fI\|to\fR\|]\fR
.ad
.RS 27n
Copies file \fIfrom\fR (on local system) to file \fIto\fR on remote system. If
\fIto\fR is omitted, the \fIfrom\fR argument is used in both places.
.RE

.sp
.ne 2
.na
\fB\fB~~\fR\fI\|line\fR\fR
.ad
.RS 27n
Sends the line \fB~\fR \fIline\fR to the remote system.
.RE

.sp
.ne 2
.na
\fB\fB~%break\fR\fR
.ad
.RS 27n
Transmits a  \fBBREAK\fR to the remote system (which can also be specified as
\fB~%b\fR).
.RE

.sp
.ne 2
.na
\fB\fB~%debug\fR\fR
.ad
.RS 27n
Toggles the \fB-d\fR debugging option on or off (which can also be specified as
\fB~%d\fR).
.RE

.sp
.ne 2
.na
\fB\fB~t\fR\fR
.ad
.RS 27n
Prints the values of the termio structure variables for the user's terminal
(useful for debugging).
.RE

.sp
.ne 2
.na
\fB\fB~l\fR\fR
.ad
.RS 27n
Prints the values of the termio structure variables for the remote
communication line (useful for debugging).
.RE

.sp
.ne 2
.na
\fB\fB~%ifc\fR\fR
.ad
.RS 27n
Toggles between DC3/DC1 input control protocol and no input control. This is
useful when the remote system does not respond properly to the DC3 and DC1
characters (can also be specified as \fB\(ap%nostop\fR).
.RE

.sp
.ne 2
.na
\fB\fB~%ofc\fR\fR
.ad
.RS 27n
Toggles the output flow control setting.  When enabled, outgoing data may be
flow controlled by the remote host (can also be specified as
\fB\(ap%noostop\fR).
.RE

.sp
.ne 2
.na
\fB\fB~%divert\fR\fR
.ad
.RS 27n
Allows/disallows unsolicited diversions.  That is, diversions not specified by
\fB~%take\fR.
.RE

.sp
.ne 2
.na
\fB\fB~%old\fR\fR
.ad
.RS 27n
Allows/disallows old style syntax for received diversions.
.RE

.sp
.ne 2
.na
\fB\fB~%nostop\fR\fR
.ad
.RS 27n
Same as  \fB~%ifc\fR.
.RE

.sp
.LP
The \fBreceive\fR process normally copies data from the remote system to the
standard output of the local system.  It may also direct the output to local
files.
.sp
.LP
The use of \fB~%put\fR requires \fBstty\fR(1) and \fBcat\fR(1) on the remote
side. It also requires that the current erase and kill characters on the remote
system be identical to these current control characters on the local system.
Backslashes are inserted at appropriate places.
.sp
.LP
The use of \fB~%take\fR requires the existence of \fBecho\fR(1) and
\fBcat\fR(1) on the remote system, and that the remote system must be using the
Bourne shell, \fBsh\fR. Also, \fBtabs\fR mode (see \fBstty\fR(1)) should be set
on the remote system if tabs are to be copied without expansion to spaces.
.sp
.LP
When \fBcu\fR is used on system X to connect to system Y and subsequently used
on system Y to connect to system Z, commands on system Y can be executed by
using \fB~\|~\fR. Executing a tilde command reminds the user of the local
system \fBuname\fR. For example, \fBuname\fR can be executed on Z, X, and Y as
follows:
.sp
.in +2
.nf
uname
Z
~[X]!uname
X
~~[Y]!uname
Y
.fi
.in -2

.sp
.LP
In general, \fB~\fR causes the command to be executed on the original machine.
\fB~\|~\fR causes the command to be executed on the next machine in the chain.
.SH EXAMPLES
.LP
\fBExample 1 \fRDialling a system
.sp
.LP
To dial a system whose telephone number is  \fB9\fR \fB1\fR \fB201\fR \fB555\fR
\fB1234\fR using  \fB1200\fR baud (where dialtone is expected after the
\fB9\fR):

.sp
.in +2
.nf
example% \fBcu \fR\fB-s\fR\fB 1200 9=12015551234\fR
.fi
.in -2
.sp

.sp
.LP
If the speed is not specified, "Any" is the default value.

.LP
\fBExample 2 \fRLogging in to a system on a direct line
.sp
.LP
To login to a system connected by a direct line:

.sp
.in +2
.nf
example% \fBcu \fR\fB-l\fR\fB /dev/term/b\fR
.fi
.in -2
.sp

.sp
.LP
or

.sp
.in +2
.nf
example% \fBcu \fR\fB-l\fR\fB term/b\fR
.fi
.in -2
.sp

.LP
\fBExample 3 \fRDialling a system with specific line and speed
.sp
.LP
To dial a system with a specific line and speed:

.sp
.in +2
.nf
example% \fBcu \fR\fB-s\fR\fB 1200 \fR\fB-l\fR\fB term/b\fR
.fi
.in -2
.sp

.LP
\fBExample 4 \fRUsing a system name
.sp
.LP
To use a system name:

.sp
.in +2
.nf
example% \fBcu systemname\fR
.fi
.in -2
.sp

.SH ENVIRONMENT VARIABLES
.sp
.LP
See \fBenviron\fR(5) for descriptions of the following environment variables
that affect the execution of \fBcu\fR: \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and
\fBNLSPATH\fR.
.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 6n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fB>0\fR\fR
.ad
.RS 6n
An error occurred.
.RE

.SH FILES
.sp
.ne 2
.na
\fB\fB/etc/uucp/Devices\fR\fR
.ad
.RS 22n
device file
.RE

.sp
.ne 2
.na
\fB\fB/etc/uucp/Sysfiles\fR\fR
.ad
.RS 22n
system file
.RE

.sp
.ne 2
.na
\fB\fB/etc/uucp/Systems\fR\fR
.ad
.RS 22n
system file
.RE

.sp
.ne 2
.na
\fB\fB/var/spool/locks/*\fR\fR
.ad
.RS 22n
lock file
.RE

.SH SEE ALSO
.sp
.LP
\fBcat\fR(1), \fBecho\fR(1), \fBstty\fR(1), \fBtip\fR(1), \fBuname\fR(1),
\fBct\fR(1C), \fBuuname\fR(1C), \fBuucp\fR(1C), \fBremote\fR(4),
\fBattributes\fR(5), \fBenviron\fR(5)
.sp
.LP
\fISystem Administration Guide: IP Services\fR
.SH NOTES
.sp
.LP
The \fBcu\fR utility takes the default action upon receipt of signals, with the
exception of:
.sp
.ne 2
.na
\fB\fBSIGHUP\fR\fR
.ad
.RS 11n
Close the connection and terminate.
.RE

.sp
.ne 2
.na
\fB\fBSIGINT\fR\fR
.ad
.RS 11n
Forward to the remote system.
.RE

.sp
.ne 2
.na
\fB\fBSIGQUIT\fR\fR
.ad
.RS 11n
Forward to the remote system.
.RE

.sp
.ne 2
.na
\fB\fBSIGUSR1\fR\fR
.ad
.RS 11n
Terminate the \fBcu\fR process without the normal connection closing sequence.
.RE

.sp
.LP
The \fBcu\fR command does not do any integrity checking on data it transfers.
Data fields with special \fBcu\fR characters may not be transmitted properly.
Depending on the interconnection hardware, it may be necessary to use a
\fB~.\fR to terminate the conversion, even if \fBstty 0\fR has been used.
Non-printing characters are not dependably transmitted using either the
\fB~%put\fR or \fB~%take\fR commands. \fB~%put\fR and \fB~%take\fR cannot be
used  over multiple links.  Files must be moved one link at a time.
.sp
.LP
There is an artificial slowing of transmission by \fBcu\fR during the
\fB~%put\fR operation so that loss of data is unlikely.  Files transferred
using \fB~%take\fR or \fB~%put\fR must contain a trailing newline, otherwise,
the operation will hang.  Entering a Control-D command usually clears the hang
condition.