bin/stty/stty.1

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