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