The Single UNIX ® Specification, Version 2
Copyright © 1997 The Open Group

 NAME

stty - set the options for a terminal

 SYNOPSIS



stty [ -a| -g]

stty operands

 DESCRIPTION

The stty utility sets or reports on terminal I/O characteristics for the device that is its standard input. Without options or operands specified, it reports the settings of certain characteristics, usually those that differ from implementation-dependent defaults. Otherwise, it modifies the terminal state according to the specified operands. Detailed information about the modes listed in the first five groups below are described in the XBD specification, General Terminal Interface  . Operands in the Combination Modes group (see Combination Modes ) are implemented using operands in the previous groups. Some combinations of operands are mutually exclusive on some terminal types; the results of using such combinations are unspecified.

Typical implementations of this utility require a communications line configured to use a XSH specification termios interface. On systems where none of these lines are available, and on lines not currently configured to support the XSH specification termios interface, some of the operands need not affect terminal characteristics.

 OPTIONS

The stty utility supports the XBD specification, Utility Syntax Guidelines  .

The following options are supported:

-a
Write to standard output all the current settings for the terminal.
-g
Write to standard output all the current settings in an unspecified form that can be used as arguments to another invocation of the stty utility on the same system. The form used will not contain any characters that would require quoting to avoid word expansion by the shell; see Word Expansions .

 OPERANDS

The following operands are supported to set the terminal characteristics:
 Control Modes
parenb (-parenb)
Enable (disable) parity generation and detection. This has the effect of setting (not setting) PARENB in the termios c_cflag field, as defined in the XBD specification, General Terminal Interface  .
parodd (-parodd)
Select odd (even) parity. This has the effect of setting (not setting) PARODD in the termios c_cflag field, as defined in the XBD specification, General Terminal Interface  .
cs5 cs6 cs7 cs8
Select character size, if possible. This has the effect of setting CS5, CS6, CS7 and CS8, respectively, in the termios c_cflag field, as defined in the XBD specification, General Terminal Interface  .
number
Set terminal baud rate to the number given, if possible. If the baud rate is set to zero, the modem control lines will no longer be asserted. This has the effect of setting the input and output termios baud rate values as defined in the XBD specification, General Terminal Interface  .
ispeed number
Set terminal input baud rate to the number given, if possible. If the input baud rate is set to zero, the input baud rate will be specified by the value of the output baud rate. This has the effect of setting the input termios baud rate values as defined in the XBD specification, General Terminal Interface  .
ospeed number
Set terminal output baud rate to the number given, if possible. If the output baud rate is set to zero, the modem control lines will no longer be asserted. This has the effect of setting the output termios baud rate values as defined in the XBD specification, General Terminal Interface  .
hupcl (-hupcl)
Stop asserting modem control lines (do not stop asserting modem control lines) on last close. This has the effect of setting (not setting) HUPCL in the termios c_cflag field, as defined in the XBD specification, General Terminal Interface  .
hup (-hup)
Same as hupcl (-hupcl).
cstopb (-cstopb)
Use two (one) stop bits per character. This has the effect of setting (not setting) CSTOPB in the termios c_cflag field, as defined in the XBD specification, General Terminal Interface  .
cread (-cread)
Enable (disable) the receiver. This has the effect of setting (not setting) CREAD in the termios c_cflag field, as defined in the XBD specification, General Terminal Interface  .
clocal (-clocal)
Assume a line without (with) modem control. This has the effect of setting (not setting) CLOCAL in the termios c_cflag field, as defined in the XBD specification, General Terminal Interface  .

It is unspecified whether stty will report an error if an attempt to set a Control Mode fails.

 Input Modes
ignbrk (-ignbrk)
Ignore (do not ignore) break on input. This has the effect of setting (not setting) IGNBRK in the termios c_iflag field, as defined in the XBD specification, General Terminal Interface  .
brkint (-brkint)
Signal (do not signal) INTR on break. This has the effect of setting (not setting) BRKINT in the termios c_iflag field, as defined in the XBD specification, General Terminal Interface  .
ignpar (-ignpar)
Ignore (do not ignore) bytes with parity errors. This has the effect of setting (not setting) IGNPAR in the termios c_iflag field, as defined in the XBD specification, General Terminal Interface  .
parmrk (-parmrk)
Mark (do not mark) parity errors. This has the effect of setting (not setting) PARMRK in the termios c_iflag field, as defined in the XBD specification, General Terminal Interface  .
inpck (-inpck)
Enable (disable) input parity checking. This has the effect of setting (not setting) INPCK in the termios c_iflag field, as defined in the XBD specification, General Terminal Interface  .
istrip (-istrip)
Strip (do not strip) input characters to seven bits. This has the effect of setting (not setting) ISTRIP in the termios c_iflag field, as defined in the XBD specification, General Terminal Interface  .
inlcr (-inlcr)
Map (do not map) NL to CR on input. This has the effect of setting (not setting) INLCR in the termios c_iflag field, as defined in the XBD specification, General Terminal Interface  .
igncr (-igncr)
Ignore (do not ignore) CR on input. This has the effect of setting (not setting) IGNCR in the termios c_iflag field, as defined in the XBD specification, General Terminal Interface  .
icrnl (-icrnl)
Map (do not map) CR to NL on input. This has the effect of setting (not setting) ICRNL in the termios c_iflag field, as defined in the XBD specification, General Terminal Interface  .
iuclc (-iuclc)
Map (do not map) upper-case alphabetics to lower-case on input. This has the effect of setting (not setting) IUCLC in the termios c_iflag field, as defined in the XBD specification, General Terminal Interface  . (LEGACY)
ixon (-ixon)
Enable (disable) START/STOP output control. Output from the system is stopped when the system receives STOP and started when the system receives START. This has the effect of setting (not setting) IXON in the termios c_iflag field, as defined in the XBD specification, General Terminal Interface  .
ixany (-ixany)
Allow any character to restart output. This has the effect of setting (not setting) IXANY in the termios c_iflag field, as defined in the XBD specification, General Terminal Interface  .
ixoff (-ixoff)
Request that the system send (not send) STOP characters when the input queue is nearly full and START characters to resume data transmission. This has the effect of setting (not setting) IXOFF in the termios c_iflag field, as defined in the XBD specification, General Terminal Interface  .
 Output Modes
opost (-opost)
Post-process output (do not post-process output; ignore all other output modes). This has the effect of setting (not setting) OPOST in the termios c_oflag field, as defined in the XBD specification, General Terminal Interface  .
olcuc (-olcuc)
Map (do not map) lower-case alphabetics to upper-case on output. This has the effect of setting (not setting) OLCUC in the termios c_oflag field, as defined in the XBD specification, General Terminal Interface  . (LEGACY)
ocrnl (-ocrnl)
Map (do not map) CR to NL on output This has the effect of setting (not setting) OCRNL in the termios c_oflag field, as defined in the XBD specification, General Terminal Interface  .
onocr (-onocr)
Do not (do) output CR at column zero. This has the effect of setting (not setting) ONOCR in the termios c_oflag field, as defined in the XBD specification, General Terminal Interface  .
onlret (-onlret)
The terminal newline key performs (does not perform) the CR function. This has the effect of setting (not setting) ONLRET in the termios c_oflag field, as defined in the XBD specification, General Terminal Interface  .
ofill (-ofill)
Use fill characters (use timing) for delays. This has the effect of setting (not setting) OFILL in the termios c_oflag field, as defined in the XBD specification, General Terminal Interface  .
ofdel (-ofdel)
Fill characters are DELs (NULs). This has the effect of setting (not setting) OFDEL in the termios c_oflag field, as defined in the XBD specification, General Terminal Interface  .
cr0 cr1 cr2 cr3
Select the style of delay for CRs. This has the effect of setting (not setting) CRDLY to CR1, CR2, CR3 or CR4, respectively, in the termios c_oflag field, as defined in the XBD specification, General Terminal Interface  .
nl0 nl1
Select the style of delay for NL. This has the effect of setting (not setting) NLDLY to NL0 or NL1, respectively, in the termios c_oflag field, as defined in the XBD specification, General Terminal Interface  .
tab0 tab1 tab2 tab3
Select the style of delay for horizontal tabs. This has the effect of setting (not setting) TABDLY to TAB0, TAB1, TAB2 or TAB3, respectively, in the termios c_oflag field, as defined in the XBD specification, General Terminal Interface  . Note that TAB3 has the effect of expanding tabs to spaces.
bs0 bs1
Select the style of delay for backspaces. This has the effect of setting (not setting) BSDLY to BS0 or BS1, respectively, in the termios c_oflag field, as defined in the XBD specification, General Terminal Interface  .
ff0 ff1
Select the style of delay for form-feeds. This has the effect of setting (not setting) FFDLY to FF0 or FF1, respectively, in the termios c_oflag field, as defined in the XBD specification, General Terminal Interface  .
vt0 vt1
Select the style of delay for vertical-tabs. This has the effect of setting (not setting) VTDLY to VT0 or VT1, respectively, in the termios c_oflag field, as defined in the XBD specification, General Terminal Interface  .
 Local Modes
isig (-isig)
Enable (disable) the checking of characters against the special control characters INTR, QUIT, and SUSP. This has the effect of setting (not setting) ISIG in the termios c_lflag field, as defined in the XBD specification, General Terminal Interface  .
icanon (-icanon)
Enable (disable) canonical input (ERASE and KILL processing). This has the effect of setting (not setting) ICANON in the termios c_lflag field, as defined in the XBD specification, General Terminal Interface  .
xcase (-xcase)
Set canonical (unprocessed) upper- or lower-case presentation. This has the effect of setting (not setting) XCASE in the termios c_lflag field, as defined in the XBD specification, General Terminal Interface  . (LEGACY)
iexten (-iexten)
Enable (disable) any implementation-dependent special control characters not currently controlled by icanon, isig, ixon or ixoff. This has the effect of setting (not setting) IEXTEN in the termios c_lflag field, as defined in the XBD specification, General Terminal Interface  .
echo (-echo)
Echo back (do not echo back) every character typed. This has the effect of setting (not setting) ECHO in the termios c_lflag field, as defined in the XBD specification, General Terminal Interface  .
echoe (-echoe)
The ERASE character will (will not) visually erase the last character in the current line from the display, if possible. This has the effect of setting (not setting) ECHOE in the termios c_lflag field, as defined in the XBD specification, General Terminal Interface  .
echok (-echok)
Echo (do not echo) NL after KILL character. This has the effect of setting (not setting) ECHOK in the termios c_lflag field, as defined in the XBD specification, General Terminal Interface  .
echonl (-echonl)
Echo (do not echo) NL, even if echo is disabled. This has the effect of setting (not setting) ECHONL in the termios c_lflag field, as defined in the XBD specification, General Terminal Interface  .
noflsh (-noflsh)
Disable (enable) flush after INTR, QUIT, SUSP. This has the effect of setting (not setting) NOFLSH in the termios c_lflag field, as defined in the XBD specification, General Terminal Interface  .
tostop (-tostop)
Send SIGTTOU for background output. This has the effect of setting (not setting) TOSTOP in the termios c_lflag field, as defined in the XBD specification, General Terminal Interface  .
Note:
Setting TOSTOP has no effect on systems not supporting the job control option, but all XSI-conformant systems do support this option.

 Special Control Character Assignments
<control>-character string
Set <control>-character to string. If <control>-character is one of the character sequences in the first column of the following table, the corresponding XBD specification, General Terminal Interface  control character from the second column will be recognised. This has the effect of setting the corresponding element of the termios c_cc array (see the XSH specification <termios.h>).
Control Character c_cc Subscript Description
eof VEOF EOF character
eol VEOL EOL character
erase VERASE ERASE character
intr VINTR INTR character
kill VKILL KILL character
quit VQUIT QUIT character
susp VSUSP SUSP character
start VSTART START character
stop VSTOP STOP character
Table: Control Character Names in stty
If string is a single character, the control character will be set to that character. If string is the two-character sequence "^-" or the string undef, the control character will be set to {_POSIX_VDISABLE}, if it is in effect for the device; if {_POSIX_VDISABLE} is not in effect for the device, it will be treated as an error. In the POSIX locale, if string is a two-character sequence beginning with circumflex (^), and the second character is one of those listed in the ^c column of the following table, the control character will be set to the corresponding character value in the Value column of the table.
^c Value ^c Value ^c Value
a, A <SOH> l, L <FF> w, W <ETB>
b, B <STX> m, M <CR> x, X <CAN>
c, C <ETX> n, N <SO> y, Y <EM>
d, D <EOT> o, O <SI> z, Z <SUB>
e, E <ENQ> p, P <DLE> [ <ESC>
f, F <ACK> q, Q <DC1> \ <FS>
g, G <BEL> r, R <DC2> ] <GS>
h, H <BS> s, S <DC3> ^ <RS>
i, I <HT> t, T <DC4> _ <US>
j, J <LF> u, U <NAK> ? <DEL>
k, K <VT> v, V <SYN>    
Table: Circumflex Control Characters in stty
min number
time number
Set the value of min or time to number. MIN and TIME are used in non-canonical mode input processing (-icanon).
 Combination Modes
saved settings
Set the current terminal characteristics to the saved settings produced by the -g option.
evenp or parity
Enable parenb and cs7; disable parodd.
oddp
Enable parenb, cs7 and parodd.
-parity, -evenp or -oddp
Disable parenb, and set cs8.
raw (-raw or cooked)
Enable (disable) raw input and output. Raw mode is equivalent to setting:

stty cs8 erase ^- kill ^- intr ^- \
    quit ^- eof ^- eol ^- -opost -inpck

nl (-nl)
Enable (disable) icrnl. In addition, -nl unsets inlcr and igncr.
lcase (-lcase)
Set (unset) xcase, iuclc and olcuc. (LEGACY)
LCASE (-LCASE)
Equivalent to lcase (-lcase). (LEGACY)
tabs (-tabs or tab3)
Preserve tabs (expand to spaces) when printing.
ek
Reset ERASE and KILL characters back to system defaults.
sane
Reset all modes to some reasonable, unspecified, values.

 STDIN

Although no input is read from standard input, standard input is used to get the current terminal I/O characteristics and to set new terminal I/O characteristics.

 INPUT FILES

None.

 ENVIRONMENT VARIABLES

The following environment variables affect the execution of stty:
LANG
Provide a default value for the internationalisation variables that are unset or null. If LANG is unset or null, the corresponding value from the implementation-dependent default locale will be used. If any of the internationalisation variables contains an invalid setting, the utility will behave as if none of the variables had been defined.
LC_ALL
If set to a non-empty string value, override the values of all the other internationalisation variables.
LC_CTYPE
This variable will determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- versus multi-byte characters in arguments) and which characters are in the class print.
LC_MESSAGES
Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.
NLSPATH
Determine the location of message catalogues for the processing of LC_MESSAGES .

 ASYNCHRONOUS EVENTS

Default.

 STDOUT

If operands are specified, no output is produced.

If the -g option is specified, stty will write to standard output the current settings in a form that can be used as arguments to another instance of stty on the same system.

If the -a option is specified, all of the information as described in the OPERANDS section will be written to standard output. Unless otherwise specified, this information is written as space-separated tokens in an unspecified format, on one or more lines, with an unspecified number of tokens per line. Additional information may be written.

If no options or operands are specified, an unspecified subset of the information written for the -a option is written.

If speed information is written as part of the default output, or if the -a option is specified and if the terminal input speed and output speed are the same, the speed information will be written as follows:

"speed %d baud;", <speed>

Otherwise, speeds will be written as:

"ispeed %d baud; ospeed %d baud;", <ispeed>,
<ospeed>

In locales other than the POSIX locale, the word baud may be changed to something more appropriate in those locales.

If control characters are written as part of the default output, or if the -a option is specified, control characters will be written as:

"%s = %s;", <<control>-character name>,
<value>
where value is either the character, or some visual representation of the character if it is non-printable, or the string <undef> if the character is disabled.

 STDERR

Used only for diagnostic messages.

 OUTPUT FILES

None.

 EXTENDED DESCRIPTION

None.

 EXIT STATUS

The following exit values are returned:
0
The terminal options were read or set successfully.
>0
An error occurred.

 CONSEQUENCES OF ERRORS

Default.

 APPLICATION USAGE

The -g flag is designed to facilitate the saving and restoring of terminal state from the shell level. For example, a program may:

saveterm="$(stty -g)"       # save terminal state
stty (new settings)         # set new state
...                             # ...
stty $saveterm              # restore terminal state

Since the format is unspecified, the saved value is not portable across systems.

Since the -a format is so loosely specified, scripts that save and restore terminal settings should use the -g option.

 EXAMPLES

None.

 FUTURE DIRECTIONS

The IEEE PASC 1003.2 Interpretations Committee has forwarded concerns about parts of this interface definition to the IEEE PASC Shell and Utilities Working Group which is identifying the corrections. A future revision of this specification will align with IEEE Std. 1003.2b when finalised.

 SEE ALSO

The XBD specification, General Terminal Interface  .

UNIX ® is a registered Trademark of The Open Group.
Copyright © 1997 The Open Group
[ Main Index | XSH | XCU | XBD | XCURSES | XNS ]