1 .\" Copyright 2002 Walter Harms <walter.harms@informatik.uni-oldenburg.de>
2 .\" and Andries Brouwer <aeb@cwi.nl>.
4 .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
5 .\" Distributed under GPL
8 .TH IOCTL_TTY 2 2021-03-22 "Linux" "Linux Programmer's Manual"
10 ioctl_tty \- ioctls for terminals and serial lines
13 .B #include <sys/ioctl.h>
14 .BR "#include <termios.h>" " /* Definition of " CLOCAL ", and"
15 .BR " TC*" { FLUSH , ON , OFF "} constants */"
17 .BI "int ioctl(int " fd ", int " cmd ", ...);"
22 call for terminals and serial ports accepts many possible command arguments.
23 Most require a third argument, of varying type, here called
30 makes for nonportable programs.
31 Use the POSIX interface described in
34 .SS Get and set terminal attributes
38 .BI "struct termios *" argp
41 .IR "tcgetattr(fd, argp)" .
43 Get the current serial port settings.
47 .BI "const struct termios *" argp
50 .IR "tcsetattr(fd, TCSANOW, argp)" .
52 Set the current serial port settings.
56 .BI "const struct termios *" argp
59 .IR "tcsetattr(fd, TCSADRAIN, argp)" .
61 Allow the output buffer to drain, and
62 set the current serial port settings.
66 .BI "const struct termios *" argp
69 .IR "tcsetattr(fd, TCSAFLUSH, argp)" .
71 Allow the output buffer to drain, discard pending input, and
72 set the current serial port settings.
74 The following four ioctls are just like
79 except that they take a
82 .IR "struct termios\ *" .
86 TCGETA \fBstruct termio *\fPargp
87 TCSETA \fBconst struct termio *\fPargp
88 TCSETAW \fBconst struct termio *\fPargp
89 TCSETAF \fBconst struct termio *\fPargp
92 .SS Locking the termios structure
95 structure of a terminal can be locked.
98 structure, with nonzero bits or fields indicating a
103 .BI "struct termios *" argp
105 Gets the locking status of the
107 structure of the terminal.
111 .BI "const struct termios *" argp
113 Sets the locking status of the
115 structure of the terminal.
116 Only a process with the
118 capability can do this.
119 .SS Get and set window size
120 Window sizes are kept in the kernel, but not used by the kernel
121 (except in the case of virtual consoles, where the kernel will
122 update the window size when the size of the virtual console changes,
123 for example, by loading a new font).
127 .BI "struct winsize *" argp
133 .BI "const struct winsize *" argp
137 The struct used by these ioctls is defined as
142 unsigned short ws_row;
143 unsigned short ws_col;
144 unsigned short ws_xpixel; /* unused */
145 unsigned short ws_ypixel; /* unused */
150 When the window size changes, a
152 signal is sent to the
153 foreground process group.
161 .IR "tcsendbreak(fd, arg)" .
163 If the terminal is using asynchronous serial data transmission, and
165 is zero, then send a break (a stream of zero bits) for between
166 0.25 and 0.5 seconds.
167 If the terminal is not using asynchronous
168 serial data transmission, then either a break is sent, or the function
169 returns without doing anything.
172 is nonzero, nobody knows what will happen.
174 (SVr4, UnixWare, Solaris, and Linux treat
175 .I "tcsendbreak(fd,arg)"
182 as a multiplier, and sends a stream of bits
184 times as long as done for zero
188 (when nonzero) as a time interval measured in milliseconds.
196 So-called "POSIX version" of
200 as a time interval measured in deciseconds, and does nothing
201 when the driver does not support breaks.
207 Turn break on, that is, start sending zero bits.
213 Turn break off, that is, stop sending zero bits.
214 .SS Software flow control
221 .IR "tcflow(fd, arg)" .
225 for the argument values
230 .SS Buffer count and flushing
236 Get the number of bytes in the input buffer.
249 Get the number of bytes in the output buffer.
256 .IR "tcflush(fd, arg)" .
260 for the argument values
268 .BI "const char *" argp
270 Insert the given byte in the input queue.
271 .SS Redirecting console output
277 Redirect output that would have gone to
281 to the given terminal.
282 If that was a pseudoterminal master, send it to the slave.
283 In Linux before version 2.6.10,
284 anybody can do this as long as the output was not redirected yet;
285 since version 2.6.10, only a process with the
287 capability may do this.
288 If output was redirected already, then
291 but redirection can be stopped by using this ioctl with
297 .SS Controlling terminal
303 Make the given terminal the controlling terminal of the calling process.
304 The calling process must be a session leader and not have a
305 controlling terminal already.
308 should be specified as zero.
310 If this terminal is already the controlling terminal
311 of a different session group, then the ioctl fails with
313 unless the caller has the
317 equals 1, in which case the terminal is stolen, and all processes that had
318 it as controlling terminal lose it.
324 If the given terminal was the controlling terminal of the calling process,
325 give up this controlling terminal.
326 If the process was session leader,
331 to the foreground process group
332 and all processes in the current session lose their controlling terminal.
333 .SS Process group and session ID
339 When successful, equivalent to
340 .IR "*argp = tcgetpgrp(fd)" .
342 Get the process group ID of the foreground process group on this terminal.
346 .BI "const pid_t *" argp
349 .IR "tcsetpgrp(fd, *argp)" .
351 Set the foreground process group ID of this terminal.
357 Get the session ID of the given terminal.
358 This fails with the error
360 if the terminal is not a master pseudoterminal
361 and not our controlling terminal.
369 Put the terminal into exclusive mode.
372 operations on the terminal are permitted.
375 except for a process with the
384 If the terminal is currently in exclusive mode,
385 place a nonzero value in the location pointed to by
387 otherwise, place zero in
394 Disable exclusive mode.
401 Get the line discipline of the terminal.
405 .BI "const int *" argp
407 Set the line discipline of the terminal.
408 .SS Pseudoterminal ioctls
412 .BI "const int *" argp
416 is nonzero) or disable packet mode.
417 Can be applied to the master side of a pseudoterminal only (and will return
420 In packet mode, each subsequent
422 will return a packet that either contains a single nonzero control byte,
423 or has a single byte containing zero (\(aq\e0\(aq) followed by data
424 written on the slave side of the pseudoterminal.
425 If the first byte is not
427 (0), it is an OR of one
428 or more of the following bits:
434 The read queue for the terminal is flushed.
436 TIOCPKT_FLUSHWRITE T{
437 The write queue for the terminal is flushed.
440 Output to the terminal is stopped.
443 Output to the terminal is restarted.
446 The start and stop characters are \fB\(haS\fP/\fB\(haQ\fP.
449 The start and stop characters are not \fB\(haS\fP/\fB\(haQ\fP.
454 While packet mode is in use, the presence
455 of control status information to be read
456 from the master side may be detected by a
458 for exceptional conditions or a
468 to implement a remote-echoed,
469 locally \fB\(haS\fP/\fB\(haQ\fP flow-controlled remote login.
473 .BI "const int *" argp
476 Return the current packet mode setting in the integer pointed to by
485 is nonzero) or remove (if
487 is zero) the lock on the pseudoterminal slave device.
496 Place the current lock state of the pseudoterminal slave device
497 in the location pointed to by
504 .\" commit 54ebbfb1603415d9953c150535850d30609ef077
506 Given a file descriptor in
508 that refers to a pseudoterminal master,
512 and return a new file descriptor that refers to the peer
513 pseudoterminal slave device.
514 This operation can be performed
515 regardless of whether the pathname of the slave device
516 is accessible through the calling process's mount namespace.
518 Security-conscious programs interacting with namespaces may wish to use this
519 operation rather than
521 with the pathname returned by
523 and similar library functions that have insecure APIs.
524 (For example, confusion can occur in some cases using
526 with a pathname where a devpts filesystem
527 has been mounted in a different mount namespace.)
535 have not been implemented under Linux.
542 Get the status of modem bits.
546 .BI "const int *" argp
548 Set the status of modem bits.
552 .BI "const int *" argp
554 Clear the indicated modem bits.
558 .BI "const int *" argp
560 Set the indicated modem bits.
562 The following bits are used by the above ioctls:
566 TIOCM_LE DSR (data set ready/line enable)
567 TIOCM_DTR DTR (data terminal ready)
568 TIOCM_RTS RTS (request to send)
569 TIOCM_ST Secondary TXD (transmit)
570 TIOCM_SR Secondary RXD (receive)
571 TIOCM_CTS CTS (clear to send)
572 TIOCM_CAR DCD (data carrier detect)
573 TIOCM_CD see TIOCM_CAR
575 TIOCM_RI see TIOCM_RNG
576 TIOCM_DSR DSR (data set ready)
583 Wait for any of the 4 modem bits (DCD, RI, DSR, CTS) to change.
584 The bits of interest are specified as a bit mask in
586 by ORing together any of the bit values,
592 The caller should use
594 to see which bit has changed.
598 .BI "struct serial_icounter_struct *" argp
600 Get counts of input serial line interrupts (DCD, RI, DSR, CTS).
601 The counts are written to the
602 .I serial_icounter_struct
603 structure pointed to by
606 Note: both 1->0 and 0->1 transitions are counted, except for
607 RI, where only 0->1 transitions are counted.
608 .SS Marking a line as local
614 ("Get software carrier flag")
615 Get the status of the CLOCAL flag in the c_cflag field of the
621 .BI "const int *" argp
623 ("Set software carrier flag")
624 Set the CLOCAL flag in the
628 is nonzero, and clear it otherwise.
632 flag for a line is off, the hardware carrier detect (DCD)
633 signal is significant, and an
635 of the corresponding terminal will block until DCD is asserted,
641 is set, the line behaves as if DCD is always asserted.
642 The software carrier flag is usually turned on for local devices,
643 and is off for lines with modems.
648 .BR ioctl_console (2).
650 .B "#include <linux/tty.h>"
654 .BI "struct tty_struct *" argp
660 This command was removed in Linux 2.5.67.
661 .\" commit b3506a09d15dc5aee6d4bb88d759b157016e1864
662 .\" Author: Andries E. Brouwer <andries.brouwer@cwi.nl>
663 .\" Date: Tue Apr 1 04:42:46 2003 -0800
665 .\" [PATCH] kill TIOCTTYGSTRUCT
667 .\" Only used for (dubious) debugging purposes, and exposes
668 .\" internal kernel state.
671 .\" .BR "#include <linux/serial.h>"
674 .\" .BI "TIOCGSERIAL struct serial_struct *" argp
677 .\" .BI "TIOCSSERIAL const struct serial_struct *" argp
682 system call returns 0 on success.
683 On error, it returns \-1 and sets
685 to indicate the error.
689 Invalid command parameter.
699 Insufficient permission.
701 Check the condition of DTR on the serial port.
706 #include <sys/ioctl.h>
713 fd = open("/dev/ttyS0", O_RDONLY);
714 ioctl(fd, TIOCMGET, &serial);
715 if (serial & TIOCM_DTR)
716 puts("TIOCM_DTR is set");
718 puts("TIOCM_DTR is not set");
725 .BR ioctl_console (2),
729 .\" FIONBIO const int *
732 .\" FIOASYNC const int *
734 .\" TIOCSERCONFIG void
735 .\" TIOCSERGWILD int *
736 .\" TIOCSERSWILD const int *
737 .\" TIOCSERGSTRUCT struct async_struct *
738 .\" TIOCSERGETLSR int *
739 .\" TIOCSERGETMULTI struct serial_multiport_struct *
740 .\" TIOCSERSETMULTI const struct serial_multiport_struct *
741 .\" TIOCGSERIAL, TIOCSSERIAL (see above)