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 .\" 4. 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 August 23, 2008
  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 .El
 149 .Ss Input Modes:
 150 This corresponds to the c_iflag in the termios structure.
 151 .Bl -tag -width Fl
 152 .It Cm ignbrk Pq Fl ignbrk
 153 Ignore (do not ignore) break on
 154 input.
 155 .It Cm brkint Pq Fl brkint
 156 Signal (do not signal)
 157 .Dv INTR
 158 on
 159 break.
 160 .It Cm ignpar Pq Fl ignpar
 161 Ignore (do not ignore) characters with parity
 162 errors.
 163 .It Cm parmrk Pq Fl parmrk
 164 Mark (do not mark) characters with parity errors.
 165 .It Cm inpck Pq Fl inpck
 166 Enable (disable) input parity
 167 checking.
 168 .It Cm istrip Pq Fl istrip
 169 Strip (do not strip) input characters
 170 to seven bits.
 171 .It Cm inlcr Pq Fl inlcr
 172 Map (do not map)
 173 .Dv NL
 174 to
 175 .Dv CR
 176 on input.
 177 .It Cm igncr Pq Fl igncr
 178 Ignore (do not ignore)
 179 .Dv CR
 180 on input.
 181 .It Cm icrnl Pq Fl icrnl
 182 Map (do not map)
 183 .Dv CR
 184 to
 185 .Dv NL
 186 on input.
 187 .It Cm ixon Pq Fl ixon
 188 Enable (disable)
 189 .Dv START/STOP
 190 output
 191 control.
 192 Output from the system is
 193 stopped when the system receives
 194 .Dv STOP
 195 and started when the system
 196 receives
 197 .Dv START ,
 198 or if
 199 .Cm ixany
 200 is set, any character restarts output.
 201 .It Cm ixoff Pq Fl ixoff
 202 Request that the system send (not
 203 send)
 204 .Dv START/STOP
 205 characters when
 206 the input queue is nearly
 207 empty/full.
 208 .It Cm ixany Pq Fl ixany
 209 Allow any character (allow only
 210 .Dv START )
 211 to restart output.
 212 .It Cm imaxbel Pq Fl imaxbel
 213 The system imposes a limit of
 214 .Dv MAX_INPUT
 215 (currently 255) characters in the input queue.
 216 If
 217 .Cm imaxbel
 218 is set and the input queue limit has been reached,
 219 subsequent input causes the system to send an ASCII BEL
 220 character to the output queue (the terminal beeps at you).
 221 Otherwise,
 222 if
 223 .Cm imaxbel
 224 is unset and the input queue is full, the next input character causes
 225 the entire input and output queues to be discarded.
 226 .El
 227 .Ss Output Modes:
 228 This corresponds to the c_oflag of the termios structure.
 229 .Bl -tag -width Fl
 230 .It Cm opost Pq Fl opost
 231 Post-process output (do not
 232 post-process output; ignore all other
 233 output modes).
 234 .It Cm onlcr Pq Fl onlcr
 235 Map (do not map)
 236 .Dv NL
 237 to
 238 .Dv CR-NL
 239 on output.
 240 .It Cm ocrnl Pq Fl ocrnl
 241 Map (do not map)
 242 .Dv CR
 243 to
 244 .Dv NL
 245 on output.
 246 .It Cm tab0 tab3
 247 Select tab expansion policy.
 248 .Cm tab0
 249 disables tab expansion, while
 250 .Cm tab3
 251 enables it.
 252 .It Cm onocr Pq Fl onocr
 253 Do not (do) output CRs at column zero.
 254 .It Cm onlret Pq Fl onlret
 255 On the terminal NL performs (does not perform) the CR function.
 256 .El
 257 .Ss Local Modes:
 258 Local mode flags (lflags) affect various and sundry characteristics of terminal
 259 processing.
 260 Historically the term "local" pertained to new job control features
 261 implemented by Jim Kulp on a
 262 .Tn Pdp 11/70
 263 at
 264 .Tn IIASA .
 265 Later the driver ran on the first
 266 .Tn VAX
 267 at Evans Hall, UC Berkeley, where the job control details
 268 were greatly modified but the structure definitions and names
 269 remained essentially unchanged.
 270 The second interpretation of the 'l' in lflag
 271 is ``line discipline flag'' which corresponds to the
 272 .Ar c_lflag
 273 of the
 274 .Ar termios
 275 structure.
 276 .Bl -tag -width Fl
 277 .It Cm isig Pq Fl isig
 278 Enable (disable) the checking of
 279 characters against the special control
 280 characters
 281 .Dv INTR , QUIT ,
 282 and
 283 .Dv SUSP .
 284 .It Cm icanon Pq Fl icanon
 285 Enable (disable) canonical input
 286 .Pf ( Dv ERASE
 287 and
 288 .Dv KILL
 289 processing).
 290 .It Cm iexten Pq Fl iexten
 291 Enable (disable) any implementation
 292 defined special control characters
 293 not currently controlled by icanon,
 294 isig, or ixon.
 295 .It Cm echo Pq Fl echo
 296 Echo back (do not echo back) every
 297 character typed.
 298 .It Cm echoe Pq Fl echoe
 299 The
 300 .Dv ERASE
 301 character shall (shall
 302 not) visually erase the last character
 303 in the current line from the
 304 display, if possible.
 305 .It Cm echok Pq Fl echok
 306 Echo (do not echo)
 307 .Dv NL
 308 after
 309 .Dv KILL
 310 character.
 311 .It Cm echoke Pq Fl echoke
 312 The
 313 .Dv KILL
 314 character shall (shall
 315 not) visually erase the
 316 current line from the
 317 display, if possible.
 318 .It Cm echonl Pq Fl echonl
 319 Echo (do not echo)
 320 .Dv NL ,
 321 even if echo
 322 is disabled.
 323 .It Cm echoctl Pq Fl echoctl
 324 If
 325 .Cm echoctl
 326 is set, echo control characters as ^X.
 327 Otherwise control characters
 328 echo as themselves.
 329 .It Cm echoprt Pq Fl echoprt
 330 For printing terminals.
 331 If set, echo erased characters backwards within ``\\''
 332 and ``/''.
 333 Otherwise, disable this feature.
 334 .It Cm noflsh Pq Fl noflsh
 335 Disable (enable) flush after
 336 .Dv INTR , QUIT , SUSP .
 337 .It Cm tostop Pq Fl tostop
 338 Send (do not send)
 339 .Dv SIGTTOU
 340 for background output.
 341 This causes background jobs to stop if they attempt
 342 terminal output.
 343 .It Cm altwerase Pq Fl altwerase
 344 Use (do not use) an alternate word erase algorithm when processing
 345 .Dv WERASE
 346 characters.
 347 This alternate algorithm considers sequences of
 348 alphanumeric/underscores as words.
 349 It also skips the first preceding character in its classification
 350 (as a convenience since the one preceding character could have been
 351 erased with simply an
 352 .Dv ERASE
 353 character.)
 354 .It Cm mdmbuf Pq Fl mdmbuf
 355 If set, flow control output based on condition of Carrier Detect.
 356 Otherwise
 357 writes return an error if Carrier Detect is low (and Carrier is not being
 358 ignored with the
 359 .Dv CLOCAL
 360 flag.)
 361 .It Cm flusho Pq Fl flusho
 362 Indicates output is (is not) being discarded.
 363 .It Cm pendin Pq Fl pendin
 364 Indicates input is (is not) pending after a switch from non-canonical
 365 to canonical mode and will be re-input when a read becomes pending
 366 or more input arrives.
 367 .El
 368 .Ss Control Characters:
 369 .Bl -tag -width Fl
 370 .It Ar control-character Ar string
 371 Set
 372 .Ar control-character
 373 to
 374 .Ar string .
 375 If string is a single character,
 376 the control character is set to
 377 that character.
 378 If string is the
 379 two character sequence "^-" or the
 380 string "undef" the control character
 381 is disabled (i.e., set to
 382 .Pf { Dv _POSIX_VDISABLE Ns } . )
 383 .Pp
 384 Recognized 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
 410 Set the value of min or time to
 411 number.
 412 .Dv MIN
 413 and
 414 .Dv TIME
 415 are used in
 416 Non-Canonical mode input processing
 417 (-icanon).
 418 .El
 419 .Ss Combination Modes:
 420 .Bl -tag -width Fl
 421 .It Ar saved settings
 422 Set the current terminal
 423 characteristics to the saved settings
 424 produced by the
 425 .Fl g
 426 option.
 427 .It Cm evenp No or Cm parity
 428 Enable parenb and cs7; disable
 429 parodd.
 430 .It Cm oddp
 431 Enable parenb, cs7, and parodd.
 432 .It Fl parity , evenp , oddp
 433 Disable parenb, and set cs8.
 434 .It Cm \&nl Pq Fl \&nl
 435 Enable (disable) icrnl.
 436 In addition
 437 -nl unsets inlcr and igncr.
 438 .It Cm ek
 439 Reset
 440 .Dv ERASE ,
 441 .Dv ERASE2 ,
 442 and
 443 .Dv KILL
 444 characters
 445 back to system defaults.
 446 .It Cm sane
 447 Resets all modes to reasonable values for interactive terminal use.
 448 .It Cm tty
 449 Set the line discipline to the standard terminal line discipline
 450 .Dv TTYDISC .
 451 .It Cm crt Pq Fl crt
 452 Set (disable) all modes suitable for a CRT display device.
 453 .It Cm kerninfo Pq Fl kerninfo
 454 Enable (disable) the system generated status line associated with
 455 processing a
 456 .Dv STATUS
 457 character (usually set to ^T).
 458 The status line consists of the
 459 system load average, the current command name, its process ID, the
 460 event the process is waiting on (or the status of the process), the user
 461 and system times, percent cpu, and current memory usage.
 462 .It Cm columns Ar number
 463 The terminal size is recorded as having
 464 .Ar number
 465 columns.
 466 .It Cm cols Ar number
 467 is an alias for
 468 .Cm columns .
 469 .It Cm rows Ar number
 470 The terminal size is recorded as having
 471 .Ar number
 472 rows.
 473 .It Cm dec
 474 Set modes suitable for users of Digital Equipment Corporation systems
 475 .Dv ( ERASE ,
 476 .Dv KILL ,
 477 and
 478 .Dv INTR
 479 characters are set to ^?, ^U, and ^C;
 480 .Dv ixany
 481 is disabled, and
 482 .Dv crt
 483 is enabled.)
 484 .It Cm extproc Pq Fl extproc
 485 If set, this flag indicates that some amount of terminal processing is being
 486 performed by either the terminal hardware or by the remote side connected
 487 to a pty.
 488 .It Cm raw Pq Fl raw
 489 If set, change the modes of the terminal so that no input or output processing
 490 is performed.
 491 If unset, change the modes of the terminal to some reasonable
 492 state that performs input and output processing.
 493 Note that since the
 494 terminal driver no longer has a single
 495 .Dv RAW
 496 bit, it is not possible to intuit what flags were set prior to setting
 497 .Cm raw .
 498 This means that unsetting
 499 .Cm raw
 500 may not put back all the setting that were previously in effect.
 501 To set the terminal into a raw state and then accurately restore it, the following
 502 shell code is recommended:
 503 .Bd -literal
 504 save_state=$(stty -g)
 505 stty raw
 506 \&...
 507 stty "$save_state"
 508 .Ed
 509 .It Cm size
 510 The size of the terminal is printed as two numbers on a single line,
 511 first rows, then columns.
 512 .El
 513 .Ss Compatibility Modes:
 514 These modes remain for compatibility with the previous version of
 515 the
 516 .Nm
 517 command.
 518 .Bl -tag -width Fl
 519 .It Cm all
 520 Reports all the terminal modes as with
 521 .Cm stty Fl a
 522 except that the control characters are printed in a columnar format.
 523 .It Cm everything
 524 Same as
 525 .Cm all .
 526 .It Cm cooked
 527 Same as
 528 .Cm sane .
 529 .It Cm cbreak
 530 If set, enables
 531 .Cm brkint , ixon , imaxbel , opost ,
 532 .Cm isig , iexten ,
 533 and
 534 .Fl icanon .
 535 If unset, same as
 536 .Cm sane .
 537 .It Cm new
 538 Same as
 539 .Cm tty .
 540 .It Cm old
 541 Same as
 542 .Cm tty .
 543 .It Cm newcrt Pq Fl newcrt
 544 Same as
 545 .Cm crt .
 546 .It Cm pass8
 547 The converse of
 548 .Cm parity .
 549 .It Cm tandem Pq Fl tandem
 550 Same as
 551 .Cm ixoff .
 552 .It Cm decctlq Pq Fl decctlq
 553 The converse of
 554 .Cm ixany .
 555 .It Cm crterase Pq Fl crterase
 556 Same as
 557 .Cm echoe .
 558 .It Cm crtbs Pq Fl crtbs
 559 Same as
 560 .Cm echoe .
 561 .It Cm crtkill Pq Fl crtkill
 562 Same as
 563 .Cm echoke .
 564 .It Cm ctlecho Pq Fl ctlecho
 565 Same as
 566 .Cm echoctl .
 567 .It Cm prterase Pq Fl prterase
 568 Same as
 569 .Cm echoprt .
 570 .It Cm litout Pq Fl litout
 571 The converse of
 572 .Cm opost .
 573 .It Cm oxtabs Pq Fl oxtabs
 574 Expand (do not expand) tabs to spaces on output.
 575 .It Cm tabs Pq Fl tabs
 576 The converse of
 577 .Cm oxtabs .
 578 .It Cm brk Ar value
 579 Same as the control character
 580 .Cm eol .
 581 .It Cm flush Ar value
 582 Same as the control character
 583 .Cm discard .
 584 .It Cm rprnt Ar value
 585 Same as the control character
 586 .Cm reprint .
 587 .El
 588 .Sh EXIT STATUS
 589 .Ex -std
 590 .Sh SEE ALSO
 591 .Xr termios 4
 592 .Sh STANDARDS
 593 The
 594 .Nm
 595 utility is expected to be
 596 .St -p1003.2
 597 compatible.
 598 The flags
 599 .Fl e
 600 and
 601 .Fl f
 602 are
 603 extensions to the standard.