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