761557315574664cca7a270e08730616b46914b0
[dragonfly.git] / bin / stty / stty.1
1 .\" Copyright (c) 1990, 1993, 1994
2 .\"     The Regents of the University of California.  All rights reserved.
3 .\"
4 .\" This code is derived from software contributed to Berkeley by
5 .\" the Institute of Electrical and Electronics Engineers, Inc.
6 .\"
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\"    notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\"    notice, this list of conditions and the following disclaimer in the
14 .\"    documentation and/or other materials provided with the distribution.
15 .\" 3. All advertising materials mentioning features or use of this software
16 .\"    must display the following acknowledgement:
17 .\"     This product includes software developed by the University of
18 .\"     California, Berkeley and its contributors.
19 .\" 4. Neither the name of the University nor the names of its contributors
20 .\"    may be used to endorse or promote products derived from this software
21 .\"    without specific prior written permission.
22 .\"
23 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33 .\" SUCH DAMAGE.
34 .\"
35 .\"     @(#)stty.1      8.4 (Berkeley) 4/18/94
36 .\" $FreeBSD: src/bin/stty/stty.1,v 1.13.2.6 2001/12/14 14:22:09 ru Exp $
37 .\" $DragonFly: src/bin/stty/stty.1,v 1.4 2006/02/10 19:01:09 swildner Exp $
38 .\"
39 .Dd April 18, 1994
40 .Dt STTY 1
41 .Os
42 .Sh NAME
43 .Nm stty
44 .Nd set the options for a terminal device interface
45 .Sh SYNOPSIS
46 .Nm
47 .Op Fl a | Fl e | Fl g
48 .Op Fl f Ar file
49 .Op operands
50 .Sh DESCRIPTION
51 The
52 .Nm
53 utility sets or reports on terminal
54 characteristics for the device that is its standard input.
55 If no options or operands are specified, it reports the settings of a subset
56 of characteristics as well as additional ones if they differ from their
57 default values.
58 Otherwise it modifies
59 the terminal state according to the specified arguments.
60 Some combinations of arguments are mutually
61 exclusive on some terminal types.
62 .Pp
63 The following options are available:
64 .Bl -tag -width indent
65 .It Fl a
66 Display all the current settings for the terminal to standard output
67 as per
68 .St -p1003.2 .
69 .It Fl e
70 Display all the current settings for the terminal to standard output
71 in the traditional
72 .Bx
73 ``all'' and ``everything'' formats.
74 .It Fl f
75 Open and use the terminal named by
76 .Ar file
77 rather than using standard input.  The file is opened
78 using the
79 .Dv O_NONBLOCK
80 flag of
81 .Fn open ,
82 making it possible to
83 set or display settings on a terminal that might otherwise
84 block on the open.
85 .It Fl g
86 Display all the current settings for the terminal to standard output
87 in a form that may be used as an argument to a subsequent invocation of
88 .Nm
89 to restore the current terminal state as per
90 .St -p1003.2 .
91 .El
92 .Pp
93 The following arguments are available to set the terminal
94 characteristics:
95 .Ss Control Modes:
96 Control mode flags affect hardware characteristics associated with the
97 terminal.  This corresponds to the c_cflag in the termios structure.
98 .Bl -tag -width Fl
99 .It Cm parenb Pq Fl parenb
100 Enable (disable) parity generation
101 and detection.
102 .It Cm parodd Pq Fl parodd
103 Select odd (even) parity.
104 .It Cm cs5 cs6 cs7 cs8
105 Select character size, if possible.
106 .It Ar number
107 Set terminal baud rate to the
108 number given, if possible.
109 If the
110 baud rate is set to zero, modem
111 control is no longer
112 asserted.
113 .It Cm ispeed Ar number
114 Set terminal input baud rate to the
115 number given, if possible.
116 If the
117 input baud rate is set to zero, the
118 input baud rate is set to the
119 value of the output baud
120 rate.
121 .It Cm ospeed Ar number
122 Set terminal output baud rate to
123 the number given, if possible.
124 If
125 the output baud rate is set to
126 zero, modem control is
127 no longer asserted.
128 .It Cm speed Ar number
129 This sets both
130 .Cm ispeed
131 and
132 .Cm ospeed
133 to
134 .Ar number .
135 .It Cm hupcl Pq Fl hupcl
136 Stop asserting modem control
137 (do not stop asserting modem control) on last close.
138 .It Cm hup Pq Fl hup
139 Same as hupcl
140 .Pq Fl hupcl .
141 .It Cm cstopb Pq Fl cstopb
142 Use two (one) stop bits per character.
143 .It Cm cread Pq Fl cread
144 Enable (disable) the receiver.
145 .It Cm clocal Pq Fl clocal
146 Assume a line without (with) modem
147 control.
148 .It Cm crtscts Pq Fl crtscts
149 Enable (disable) RTS/CTS flow control.
150 .El
151 .Ss Input Modes:
152 This corresponds to the c_iflag in the termios structure.
153 .Bl -tag -width Fl
154 .It Cm ignbrk Pq Fl ignbrk
155 Ignore (do not ignore) break on
156 input.
157 .It Cm brkint Pq Fl brkint
158 Signal (do not signal)
159 .Dv INTR
160 on
161 break.
162 .It Cm ignpar Pq Fl ignpar
163 Ignore (do not ignore) characters with parity
164 errors.
165 .It Cm parmrk Pq Fl parmrk
166 Mark (do not mark) characters with parity errors.
167 .It Cm inpck Pq Fl inpck
168 Enable (disable) input parity
169 checking.
170 .It Cm istrip Pq Fl istrip
171 Strip (do not strip) input characters
172 to seven bits.
173 .It Cm inlcr Pq Fl inlcr
174 Map (do not map)
175 .Dv NL
176 to
177 .Dv CR
178 on input.
179 .It Cm igncr Pq Fl igncr
180 Ignore (do not ignore)
181 .Dv CR
182 on input.
183 .It Cm icrnl Pq Fl icrnl
184 Map (do not map)
185 .Dv CR
186 to
187 .Dv NL
188 on input.
189 .It Cm ixon Pq Fl ixon
190 Enable (disable)
191 .Dv START/STOP
192 output
193 control.
194 Output from the system is
195 stopped when the system receives
196 .Dv STOP
197 and started when the system
198 receives
199 .Dv START ,
200 or if
201 .Cm ixany
202 is set, any character restarts output.
203 .It Cm ixoff Pq Fl ixoff
204 Request that the system send (not
205 send)
206 .Dv START/STOP
207 characters when
208 the input queue is nearly
209 empty/full.
210 .It Cm ixany Pq Fl ixany
211 Allow any character (allow only
212 .Dv START )
213 to restart output.
214 .It Cm imaxbel Pq Fl imaxbel
215 The system imposes a limit of
216 .Dv MAX_INPUT
217 (currently 255) characters in the input queue.  If
218 .Cm imaxbel
219 is set and the input queue limit has been reached,
220 subsequent input causes the system to send an ASCII BEL
221 character to the output queue (the terminal beeps at you).  Otherwise,
222 if
223 .Cm imaxbel
224 is unset and the input queue is full, the next input character causes
225 the entire input and output queues to be discarded.
226 .El
227 .Ss Output Modes:
228 This corresponds to the c_oflag of the termios structure.
229 .Bl -tag -width Fl
230 .It Cm opost Pq Fl opost
231 Post-process output (do not
232 post-process output; ignore all other
233 output modes).
234 .It Cm onlcr Pq Fl onlcr
235 Map (do not map)
236 .Dv NL
237 to
238 .Dv CR-NL
239 on output.
240 .It Cm ocrnl Pq Fl ocrnl
241 Map (do not map)
242 .Dv CR
243 to
244 .Dv NL
245 on output.
246 .It Cm oxtabs Pq Fl oxtabs
247 Expand (do not expand) tabs to spaces on output.
248 .It Cm onocr Pq Fl onocr
249 Do not (do) output CRs at column zero.
250 .It Cm onlret Pq Fl onlret
251 On the terminal NL performs (does not perform) the CR function.
252 .El
253 .Ss Local Modes:
254 Local mode flags (lflags) affect various and sundry characteristics of terminal
255 processing.
256 Historically the term "local" pertained to new job control features
257 implemented by Jim Kulp on a
258 .Tn Pdp 11/70
259 at
260 .Tn IIASA .
261 Later the driver ran on the first
262 .Tn VAX
263 at Evans Hall, UC Berkeley, where the job control details
264 were greatly modified but the structure definitions and names
265 remained essentially unchanged.
266 The second interpretation of the 'l' in lflag
267 is ``line discipline flag'' which corresponds to the
268 .Ar c_lflag
269 of the
270 .Ar termios
271 structure.
272 .Bl -tag -width Fl
273 .It Cm isig Pq Fl isig
274 Enable (disable) the checking of
275 characters against the special control
276 characters
277 .Dv INTR , QUIT ,
278 and
279 .Dv SUSP .
280 .It Cm icanon Pq Fl icanon
281 Enable (disable) canonical input
282 .Pf ( Dv ERASE
283 and
284 .Dv KILL
285 processing).
286 .It Cm iexten Pq Fl iexten
287 Enable (disable) any implementation
288 defined special control characters
289 not currently controlled by icanon,
290 isig, or ixon.
291 .It Cm echo Pq Fl echo
292 Echo back (do not echo back) every
293 character typed.
294 .It Cm echoe Pq Fl echoe
295 The
296 .Dv ERASE
297 character shall (shall
298 not) visually erase the last character
299 in the current line from the
300 display, if possible.
301 .It Cm echok Pq Fl echok
302 Echo (do not echo)
303 .Dv NL
304 after
305 .Dv KILL
306 character.
307 .It Cm echoke Pq Fl echoke
308 The
309 .Dv KILL
310 character shall (shall
311 not) visually erase the
312 current line from the
313 display, if possible.
314 .It Cm echonl Pq Fl echonl
315 Echo (do not echo)
316 .Dv NL ,
317 even if echo
318 is disabled.
319 .It Cm echoctl Pq Fl echoctl
320 If
321 .Cm echoctl
322 is set, echo control characters as ^X.  Otherwise control characters
323 echo as themselves.
324 .It Cm echoprt Pq Fl echoprt
325 For printing terminals.
326 If set, echo erased characters backwards within ``\\''
327 and ``/''.  Otherwise, disable this feature.
328 .It Cm noflsh Pq Fl noflsh
329 Disable (enable) flush after
330 .Dv INTR , QUIT , SUSP .
331 .It Cm tostop Pq Fl tostop
332 Send (do not send)
333 .Dv SIGTTOU
334 for background output.  This causes background jobs to stop if they attempt
335 terminal output.
336 .It Cm altwerase Pq Fl altwerase
337 Use (do not use) an alternate word erase algorithm when processing
338 .Dv WERASE
339 characters.
340 This alternate algorithm considers sequences of
341 alphanumeric/underscores as words.
342 It also skips the first preceding character in its classification
343 (as a convenience since the one preceding character could have been
344 erased with simply an
345 .Dv ERASE
346 character.)
347 .It Cm mdmbuf Pq Fl mdmbuf
348 If set, flow control output based on condition of Carrier Detect.  Otherwise
349 writes return an error if Carrier Detect is low (and Carrier is not being
350 ignored with the
351 .Dv CLOCAL
352 flag.)
353 .It Cm flusho Pq Fl flusho
354 Indicates output is (is not) being discarded.
355 .It Cm pendin Pq Fl pendin
356 Indicates input is (is not) pending after a switch from non-canonical
357 to canonical mode and will be re-input when a read becomes pending
358 or more input arrives.
359 .El
360 .Ss Control Characters:
361 .Bl -tag -width Fl
362 .It Ar control-character Ar string
363 Set
364 .Ar control-character
365 to
366 .Ar string .
367 If string is a single character,
368 the control character is set to
369 that character.
370 If string is the
371 two character sequence "^-" or the
372 string "undef" the control character
373 is disabled (i.e. set to
374 .Pf { Dv _POSIX_VDISABLE Ns } . )
375 .Pp
376 Recognized control-characters:
377 .Bd -ragged -offset indent
378 .Bl -column character Subscript
379 .It control-
380 .It character Ta Subscript Ta Description
381 .It _________ Ta _________ Ta _______________
382 .It eof Ta Tn VEOF Ta EOF No character
383 .It eol Ta Tn VEOL Ta EOL No character
384 .It eol2 Ta Tn VEOL2 Ta EOL2 No character
385 .It erase Ta Tn VERASE Ta ERASE No character
386 .It erase2 Ta Tn VERASE2 Ta ERASE2 No character
387 .It werase Ta Tn VWERASE Ta WERASE No character
388 .It intr Ta Tn VINTR Ta INTR No character
389 .It kill Ta Tn VKILL Ta KILL No character
390 .It quit Ta Tn VQUIT Ta QUIT No character
391 .It susp Ta Tn VSUSP Ta SUSP No character
392 .It start Ta Tn VSTART Ta START No character
393 .It stop Ta Tn VSTOP Ta STOP No character
394 .It dsusp Ta Tn VDSUSP Ta DSUSP No character
395 .It lnext Ta Tn VLNEXT Ta LNEXT No character
396 .It reprint Ta Tn VREPRINT Ta REPRINT No character
397 .It status Ta Tn VSTATUS Ta STATUS No character
398 .It ckpt Ta Tn VCHECKPT Ta CKPT No character
399 .El
400 .Ed
401 .It Cm min Ar number
402 .It Cm time Ar number
403 Set the value of min or time to
404 number.
405 .Dv MIN
406 and
407 .Dv TIME
408 are used in
409 Non-Canonical mode input processing
410 (-icanon).
411 .El
412 .Ss Combination Modes:
413 .Bl -tag -width Fl
414 .It Ar saved settings
415 Set the current terminal
416 characteristics to the saved settings
417 produced by the
418 .Fl g
419 option.
420 .It Cm evenp No or Cm parity
421 Enable parenb and cs7; disable
422 parodd.
423 .It Cm oddp
424 Enable parenb, cs7, and parodd.
425 .It Fl parity , evenp ,  oddp
426 Disable parenb, and set cs8.
427 .It Cm \&nl Pq Fl \&nl
428 Enable (disable) icrnl.
429 In addition
430 -nl unsets inlcr and igncr.
431 .It Cm ek
432 Reset
433 .Dv ERASE ,
434 .Dv ERASE2 ,
435 and
436 .Dv KILL
437 characters
438 back to system defaults.
439 .It Cm sane
440 Resets all modes to reasonable values for interactive terminal use.
441 .It Cm tty
442 Set the line discipline to the standard terminal line discipline
443 .Dv TTYDISC .
444 .It Cm crt Pq Fl crt
445 Set (disable) all modes suitable for a CRT display device.
446 .It Cm kerninfo Pq Fl kerninfo
447 Enable (disable) the system generated status line associated with
448 processing a
449 .Dv STATUS
450 character (usually set to ^T).  The status line consists of the
451 system load average, the current command name, its process ID, the
452 event the process is waiting on (or the status of the process), the user
453 and system times, percent cpu, and current memory usage.
454 .It Cm columns Ar number
455 The terminal size is recorded as having
456 .Ar number
457 columns.
458 .It Cm cols Ar number
459 is an alias for
460 .Cm columns .
461 .It Cm rows Ar number
462 The terminal size is recorded as having
463 .Ar number
464 rows.
465 .It Cm dec
466 Set modes suitable for users of Digital Equipment Corporation systems
467 .Dv ( ERASE ,
468 .Dv KILL ,
469 and
470 .Dv INTR
471 characters are set to ^?, ^U, and ^C;
472 .Dv ixany
473 is disabled, and
474 .Dv crt
475 is enabled.)
476 .It Cm extproc Pq Fl extproc
477 If set, this flag indicates that some amount of terminal processing is being
478 performed by either the terminal hardware or by the remote side connected
479 to a pty.
480 .It Cm raw Pq Fl raw
481 If set, change the modes of the terminal so that no input or output processing
482 is performed.
483 If unset, change the modes of the terminal to some reasonable
484 state that performs input and output processing.  Note that since the
485 terminal driver no longer has a single
486 .Dv RAW
487 bit, it is not possible to intuit what flags were set prior to setting
488 .Cm raw .
489 This means that unsetting
490 .Cm raw
491 may not put back all the setting that were previously in effect.
492 To set the terminal into a raw state and then accurately restore it, the following
493 shell code is recommended:
494 .Bd -literal
495 save_state=$(stty -g)
496 stty raw
497 \&...
498 stty "$save_state"
499 .Ed
500 .It Cm size
501 The size of the terminal is printed as two numbers on a single line,
502 first rows, then columns.
503 .El
504 .Ss Compatibility Modes:
505 These modes remain for compatibility with the previous version of
506 the
507 .Nm
508 command.
509 .Bl -tag -width Fl
510 .It Cm all
511 Reports all the terminal modes as with
512 .Cm stty Fl a
513 except that the control characters are printed in a columnar format.
514 .It Cm everything
515 Same as
516 .Cm all .
517 .It Cm cooked
518 Same as
519 .Cm sane .
520 .It Cm cbreak
521 If set, enables
522 .Cm brkint , ixon , imaxbel , opost ,
523 .Cm isig , iexten ,
524 and
525 .Fl icanon .
526 If unset, same as
527 .Cm sane .
528 .It Cm new
529 Same as
530 .Cm tty .
531 .It Cm old
532 Same as
533 .Cm tty .
534 .It Cm newcrt Pq Fl newcrt
535 Same as
536 .Cm crt .
537 .It Cm pass8
538 The converse of
539 .Cm parity .
540 .It Cm tandem Pq Fl tandem
541 Same as
542 .Cm ixoff .
543 .It Cm decctlq Pq Fl decctlq
544 The converse of
545 .Cm ixany .
546 .It Cm crterase Pq Fl crterase
547 Same as
548 .Cm echoe .
549 .It Cm crtbs Pq Fl crtbs
550 Same as
551 .Cm echoe .
552 .It Cm crtkill Pq Fl crtkill
553 Same as
554 .Cm echoke .
555 .It Cm ctlecho Pq Fl ctlecho
556 Same as
557 .Cm echoctl .
558 .It Cm prterase Pq Fl prterase
559 Same as
560 .Cm echoprt .
561 .It Cm litout Pq Fl litout
562 The converse of
563 .Cm opost .
564 .It Cm tabs Pq Fl tabs
565 The converse of
566 .Cm oxtabs .
567 .It Cm brk Ar value
568 Same as the control character
569 .Cm eol .
570 .It Cm flush Ar value
571 Same as the control character
572 .Cm discard .
573 .It Cm rprnt Ar value
574 Same as the control character
575 .Cm reprint .
576 .El
577 .Sh EXIT STATUS
578 .Ex -std
579 .Sh SEE ALSO
580 .Xr termios 4
581 .Sh STANDARDS
582 The
583 .Nm
584 utility is expected to be
585 .St -p1003.2
586 compatible.  The flags
587 .Fl e
588 and
589 .Fl f
590 are
591 extensions to the standard.