ioctl_tty.2: Remove duplicated text
[man-pages.git] / man2 / ioctl_tty.2
blob581e139d2f457cfc4cbfc451ccc6cddafa0980f8
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 2021-03-22 "Linux" "Linux Programmer's Manual"
9 .SH NAME
10 ioctl_tty \- ioctls for terminals and serial lines
11 .SH SYNOPSIS
12 .nf
13 .B #include <sys/ioctl.h>
14 .BR "#include <termios.h>" "      /* Definition of " CLOCAL ", and"
15 .BR    "                             TC*" { FLUSH , ON , OFF "} constants */"
16 .PP
17 .BI "int ioctl(int " fd ", int " cmd ", ...);"
18 .fi
19 .SH DESCRIPTION
20 The
21 .BR ioctl (2)
22 call for terminals and serial ports accepts many possible command arguments.
23 Most require a third argument, of varying type, here called
24 .I argp
26 .IR arg .
27 .PP
28 Use of
29 .BR ioctl ()
30 makes for nonportable programs.
31 Use the POSIX interface described in
32 .BR termios (3)
33 whenever possible.
34 .SS Get and set terminal attributes
35 .TP
36 .B TCGETS
37 Argument:
38 .BI "struct termios *" argp
39 .IP
40 Equivalent to
41 .IR "tcgetattr(fd, argp)" .
42 .IP
43 Get the current serial port settings.
44 .TP
45 .B TCSETS
46 Argument:
47 .BI "const struct termios *" argp
48 .IP
49 Equivalent to
50 .IR "tcsetattr(fd, TCSANOW, argp)" .
51 .IP
52 Set the current serial port settings.
53 .TP
54 .B TCSETSW
55 Argument:
56 .BI "const struct termios *" argp
57 .IP
58 Equivalent to
59 .IR "tcsetattr(fd, TCSADRAIN, argp)" .
60 .IP
61 Allow the output buffer to drain, and
62 set the current serial port settings.
63 .TP
64 .B TCSETSF
65 Argument:
66 .BI "const struct termios *" argp
67 .IP
68 Equivalent to
69 .IR "tcsetattr(fd, TCSAFLUSH, argp)" .
70 .IP
71 Allow the output buffer to drain, discard pending input, and
72 set the current serial port settings.
73 .PP
74 The following four ioctls, added in Linux 2.6.20,
75 .\" commit 64bb6c5e1ddcd47c951740485026ef08975ee2e6
76 .\" commit 592ee3a5e5e2a981ef2829a0380093006d045661
77 are just like
78 .BR TCGETS ,
79 .BR TCSETS ,
80 .BR TCSETSW ,
81 .BR TCSETSF ,
82 except that they take a
83 .I "struct termios2\ *"
84 instead of a
85 .IR "struct termios\ *" .
86 If the structure member
87 .B c_cflag
88 contains the flag
89 .BR BOTHER ,
90 then the baud rate is stored in the structure members
91 .B c_ispeed
92 and
93 .B c_ospeed
94 as integer values.
95 These ioctls are not supported on all architectures.
96 .RS
97 .TS
98 lb l.
99 TCGETS2 \fBstruct termios2 *\fPargp
100 TCSETS2 \fBconst struct termios2 *\fPargp
101 TCSETSW2        \fBconst struct termios2 *\fPargp
102 TCSETSF2        \fBconst struct termios2 *\fPargp
106 The following four ioctls are just like
107 .BR TCGETS ,
108 .BR TCSETS ,
109 .BR TCSETSW ,
110 .BR TCSETSF ,
111 except that they take a
112 .I "struct termio\ *"
113 instead of a
114 .IR "struct termios\ *" .
117 lb l.
118 TCGETA  \fBstruct termio *\fPargp
119 TCSETA  \fBconst struct termio *\fPargp
120 TCSETAW \fBconst struct termio *\fPargp
121 TCSETAF \fBconst struct termio *\fPargp
124 .SS Locking the termios structure
126 .I termios
127 structure of a terminal can be locked.
128 The lock is itself a
129 .I termios
130 structure, with nonzero bits or fields indicating a
131 locked value.
133 .B TIOCGLCKTRMIOS
134 Argument:
135 .BI "struct termios *" argp
137 Gets the locking status of the
138 .I termios
139 structure of the terminal.
141 .B TIOCSLCKTRMIOS
142 Argument:
143 .BI "const struct termios *" argp
145 Sets the locking status of the
146 .I termios
147 structure of the terminal.
148 Only a process with the
149 .BR CAP_SYS_ADMIN
150 capability can do this.
151 .SS Get and set window size
152 Window sizes are kept in the kernel, but not used by the kernel
153 (except in the case of virtual consoles, where the kernel will
154 update the window size when the size of the virtual console changes,
155 for example, by loading a new font).
157 .B TIOCGWINSZ
158 Argument:
159 .BI "struct winsize *" argp
161 Get window size.
163 .B TIOCSWINSZ
164 Argument:
165 .BI "const struct winsize *" argp
167 Set window size.
169 The struct used by these ioctls is defined as
171 .in +4n
173 struct winsize {
174     unsigned short ws_row;
175     unsigned short ws_col;
176     unsigned short ws_xpixel;   /* unused */
177     unsigned short ws_ypixel;   /* unused */
182 When the window size changes, a
183 .B SIGWINCH
184 signal is sent to the
185 foreground process group.
186 .SS Sending a break
188 .B TCSBRK
189 Argument:
190 .BI "int " arg
192 Equivalent to
193 .IR "tcsendbreak(fd, arg)" .
195 If the terminal is using asynchronous serial data transmission, and
196 .I arg
197 is zero, then send a break (a stream of zero bits) for between
198 0.25 and 0.5 seconds.
199 If the terminal is not using asynchronous
200 serial data transmission, then either a break is sent, or the function
201 returns without doing anything.
202 When
203 .I arg
204 is nonzero, nobody knows what will happen.
206 (SVr4, UnixWare, Solaris, and Linux treat
207 .I "tcsendbreak(fd,arg)"
208 with nonzero
209 .I arg
210 like
211 .IR "tcdrain(fd)" .
212 SunOS treats
213 .I arg
214 as a multiplier, and sends a stream of bits
215 .I arg
216 times as long as done for zero
217 .IR arg .
218 DG/UX and AIX treat
219 .I arg
220 (when nonzero) as a time interval measured in milliseconds.
221 HP-UX ignores
222 .IR arg .)
224 .B TCSBRKP
225 Argument:
226 .BI "int " arg
228 So-called "POSIX version" of
229 .BR TCSBRK .
230 It treats nonzero
231 .I arg
232 as a time interval measured in deciseconds, and does nothing
233 when the driver does not support breaks.
235 .B TIOCSBRK
236 Argument:
237 .BI "void"
239 Turn break on, that is, start sending zero bits.
241 .B TIOCCBRK
242 Argument:
243 .BI "void"
245 Turn break off, that is, stop sending zero bits.
246 .SS Software flow control
248 .B TCXONC
249 Argument:
250 .BI "int " arg
252 Equivalent to
253 .IR "tcflow(fd, arg)" .
256 .BR tcflow (3)
257 for the argument values
258 .BR TCOOFF ,
259 .BR TCOON ,
260 .BR TCIOFF ,
261 .BR TCION .
262 .SS Buffer count and flushing
264 .BI FIONREAD
265 Argument:
266 .BI "int *" argp
268 Get the number of bytes in the input buffer.
270 .B TIOCINQ
271 Argument:
272 .BI "int *" argp
274 Same as
275 .BR FIONREAD .
277 .B TIOCOUTQ
278 Argument:
279 .BI "int *" argp
281 Get the number of bytes in the output buffer.
283 .B TCFLSH
284 Argument:
285 .BI "int " arg
287 Equivalent to
288 .IR "tcflush(fd, arg)" .
291 .BR tcflush (3)
292 for the argument values
293 .BR TCIFLUSH ,
294 .BR TCOFLUSH ,
295 .BR TCIOFLUSH .
296 .SS Faking input
298 .B TIOCSTI
299 Argument:
300 .BI "const char *" argp
302 Insert the given byte in the input queue.
303 .SS Redirecting console output
305 .B TIOCCONS
306 Argument:
307 .BI "void"
309 Redirect output that would have gone to
310 .I /dev/console
312 .I /dev/tty0
313 to the given terminal.
314 If that was a pseudoterminal master, send it to the slave.
315 In Linux before version 2.6.10,
316 anybody can do this as long as the output was not redirected yet;
317 since version 2.6.10, only a process with the
318 .BR CAP_SYS_ADMIN
319 capability may do this.
320 If output was redirected already, then
321 .B EBUSY
322 is returned,
323 but redirection can be stopped by using this ioctl with
324 .I fd
325 pointing at
326 .I /dev/console
328 .IR /dev/tty0 .
329 .SS Controlling terminal
331 .B TIOCSCTTY
332 Argument:
333 .BI "int " arg
335 Make the given terminal the controlling terminal of the calling process.
336 The calling process must be a session leader and not have a
337 controlling terminal already.
338 For this case,
339 .I arg
340 should be specified as zero.
342 If this terminal is already the controlling terminal
343 of a different session group, then the ioctl fails with
344 .BR EPERM ,
345 unless the caller has the
346 .BR CAP_SYS_ADMIN
347 capability and
348 .I arg
349 equals 1, in which case the terminal is stolen, and all processes that had
350 it as controlling terminal lose it.
352 .B TIOCNOTTY
353 Argument:
354 .BI "void"
356 If the given terminal was the controlling terminal of the calling process,
357 give up this controlling terminal.
358 If the process was session leader,
359 then send
360 .B SIGHUP
362 .B SIGCONT
363 to the foreground process group
364 and all processes in the current session lose their controlling terminal.
365 .SS Process group and session ID
367 .B TIOCGPGRP
368 Argument:
369 .BI "pid_t *" argp
371 When successful, equivalent to
372 .IR "*argp = tcgetpgrp(fd)" .
374 Get the process group ID of the foreground process group on this terminal.
376 .B TIOCSPGRP
377 Argument:
378 .BI "const pid_t *" argp
380 Equivalent to
381 .IR "tcsetpgrp(fd, *argp)" .
383 Set the foreground process group ID of this terminal.
385 .B TIOCGSID
386 Argument:
387 .BI "pid_t *" argp
389 Get the session ID of the given terminal.
390 This fails with the error
391 .B ENOTTY
392 if the terminal is not a master pseudoterminal
393 and not our controlling terminal.
394 Strange.
395 .SS Exclusive mode
397 .B TIOCEXCL
398 Argument:
399 .BI "void"
401 Put the terminal into exclusive mode.
402 No further
403 .BR open (2)
404 operations on the terminal are permitted.
405 (They fail with
406 .BR EBUSY ,
407 except for a process with the
408 .BR CAP_SYS_ADMIN
409 capability.)
411 .B TIOCGEXCL
412 Argument:
413 .BI "int *" argp
415 (since Linux 3.8)
416 If the terminal is currently in exclusive mode,
417 place a nonzero value in the location pointed to by
418 .IR argp ;
419 otherwise, place zero in
420 .IR *argp .
422 .B TIOCNXCL
423 Argument:
424 .BI "void"
426 Disable exclusive mode.
427 .SS Line discipline
429 .B TIOCGETD
430 Argument:
431 .BI "int *" argp
433 Get the line discipline of the terminal.
435 .B TIOCSETD
436 Argument:
437 .BI "const int *" argp
439 Set the line discipline of the terminal.
440 .SS Pseudoterminal ioctls
442 .B TIOCPKT
443 Argument:
444 .BI "const int *" argp
446 Enable (when
447 .RI * argp
448 is nonzero) or disable packet mode.
449 Can be applied to the master side of a pseudoterminal only (and will return
450 .B ENOTTY
451 otherwise).
452 In packet mode, each subsequent
453 .BR read (2)
454 will return a packet that either contains a single nonzero control byte,
455 or has a single byte containing zero (\(aq\e0\(aq) followed by data
456 written on the slave side of the pseudoterminal.
457 If the first byte is not
458 .B TIOCPKT_DATA
459 (0), it is an OR of one
460 or more of the following bits:
462 .ad l
464 lb l.
465 TIOCPKT_FLUSHREAD       T{
466 The read queue for the terminal is flushed.
468 TIOCPKT_FLUSHWRITE      T{
469 The write queue for the terminal is flushed.
471 TIOCPKT_STOP    T{
472 Output to the terminal is stopped.
474 TIOCPKT_START   T{
475 Output to the terminal is restarted.
477 TIOCPKT_DOSTOP  T{
478 The start and stop characters are \fB\(haS\fP/\fB\(haQ\fP.
480 TIOCPKT_NOSTOP  T{
481 The start and stop characters are not \fB\(haS\fP/\fB\(haQ\fP.
486 While packet mode is in use, the presence
487 of control status information to be read
488 from the master side may be detected by a
489 .BR select (2)
490 for exceptional conditions or a
491 .BR poll (2)
492 for the
493 .B POLLPRI
494 event.
496 This mode is used by
497 .BR rlogin (1)
499 .BR rlogind (8)
500 to implement a remote-echoed,
501 locally \fB\(haS\fP/\fB\(haQ\fP flow-controlled remote login.
503 .B TIOCGPKT
504 Argument:
505 .BI "const int *" argp
507 (since Linux 3.8)
508 Return the current packet mode setting in the integer pointed to by
509 .IR argp .
511 .B TIOCSPTLCK
512 Argument:
513 .BI "int *" argp
515 Set (if
516 .IR *argp
517 is nonzero) or remove (if
518 .IR *argp
519 is zero) the lock on the pseudoterminal slave device.
520 (See also
521 .BR unlockpt (3).)
523 .B TIOCGPTLCK
524 Argument:
525 .BI "int *" argp
527 (since Linux 3.8)
528 Place the current lock state of the pseudoterminal slave device
529 in the location pointed to by
530 .IR argp .
532 .B TIOCGPTPEER
533 Argument:
534 .BI "int " flags
536 .\" commit 54ebbfb1603415d9953c150535850d30609ef077
537 (since Linux 4.13)
538 Given a file descriptor in
539 .I fd
540 that refers to a pseudoterminal master,
541 open (with the given
542 .BR open (2)-style
543 .IR flags )
544 and return a new file descriptor that refers to the peer
545 pseudoterminal slave device.
546 This operation can be performed
547 regardless of whether the pathname of the slave device
548 is accessible through the calling process's mount namespace.
550 Security-conscious programs interacting with namespaces may wish to use this
551 operation rather than
552 .BR open (2)
553 with the pathname returned by
554 .BR ptsname (3),
555 and similar library functions that have insecure APIs.
556 (For example, confusion can occur in some cases using
557 .BR ptsname (3)
558 with a pathname where a devpts filesystem
559 has been mounted in a different mount namespace.)
561 The BSD ioctls
562 .BR TIOCSTOP ,
563 .BR TIOCSTART ,
564 .BR TIOCUCNTL ,
566 .B TIOCREMOTE
567 have not been implemented under Linux.
568 .SS Modem control
570 .B TIOCMGET
571 Argument:
572 .BI "int *" argp
574 Get the status of modem bits.
576 .B TIOCMSET
577 Argument:
578 .BI "const int *" argp
580 Set the status of modem bits.
582 .B TIOCMBIC
583 Argument:
584 .BI "const int *" argp
586 Clear the indicated modem bits.
588 .B TIOCMBIS
589 Argument:
590 .BI "const int *" argp
592 Set the indicated modem bits.
594 The following bits are used by the above ioctls:
597 lb l.
598 TIOCM_LE        DSR (data set ready/line enable)
599 TIOCM_DTR       DTR (data terminal ready)
600 TIOCM_RTS       RTS (request to send)
601 TIOCM_ST        Secondary TXD (transmit)
602 TIOCM_SR        Secondary RXD (receive)
603 TIOCM_CTS       CTS (clear to send)
604 TIOCM_CAR       DCD (data carrier detect)
605 TIOCM_CD        see TIOCM_CAR
606 TIOCM_RNG       RNG (ring)
607 TIOCM_RI        see TIOCM_RNG
608 TIOCM_DSR       DSR (data set ready)
611 .B TIOCMIWAIT
612 Argument:
613 .BI "int " arg
615 Wait for any of the 4 modem bits (DCD, RI, DSR, CTS) to change.
616 The bits of interest are specified as a bit mask in
617 .IR arg ,
618 by ORing together any of the bit values,
619 .BR TIOCM_RNG ,
620 .BR TIOCM_DSR ,
621 .BR TIOCM_CD ,
623 .BR TIOCM_CTS .
624 The caller should use
625 .B TIOCGICOUNT
626 to see which bit has changed.
628 .B TIOCGICOUNT
629 Argument:
630 .BI "struct serial_icounter_struct *" argp
632 Get counts of input serial line interrupts (DCD, RI, DSR, CTS).
633 The counts are written to the
634 .I serial_icounter_struct
635 structure pointed to by
636 .IR argp .
638 Note: both 1->0 and 0->1 transitions are counted, except for
639 RI, where only 0->1 transitions are counted.
640 .SS Marking a line as local
642 .B TIOCGSOFTCAR
643 Argument:
644 .BI "int *" argp
646 ("Get software carrier flag")
647 Get the status of the CLOCAL flag in the c_cflag field of the
648 .I termios
649 structure.
651 .B TIOCSSOFTCAR
652 Argument:
653 .BI "const int *" argp
655 ("Set software carrier flag")
656 Set the CLOCAL flag in the
657 .I termios
658 structure when
659 .RI * argp
660 is nonzero, and clear it otherwise.
662 If the
663 .B CLOCAL
664 flag for a line is off, the hardware carrier detect (DCD)
665 signal is significant, and an
666 .BR open (2)
667 of the corresponding terminal will block until DCD is asserted,
668 unless the
669 .B O_NONBLOCK
670 flag is given.
672 .B CLOCAL
673 is set, the line behaves as if DCD is always asserted.
674 The software carrier flag is usually turned on for local devices,
675 and is off for lines with modems.
676 .SS Linux-specific
677 For the
678 .B TIOCLINUX
679 ioctl, see
680 .BR ioctl_console (2).
681 .SS Kernel debugging
682 .B "#include <linux/tty.h>"
684 .B TIOCTTYGSTRUCT
685 Argument:
686 .BI "struct tty_struct *" argp
688 Get the
689 .I tty_struct
690 corresponding to
691 .IR fd .
692 This command was removed in Linux 2.5.67.
693 .\"     commit b3506a09d15dc5aee6d4bb88d759b157016e1864
694 .\"     Author: Andries E. Brouwer <andries.brouwer@cwi.nl>
695 .\"     Date:   Tue Apr 1 04:42:46 2003 -0800
697 .\"     [PATCH] kill TIOCTTYGSTRUCT
699 .\"     Only used for (dubious) debugging purposes, and exposes
700 .\"     internal kernel state.
702 .\" .SS Serial info
703 .\" .BR "#include <linux/serial.h>"
704 .\" .PP
705 .\" .TP
706 .\" .BI "TIOCGSERIAL    struct serial_struct *" argp
707 .\" Get serial info.
708 .\" .TP
709 .\" .BI "TIOCSSERIAL    const struct serial_struct *" argp
710 .\" Set serial info.
711 .SH RETURN VALUE
713 .BR ioctl (2)
714 system call returns 0 on success.
715 On error, it returns \-1 and sets
716 .I errno
717 to indicate the error.
718 .SH ERRORS
720 .B EINVAL
721 Invalid command parameter.
723 .B ENOIOCTLCMD
724 Unknown command.
726 .B ENOTTY
727 Inappropriate
728 .IR fd .
730 .B EPERM
731 Insufficient permission.
732 .SH EXAMPLES
733 Check the condition of DTR on the serial port.
736 #include <stdio.h>
737 #include <unistd.h>
738 #include <fcntl.h>
739 #include <sys/ioctl.h>
742 main(void)
744     int fd, serial;
746     fd = open("/dev/ttyS0", O_RDONLY);
747     ioctl(fd, TIOCMGET, &serial);
748     if (serial & TIOCM_DTR)
749         puts("TIOCM_DTR is set");
750     else
751         puts("TIOCM_DTR is not set");
752     close(fd);
755 .SH SEE ALSO
756 .BR ldattach (1),
757 .BR ioctl (2),
758 .BR ioctl_console (2),
759 .BR termios (3),
760 .BR pty (7)
762 .\" FIONBIO                     const int *
763 .\" FIONCLEX                    void
764 .\" FIOCLEX                     void
765 .\" FIOASYNC                    const int *
766 .\" from serial.c:
767 .\" TIOCSERCONFIG               void
768 .\" TIOCSERGWILD                int *
769 .\" TIOCSERSWILD                const int *
770 .\" TIOCSERGSTRUCT              struct async_struct *
771 .\" TIOCSERGETLSR               int *
772 .\" TIOCSERGETMULTI             struct serial_multiport_struct *
773 .\" TIOCSERSETMULTI             const struct serial_multiport_struct *
774 .\" TIOCGSERIAL, TIOCSSERIAL (see above)