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 .sp
  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 If the terminal is currently in exclusive mode,
 304 place a nonzero value in the location pointed to by
 305 .IR argp ;
 306 otherwise, place zero in
 307 .IR *argp
 308 (since Linux 3.8).
 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 Return the current packet mode setting in the integer pointed to by
 366 .IR argp
 367 (since Linux 3.8).
 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 Place the current lock state of the pseudoterminal slave device
 380 in the location pointed to by
 381 .IR argp
 382 (since Linux 3.8).
 383 .PP
 384 The BSD ioctls
 385 .BR TIOCSTOP ,
 386 .BR TIOCSTART ,
 387 .BR TIOCUCNTL ,
 388 .B TIOCREMOTE
 389 have not been implemented under Linux.
 390 .SS Modem control
 391 .TP
 392 .BI "TIOCMGET   int *" argp
 393 Get the status of modem bits.
 394 .TP
 395 .BI "TIOCMSET   const int *" argp
 396 Set the status of modem bits.
 397 .TP
 398 .BI "TIOCMBIC   const int *" argp
 399 Clear the indicated modem bits.
 400 .TP
 401 .BI "TIOCMBIS   const int *" argp
 402 Set the indicated modem bits.
 403 .LP
 404 The following bits are used by the above ioctls:
 405
 406 .nf
 407 TIOCM_LE        DSR (data set ready/line enable)
 408 TIOCM_DTR       DTR (data terminal ready)
 409 TIOCM_RTS       RTS (request to send)
 410 TIOCM_ST        Secondary TXD (transmit)
 411 TIOCM_SR        Secondary RXD (receive)
 412 TIOCM_CTS       CTS (clear to send)
 413 TIOCM_CAR       DCD (data carrier detect)
 414 TIOCM_CD         see TIOCM_CAR
 415 TIOCM_RNG       RNG (ring)
 416 TIOCM_RI         see TIOCM_RNG
 417 TIOCM_DSR       DSR (data set ready)
 418 .fi
 419 .TP
 420 .BI "TIOCMIWAIT int " arg
 421 Wait for any of the 4 modem bits (DCD, RI, DSR, CTS) to change.
 422 The bits of interest are specified as a bit mask in
 423 .IR arg ,
 424 by ORing together any of the bit values,
 425 .BR TIOCM_RNG ,
 426 .BR TIOCM_DSR ,
 427 .BR TIOCM_CD ,
 428 and
 429 .BR TIOCM_CTS .
 430 The caller should use
 431 .B TIOCGICOUNT
 432 to see which bit has changed.
 433 .TP
 434 .BI "TIOCGICOUNT        struct serial_icounter_struct *" argp
 435 Get counts of input serial line interrupts (DCD, RI, DSR, CTS).
 436 The counts are written to the
 437 .I serial_icounter_struct
 438 structure pointed to by
 439 .IR argp .
 440
 441 Note: both 1->0 and 0->1 transitions are counted, except for
 442 RI, where only 0->1 transitions are counted.
 443 .SS Marking a line as local
 444 .TP
 445 .BI "TIOCGSOFTCAR       int *" argp
 446 ("Get software carrier flag")
 447 Get the status of the CLOCAL flag in the c_cflag field of the
 448 .I termios
 449 structure.
 450 .TP
 451 .BI "TIOCSSOFTCAR       const int *" argp
 452 ("Set software carrier flag")
 453 Set the CLOCAL flag in the
 454 .I termios
 455 structure when
 456 .RI * argp
 457 is nonzero, and clear it otherwise.
 458 .LP
 459 If the
 460 .B CLOCAL
 461 flag for a line is off, the hardware carrier detect (DCD)
 462 signal is significant, and an
 463 .BR open (2)
 464 of the corresponding terminal will block until DCD is asserted,
 465 unless the
 466 .B O_NONBLOCK
 467 flag is given.
 468 If
 469 .B CLOCAL
 470 is set, the line behaves as if DCD is always asserted.
 471 The software carrier flag is usually turned on for local devices,
 472 and is off for lines with modems.
 473 .SS Linux-specific
 474 For the
 475 .B TIOCLINUX
 476 ioctl, see
 477 .BR ioctl_console (2).
 478 .SS Kernel debugging
 479 .B "#include <linux/tty.h>"
 480 .TP
 481 .BI "TIOCTTYGSTRUCT     struct tty_struct *" argp
 482 Get the
 483 .I tty_struct
 484 corresponding to
 485 .IR fd .
 486 This command was removed in Linux 2.5.67.
 487 .\"     commit b3506a09d15dc5aee6d4bb88d759b157016e1864
 488 .\"     Author: Andries E. Brouwer <andries.brouwer@cwi.nl>
 489 .\"     Date:   Tue Apr 1 04:42:46 2003 -0800
 490 .\"
 491 .\"     [PATCH] kill TIOCTTYGSTRUCT
 492 .\"
 493 .\"     Only used for (dubious) debugging purposes, and exposes
 494 .\"     internal kernel state.
 495 .\"
 496 .\" .SS Serial info
 497 .\" .BR "#include <linux/serial.h>"
 498 .\" .sp
 499 .\" .TP
 500 .\" .BI "TIOCGSERIAL    struct serial_struct *" argp
 501 .\" Get serial info.
 502 .\" .TP
 503 .\" .BI "TIOCSSERIAL    const struct serial_struct *" argp
 504 .\" Set serial info.
 505 .SH RETURN VALUE
 506 The
 507 .BR ioctl (2)
 508 system call returns 0 on success.
 509 On error, it returns \-1 and sets
 510 .I errno
 511 appropriately.
 512 .SH ERRORS
 513 .TP
 514 .B EINVAL
 515 Invalid command parameter.
 516 .TP
 517 .B ENOIOCTLCMD
 518 Unknown command.
 519 .TP
 520 .B ENOTTY
 521 Inappropriate
 522 .IR fd .
 523 .TP
 524 .B EPERM
 525 Insufficient permission.
 526 .SH EXAMPLE
 527 Check the condition of DTR on the serial port.
 528
 529 .nf
 530 #include <termios.h>
 531 #include <fcntl.h>
 532 #include <sys/ioctl.h>
 533
 534 int
 535 main(void)
 536 {
 537     int fd, serial;
 538
 539     fd = open("/dev/ttyS0", O_RDONLY);
 540     ioctl(fd, TIOCMGET, &serial);
 541     if (serial & TIOCM_DTR)
 542         puts("TIOCM_DTR is set");
 543     else
 544         puts("TIOCM_DTR is not set");
 545     close(fd);
 546 }
 547 .fi
 548 .SH SEE ALSO
 549 .BR ldattach (1),
 550 .BR ioctl (2),
 551 .BR ioctl_console (2),
 552 .BR termios (3),
 553 .BR pty (7)
 554 .\"
 555 .\" FIONBIO                     const int *
 556 .\" FIONCLEX                    void
 557 .\" FIOCLEX                     void
 558 .\" FIOASYNC                    const int *
 559 .\" from serial.c:
 560 .\" TIOCSERCONFIG               void
 561 .\" TIOCSERGWILD                int *
 562 .\" TIOCSERSWILD                const int *
 563 .\" TIOCSERGSTRUCT              struct async_struct *
 564 .\" TIOCSERGETLSR               int *
 565 .\" TIOCSERGETMULTI             struct serial_multiport_struct *
 566 .\" TIOCSERSETMULTI             const struct serial_multiport_struct *
 567 .\" TIOCGSERIAL, TIOCSSERIAL (see above)