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