STTY(1P)

📦 version 2017a, in alpine 3.22, alpine 3.23, alpine 3.24, arch rolling, nixpkgs unstable, opensuse-leap 16.0

✨ STTY(1P) ✨ — coming at you straight from the POSIX Programmer's Manual, and yes bestie we are doing the WHOLE thing, no skimming, no skipping, every single flag gets its moment. 💖

🫶 PROLOG 🫶

okay so housekeeping first, it's giving legal-but-make-it-cute: this manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ — so like, go consult the corresponding Linux manual page for the tea on Linux behavior — or honestly the interface may not be implemented on Linux at all. 💀

👑 NAME 👑

stty — set the options for a terminal. that's the whole name section. short, sweet, iconic.

✨ SYNOPSIS ✨

stty [-a|-g]

stty operand...

🌸 DESCRIPTION 🌸

So what does stty actually do? It sets or reports on terminal I/O characteristics for the device that is its standard input. that's the vibe. 🎀

If you give it no options and no operands at all? It reports the settings of certain characteristics — usually the ones that differ from implementation-defined defaults. Otherwise, it modifies the terminal state according to whatever operands you handed it. 🌈

Detailed info about the modes in the first five groups below lives in the Base Definitions volume of POSIX.1-2017, Chapter 11, General Terminal Interface. The operands in the Combination Modes group (peep Combination Modes) are implemented using the operands from the previous groups, no cap. And heads up: some combinations of operands are mutually-exclusive on some terminal types, and the results of using such combos are unspecified. so like, don't be messy. 🙈

Typical implementations of this utility require a communications line configured to use the termios interface defined in the System Interfaces volume of POSIX.1-2017. On systems where none of these lines are available, and on lines not currently configured to support the termios interface, some of the operands need not affect terminal characteristics. lowkey important, highkey boring, moving on. 💅

🎀 OPTIONS 🎀

The stty utility shall conform to the Base Definitions volume of POSIX.1-2017, Section 12.2, Utility Syntax Guidelines. (Yes, that's a real thing. Yes, it's just as glamorous as it sounds.)

The following options shall be supported:

  • -a — write to standard output all the current settings for the terminal. everything. the whole closet. 👑
  • -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. and the form used shall not contain any characters that would require quoting to avoid word expansion by the shell — see Section 2.6, Word Expansions. so it's the "save your settings and replay them later" girlie. 🦋

🧚 OPERANDS 🧚

The following operands shall be supported to set the terminal characteristics. buckle up bestie, there are a LOT of them, and we're doing every single one.

💜 Control Modes 💜

  • parenb (-parenb) — enable (disable) parity generation and detection. this sets (or doesn't set, if you used the - form) PARENB in the termios c_cflag field, as defined in the Base Definitions volume of POSIX.1-2017, Chapter 11, General Terminal Interface.
  • parodd (-parodd) — pick odd (even) parity. that's PARODD in the termios c_cflag field, set or not set, as defined in the Base Definitions volume of POSIX.1-2017, Chapter 11, General Terminal Interface.
  • cs5 cs6 cs7 cs8 — select the character size, if possible. these set CS5, CS6, CS7, and CS8 respectively in the termios c_cflag field, as defined in the Base Definitions volume of POSIX.1-2017, Chapter 11, General Terminal Interface. pick your fighter. ⭐
  • number — set the terminal baud rate to the number given, if possible. and if the baud rate is set to zero, the modem control lines shall no longer be asserted. this sets the input and output termios baud rate values, as defined in the Base Definitions volume of POSIX.1-2017, Chapter 11, General Terminal Interface.
  • ispeed number — set the terminal input baud rate to the number given, if possible. if the input baud rate is set to zero, the input baud rate shall be specified by the value of the output baud rate. this sets the input termios baud rate values, as defined in the Base Definitions volume of POSIX.1-2017, Chapter 11, General Terminal Interface.
  • ospeed number — set the terminal output baud rate to the number given, if possible. if the output baud rate is set to zero, the modem control lines shall no longer be asserted. this sets the output termios baud rate values, as defined in the Base Definitions volume of POSIX.1-2017, Chapter 11, General Terminal Interface.
  • hupcl (-hupcl) — stop asserting modem control lines (or don't stop asserting them) on last close. HUPCL in the termios c_cflag field, set or not set, as defined in the Base Definitions volume of POSIX.1-2017, Chapter 11, General Terminal Interface.
  • hup (-hup) — equivalent to hupcl(-hupcl). the little shortcut. 🫶
  • cstopb (-cstopb) — use two (one) stop bits per character. CSTOPB in the termios c_cflag field, set or not set, as defined in the Base Definitions volume of POSIX.1-2017, Chapter 11, General Terminal Interface.
  • cread (-cread) — enable (disable) the receiver. CREAD in the termios c_cflag field, set or not set, as defined in the Base Definitions volume of POSIX.1-2017, Chapter 11, General Terminal Interface.
  • clocal (-clocal) — assume a line without (with) modem control. CLOCAL in the termios c_cflag field, set or not set, as defined in the Base Definitions volume of POSIX.1-2017, Chapter 11, General Terminal Interface.
It is unspecified whether stty shall report an error if an attempt to set a Control Mode fails. so like… maybe it yells, maybe it doesn't. we don't know. 😭

🌈 Input Modes 🌈

  • ignbrk (-ignbrk) — ignore (do not ignore) break on input. this sets (not sets) IGNBRK in the termios c_iflag field, as defined in the Base Definitions volume of POSIX.1-2017, Chapter 11, General Terminal Interface.
  • brkint (-brkint) — signal (do not signal) INTR on break. that's BRKINT in the termios c_iflag field, set or not set, as defined in the Base Definitions volume of POSIX.1-2017, Chapter 11, General Terminal Interface.
  • ignpar (-ignpar) — ignore (do not ignore) bytes with parity errors. IGNPAR in the termios c_iflag field, set or not set, as defined in the Base Definitions volume of POSIX.1-2017, Chapter 11, General Terminal Interface.
  • parmrk (-parmrk) — mark (do not mark) parity errors. PARMRK in the termios c_iflag field, set or not set, as defined in the Base Definitions volume of POSIX.1-2017, Chapter 11, General Terminal Interface.
  • inpck (-inpck) — enable (disable) input parity checking. INPCK in the termios c_iflag field, set or not set, as defined in the Base Definitions volume of POSIX.1-2017, Chapter 11, General Terminal Interface.
  • istrip (-istrip) — strip (do not strip) input characters down to seven bits. ISTRIP in the termios c_iflag field, set or not set, as defined in the Base Definitions volume of POSIX.1-2017, Chapter 11, General Terminal Interface.
  • inlcr (-inlcr) — map (do not map) NL to CR on input. INLCR in the termios c_iflag field, set or not set, as defined in the Base Definitions volume of POSIX.1-2017, Chapter 11, General Terminal Interface.
  • igncr (-igncr) — ignore (do not ignore) CR on input. IGNCR in the termios c_iflag field, set or not set, as defined in the Base Definitions volume of POSIX.1-2017, Chapter 11, General Terminal Interface.
  • icrnl (-icrnl) — map (do not map) CR to NL on input. ICRNL in the termios c_iflag field, set or not set, as defined in the Base Definitions volume of POSIX.1-2017, Chapter 11, General Terminal Interface.
  • 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. IXON in the termios c_iflag field, set or not set, as defined in the Base Definitions volume of POSIX.1-2017, Chapter 11, General Terminal Interface.
  • ixany (-ixany) — allow any character to restart output. IXANY in the termios c_iflag field, set or not set, as defined in the Base Definitions volume of POSIX.1-2017, Chapter 11, General Terminal Interface.
  • ixoff (-ixoff) — request that the system send (not send) STOP characters when the input queue is nearly full, plus START characters to resume data transmission. IXOFF in the termios c_iflag field, set or not set, as defined in the Base Definitions volume of POSIX.1-2017, Chapter 11, General Terminal Interface.

🦋 Output Modes 🦋

  • opost (-opost) — post-process output (do not post-process output; ignore all other output modes). OPOST in the termios c_oflag field, set or not set, as defined in the Base Definitions volume of POSIX.1-2017, Chapter 11, General Terminal Interface.
  • onlcr (-onlcr) — map (do not map) NL to CR-NL on output. ONLCR in the termios c_oflag field, set or not set, as defined in the Base Definitions volume of POSIX.1-2017, Chapter 11, General Terminal Interface.
  • ocrnl (-ocrnl) — map (do not map) CR to NL on output. OCRNL in the termios c_oflag field, set or not set, as defined in the Base Definitions volume of POSIX.1-2017, Chapter 11, General Terminal Interface.
  • onocr, -onocr — don't (do) drop a CR at column zero. Lowkey this flips ONOCR in the termios c_oflag field, exactly like the Base Definitions volume of POSIX.1‐2017, Chapter 11, General Terminal Interface says. 🎀
  • onlret, -onlret — the terminal's newline key does (doesn't) do the CR thing. Sets (or unsets) ONLRET in termios c_oflag, per the Base Definitions volume of POSIX.1‐2017, Chapter 11, General Terminal Interface. ✨
  • ofill, -ofill — use fill characters (or use timing) for delays. That's OFILL in termios c_oflag, set (not set), per the Base Definitions volume of POSIX.1‐2017, Chapter 11, General Terminal Interface. 💅
  • ofdel, -ofdel — fill characters are DELs (NULs). Sets (not sets) OFDEL in termios c_oflag, per the Base Definitions volume of POSIX.1‐2017, Chapter 11, General Terminal Interface. 🌸
  • cr0 cr1 cr2 cr3 — pick the delay style for CRs. This sets CRDLY to CR0, CR1, CR2, or CR3 respectively, in termios c_oflag, per the Base Definitions volume of POSIX.1‐2017, Chapter 11, General Terminal Interface. 🦋
  • nl0 nl1 — pick the delay style for NL. Sets NLDLY to NL0 or NL1 respectively, in termios c_oflag, per the Base Definitions volume of POSIX.1‐2017, Chapter 11, General Terminal Interface. ⭐
  • tab0 tab1 tab2 tab3 — pick the delay style for horizontal tabs. Sets TABDLY to TAB0, TAB1, TAB2, or TAB3 respectively, in termios c_oflag, per the Base Definitions volume of POSIX.1‐2017, Chapter 11, General Terminal Interface. Heads up bestie: TAB3 has the effect of expanding <tab> characters to <space> characters. 😭
  • tabs, -tabs — just a synonym for tab0 (tab3). 💖
  • bs0 bs1 — pick the delay style for <backspace> characters. Sets BSDLY to BS0 or BS1 respectively, in termios c_oflag, per the Base Definitions volume of POSIX.1‐2017, Chapter 11, General Terminal Interface. 🎀
  • ff0 ff1 — pick the delay style for <form-feed> characters. Sets FFDLY to FF0 or FF1 respectively, in termios c_oflag, per the Base Definitions volume of POSIX.1‐2017, Chapter 11, General Terminal Interface. 🌈
  • vt0 vt1 — pick the delay style for <vertical-tab> characters. Sets VTDLY to VT0 or VT1 respectively, in termios c_oflag, per the Base Definitions volume of POSIX.1‐2017, Chapter 11, General Terminal Interface. ✨

💅 Local Modes 💅

  • isig, -isig — turn on (off) checking characters against the special control characters INTR, QUIT, and SUSP. Sets (not sets) ISIG in termios c_lflag, per the Base Definitions volume of POSIX.1‐2017, Chapter 11, General Terminal Interface. 🫶
  • icanon, -icanon — turn on (off) canonical input, aka ERASE and KILL processing. Sets (not sets) ICANON in termios c_lflag, per the Base Definitions volume of POSIX.1‐2017, Chapter 11, General Terminal Interface. 👑
  • iexten, -iexten — turn on (off) any implementation-defined special control characters that aren't currently controlled by icanon, isig, ixon, or ixoff. Sets (not sets) IEXTEN in termios c_lflag, per the Base Definitions volume of POSIX.1‐2017, Chapter 11, General Terminal Interface. 🦋
  • echo, -echo — echo back (don't echo back) every single character typed. Sets (not sets) ECHO in termios c_lflag, per the Base Definitions volume of POSIX.1‐2017, Chapter 11, General Terminal Interface. 😭
  • echoe, -echoe — the ERASE character visually erases (doesn't erase) the last character in the current line from the display, if possible. Sets (not sets) ECHOE in termios c_lflag, per the Base Definitions volume of POSIX.1‐2017, Chapter 11, General Terminal Interface. 🌸
  • echok, -echok — echo (don't echo) NL after the KILL character. Sets (not sets) ECHOK in termios c_lflag, per the Base Definitions volume of POSIX.1‐2017, Chapter 11, General Terminal Interface. 💖
  • echonl, -echonl — echo (don't echo) NL even when echo is disabled. Sets (not sets) ECHONL in termios c_lflag, per the Base Definitions volume of POSIX.1‐2017, Chapter 11, General Terminal Interface. ⭐
  • noflsh, -noflsh — disable (enable) flush after INTR, QUIT, SUSP. Sets (not sets) NOFLSH in termios c_lflag, per the Base Definitions volume of POSIX.1‐2017, Chapter 11, General Terminal Interface. 🔥
  • tostop, -tostop — send SIGTTOU for background output. Sets (not sets) TOSTOP in termios c_lflag, per the Base Definitions volume of POSIX.1‐2017, Chapter 11, General Terminal Interface. 💀

🎀 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 table below, then the matching Base Definitions volume of POSIX.1‐2017, Chapter 11, General Terminal Interface control character from the second column gets recognized. This has the effect of setting the corresponding element of the termios c_cc array (peep the Base Definitions volume of POSIX.1‐2017, Chapter 13, Headers, <termios.h>). ✨

Table: Control Character Names in stty

  • eof — c_cc Subscript: VEOF — EOF character
  • eol — c_cc Subscript: VEOL — EOL character
  • erase — c_cc Subscript: VERASE — ERASE character
  • intr — c_cc Subscript: VINTR — INTR character
  • kill — c_cc Subscript: VKILL — KILL character
  • quit — c_cc Subscript: VQUIT — QUIT character
  • susp — c_cc Subscript: VSUSP — SUSP character
  • start — c_cc Subscript: VSTART — START character
  • stop — c_cc Subscript: VSTOP — STOP character

If string is a single character, the control character shall be set to that character. If string is the two-character sequence "^-" or the string undef, the control character shall be set to _POSIX_VDISABLE, if it's in effect for the device; but if _POSIX_VDISABLE is not in effect for the device, it shall 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 table below, the control character shall be set to the corresponding character value in the Value column. 💅

Table: Circumflex Control Characters in stty

  • a, A — <SOH>
  • b, B — <STX>
  • c, C — <ETX>
  • d, D — <EOT>
  • e, E — <ENQ>
  • f, F — <ACK>
  • g, G — <BEL>
  • h, H — <BS>
  • i, I — <HT>
  • j, J — <LF>
  • k, K — <VT>
  • l, L — <FF>
  • m, M — <CR>
  • n, N — <SO>
  • o, O — <SI>
  • p, P — <DLE>
  • q, Q — <DC1>
  • r, R — <DC2>
  • s, S — <DC3>
  • t, T — <DC4>
  • u, U — <NAK>
  • v, V — <SYN>
  • w, W — <ETB>
  • x, X — <CAN>
  • y, Y — <EM>
  • z, Z — <SUB>
  • [ — <ESC>
  • \ — <FS>
  • ] — <GS>
  • ^ — <RS>
  • _ — <US>
  • ? — <DEL>

min number

Set the value of MIN to number. MIN is used in non-canonical mode input processing (icanon). 🌸

time number

Set the value of TIME to number. TIME is 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 — flip on parenb and cs7, flip off parodd. ✨
  • oddp — flip on parenb, cs7, and parodd. bestie it's the odd one out 💅
  • -parity, -evenp, or -oddp — flip off parenb and set cs8. bye parity 👋
  • raw (-raw or cooked) — turn raw input and output on (or off, respectively). Raw mode is equivalent to setting exactly this:
stty cs8 erase ^- kill ^- intr ^- \
    quit ^- eof ^- eol ^- -post -inpck
  • nl (-nl) — disable (enable) icrnl. and like, as a lil bonus, -nl also unsets inlcr and igncr 🎀
  • ek — reset the ERASE and KILL characters back to the system defaults. fresh start fr 🦋
  • sane — reset all modes to some reasonable, unspecified, values. the ultimate glow-up ✨🧚

💖 STDIN 💖

okay so even though nothing actually gets read from standard input, standard input is still the thing that's used to grab the current terminal I/O characteristics and to set the new terminal I/O characteristics. it's giving behind-the-scenes main character energy. 👑

🎀 INPUT FILES 🎀

None. literally none. empty. nada. the void. 💀

🌈 ENVIRONMENT VARIABLES 🌈

these variables affect how stty runs, bestie:

  • LANG — provides a default value for the internationalization variables that are unset or null. (see the Base Definitions volume of POSIX.1‐2017, Section 8.2, Internationalization Variables for the precedence of internationalization variables used to determine the values of locale categories.) 🫶
  • LC_ALL — if it's set to a non-empty string value, it overrides the values of all the other internationalization variables. it said "i'm the captain now" 💅
  • LC_CTYPE — this one determines the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as opposed to multi-byte characters in arguments) and which characters are in the class print.
  • LC_MESSAGES — determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error.
  • NLSPATH — determines the location of message catalogs for the processing of LC_MESSAGES. ✨

🌸 ASYNCHRONOUS EVENTS 🌸

Default. that's it, that's the section. 😌

⭐ STDOUT ⭐

if operands are specified, no output shall be produced. silence. iconic. 🤫

if the -g option is specified, stty shall 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. copy-paste-able slay. 💾

if the -a option is specified, all of the information as described in the OPERANDS section shall be written to standard output. Unless otherwise specified, this information shall be 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. no cap, it's vague on purpose. 🙈

if no options or operands are specified, an unspecified subset of the information written for the -a option shall be 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 shall be written as follows:

"speed %d baud;", <speed>

otherwise, speeds shall 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. ✨ localization ate. 🌍

if control characters are written as part of the default output, or if the -a option is specified, control characters shall 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 💜

the standard error shall be used only for diagnostic messages. that's its whole job bestie. 📢

🍓 OUTPUT FILES 🍓

None. again. the emptiness is the vibe. 🕳️

🧚 EXTENDED DESCRIPTION 🧚

None.

🔥 EXIT STATUS 🔥

the following exit values shall be returned:

  • 0 — the terminal options were read or set successfully. we love a win 💖
  • >0 — an error occurred. 😭

💀 CONSEQUENCES OF ERRORS 💀

Default.

heads up bestie: the following sections are informative. (not normative, just so you know the vibe.) 🎀

🌈 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. 😭 don't be out here copying it between machines, fr.

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

🦋 EXAMPLES 🦋

None. 💀

👑 RATIONALE 👑

the original stty description was taken directly from System V and reflected the System V terminal driver termio. It has been modified to correspond to the terminal driver termios. glow-up complete. ✨

output modes are specified only for XSI-conformant systems. All implementations are expected to provide stty operands corresponding to all of the output modes they support.

the stty utility is primarily used to tailor the user interface of the terminal, such as selecting the preferred ERASE and KILL characters. As an application programming utility, stty can be used within shell scripts to alter the terminal settings for the duration of the script.

the termios section states that individual disabling of control characters is possible through the option _POSIX_VDISABLE. If enabled, two conventions currently exist for specifying this: System V uses "^-", and BSD uses undef. Both are accepted by stty in this volume of POSIX.1‐2017. The other BSD convention of using the letter 'u' was rejected because it conflicts with the actual letter 'u', which is an acceptable value for a control character. bestie the letter u said "not today" 🙅‍♀️

early proposals did not specify the mapping of "^c" to control characters because the control characters were not specified in the POSIX locale character set description file requirements. The control character set is now specified in the Base Definitions volume of POSIX.1‐2017, Chapter 3, Definitions, so the historical mapping is specified. Note that although the mapping corresponds to control-character key assignments on many terminals that use the ISO/IEC 646:1991 standard (or ASCII) character encodings, the mapping specified here is to the control characters, not their keyboard encodings. iykyk ⌨️

since termios supports separate speeds for input and output, two new options were added to specify each distinctly. ✨

some historical implementations use standard input to get and set terminal characteristics; others use standard output. Since input from a login TTY is usually restricted to the owner while output to a TTY is frequently open to anyone, using standard input provides fewer chances of accidentally (or maliciously) altering the terminal settings of other users. Using standard input also allows stty -a and stty -g output to be redirected for later use. Therefore, usage of standard input is required by this volume of POSIX.1‐2017. safety first bestie, no cap. 🔒

🌟 FUTURE DIRECTIONS 🌟

None.

🫶 SEE ALSO 🫶

  • Chapter 2, Shell Command Language
  • The Base Definitions volume of POSIX.1‐2017, Chapter 8, Environment Variables, Chapter 11, General Terminal Interface, Section 12.2, Utility Syntax Guidelines, <termios.h>

Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .

and that's the whole page bestie!! 🎀 source/version is IEEE/The Open Group and the date is 2017, for STTY(1P) — thanks for reading the whole thing, you ate that. mwah. 💅✨

📦 where this page comes from