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