man4/tty_ioctl.4

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