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