original/man4/tty_ioctl.4

   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 TTY_IOCTL 4 2013-11-12 "Linux" "Linux Programmer's Manual"
   9 .SH NAME
  10 tty_ioctl \- 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 .B "TIOCNXCL    void"
 303 Disable exclusive mode.
 304 .SS Line discipline
 305 .TP
 306 .BI "TIOCGETD   int *" argp
 307 Get the line discipline of the terminal.
 308 .TP
 309 .BI "TIOCSETD   const int *" argp
 310 Set the line discipline of the terminal.
 311 .SS Pseudoterminal ioctls
 312 .TP
 313 .BI "TIOCPKT    const int *" argp
 314 Enable (when
 315 .RI * argp
 316 is nonzero) or disable packet mode.
 317 Can be applied to the master side of a pseudoterminal only (and will return
 318 .B ENOTTY
 319 otherwise).
 320 In packet mode, each subsequent
 321 .BR read (2)
 322 will return a packet that either contains a single nonzero control byte,
 323 or has a single byte containing zero (\(aq\0\(aq) followed by data
 324 written on the slave side of the pseudoterminal.
 325 If the first byte is not
 326 .B TIOCPKT_DATA
 327 (0), it is an OR of one
 328 or more of the following bits:
 329
 330 .nf
 331 TIOCPKT_FLUSHREAD   The read queue for the terminal is flushed.
 332 TIOCPKT_FLUSHWRITE  The write queue for the terminal is flushed.
 333 TIOCPKT_STOP        Output to the terminal is stopped.
 334 TIOCPKT_START       Output to the terminal is restarted.
 335 TIOCPKT_DOSTOP      The start and stop characters are \fB^S\fP/\fB^Q\fP.
 336 TIOCPKT_NOSTOP      The start and stop characters are not \fB^S\fP/\fB^Q\fP.
 337 .fi
 338
 339 While this mode is in use, the presence
 340 of control status information to be read
 341 from the master side may be detected by a
 342 .BR select (2)
 343 for exceptional conditions.
 344
 345 This mode is used by
 346 .BR rlogin (1)
 347 and
 348 .BR rlogind (8)
 349 to implement a remote-echoed,
 350 locally \fB^S\fP/\fB^Q\fP flow-controlled remote login.
 351
 352 The BSD ioctls
 353 .BR TIOCSTOP ,
 354 .BR TIOCSTART ,
 355 .BR TIOCUCNTL ,
 356 .B TIOCREMOTE
 357 have not been implemented under Linux.
 358 .SS Modem control
 359 .TP
 360 .BI "TIOCMGET   int *" argp
 361 get the status of modem bits.
 362 .TP
 363 .BI "TIOCMSET   const int *" argp
 364 set the status of modem bits.
 365 .TP
 366 .BI "TIOCMBIC   const int *" argp
 367 clear the indicated modem bits.
 368 .TP
 369 .BI "TIOCMBIS   const int *" argp
 370 set the indicated modem bits.
 371 .LP
 372 Bits used by these four ioctls:
 373
 374 .nf
 375 TIOCM_LE        DSR (data set ready/line enable)
 376 TIOCM_DTR       DTR (data terminal ready)
 377 TIOCM_RTS       RTS (request to send)
 378 TIOCM_ST        Secondary TXD (transmit)
 379 TIOCM_SR        Secondary RXD (receive)
 380 TIOCM_CTS       CTS (clear to send)
 381 TIOCM_CAR       DCD (data carrier detect)
 382 TIOCM_CD         see TIOCM_CAR
 383 TIOCM_RNG       RNG (ring)
 384 TIOCM_RI         see TIOCM_RNG
 385 TIOCM_DSR       DSR (data set ready)
 386 .fi
 387 .SS Marking a line as local
 388 .TP
 389 .BI "TIOCGSOFTCAR       int *" argp
 390 ("Get software carrier flag")
 391 Get the status of the CLOCAL flag in the c_cflag field of the
 392 .I termios
 393 structure.
 394 .TP
 395 .BI "TIOCSSOFTCAR       const int *" argp
 396 ("Set software carrier flag")
 397 Set the CLOCAL flag in the
 398 .I termios
 399 structure when
 400 .RI * argp
 401 is nonzero, and clear it otherwise.
 402 .LP
 403 If the
 404 .B CLOCAL
 405 flag for a line is off, the hardware carrier detect (DCD)
 406 signal is significant, and an
 407 .BR open (2)
 408 of the corresponding terminal will block until DCD is asserted,
 409 unless the
 410 .B O_NONBLOCK
 411 flag is given.
 412 If
 413 .B CLOCAL
 414 is set, the line behaves as if DCD is always asserted.
 415 The software carrier flag is usually turned on for local devices,
 416 and is off for lines with modems.
 417 .SS Linux-specific
 418 For the
 419 .B TIOCLINUX
 420 ioctl, see
 421 .BR console_ioctl (4).
 422 .SS Kernel debugging
 423 .B "#include <linux/tty.h>"
 424 .TP
 425 .BI "TIOCTTYGSTRUCT     struct tty_struct *" argp
 426 Get the
 427 .I tty_struct
 428 corresponding to
 429 .IR fd .
 430 .\"
 431 .\" .SS "Serial info"
 432 .\" .BR "#include <linux/serial.h>"
 433 .\" .sp
 434 .\" .TP
 435 .\" .BI "TIOCGSERIAL    struct serial_struct *" argp
 436 .\" Get serial info.
 437 .\" .TP
 438 .\" .BI "TIOCSSERIAL    const struct serial_struct *" argp
 439 .\" Set serial info.
 440 .SH RETURN VALUE
 441 The
 442 .BR ioctl (2)
 443 system call returns 0 on success.
 444 On error, it returns \-1 and sets
 445 .I errno
 446 appropriately.
 447 .SH ERRORS
 448 .TP
 449 .B EINVAL
 450 Invalid command parameter.
 451 .TP
 452 .B ENOIOCTLCMD
 453 Unknown command.
 454 .TP
 455 .B ENOTTY
 456 Inappropriate
 457 .IR fd .
 458 .TP
 459 .B EPERM
 460 Insufficient permission.
 461 .SH EXAMPLE
 462 Check the condition of DTR on the serial port.
 463
 464 .nf
 465 #include <termios.h>
 466 #include <fcntl.h>
 467 #include <sys/ioctl.h>
 468
 469 int
 470 main(void)
 471 {
 472     int fd, serial;
 473
 474     fd = open("/dev/ttyS0", O_RDONLY);
 475     ioctl(fd, TIOCMGET, &serial);
 476     if (serial & TIOCM_DTR)
 477         puts("TIOCM_DTR is not set");
 478     else
 479         puts("TIOCM_DTR is set");
 480     close(fd);
 481 }
 482 .fi
 483 .SH SEE ALSO
 484 .BR ioctl (2),
 485 .BR termios (3),
 486 .BR console_ioctl (4),
 487 .BR pty (7)
 488 .\"
 489 .\" FIONBIO                     const int *
 490 .\" FIONCLEX                    void
 491 .\" FIOCLEX                     void
 492 .\" FIOASYNC                    const int *
 493 .\" from serial.c:
 494 .\" TIOCSERCONFIG               void
 495 .\" TIOCSERGWILD                int *
 496 .\" TIOCSERSWILD                const int *
 497 .\" TIOCSERGSTRUCT              struct async_struct *
 498 .\" TIOCSERGETLSR               int *
 499 .\" TIOCSERGETMULTI             struct serial_multiport_struct *
 500 .\" TIOCSERSETMULTI             const struct serial_multiport_struct *
 501 .\" TIOCGSERIAL, TIOCSSERIAL (see above)
 502 .SH COLOPHON
 503 This page is part of release 3.79 of the Linux
 504 .I man-pages
 505 project.
 506 A description of the project,
 507 information about reporting bugs,
 508 and the latest version of this page,
 509 can be found at
 510 \%http://www.kernel.org/doc/man\-pages/.