man2/ioctl_tty.2

   1 .\" Copyright 2002 Walter Harms <walter.harms@informatik.uni-oldenburg.de>
   2 .\" and Andries Brouwer <aeb@cwi.nl>.
   3 .\"
   4 .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
   5 .\" Distributed under GPL
   6 .\" %%%LICENSE_END
   7 .\"
   8 .TH IOCTL_TTY 2 2021-03-22 "Linux" "Linux Programmer's Manual"
   9 .SH NAME
  10 ioctl_tty \- ioctls for terminals and serial lines
  11 .SH SYNOPSIS
  12 .nf
  13 .B #include <sys/ioctl.h>
  14 .BR "#include <termios.h>" "      /* Definition of " CLOCAL ", and"
  15 .BR    "                             TC*" { FLUSH , ON , OFF "} constants */"
  16 .PP
  17 .BI "int ioctl(int " fd ", int " cmd ", ...);"
  18 .fi
  19 .SH DESCRIPTION
  20 The
  21 .BR ioctl (2)
  22 call for terminals and serial ports accepts many possible command arguments.
  23 Most require a third argument, of varying type, here called
  24 .I argp
  25 or
  26 .IR arg .
  27 .PP
  28 Use of
  29 .BR ioctl ()
  30 makes for nonportable programs.
  31 Use the POSIX interface described in
  32 .BR termios (3)
  33 whenever possible.
  34 .SS Get and set terminal attributes
  35 .TP
  36 .B TCGETS
  37 Argument:
  38 .BI "struct termios *" argp
  39 .IP
  40 Equivalent to
  41 .IR "tcgetattr(fd, argp)" .
  42 .IP
  43 Get the current serial port settings.
  44 .TP
  45 .B TCSETS
  46 Argument:
  47 .BI "const struct termios *" argp
  48 .IP
  49 Equivalent to
  50 .IR "tcsetattr(fd, TCSANOW, argp)" .
  51 .IP
  52 Set the current serial port settings.
  53 .TP
  54 .B TCSETSW
  55 Argument:
  56 .BI "const struct termios *" argp
  57 .IP
  58 Equivalent to
  59 .IR "tcsetattr(fd, TCSADRAIN, argp)" .
  60 .IP
  61 Allow the output buffer to drain, and
  62 set the current serial port settings.
  63 .TP
  64 .B TCSETSF
  65 Argument:
  66 .BI "const struct termios *" argp
  67 .IP
  68 Equivalent to
  69 .IR "tcsetattr(fd, TCSAFLUSH, argp)" .
  70 .IP
  71 Allow the output buffer to drain, discard pending input, and
  72 set the current serial port settings.
  73 .PP
  74 The following four ioctls are just like
  75 .BR TCGETS ,
  76 .BR TCSETS ,
  77 .BR TCSETSW ,
  78 .BR TCSETSF ,
  79 except that they take a
  80 .I "struct termio\ *"
  81 instead of a
  82 .IR "struct termios\ *" .
  83 .RS
  84 .TS
  85 lb l.
  86 TCGETA  \fBstruct termio *\fPargp
  87 TCSETA  \fBconst struct termio *\fPargp
  88 TCSETAW \fBconst struct termio *\fPargp
  89 TCSETAF \fBconst struct termio *\fPargp
  90 .TE
  91 .RE
  92 .SS Locking the termios structure
  93 The
  94 .I termios
  95 structure of a terminal can be locked.
  96 The lock is itself a
  97 .I termios
  98 structure, with nonzero bits or fields indicating a
  99 locked value.
 100 .TP
 101 .B TIOCGLCKTRMIOS
 102 Argument:
 103 .BI "struct termios *" argp
 104 .IP
 105 Gets the locking status of the
 106 .I termios
 107 structure of the terminal.
 108 .TP
 109 .B TIOCSLCKTRMIOS
 110 Argument:
 111 .BI "const struct termios *" argp
 112 .IP
 113 Sets the locking status of the
 114 .I termios
 115 structure of the terminal.
 116 Only a process with the
 117 .BR CAP_SYS_ADMIN
 118 capability can do this.
 119 .SS Get and set window size
 120 Window sizes are kept in the kernel, but not used by the kernel
 121 (except in the case of virtual consoles, where the kernel will
 122 update the window size when the size of the virtual console changes,
 123 for example, by loading a new font).
 124 .TP
 125 .B TIOCGWINSZ
 126 Argument:
 127 .BI "struct winsize *" argp
 128 .IP
 129 Get window size.
 130 .TP
 131 .B TIOCSWINSZ
 132 Argument:
 133 .BI "const struct winsize *" argp
 134 .IP
 135 Set window size.
 136 .PP
 137 The struct used by these ioctls is defined as
 138 .PP
 139 .in +4n
 140 .EX
 141 struct winsize {
 142     unsigned short ws_row;
 143     unsigned short ws_col;
 144     unsigned short ws_xpixel;   /* unused */
 145     unsigned short ws_ypixel;   /* unused */
 146 };
 147 .EE
 148 .in
 149 .PP
 150 When the window size changes, a
 151 .B SIGWINCH
 152 signal is sent to the
 153 foreground process group.
 154 .SS Sending a break
 155 .TP
 156 .B TCSBRK
 157 Argument:
 158 .BI "int " arg
 159 .IP
 160 Equivalent to
 161 .IR "tcsendbreak(fd, arg)" .
 162 .IP
 163 If the terminal is using asynchronous serial data transmission, and
 164 .I arg
 165 is zero, then send a break (a stream of zero bits) for between
 166 0.25 and 0.5 seconds.
 167 If the terminal is not using asynchronous
 168 serial data transmission, then either a break is sent, or the function
 169 returns without doing anything.
 170 When
 171 .I arg
 172 is nonzero, nobody knows what will happen.
 173 .IP
 174 (SVr4, UnixWare, Solaris, Linux treat
 175 .I "tcsendbreak(fd,arg)"
 176 with nonzero
 177 .I arg
 178 like
 179 .IR "tcdrain(fd)" .
 180 SunOS treats
 181 .I arg
 182 as a multiplier, and sends a stream of bits
 183 .I arg
 184 times as long as done for zero
 185 .IR arg .
 186 DG/UX and AIX treat
 187 .I arg
 188 (when nonzero) as a time interval measured in milliseconds.
 189 HP-UX ignores
 190 .IR arg .)
 191 .TP
 192 .B TCSBRKP
 193 Argument:
 194 .BI "int " arg
 195 .IP
 196 So-called "POSIX version" of
 197 .BR TCSBRK .
 198 It treats nonzero
 199 .I arg
 200 as a time interval measured in deciseconds, and does nothing
 201 when the driver does not support breaks.
 202 .TP
 203 .B TIOCSBRK
 204 Argument:
 205 .BI "void"
 206 .IP
 207 Turn break on, that is, start sending zero bits.
 208 .TP
 209 .B TIOCCBRK
 210 Argument:
 211 .BI "void"
 212 .IP
 213 Turn break off, that is, stop sending zero bits.
 214 .SS Software flow control
 215 .TP
 216 .B TCXONC
 217 Argument:
 218 .BI "int " arg
 219 .IP
 220 Equivalent to
 221 .IR "tcflow(fd, arg)" .
 222 .IP
 223 See
 224 .BR tcflow (3)
 225 for the argument values
 226 .BR TCOOFF ,
 227 .BR TCOON ,
 228 .BR TCIOFF ,
 229 .BR TCION .
 230 .SS Buffer count and flushing
 231 .TP
 232 .BI FIONREAD
 233 Argument:
 234 .BI "int *" argp
 235 .IP
 236 Get the number of bytes in the input buffer.
 237 .TP
 238 .B TIOCINQ
 239 Argument:
 240 .BI "int *" argp
 241 .IP
 242 Same as
 243 .BR FIONREAD .
 244 .TP
 245 .B TIOCOUTQ
 246 Argument:
 247 .BI "int *" argp
 248 .IP
 249 Get the number of bytes in the output buffer.
 250 .TP
 251 .B TCFLSH
 252 Argument:
 253 .BI "int " arg
 254 .IP
 255 Equivalent to
 256 .IR "tcflush(fd, arg)" .
 257 .IP
 258 See
 259 .BR tcflush (3)
 260 for the argument values
 261 .BR TCIFLUSH ,
 262 .BR TCOFLUSH ,
 263 .BR TCIOFLUSH .
 264 .SS Faking input
 265 .TP
 266 .B TIOCSTI
 267 Argument:
 268 .BI "const char *" argp
 269 .IP
 270 Insert the given byte in the input queue.
 271 .SS Redirecting console output
 272 .TP
 273 .B TIOCCONS
 274 Argument:
 275 .BI "void"
 276 .IP
 277 Redirect output that would have gone to
 278 .I /dev/console
 279 or
 280 .I /dev/tty0
 281 to the given terminal.
 282 If that was a pseudoterminal master, send it to the slave.
 283 In Linux before version 2.6.10,
 284 anybody can do this as long as the output was not redirected yet;
 285 since version 2.6.10, only a process with the
 286 .BR CAP_SYS_ADMIN
 287 capability may do this.
 288 If output was redirected already, then
 289 .B EBUSY
 290 is returned,
 291 but redirection can be stopped by using this ioctl with
 292 .I fd
 293 pointing at
 294 .I /dev/console
 295 or
 296 .IR /dev/tty0 .
 297 .SS Controlling terminal
 298 .TP
 299 .B TIOCSCTTY
 300 Argument:
 301 .BI "int " arg
 302 .IP
 303 Make the given terminal the controlling terminal of the calling process.
 304 The calling process must be a session leader and not have a
 305 controlling terminal already.
 306 For this case,
 307 .I arg
 308 should be specified as zero.
 309 .IP
 310 If this terminal is already the controlling terminal
 311 of a different session group, then the ioctl fails with
 312 .BR EPERM ,
 313 unless the caller has the
 314 .BR CAP_SYS_ADMIN
 315 capability and
 316 .I arg
 317 equals 1, in which case the terminal is stolen, and all processes that had
 318 it as controlling terminal lose it.
 319 .TP
 320 .B TIOCNOTTY
 321 Argument:
 322 .BI "void"
 323 .IP
 324 If the given terminal was the controlling terminal of the calling process,
 325 give up this controlling terminal.
 326 If the process was session leader,
 327 then send
 328 .B SIGHUP
 329 and
 330 .B SIGCONT
 331 to the foreground process group
 332 and all processes in the current session lose their controlling terminal.
 333 .SS Process group and session ID
 334 .TP
 335 .B TIOCGPGRP
 336 Argument:
 337 .BI "pid_t *" argp
 338 .IP
 339 When successful, equivalent to
 340 .IR "*argp = tcgetpgrp(fd)" .
 341 .IP
 342 Get the process group ID of the foreground process group on this terminal.
 343 .TP
 344 .B TIOCSPGRP
 345 Argument:
 346 .BI "const pid_t *" argp
 347 .IP
 348 Equivalent to
 349 .IR "tcsetpgrp(fd, *argp)" .
 350 .IP
 351 Set the foreground process group ID of this terminal.
 352 .TP
 353 .B TIOCGSID
 354 Argument:
 355 .BI "pid_t *" argp
 356 .IP
 357 Get the session ID of the given terminal.
 358 This fails with the error
 359 .B ENOTTY
 360 if the terminal is not a master pseudoterminal
 361 and not our controlling terminal.
 362 Strange.
 363 .SS Exclusive mode
 364 .TP
 365 .B TIOCEXCL
 366 Argument:
 367 .BI "void"
 368 .IP
 369 Put the terminal into exclusive mode.
 370 No further
 371 .BR open (2)
 372 operations on the terminal are permitted.
 373 (They fail with
 374 .BR EBUSY ,
 375 except for a process with the
 376 .BR CAP_SYS_ADMIN
 377 capability.)
 378 .TP
 379 .B TIOCGEXCL
 380 Argument:
 381 .BI "int *" argp
 382 .IP
 383 (since Linux 3.8)
 384 If the terminal is currently in exclusive mode,
 385 place a nonzero value in the location pointed to by
 386 .IR argp ;
 387 otherwise, place zero in
 388 .IR *argp .
 389 .TP
 390 .B TIOCNXCL
 391 Argument:
 392 .BI "void"
 393 .IP
 394 Disable exclusive mode.
 395 .SS Line discipline
 396 .TP
 397 .B TIOCGETD
 398 Argument:
 399 .BI "int *" argp
 400 .IP
 401 Get the line discipline of the terminal.
 402 .TP
 403 .B TIOCSETD
 404 Argument:
 405 .BI "const int *" argp
 406 .IP
 407 Set the line discipline of the terminal.
 408 .SS Pseudoterminal ioctls
 409 .TP
 410 .B TIOCPKT
 411 Argument:
 412 .BI "const int *" argp
 413 .IP
 414 Enable (when
 415 .RI * argp
 416 is nonzero) or disable packet mode.
 417 Can be applied to the master side of a pseudoterminal only (and will return
 418 .B ENOTTY
 419 otherwise).
 420 In packet mode, each subsequent
 421 .BR read (2)
 422 will return a packet that either contains a single nonzero control byte,
 423 or has a single byte containing zero (\(aq\e0\(aq) followed by data
 424 written on the slave side of the pseudoterminal.
 425 If the first byte is not
 426 .B TIOCPKT_DATA
 427 (0), it is an OR of one
 428 or more of the following bits:
 429 .IP
 430 .ad l
 431 .TS
 432 lb l.
 433 TIOCPKT_FLUSHREAD       T{
 434 The read queue for the terminal is flushed.
 435 T}
 436 TIOCPKT_FLUSHWRITE      T{
 437 The write queue for the terminal is flushed.
 438 T}
 439 TIOCPKT_STOP    T{
 440 Output to the terminal is stopped.
 441 T}
 442 TIOCPKT_START   T{
 443 Output to the terminal is restarted.
 444 T}
 445 TIOCPKT_DOSTOP  T{
 446 The start and stop characters are \fB\(haS\fP/\fB\(haQ\fP.
 447 T}
 448 TIOCPKT_NOSTOP  T{
 449 The start and stop characters are not \fB\(haS\fP/\fB\(haQ\fP.
 450 T}
 451 .TE
 452 .ad
 453 .IP
 454 While packet mode is in use, the presence
 455 of control status information to be read
 456 from the master side may be detected by a
 457 .BR select (2)
 458 for exceptional conditions or a
 459 .BR poll (2)
 460 for the
 461 .B POLLPRI
 462 event.
 463 .IP
 464 This mode is used by
 465 .BR rlogin (1)
 466 and
 467 .BR rlogind (8)
 468 to implement a remote-echoed,
 469 locally \fB\(haS\fP/\fB\(haQ\fP flow-controlled remote login.
 470 .TP
 471 .B TIOCGPKT
 472 Argument:
 473 .BI "const int *" argp
 474 .IP
 475 (since Linux 3.8)
 476 Return the current packet mode setting in the integer pointed to by
 477 .IR argp .
 478 .TP
 479 .B TIOCSPTLCK
 480 Argument:
 481 .BI "int *" argp
 482 .IP
 483 Set (if
 484 .IR *argp
 485 is nonzero) or remove (if
 486 .IR *argp
 487 is zero) the lock on the pseudoterminal slave device.
 488 (See also
 489 .BR unlockpt (3).)
 490 .TP
 491 .B TIOCGPTLCK
 492 Argument:
 493 .BI "int *" argp
 494 .IP
 495 (since Linux 3.8)
 496 Place the current lock state of the pseudoterminal slave device
 497 in the location pointed to by
 498 .IR argp .
 499 .TP
 500 .B TIOCGPTPEER
 501 Argument:
 502 .BI "int " flags
 503 .IP
 504 .\" commit 54ebbfb1603415d9953c150535850d30609ef077
 505 (since Linux 4.13)
 506 Given a file descriptor in
 507 .I fd
 508 that refers to a pseudoterminal master,
 509 open (with the given
 510 .BR open (2)-style
 511 .IR flags )
 512 and return a new file descriptor that refers to the peer
 513 pseudoterminal slave device.
 514 This operation can be performed
 515 regardless of whether the pathname of the slave device
 516 is accessible through the calling process's mount namespace.
 517 .IP
 518 Security-conscious programs interacting with namespaces may wish to use this
 519 operation rather than
 520 .BR open (2)
 521 with the pathname returned by
 522 .BR ptsname (3),
 523 and similar library functions that have insecure APIs.
 524 (For example, confusion can occur in some cases using
 525 .BR ptsname (3)
 526 with a pathname where a devpts filesystem
 527 has been mounted in a different mount namespace.)
 528 .PP
 529 The BSD ioctls
 530 .BR TIOCSTOP ,
 531 .BR TIOCSTART ,
 532 .BR TIOCUCNTL ,
 533 .B TIOCREMOTE
 534 have not been implemented under Linux.
 535 .SS Modem control
 536 .TP
 537 .B TIOCMGET
 538 Argument:
 539 .BI "int *" argp
 540 .IP
 541 Get the status of modem bits.
 542 .TP
 543 .B TIOCMSET
 544 Argument:
 545 .BI "const int *" argp
 546 .IP
 547 Set the status of modem bits.
 548 .TP
 549 .B TIOCMBIC
 550 Argument:
 551 .BI "const int *" argp
 552 .IP
 553 Clear the indicated modem bits.
 554 .TP
 555 .B TIOCMBIS
 556 Argument:
 557 .BI "const int *" argp
 558 .IP
 559 Set the indicated modem bits.
 560 .PP
 561 The following bits are used by the above ioctls:
 562 .PP
 563 .TS
 564 lb l.
 565 TIOCM_LE        DSR (data set ready/line enable)
 566 TIOCM_DTR       DTR (data terminal ready)
 567 TIOCM_RTS       RTS (request to send)
 568 TIOCM_ST        Secondary TXD (transmit)
 569 TIOCM_SR        Secondary RXD (receive)
 570 TIOCM_CTS       CTS (clear to send)
 571 TIOCM_CAR       DCD (data carrier detect)
 572 TIOCM_CD        see TIOCM_CAR
 573 TIOCM_RNG       RNG (ring)
 574 TIOCM_RI        see TIOCM_RNG
 575 TIOCM_DSR       DSR (data set ready)
 576 .TE
 577 .TP
 578 .B TIOCMIWAIT
 579 Argument:
 580 .BI "int " arg
 581 .IP
 582 Wait for any of the 4 modem bits (DCD, RI, DSR, CTS) to change.
 583 The bits of interest are specified as a bit mask in
 584 .IR arg ,
 585 by ORing together any of the bit values,
 586 .BR TIOCM_RNG ,
 587 .BR TIOCM_DSR ,
 588 .BR TIOCM_CD ,
 589 and
 590 .BR TIOCM_CTS .
 591 The caller should use
 592 .B TIOCGICOUNT
 593 to see which bit has changed.
 594 .TP
 595 .B TIOCGICOUNT
 596 Argument:
 597 .BI "struct serial_icounter_struct *" argp
 598 .IP
 599 Get counts of input serial line interrupts (DCD, RI, DSR, CTS).
 600 The counts are written to the
 601 .I serial_icounter_struct
 602 structure pointed to by
 603 .IR argp .
 604 .IP
 605 Note: both 1->0 and 0->1 transitions are counted, except for
 606 RI, where only 0->1 transitions are counted.
 607 .SS Marking a line as local
 608 .TP
 609 .B TIOCGSOFTCAR
 610 Argument:
 611 .BI "int *" argp
 612 .IP
 613 ("Get software carrier flag")
 614 Get the status of the CLOCAL flag in the c_cflag field of the
 615 .I termios
 616 structure.
 617 .TP
 618 .B TIOCSSOFTCAR
 619 Argument:
 620 .BI "const int *" argp
 621 .IP
 622 ("Set software carrier flag")
 623 Set the CLOCAL flag in the
 624 .I termios
 625 structure when
 626 .RI * argp
 627 is nonzero, and clear it otherwise.
 628 .PP
 629 If the
 630 .B CLOCAL
 631 flag for a line is off, the hardware carrier detect (DCD)
 632 signal is significant, and an
 633 .BR open (2)
 634 of the corresponding terminal will block until DCD is asserted,
 635 unless the
 636 .B O_NONBLOCK
 637 flag is given.
 638 If
 639 .B CLOCAL
 640 is set, the line behaves as if DCD is always asserted.
 641 The software carrier flag is usually turned on for local devices,
 642 and is off for lines with modems.
 643 .SS Linux-specific
 644 For the
 645 .B TIOCLINUX
 646 ioctl, see
 647 .BR ioctl_console (2).
 648 .SS Kernel debugging
 649 .B "#include <linux/tty.h>"
 650 .TP
 651 .B TIOCTTYGSTRUCT
 652 Argument:
 653 .BI "struct tty_struct *" argp
 654 .IP
 655 Get the
 656 .I tty_struct
 657 corresponding to
 658 .IR fd .
 659 This command was removed in Linux 2.5.67.
 660 .\"     commit b3506a09d15dc5aee6d4bb88d759b157016e1864
 661 .\"     Author: Andries E. Brouwer <andries.brouwer@cwi.nl>
 662 .\"     Date:   Tue Apr 1 04:42:46 2003 -0800
 663 .\"
 664 .\"     [PATCH] kill TIOCTTYGSTRUCT
 665 .\"
 666 .\"     Only used for (dubious) debugging purposes, and exposes
 667 .\"     internal kernel state.
 668 .\"
 669 .\" .SS Serial info
 670 .\" .BR "#include <linux/serial.h>"
 671 .\" .PP
 672 .\" .TP
 673 .\" .BI "TIOCGSERIAL    struct serial_struct *" argp
 674 .\" Get serial info.
 675 .\" .TP
 676 .\" .BI "TIOCSSERIAL    const struct serial_struct *" argp
 677 .\" Set serial info.
 678 .SH RETURN VALUE
 679 The
 680 .BR ioctl (2)
 681 system call returns 0 on success.
 682 On error, it returns \-1 and sets
 683 .I errno
 684 to indicate the error.
 685 .SH ERRORS
 686 .TP
 687 .B EINVAL
 688 Invalid command parameter.
 689 .TP
 690 .B ENOIOCTLCMD
 691 Unknown command.
 692 .TP
 693 .B ENOTTY
 694 Inappropriate
 695 .IR fd .
 696 .TP
 697 .B EPERM
 698 Insufficient permission.
 699 .SH EXAMPLES
 700 Check the condition of DTR on the serial port.
 701 .PP
 702 .EX
 703 #include <termios.h>
 704 #include <fcntl.h>
 705 #include <sys/ioctl.h>
 706
 707 int
 708 main(void)
 709 {
 710     int fd, serial;
 711
 712     fd = open("/dev/ttyS0", O_RDONLY);
 713     ioctl(fd, TIOCMGET, &serial);
 714     if (serial & TIOCM_DTR)
 715         puts("TIOCM_DTR is set");
 716     else
 717         puts("TIOCM_DTR is not set");
 718     close(fd);
 719 }
 720 .EE
 721 .SH SEE ALSO
 722 .BR ldattach (1),
 723 .BR ioctl (2),
 724 .BR ioctl_console (2),
 725 .BR termios (3),
 726 .BR pty (7)
 727 .\"
 728 .\" FIONBIO                     const int *
 729 .\" FIONCLEX                    void
 730 .\" FIOCLEX                     void
 731 .\" FIOASYNC                    const int *
 732 .\" from serial.c:
 733 .\" TIOCSERCONFIG               void
 734 .\" TIOCSERGWILD                int *
 735 .\" TIOCSERSWILD                const int *
 736 .\" TIOCSERGSTRUCT              struct async_struct *
 737 .\" TIOCSERGETLSR               int *
 738 .\" TIOCSERGETMULTI             struct serial_multiport_struct *
 739 .\" TIOCSERSETMULTI             const struct serial_multiport_struct *
 740 .\" TIOCGSERIAL, TIOCSSERIAL (see above)