path: root/usr.bin/cu/cu.1

.\"	$OpenBSD: cu.1,v 1.25 2023/10/03 05:20:38 jmc Exp $
.\"
.\" Copyright (c) 1980, 1990, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd $Mdocdate: October 3 2023 $
.Dt CU 1
.Os
.Sh NAME
.Nm cu
.Nd serial terminal emulator
.Sh SYNOPSIS
.Nm
.Op Fl dr
.Op Fl E Ar escape_char
.Op Fl l Ar line
.Op Fl s Ar speed | Fl Ar speed
.Nm
.Op Ar host
.Sh DESCRIPTION
.Nm
is used to connect to another system over a serial link.
In the era before modern networks, it was typically used to
connect to a modem in order to dial in to a remote host.
It is now frequently used for tasks such as attaching to the
serial console of another machine for administrative or
debugging purposes.
.Pp
The options are as follows:
.Bl -tag -width 4n
.It Fl d
Specify that the line is directly connected and
.Nm
should not allow the driver to block waiting for a carrier to be detected.
.It Fl E Ar escape_char
Specify an escape character to use instead of the default tilde.
.It Fl l Ar line
Specify the line to use.
Any of the forms
.Pa cua00 ,
.Pa /dev/cua00 ,
or
.Pa usb0.1.00002.3
are permitted.
.Pp
The default is
.Pa /dev/cua00 .
See
.Xr cua 4
for information on terminal devices.
Users in group
.Dq dialer
are permitted to use
.Xr cua 4
devices by default.
.Pp
See
.Xr sysctl 2
.Va hw.ucomnames
for available USB serial lines.
.It Fl r
Start
.Nm
in restricted mode.
This prevents all local filesystem operations
.Po
.Cm ~R ,
.Cm ~X ,
and
.Cm ~>
.Pc
and command executions
.Po
.Cm ~C
and
.Cm ~$
.Pc .
.It Fl s Ar speed | Fl Ar speed
Set the speed of the connection.
The default is 9600.
.El
.Pp
If
.Ar host
is given,
.Nm
uses the
.Xr remote 5
database to retrieve the
.Sy dc Pq directly connected ,
.Sy dv Pq device
and
.Sy br Pq baud rate
capabilities for that host.
The
.Nm
utility ignores other capabilities found in that database.
.Pp
Typed characters are normally transmitted directly to the remote
machine (which does the echoing as well).
A tilde
.Pq Ql ~
appearing as the first character of a line is an escape signal; the
following are recognized:
.Bl -tag -offset indent -width Fl
.It Ic ~^D No or Ic ~.
Drop the connection and exit.
Only the connection is dropped \(en the login session is not terminated.
.It Ic ~>
Copy file from local to remote.
.Nm
prompts for the name of a local file to transmit.
.It Ic ~$
Pipe the output from a local
.Ux
process to the remote host.
The command string sent to the local
.Ux
system is processed by the shell.
.It Ic ~#
Send a
.Dv BREAK
to the remote system.
.It Ic ~^Z
Stop
.Nm
(only available with job control).
.It Ic ~C
Fork a child process on the local system to perform special protocols
such as XMODEM.
The child program will be run with the following arrangement of
file descriptors:
.Pp
.Bl -item -compact -offset indent
.It
0 \(<> remote tty in
.It
1 \(<> remote tty out
.It
2 \(<> local tty stderr
.El
.It Ic ~D
Deassert the data terminal ready (DTR) line briefly.
.It Ic ~R
Record all output from the remote system to a file.
If the given file already exists, it is appended to.
If no file is specified, any existing recording is stopped.
.It Ic ~S
Change the speed of the connection.
.It Ic ~X
Send a file with the XMODEM protocol.
.It Ic ~?
Get a summary of the tilde escapes.
.El
.Pp
When
.Nm
prompts for an argument, for example during setup of a file transfer,
the line typed may be edited with the standard erase and kill characters.
A null line in response to a prompt, or an interrupt, will abort the
dialogue and return the user to the remote machine.
.Pp
.Nm
guards against multiple users connecting to a remote system by opening
modems and terminal lines with exclusive access.
.Sh ENVIRONMENT
.Bl -tag -width REMOTEXXX
.It Ev HOST
The default value for
.Ar host
if none is specified via the command line.
.It Ev REMOTE
A system description, or an absolute path to a
.Xr remote 5
system description database.
.El
.Sh FILES
.Bl -tag -width /etc/remote
.It Pa /etc/remote
host description file
.El
.Sh EXIT STATUS
.Ex -std cu
.Sh SEE ALSO
.Xr sysctl 2 ,
.Xr cua 4 ,
.Xr remote 5
.Sh HISTORY
The
.Nm
.Pq Dq Call Unix
command first appeared outside of Bell Labs in PWB/UNIX 1.0.
It was reimplemented as part of the
.Nm tip
command in
.Bx 4.1c .
The current version was written for
.Ox 5.4 .
.Sh AUTHORS
.An Nicholas Marriott Aq Mt nicm@openbsd.org