Annotation of src/usr.bin/cu/cu.1, Revision 1.16
1.16 ! deraadt 1: .\" $OpenBSD: cu.1,v 1.15 2015/05/18 09:35:05 nicm Exp $
1.1 nicm 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: .\"
1.16 ! deraadt 30: .Dd $Mdocdate: May 18 2015 $
1.1 nicm 31: .Dt CU 1
32: .Os
33: .Sh NAME
34: .Nm cu
35: .Nd serial terminal emulator
36: .Sh SYNOPSIS
37: .Nm
1.16 ! deraadt 38: .Op Fl dr
1.1 nicm 39: .Op Fl l Ar line
1.13 bentley 40: .Op Fl s Ar speed | Fl Ar speed
1.12 nicm 41: .Nm
1.10 nicm 42: .Op Ar host
1.1 nicm 43: .Sh DESCRIPTION
44: .Nm
45: is used to connect to another system over a serial link.
46: In the era before modern networks, it was typically used to
47: connect to a modem in order to dial in to a remote host.
48: It is now frequently used for tasks such as attaching to the
49: serial console of another machine for administrative or
50: debugging purposes.
51: .Pp
52: The options are as follows:
53: .Bl -tag -width 4n
1.15 nicm 54: .It Fl d
55: Specify that the line is directly connected and
56: .Nm
57: should not allow the driver to block waiting for a carrier to be detected.
1.16 ! deraadt 58: .It Fl r
! 59: Starts
! 60: .Nm
! 61: in restricted mode.
! 62: This prevents all local filesystem operations and command executions.
1.1 nicm 63: .It Fl l Ar line
64: Specify the line to use.
65: Either of the forms like
1.9 nicm 66: .Pa cua00
1.1 nicm 67: or
1.9 nicm 68: .Pa /dev/cua00
1.1 nicm 69: are permitted.
70: The default is
71: .Pa /dev/cua00 .
1.9 nicm 72: See
1.1 nicm 73: .Xr cua 4
1.9 nicm 74: for information on terminal devices.
1.1 nicm 75: Users in group
76: .Dq dialer
77: are permitted to use
78: .Xr cua 4
1.9 nicm 79: devices by default.
1.13 bentley 80: .It Fl s Ar speed | Fl Ar speed
1.1 nicm 81: Set the speed of the connection.
82: The default is 9600.
83: .El
84: .Pp
1.10 nicm 85: If
86: .Ar host
87: is given,
88: .Nm
89: uses the
90: .Xr remote 5
1.11 nicm 91: database to retrieve the
1.15 nicm 92: .Sy dc Pq directly connected ,
1.10 nicm 93: .Sy dv Pq device
94: and
95: .Sy br Pq baud rate
96: capabilities for that host.
97: The
98: .Nm
99: utility ignores other capabilities found in that database.
100: .Pp
1.1 nicm 101: Typed characters are normally transmitted directly to the remote
102: machine (which does the echoing as well).
103: A tilde
104: .Pq Ql ~
105: appearing as the first character of a line is an escape signal; the
106: following are recognized:
107: .Bl -tag -offset indent -width Fl
108: .It Ic ~^D No or Ic ~.
109: Drop the connection and exit.
110: Only the connection is dropped \(en the login session is not terminated.
111: .It Ic ~\*(Gt
112: Copy file from local to remote.
113: .Nm
114: prompts for the name of a local file to transmit.
115: .It Ic ~$
116: Pipe the output from a local
117: .Ux
118: process to the remote host.
119: The command string sent to the local
120: .Ux
121: system is processed by the shell.
1.16 ! deraadt 122: This command is not allowed in restricted mode.
1.1 nicm 123: .It Ic ~#
124: Send a
125: .Dv BREAK
126: to the remote system.
127: .It Ic ~^Z
128: Stop
129: .Nm
130: (only available with job control).
1.3 nicm 131: .It Ic ~C
132: Fork a child process on the local system to perform special protocols
133: such as XMODEM.
134: The child program will be run with the following arrangement of
135: file descriptors:
136: .Bd -literal -offset indent
137: 0 \*(Lt-\*(Gt remote tty in
138: 1 \*(Lt-\*(Gt remote tty out
139: 2 \*(Lt-\*(Gt local tty stderr
140: .Ed
1.16 ! deraadt 141: .Pp
! 142: This command is not allowed in restricted mode.
1.7 nicm 143: .It Ic ~D
144: Deassert the data terminal ready (DTR) line briefly.
1.16 ! deraadt 145: This command is not allowed in restricted mode.
1.5 nicm 146: .It Ic ~R
147: Record all output from the remote system to a file.
148: If the given file already exists, it is appended to.
149: If no file is specified, any existing recording is stopped.
1.16 ! deraadt 150: This command is not allowed in restricted mode.
1.2 nicm 151: .It Ic ~S
152: Change the speed of the connection.
1.4 nicm 153: .It Ic ~X
1.6 nicm 154: Send a file with the XMODEM protocol.
1.16 ! deraadt 155: This command is not allowed in restricted mode.
1.1 nicm 156: .It Ic ~?
157: Get a summary of the tilde escapes.
158: .El
159: .Pp
160: When
161: .Nm
162: prompts for an argument, for example during setup of a file transfer,
163: the line typed may be edited with the standard erase and kill characters.
164: A null line in response to a prompt, or an interrupt, will abort the
165: dialogue and return the user to the remote machine.
166: .Pp
167: .Nm
168: guards against multiple users connecting to a remote system by opening
169: modems and terminal lines with exclusive access.
1.10 nicm 170: .Sh ENVIRONMENT
1.11 nicm 171: .Bl -tag -width REMOTEXXX
172: .It Ev HOST
173: The default value for
174: .Ar host
175: if none is specified via the command line.
176: .It Ev REMOTE
177: A system description, or an absolute path to a
1.10 nicm 178: .Xr remote 5
1.11 nicm 179: system description database.
180: .El
1.10 nicm 181: .Sh FILES
182: .Bl -tag -width /etc/remote
183: .It Pa /etc/remote
184: host description file
185: .El
1.11 nicm 186: .Sh EXIT STATUS
187: .Ex -std cu
188: .Sh SEE ALSO
189: .Xr remote 5
1.1 nicm 190: .Sh HISTORY
191: The
192: .Nm
193: command appeared in
194: .Bx 4.2 .
195: This version was written for
1.8 nicm 196: .Ox 5.4
1.1 nicm 197: by Nicholas Marriott.