adv_cmds/stty/stty.1

   1 .\" Copyright (c) 1990, 1993, 1994
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" the Institute of Electrical and Electronics Engineers, Inc.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. All advertising materials mentioning features or use of this software
  16 .\"    must display the following acknowledgement:
  17 .\"     This product includes software developed by the University of
  18 .\"     California, Berkeley and its contributors.
  19 .\" 4. Neither the name of the University nor the names of its contributors
  20 .\"    may be used to endorse or promote products derived from this software
  21 .\"    without specific prior written permission.
  22 .\"
  23 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  26 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  33 .\" SUCH DAMAGE.
  34 .\"
  35 .\"     @(#)stty.1      8.4 (Berkeley) 4/18/94
  36 .\" $FreeBSD: src/bin/stty/stty.1,v 1.27 2001/11/29 15:46:54 green Exp $
  37 .\"
  38 .Dd April 18, 1994
  39 .Dt STTY 1
  40 .Os
  41 .Sh NAME
  42 .Nm stty
  43 .Nd set the options for a terminal device interface
  44 .Sh SYNOPSIS
  45 .Nm
  46 .Op Fl a | Fl e | Fl g
  47 .Op Fl f Ar file
  48 .Op operands
  49 .Sh DESCRIPTION
  50 The
  51 .Nm
  52 utility sets or reports on terminal
  53 characteristics for the device that is its standard input.
  54 If no options or operands are specified, it reports the settings of a subset
  55 of characteristics as well as additional ones if they differ from their
  56 default values.
  57 Otherwise it modifies
  58 the terminal state according to the specified arguments.
  59 Some combinations of arguments are mutually
  60 exclusive on some terminal types.
  61 .Pp
  62 The following options are available:
  63 .Bl -tag -width indent
  64 .It Fl a
  65 Display all the current settings for the terminal to standard output
  66 as per
  67 .St -p1003.2 .
  68 .It Fl e
  69 Display all the current settings for the terminal to standard output
  70 in the traditional
  71 .Bx
  72 ``all'' and ``everything'' formats.
  73 .It Fl f
  74 Open and use the terminal named by
  75 .Ar file
  76 rather than using standard input.  The file is opened
  77 using the
  78 .Dv O_NONBLOCK
  79 flag of
  80 .Fn open ,
  81 making it possible to
  82 set or display settings on a terminal that might otherwise
  83 block on the open.
  84 .It Fl g
  85 Display all the current settings for the terminal to standard output
  86 in a form that may be used as an argument to a subsequent invocation of
  87 .Nm
  88 to restore the current terminal state as per
  89 .St -p1003.2 .
  90 .El
  91 .Pp
  92 The following arguments are available to set the terminal
  93 characteristics:
  94 .Ss Control Modes:
  95 .Pp
  96 Control mode flags affect hardware characteristics associated with the
  97 terminal.  This corresponds to the c_cflag in the termios structure.
  98 .Bl -tag -width Fl
  99 .It Ar number
 100 Set terminal baud rate to the number given, if possible.
 101 If the baud rate is set to zero,
 102 modem control is no longer asserted.
 103 .It Cm clocal Pq Fl clocal
 104 Assume a line without (with) modem control.
 105 .It Cm cread Pq Fl cread
 106 Enable (disable) the receiver.
 107 .It Cm crtscts Pq Fl crtscts
 108 Enable (disable) RTS/CTS flow control.
 109 .It Cm cs5 cs6 cs7 cs8
 110 Select character size, if possible.
 111 .It Cm cstopb Pq Fl cstopb
 112 Use two (one) stop bits per character.
 113 .It Cm hup Pq Fl hup
 114 Same as
 115 .Cm hupcl
 116 .Pq Fl hupcl .
 117 .It Cm hupcl Pq Fl hupcl
 118 Stop asserting modem control
 119 (do not stop asserting modem control) on last close.
 120 .It Cm ispeed Ar number
 121 Set terminal input baud rate to the number given, if possible.
 122 If the input baud rate is set to zero,
 123 the input baud rate is set to the value of the output baud rate.
 124 .It Cm ospeed Ar number
 125 Set terminal output baud rate to the number given, if possible.
 126 If the output baud rate is set to zero,
 127 modem control is no longer asserted.
 128 .It Cm parenb Pq Fl parenb
 129 Enable (disable) parity generation and detection.
 130 .It Cm parodd Pq Fl parodd
 131 Select odd (even) parity.
 132 .It Cm speed Ar number
 133 This sets both
 134 .Cm ispeed
 135 and
 136 .Cm ospeed
 137 to
 138 .Ar number .
 139 .El
 140 .Ss Input Modes:
 141 This corresponds to the c_iflag in the termios structure.
 142 .Bl -tag -width Fl
 143 .It Cm brkint Pq Fl brkint
 144 Signal (do not signal)
 145 .Dv INTR
 146 on
 147 break.
 148 .It Cm icrnl Pq Fl icrnl
 149 Map (do not map)
 150 .Dv CR
 151 to
 152 .Dv NL
 153 on input.
 154 .It Cm ignbrk Pq Fl ignbrk
 155 Ignore (do not ignore) break on input.
 156 .It Cm igncr Pq Fl igncr
 157 Ignore (do not ignore)
 158 .Dv CR
 159 on input.
 160 .It Cm ignpar Pq Fl ignpar
 161 Ignore (do not ignore) characters with parity errors.
 162 .It Cm imaxbel Pq Fl imaxbel
 163 The system imposes a limit of
 164 .Dv MAX_INPUT
 165 (currently 255) characters in the input queue.  If
 166 .Cm imaxbel
 167 is set and the input queue limit has been reached,
 168 subsequent input causes the system to send an ASCII BEL
 169 character to the output queue (the terminal beeps at you).  Otherwise,
 170 if
 171 .Cm imaxbel
 172 is unset and the input queue is full, the next input character causes
 173 the entire input and output queues to be discarded.
 174 .It Cm inlcr Pq Fl inlcr
 175 Map (do not map)
 176 .Dv NL
 177 to
 178 .Dv CR
 179 on input.
 180 .It Cm inpck Pq Fl inpck
 181 Enable (disable) input parity checking.
 182 .It Cm istrip Pq Fl istrip
 183 Strip (do not strip) input characters to seven bits.
 184 .It Cm iutf8 Pq Fl iutf8
 185 Assume input characters are UTF-8 encoded.
 186 .It Cm ixany Pq Fl ixany
 187 Allow any character (allow only
 188 .Dv START )
 189 to restart output.
 190 .It Cm ixoff Pq Fl ixoff
 191 Request that the system send (not send)
 192 .Dv START/STOP
 193 characters when the input queue is nearly empty/full.
 194 .It Cm ixon Pq Fl ixon
 195 Enable (disable)
 196 .Dv START/STOP
 197 output control.
 198 Output from the system is stopped when the system receives
 199 .Dv STOP
 200 and started when the system receives
 201 .Dv START ,
 202 or if
 203 .Cm ixany
 204 is set, any character restarts output.
 205 .It Cm parmrk Pq Fl parmrk
 206 Mark (do not mark) characters with parity errors.
 207 .El
 208 .Ss Output Modes:
 209 This corresponds to the c_oflag of the termios structure.
 210 .Bl -tag -width Fl
 211 .It Cm bs0 bs1
 212 Select the style of delay for backspaces (e.g., set BSDLY to BS0).
 213 .It Cm cr0 cr1 cr2 cr3
 214 Select the style of delay for carriage returns (e.g., set CRDLY to CR0).
 215 .It Cm ff0 ff1
 216 Select the style of delay for form feeds (e.g., set FFDLY to FF0).
 217 .It Cm nl0 nl1
 218 Select the style of delay for newlines (e.g., set NLDLY to NL0).
 219 .It Cm ocrnl Pq Fl ocrnl
 220 Map (do not map) carriage return to newline on output.
 221 .It Cm ofdel Pq Fl odell
 222 Use DELs (NULs) as fill characters.
 223 .It Cm ofill Pq Fl ofill
 224 Use fill characters (use timing) for delays.
 225 .It Cm onlcr Pq Fl onlcr
 226 Map (do not map)
 227 .Dv NL
 228 to
 229 .Dv CR-NL
 230 on output.
 231 .It Cm onlret Pq Fl onlret
 232 On the terminal, NL performs (does not perform) the CR function.
 233 .It Cm onocr Pq Fl onocr
 234 Do not (do) output CRs at column zero.
 235 .It Cm opost Pq Fl opost
 236 Post-process output (do not post-process output;
 237 ignore all other output modes).
 238 .It Cm oxtabs Pq Fl oxtabs
 239 Expand (do not expand) tabs to spaces on output.
 240 .It Cm tab0 tab1 tab2 tab3
 241 Select the style of delay for horizontal tabs (e.g., set TABDLY to TAB0).
 242 .It Cm tabs Pq Fl tabs
 243 Same as
 244 .Cm tab0
 245 .Cm ( tab3 ) .
 246 .It Cm vt0 vt1
 247 Select the style of delay for vertical tabs (e.g., set VTDLY to VT0).
 248 .El
 249 .Ss Local Modes:
 250 .Pp
 251 Local mode flags (lflags) affect various and sundry characteristics
 252 of terminal processing.
 253 Historically the term "local" pertained to new job control features
 254 implemented by Jim Kulp on a
 255 .Tn Pdp 11/70
 256 at
 257 .Tn IIASA .
 258 Later, the driver ran on the first
 259 .Tn VAX
 260 at Evans Hall, UC Berkeley, where the job control details
 261 were greatly modified,
 262 but the structure definitions and names remained essentially unchanged.
 263 The second interpretation of the 'l' in lflag
 264 is ``line discipline flag'', which corresponds to the
 265 .Ar c_lflag
 266 of the
 267 .Ar termios
 268 structure.
 269 .Bl -tag -width Fl
 270 .It Cm altwerase Pq Fl altwerase
 271 Use (do not use) an alternate word erase algorithm when processing
 272 .Dv WERASE
 273 characters.
 274 This alternate algorithm considers sequences of
 275 alphanumeric/underscores as words.
 276 It also skips the first preceding character in its classification
 277 (as a convenience, since the one preceding character could have been
 278 erased with simply an
 279 .Dv ERASE
 280 character.)
 281 .It Cm echo Pq Fl echo
 282 Echo back (do not echo back) every character typed.
 283 .It Cm echoctl Pq Fl echoctl
 284 If
 285 .Cm echoctl
 286 is set, echo control characters as ^X.
 287 Otherwise, control characters echo as themselves.
 288 .It Cm echoe Pq Fl echoe
 289 The
 290 .Dv ERASE
 291 character shall (shall not) visually erase the last character
 292 in the current line from the display, if possible.
 293 .It Cm echok Pq Fl echok
 294 Echo (do not echo)
 295 .Dv NL
 296 after
 297 .Dv KILL
 298 character.
 299 .It Cm echoke Pq Fl echoke
 300 The
 301 .Dv KILL
 302 character shall (shall
 303 not) visually erase the
 304 current line from the
 305 display, if possible.
 306 .It Cm echonl Pq Fl echonl
 307 Echo (do not echo)
 308 .Dv NL ,
 309 even if echo is disabled.
 310 .It Cm echoprt Pq Fl echoprt
 311 For printing terminals.
 312 If set, echo erased characters backwards within ``\\'' and ``/''.
 313 Otherwise, disable this feature.
 314 .It Cm flusho Pq Fl flusho
 315 Indicates output is (is not) being discarded.
 316 .It Cm icanon Pq Fl icanon
 317 Enable (disable) canonical input
 318 .Pf ( Dv ERASE
 319 and
 320 .Dv KILL
 321 processing).
 322 .It Cm iexten Pq Fl iexten
 323 Enable (disable) any implementation-defined special control characters
 324 that are not currently controlled by
 325 .Cm icanon ,
 326 .Cm isig ,
 327 .Cm ixoff ,
 328 or
 329 .Cm ixon .
 330 .It Cm isig Pq Fl isig
 331 Enable (disable) the checking of characters
 332 against the special control characters
 333 .Dv INTR , QUIT ,
 334 and
 335 .Dv SUSP .
 336 .It Cm mdmbuf Pq Fl mdmbuf
 337 If set, flow control output based on condition of Carrier Detect.
 338 Otherwise, writes return an error if Carrier Detect is low
 339 (and Carrier is not being ignored with the
 340 .Dv CLOCAL
 341 flag.)
 342 .It Cm noflsh Pq Fl noflsh
 343 Disable (enable) flush after
 344 .Dv INTR , QUIT ,
 345 or
 346 .Dv SUSP .
 347 .It Cm pendin Pq Fl pendin
 348 Indicates input is (is not) pending
 349 after a switch from non-canonical to canonical mode
 350 and will be re-input when a read becomes pending or more input arrives.
 351 .It Cm tostop Pq Fl tostop
 352 Send (do not send)
 353 .Dv SIGTTOU
 354 for background output.
 355 This causes background jobs to stop if they attempt terminal output.
 356 .El
 357 .Ss Control Characters:
 358 .Bl -tag -width Fl
 359 .It Ar control-character Ar string
 360 Set
 361 .Ar control-character
 362 to
 363 .Ar string .
 364 If string is a single character,
 365 the control character is set to
 366 that character.
 367 If string is the
 368 two character sequence "^-" or the
 369 string "undef" the control character
 370 is disabled (i.e. set to
 371 .Pf { Dv _POSIX_VDISABLE Ns } . )
 372 .Pp
 373 Recognized control-characters:
 374 .Bd -ragged -offset indent
 375 .Bl -column character Subscript
 376 .It control-
 377 .It character Ta Subscript Ta Description
 378 .It _________ Ta _________ Ta _______________
 379 .It eof Ta Tn VEOF Ta EOF No character
 380 .It eol Ta Tn VEOL Ta EOL No character
 381 .It eol2 Ta Tn VEOL2 Ta EOL2 No character
 382 .It erase Ta Tn VERASE Ta ERASE No character
 383 .It erase2 Ta Tn VERASE2 Ta ERASE2 No character
 384 .It werase Ta Tn VWERASE Ta WERASE No character
 385 .It intr Ta Tn VINTR Ta INTR No character
 386 .It kill Ta Tn VKILL Ta KILL No character
 387 .It quit Ta Tn VQUIT Ta QUIT No character
 388 .It susp Ta Tn VSUSP Ta SUSP No character
 389 .It start Ta Tn VSTART Ta START No character
 390 .It stop Ta Tn VSTOP Ta STOP No character
 391 .It dsusp Ta Tn VDSUSP Ta DSUSP No character
 392 .It lnext Ta Tn VLNEXT Ta LNEXT No character
 393 .It reprint Ta Tn VREPRINT Ta REPRINT No character
 394 .It status Ta Tn VSTATUS Ta STATUS No character
 395 .El
 396 .Ed
 397 .It Cm min Ar number
 398 .It Cm time Ar number
 399 Set the value of min or time to number.
 400 .Dv MIN
 401 and
 402 .Dv TIME
 403 are used in Non-Canonical mode input processing (-icanon).
 404 .El
 405 .Ss Combination Modes:
 406 .Pp
 407 .Bl -tag -width Fl
 408 .It Ar saved settings
 409 Set the current terminal characteristics
 410 to the saved settings produced by the
 411 .Fl g
 412 option.
 413 .It Cm cols Ar number
 414 Same as
 415 .Cm columns .
 416 .It Cm columns Ar number
 417 The terminal size is recorded as having
 418 .Ar number
 419 columns.
 420 .It Cm crt Pq Fl crt
 421 Set (disable) all modes suitable for a CRT display device.
 422 .It Cm dec
 423 Set modes suitable for users of Digital Equipment Corporation systems
 424 .Dv ( ERASE ,
 425 .Dv KILL ,
 426 and
 427 .Dv INTR
 428 characters are set to ^?, ^U, and ^C;
 429 .Dv ixany
 430 is disabled, and
 431 .Dv crt
 432 is enabled.)
 433 .It Cm ek
 434 Reset
 435 .Dv ERASE ,
 436 .Dv ERASE2 ,
 437 and
 438 .Dv KILL
 439 characters
 440 back to system defaults.
 441 .It Fl  evenp
 442 Same as
 443 .Fl oddp
 444 and
 445 .Fl parity .
 446 .It Cm evenp
 447 Enable
 448 .Cm parenb
 449 and
 450 .Cm cs7 ;
 451 disable
 452 .Cm parodd .
 453 .It Cm extproc Pq Fl extproc
 454 If set, this flag indicates that some amount of terminal processing
 455 is being performed by either the terminal hardware
 456 or by the remote side connected to a pty.
 457 .It Cm kerninfo Pq Fl kerninfo
 458 Enable (disable) the system generated status line associated with
 459 processing a
 460 .Dv STATUS
 461 character (usually set to ^T).  The status line consists of the
 462 system load average, the current command name, its process ID, the
 463 event the process is waiting on (or the status of the process), the user
 464 and system times, percent cpu, and current memory usage.
 465 .It Cm \&nl Pq Fl \&nl
 466 Enable (disable)
 467 .Cm icrnl .
 468 In addition,
 469 .Fl nl
 470 unsets
 471 .Cm inlcr
 472 and
 473 .Cm igncr .
 474 .It Fl  oddp
 475 Same as
 476 .Fl evenp
 477 and
 478 .Fl parity .
 479 .It Cm oddp
 480 Enable
 481 .Cm parenb ,
 482 .Cm cs7 ,
 483 and
 484 .Cm parodd .
 485 .It Fl parity
 486 Disable
 487 .Cm parenb ;
 488 set
 489 .Cm cs8 .
 490 .It Cm parity
 491 Same as
 492 .Cm evenp .
 493 .It Cm raw Pq Fl raw
 494 If set, change the modes of the terminal
 495 so that no input or output processing is performed.
 496 If unset, change the modes of the terminal to some reasonable state
 497 that performs input and output processing.
 498 Note that since the terminal driver no longer has a single
 499 .Dv RAW
 500 bit, it is not possible to intuit what flags were set prior to setting
 501 .Cm raw .
 502 This means that unsetting
 503 .Cm raw
 504 may not put back all the setting that were previously in effect.
 505 To set the terminal into a raw state and then accurately restore it,
 506 the following shell code is recommended:
 507 .Bd -literal
 508 save_state=$(stty -g)
 509 stty raw
 510 \&...
 511 stty "$save_state"
 512 .Ed
 513 .It Cm rows Ar number
 514 The terminal size is recorded as having
 515 .Ar number
 516 rows.
 517 .It Cm sane
 518 Resets all modes to reasonable values for interactive terminal use.
 519 .It Cm size
 520 The size of the terminal is printed as two numbers on a single line,
 521 first rows, then columns.
 522 .It Cm tty
 523 Set the line discipline to the standard terminal line discipline
 524 .Dv TTYDISC .
 525 .El
 526 .Ss Compatibility Modes:
 527 .Pp
 528 These modes remain for compatibility with the previous version of
 529 the
 530 .Nm
 531 command.
 532 .Bl -tag -width Fl
 533 .It Cm all
 534 Reports all the terminal modes as with
 535 .Cm stty Fl a ,
 536 except that the control characters are printed in a columnar format.
 537 .It Cm brk Ar value
 538 Same as the control character
 539 .Cm eol .
 540 .It Cm cbreak
 541 If set, enables
 542 .Cm brkint , ixon , imaxbel , opost , isig , iexten ,
 543 and
 544 .Fl icanon .
 545 If unset, same as
 546 .Cm sane .
 547 .It Cm cooked
 548 Same as
 549 .Cm sane .
 550 .It Cm crtbs Pq Fl crtbs
 551 Same as
 552 .Cm echoe .
 553 .It Cm crterase Pq Fl crterase
 554 Same as
 555 .Cm echoe .
 556 .It Cm crtkill Pq Fl crtkill
 557 Same as
 558 .Cm echoke .
 559 .It Cm ctlecho Pq Fl ctlecho
 560 Same as
 561 .Cm echoctl .
 562 .It Cm decctlq Pq Fl decctlq
 563 The converse of
 564 .Cm ixany .
 565 .It Cm everything
 566 Same as
 567 .Cm all .
 568 .It Cm flush Ar value
 569 Same as the control character
 570 .Cm discard .
 571 .It Cm litout Pq Fl litout
 572 The converse of
 573 .Cm opost .
 574 .It Cm new
 575 Same as
 576 .Cm tty .
 577 .It Cm newcrt Pq Fl newcrt
 578 Same as
 579 .Cm crt .
 580 .It Cm old
 581 Same as
 582 .Cm tty .
 583 .It Cm pass8
 584 The converse of
 585 .Cm parity .
 586 .It Cm prterase Pq Fl prterase
 587 Same as
 588 .Cm echoprt .
 589 .It Cm rprnt Ar value
 590 Same as the control character
 591 .Cm reprint .
 592 .It Cm tabs Pq Fl tabs
 593 The converse of
 594 .Cm oxtabs .
 595 .It Cm tandem Pq Fl tandem
 596 Same as
 597 .Cm ixoff .
 598 .El
 599 .Sh DIAGNOSTICS
 600 .Ex -std
 601 .Sh LEGACY DESCRIPTION
 602 In legacy operation, the
 603 .Cm bs[01] ,
 604 .Cm cr[0-3] ,
 605 .Cm ff[01] ,
 606 .Cm nl[01] ,
 607 .Cm tab[0-3] ,
 608 and
 609 .Cm vt[01]
 610 control modes are not accepted, nor are
 611 .Cm ocrnl Pq Fl ocrnl ,
 612 .Cm ofdel Pq Fl ofdel ,
 613 .Cm ofill Pq Fl ofill ,
 614 .Cm onlret Pq Fl onlret ,
 615 and
 616 .Cm onocr Pq Fl onocr .
 617 .Pp
 618 For more information about legacy mode, see
 619 .Xr compat 5 .
 620 .Sh SEE ALSO
 621 .Xr termios 4 ,
 622 .Xr compat 5
 623 .Sh STANDARDS
 624 The
 625 .Nm
 626 utility is expected to be
 627 .St -p1003.2
 628 compatible.  The flags
 629 .Fl e
 630 and
 631 .Fl f
 632 are
 633 extensions to the standard.