Annotation of src/usr.bin/cu/cu.1, Revision 1.24
1.24 ! krw 1: .\" $OpenBSD: cu.1,v 1.23 2023/10/02 14:48:10 krw 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.24 ! krw 30: .Dd $Mdocdate: October 2 2023 $
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.19 nicm 39: .Op Fl E Ar escape_char
1.1 nicm 40: .Op Fl l Ar line
1.13 bentley 41: .Op Fl s Ar speed | Fl Ar speed
1.12 nicm 42: .Nm
1.10 nicm 43: .Op Ar host
1.1 nicm 44: .Sh DESCRIPTION
45: .Nm
46: is used to connect to another system over a serial link.
47: In the era before modern networks, it was typically used to
48: connect to a modem in order to dial in to a remote host.
49: It is now frequently used for tasks such as attaching to the
50: serial console of another machine for administrative or
51: debugging purposes.
52: .Pp
53: The options are as follows:
54: .Bl -tag -width 4n
1.15 nicm 55: .It Fl d
56: Specify that the line is directly connected and
57: .Nm
58: should not allow the driver to block waiting for a carrier to be detected.
1.19 nicm 59: .It Fl E Ar escape_char
60: Specify an escape character to use instead of the default tilde.
1.1 nicm 61: .It Fl l Ar line
62: Specify the line to use.
1.23 krw 63: Any of the forms
64: .Pa cua00 ,
65: .Pa /dev/cua00 ,
1.1 nicm 66: or
1.24 ! krw 67: .Pa usb0.1.00002.3
1.1 nicm 68: are permitted.
1.23 krw 69: .Pp
1.1 nicm 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.23 krw 80: .Pp
81: See
82: .Xr sysctl 2
83: .Va hw.ucomnames
84: for available USB serial lines.
85: .Pp
1.17 jmc 86: .It Fl r
87: Start
88: .Nm
89: in restricted mode.
1.18 jmc 90: This prevents all local filesystem operations
91: .Po
92: .Cm ~R ,
93: .Cm ~X ,
94: and
95: .Cm ~>
96: .Pc
97: and command executions
98: .Po
99: .Cm ~C
100: and
101: .Cm ~$
102: .Pc .
1.13 bentley 103: .It Fl s Ar speed | Fl Ar speed
1.1 nicm 104: Set the speed of the connection.
105: The default is 9600.
106: .El
107: .Pp
1.10 nicm 108: If
109: .Ar host
110: is given,
111: .Nm
112: uses the
113: .Xr remote 5
1.11 nicm 114: database to retrieve the
1.15 nicm 115: .Sy dc Pq directly connected ,
1.10 nicm 116: .Sy dv Pq device
117: and
118: .Sy br Pq baud rate
119: capabilities for that host.
120: The
121: .Nm
122: utility ignores other capabilities found in that database.
123: .Pp
1.1 nicm 124: Typed characters are normally transmitted directly to the remote
125: machine (which does the echoing as well).
126: A tilde
127: .Pq Ql ~
128: appearing as the first character of a line is an escape signal; the
129: following are recognized:
130: .Bl -tag -offset indent -width Fl
131: .It Ic ~^D No or Ic ~.
132: Drop the connection and exit.
133: Only the connection is dropped \(en the login session is not terminated.
1.18 jmc 134: .It Ic ~>
1.1 nicm 135: Copy file from local to remote.
136: .Nm
137: prompts for the name of a local file to transmit.
138: .It Ic ~$
139: Pipe the output from a local
140: .Ux
141: process to the remote host.
142: The command string sent to the local
143: .Ux
144: system is processed by the shell.
145: .It Ic ~#
146: Send a
147: .Dv BREAK
148: to the remote system.
149: .It Ic ~^Z
150: Stop
151: .Nm
152: (only available with job control).
1.3 nicm 153: .It Ic ~C
154: Fork a child process on the local system to perform special protocols
155: such as XMODEM.
156: The child program will be run with the following arrangement of
157: file descriptors:
1.21 bentley 158: .Pp
159: .Bl -item -compact -offset indent
160: .It
161: 0 \(<> remote tty in
162: .It
163: 1 \(<> remote tty out
164: .It
165: 2 \(<> local tty stderr
166: .El
1.7 nicm 167: .It Ic ~D
168: Deassert the data terminal ready (DTR) line briefly.
1.5 nicm 169: .It Ic ~R
170: Record all output from the remote system to a file.
171: If the given file already exists, it is appended to.
172: If no file is specified, any existing recording is stopped.
1.2 nicm 173: .It Ic ~S
174: Change the speed of the connection.
1.4 nicm 175: .It Ic ~X
1.6 nicm 176: Send a file with the XMODEM protocol.
1.1 nicm 177: .It Ic ~?
178: Get a summary of the tilde escapes.
179: .El
180: .Pp
181: When
182: .Nm
183: prompts for an argument, for example during setup of a file transfer,
184: the line typed may be edited with the standard erase and kill characters.
185: A null line in response to a prompt, or an interrupt, will abort the
186: dialogue and return the user to the remote machine.
187: .Pp
188: .Nm
189: guards against multiple users connecting to a remote system by opening
190: modems and terminal lines with exclusive access.
1.10 nicm 191: .Sh ENVIRONMENT
1.11 nicm 192: .Bl -tag -width REMOTEXXX
193: .It Ev HOST
194: The default value for
195: .Ar host
196: if none is specified via the command line.
197: .It Ev REMOTE
198: A system description, or an absolute path to a
1.10 nicm 199: .Xr remote 5
1.11 nicm 200: system description database.
201: .El
1.10 nicm 202: .Sh FILES
203: .Bl -tag -width /etc/remote
204: .It Pa /etc/remote
205: host description file
206: .El
1.11 nicm 207: .Sh EXIT STATUS
208: .Ex -std cu
209: .Sh SEE ALSO
1.23 krw 210: .Xr sysctl 2 ,
211: .Xr cua 4 ,
1.11 nicm 212: .Xr remote 5
1.1 nicm 213: .Sh HISTORY
214: The
215: .Nm
1.22 jsg 216: .Pq Dq Call Unix
217: command first appeared outside of Bell Labs in PWB/UNIX 1.0.
218: It was reimplemented as part of the
219: .Nm tip
220: command in
221: .Bx 4.1c .
222: The current version was written for
223: .Ox 5.4 .
224: .Sh AUTHORS
225: .An Nicholas Marriott Aq Mt nicm@openbsd.org
![[BACK]](/icons/back.gif){kind=icon}
Return to cu.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / cu