K&R style function removal. Update functions to ANSI style.
[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.2 2003/06/17 04:22:50 dillon 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 .Pp
97 Control mode flags affect hardware characteristics associated with the
98 terminal.  This corresponds to the c_cflag in the termios structure.
99 .Bl -tag -width Fl
100 .It Cm parenb Pq Fl parenb
101 Enable (disable) parity generation
102 and detection.
103 .It Cm parodd Pq Fl parodd
104 Select odd (even) parity.
105 .It Cm cs5 cs6 cs7 cs8
106 Select character size, if possible.
107 .It Ar number
108 Set terminal baud rate to the
109 number given, if possible.
110 If the
111 baud rate is set to zero, modem
112 control is no longer
113 asserted.
114 .It Cm ispeed Ar number
115 Set terminal input baud rate to the
116 number given, if possible.
117 If the
118 input baud rate is set to zero, the
119 input baud rate is set to the
120 value of the output baud
121 rate.
122 .It Cm ospeed Ar number
123 Set terminal output baud rate to
124 the number given, if possible.
125 If
126 the output baud rate is set to
127 zero, modem control is
128 no longer asserted.
129 .It Cm speed Ar number
130 This sets both
131 .Cm ispeed
132 and
133 .Cm ospeed
134 to
135 .Ar number .
136 .It Cm hupcl Pq Fl hupcl
137 Stop asserting modem control
138 (do not stop asserting modem control) on last close.
139 .It Cm hup Pq Fl hup
140 Same as hupcl
141 .Pq Fl hupcl .
142 .It Cm cstopb Pq Fl cstopb
143 Use two (one) stop bits per character.
144 .It Cm cread Pq Fl cread
145 Enable (disable) the receiver.
146 .It Cm clocal Pq Fl clocal
147 Assume a line without (with) modem
148 control.
149 .It Cm crtscts Pq Fl crtscts
150 Enable (disable) RTS/CTS flow control.
151 .El
152 .Ss Input Modes:
153 This corresponds to the c_iflag in the termios structure.
154 .Bl -tag -width Fl
155 .It Cm ignbrk Pq Fl ignbrk
156 Ignore (do not ignore) break on
157 input.
158 .It Cm brkint Pq Fl brkint
159 Signal (do not signal)
160 .Dv INTR
161 on
162 break.
163 .It Cm ignpar Pq Fl ignpar
164 Ignore (do not ignore) characters with parity
165 errors.
166 .It Cm parmrk Pq Fl parmrk
167 Mark (do not mark) characters with parity errors.
168 .It Cm inpck Pq Fl inpck
169 Enable (disable) input parity
170 checking.
171 .It Cm istrip Pq Fl istrip
172 Strip (do not strip) input characters
173 to seven bits.
174 .It Cm inlcr Pq Fl inlcr
175 Map (do not map)
176 .Dv NL
177 to
178 .Dv CR
179 on input.
180 .It Cm igncr Pq Fl igncr
181 Ignore (do not ignore)
182 .Dv CR
183 on input.
184 .It Cm icrnl Pq Fl icrnl
185 Map (do not map)
186 .Dv CR
187 to
188 .Dv NL
189 on input.
190 .It Cm ixon Pq Fl ixon
191 Enable (disable)
192 .Dv START/STOP
193 output
194 control.
195 Output from the system is
196 stopped when the system receives
197 .Dv STOP
198 and started when the system
199 receives
200 .Dv START ,
201 or if
202 .Cm ixany
203 is set, any character restarts output.
204 .It Cm ixoff Pq Fl ixoff
205 Request that the system send (not
206 send)
207 .Dv START/STOP
208 characters when
209 the input queue is nearly
210 empty/full.
211 .It Cm ixany Pq Fl ixany
212 Allow any character (allow only
213 .Dv START )
214 to restart output.
215 .It Cm imaxbel Pq Fl imaxbel
216 The system imposes a limit of
217 .Dv MAX_INPUT
218 (currently 255) characters in the input queue.  If
219 .Cm imaxbel
220 is set and the input queue limit has been reached,
221 subsequent input causes the system to send an ASCII BEL
222 character to the output queue (the terminal beeps at you).  Otherwise,
223 if
224 .Cm imaxbel
225 is unset and the input queue is full, the next input character causes
226 the entire input and output queues to be discarded.
227 .El
228 .Ss Output Modes:
229 This corresponds to the c_oflag of the termios structure.
230 .Bl -tag -width Fl
231 .It Cm opost Pq Fl opost
232 Post-process output (do not
233 post-process output; ignore all other
234 output modes).
235 .It Cm onlcr Pq Fl onlcr
236 Map (do not map)
237 .Dv NL
238 to
239 .Dv CR-NL
240 on output.
241 .It Cm ocrnl Pq Fl ocrnl
242 Map (do not map)
243 .Dv CR
244 to
245 .Dv NL
246 on output.
247 .It Cm oxtabs Pq Fl oxtabs
248 Expand (do not expand) tabs to spaces on output.
249 .It Cm onocr Pq Fl onocr
250 Do not (do) output CRs at column zero.
251 .It Cm onlret Pq Fl onlret
252 On the terminal NL performs (does not perform) the CR function.
253 .El
254 .Ss Local Modes:
255 .Pp
256 Local mode flags (lflags) affect various and sundry characteristics of terminal
257 processing.
258 Historically the term "local" pertained to new job control features
259 implemented by Jim Kulp on a
260 .Tn Pdp 11/70
261 at
262 .Tn IIASA .
263 Later the driver ran on the first
264 .Tn VAX
265 at Evans Hall, UC Berkeley, where the job control details
266 were greatly modified but the structure definitions and names
267 remained essentially unchanged.
268 The second interpretation of the 'l' in lflag
269 is ``line discipline flag'' which corresponds to the
270 .Ar c_lflag
271 of the
272 .Ar termios
273 structure.
274 .Bl -tag -width Fl
275 .It Cm isig Pq Fl isig
276 Enable (disable) the checking of
277 characters against the special control
278 characters
279 .Dv INTR , QUIT ,
280 and
281 .Dv SUSP .
282 .It Cm icanon Pq Fl icanon
283 Enable (disable) canonical input
284 .Pf ( Dv ERASE
285 and
286 .Dv KILL
287 processing).
288 .It Cm iexten Pq Fl iexten
289 Enable (disable) any implementation
290 defined special control characters
291 not currently controlled by icanon,
292 isig, or ixon.
293 .It Cm echo Pq Fl echo
294 Echo back (do not echo back) every
295 character typed.
296 .It Cm echoe Pq Fl echoe
297 The
298 .Dv ERASE
299 character shall (shall
300 not) visually erase the last character
301 in the current line from the
302 display, if possible.
303 .It Cm echok Pq Fl echok
304 Echo (do not echo)
305 .Dv NL
306 after
307 .Dv KILL
308 character.
309 .It Cm echoke Pq Fl echoke
310 The
311 .Dv KILL
312 character shall (shall
313 not) visually erase the
314 current line from the
315 display, if possible.
316 .It Cm echonl Pq Fl echonl
317 Echo (do not echo)
318 .Dv NL ,
319 even if echo
320 is disabled.
321 .It Cm echoctl Pq Fl echoctl
322 If
323 .Cm echoctl
324 is set, echo control characters as ^X.  Otherwise control characters
325 echo as themselves.
326 .It Cm echoprt Pq Fl echoprt
327 For printing terminals.
328 If set, echo erased characters backwards within ``\\''
329 and ``/''.  Otherwise, disable this feature.
330 .It Cm noflsh Pq Fl noflsh
331 Disable (enable) flush after
332 .Dv INTR , QUIT , SUSP .
333 .It Cm tostop Pq Fl tostop
334 Send (do not send)
335 .Dv SIGTTOU
336 for background output.  This causes background jobs to stop if they attempt
337 terminal output.
338 .It Cm altwerase Pq Fl altwerase
339 Use (do not use) an alternate word erase algorithm when processing
340 .Dv WERASE
341 characters.
342 This alternate algorithm considers sequences of
343 alphanumeric/underscores as words.
344 It also skips the first preceding character in its classification
345 (as a convenience since the one preceding character could have been
346 erased with simply an
347 .Dv ERASE
348 character.)
349 .It Cm mdmbuf Pq Fl mdmbuf
350 If set, flow control output based on condition of Carrier Detect.  Otherwise
351 writes return an error if Carrier Detect is low (and Carrier is not being
352 ignored with the
353 .Dv CLOCAL
354 flag.)
355 .It Cm flusho Pq Fl flusho
356 Indicates output is (is not) being discarded.
357 .It Cm pendin Pq Fl pendin
358 Indicates input is (is not) pending after a switch from non-canonical
359 to canonical mode and will be re-input when a read becomes pending
360 or more input arrives.
361 .El
362 .Ss Control Characters:
363 .Bl -tag -width Fl
364 .It Ar control-character Ar string
365 Set
366 .Ar control-character
367 to
368 .Ar string .
369 If string is a single character,
370 the control character is set to
371 that character.
372 If string is the
373 two character sequence "^-" or the
374 string "undef" the control character
375 is disabled (i.e. set to
376 .Pf { Dv _POSIX_VDISABLE Ns } . )
377 .Pp
378 Recognized control-characters:
379 .Bd -ragged -offset indent
380 .Bl -column character Subscript
381 .It control-
382 .It character Ta Subscript Ta Description
383 .It _________ Ta _________ Ta _______________
384 .It eof Ta Tn VEOF Ta EOF No character
385 .It eol Ta Tn VEOL Ta EOL No character
386 .It eol2 Ta Tn VEOL2 Ta EOL2 No character
387 .It erase Ta Tn VERASE Ta ERASE No character
388 .It erase2 Ta Tn VERASE2 Ta ERASE2 No character
389 .It werase Ta Tn VWERASE Ta WERASE No character
390 .It intr Ta Tn VINTR Ta INTR No character
391 .It kill Ta Tn VKILL Ta KILL No character
392 .It quit Ta Tn VQUIT Ta QUIT No character
393 .It susp Ta Tn VSUSP Ta SUSP No character
394 .It start Ta Tn VSTART Ta START No character
395 .It stop Ta Tn VSTOP Ta STOP No character
396 .It dsusp Ta Tn VDSUSP Ta DSUSP No character
397 .It lnext Ta Tn VLNEXT Ta LNEXT No character
398 .It reprint Ta Tn VREPRINT Ta REPRINT No character
399 .It status Ta Tn VSTATUS Ta STATUS No character
400 .El
401 .Ed
402 .It Cm min Ar number
403 .It Cm time Ar number
404 Set the value of min or time to
405 number.
406 .Dv MIN
407 and
408 .Dv TIME
409 are used in
410 Non-Canonical mode input processing
411 (-icanon).
412 .El
413 .Ss Combination Modes:
414 .Pp
415 .Bl -tag -width Fl
416 .It Ar saved settings
417 Set the current terminal
418 characteristics to the saved settings
419 produced by the
420 .Fl g
421 option.
422 .It Cm evenp No or Cm parity
423 Enable parenb and cs7; disable
424 parodd.
425 .It Cm oddp
426 Enable parenb, cs7, and parodd.
427 .It Fl parity , evenp ,  oddp
428 Disable parenb, and set cs8.
429 .It Cm \&nl Pq Fl \&nl
430 Enable (disable) icrnl.
431 In addition
432 -nl unsets inlcr and igncr.
433 .It Cm ek
434 Reset
435 .Dv ERASE ,
436 .Dv ERASE2 ,
437 and
438 .Dv KILL
439 characters
440 back to system defaults.
441 .It Cm sane
442 Resets all modes to reasonable values for interactive terminal use.
443 .It Cm tty
444 Set the line discipline to the standard terminal line discipline
445 .Dv TTYDISC .
446 .It Cm crt Pq Fl crt
447 Set (disable) all modes suitable for a CRT display device.
448 .It Cm kerninfo Pq Fl kerninfo
449 Enable (disable) the system generated status line associated with
450 processing a
451 .Dv STATUS
452 character (usually set to ^T).  The status line consists of the
453 system load average, the current command name, its process ID, the
454 event the process is waiting on (or the status of the process), the user
455 and system times, percent cpu, and current memory usage.
456 .It Cm columns Ar number
457 The terminal size is recorded as having
458 .Ar number
459 columns.
460 .It Cm cols Ar number
461 is an alias for
462 .Cm columns .
463 .It Cm rows Ar number
464 The terminal size is recorded as having
465 .Ar number
466 rows.
467 .It Cm dec
468 Set modes suitable for users of Digital Equipment Corporation systems
469 .Dv ( ERASE ,
470 .Dv KILL ,
471 and
472 .Dv INTR
473 characters are set to ^?, ^U, and ^C;
474 .Dv ixany
475 is disabled, and
476 .Dv crt
477 is enabled.)
478 .It Cm extproc Pq Fl extproc
479 If set, this flag indicates that some amount of terminal processing is being
480 performed by either the terminal hardware or by the remote side connected
481 to a pty.
482 .It Cm raw Pq Fl raw
483 If set, change the modes of the terminal so that no input or output processing
484 is performed.
485 If unset, change the modes of the terminal to some reasonable
486 state that performs input and output processing.  Note that since the
487 terminal driver no longer has a single
488 .Dv RAW
489 bit, it is not possible to intuit what flags were set prior to setting
490 .Cm raw .
491 This means that unsetting
492 .Cm raw
493 may not put back all the setting that were previously in effect.
494 To set the terminal into a raw state and then accurately restore it, the following
495 shell code is recommended:
496 .Bd -literal
497 save_state=$(stty -g)
498 stty raw
499 \&...
500 stty "$save_state"
501 .Ed
502 .It Cm size
503 The size of the terminal is printed as two numbers on a single line,
504 first rows, then columns.
505 .El
506 .Ss Compatibility Modes:
507 .Pp
508 These modes remain for compatibility with the previous version of
509 the
510 .Nm
511 command.
512 .Bl -tag -width Fl
513 .It Cm all
514 Reports all the terminal modes as with
515 .Cm stty Fl a
516 except that the control characters are printed in a columnar format.
517 .It Cm everything
518 Same as
519 .Cm all .
520 .It Cm cooked
521 Same as
522 .Cm sane .
523 .It Cm cbreak
524 If set, enables
525 .Cm brkint , ixon , imaxbel , opost ,
526 .Cm isig , iexten ,
527 and
528 .Fl icanon .
529 If unset, same as
530 .Cm sane .
531 .It Cm new
532 Same as
533 .Cm tty .
534 .It Cm old
535 Same as
536 .Cm tty .
537 .It Cm newcrt Pq Fl newcrt
538 Same as
539 .Cm crt .
540 .It Cm pass8
541 The converse of
542 .Cm parity .
543 .It Cm tandem Pq Fl tandem
544 Same as
545 .Cm ixoff .
546 .It Cm decctlq Pq Fl decctlq
547 The converse of
548 .Cm ixany .
549 .It Cm crterase Pq Fl crterase
550 Same as
551 .Cm echoe .
552 .It Cm crtbs Pq Fl crtbs
553 Same as
554 .Cm echoe .
555 .It Cm crtkill Pq Fl crtkill
556 Same as
557 .Cm echoke .
558 .It Cm ctlecho Pq Fl ctlecho
559 Same as
560 .Cm echoctl .
561 .It Cm prterase Pq Fl prterase
562 Same as
563 .Cm echoprt .
564 .It Cm litout Pq Fl litout
565 The converse of
566 .Cm opost .
567 .It Cm tabs Pq Fl tabs
568 The converse of
569 .Cm oxtabs .
570 .It Cm brk Ar value
571 Same as the control character
572 .Cm eol .
573 .It Cm flush Ar value
574 Same as the control character
575 .Cm discard .
576 .It Cm rprnt Ar value
577 Same as the control character
578 .Cm reprint .
579 .El
580 .Sh DIAGNOSTICS
581 .Ex -std
582 .Sh SEE ALSO
583 .Xr termios 4
584 .Sh STANDARDS
585 The
586 .Nm
587 utility is expected to be
588 .St -p1003.2
589 compatible.  The flags
590 .Fl e
591 and
592 .Fl f
593 are
594 extensions to the standard.