1IOCTL_TTY(2) Linux Programmer's Manual IOCTL_TTY(2)
2
6 ioctl_tty - ioctls for terminals and serial lines
7
9 #include <sys/ioctl.h>
10 #include <termios.h> /* Definition of CLOCAL, and
11 TC*{FLUSH,ON,OFF} constants */
12 int ioctl(int fd, int cmd, ...);
14
16 The ioctl(2) call for terminals and serial ports accepts many possible
17 command arguments. Most require a third argument, of varying type,
18 here called argp or arg.
19 Use of ioctl makes for nonportable programs. Use the POSIX interface
21 described in termios(3) whenever possible.
22 Get and set terminal attributes
24 TCGETS Argument: struct termios *argp
25 Equivalent to tcgetattr(fd, argp).
27 Get the current serial port settings.
29 TCSETS Argument: const struct termios *argp
31 Equivalent to tcsetattr(fd, TCSANOW, argp).
33 Set the current serial port settings.
35 TCSETSW
37 Argument: const struct termios *argp
38 Equivalent to tcsetattr(fd, TCSADRAIN, argp).
40 Allow the output buffer to drain, and set the current serial
42 port settings.
43 TCSETSF
45 Argument: const struct termios *argp
46 Equivalent to tcsetattr(fd, TCSAFLUSH, argp).
48 Allow the output buffer to drain, discard pending input, and set
50 the current serial port settings.
51 The following four ioctls are just like TCGETS, TCSETS, TCSETSW, TC‐
53 SETSF, except that they take a struct termio * instead of a struct
54 termios *.
55 TCGETA struct termio *argp
57 TCSETA const struct termio *argp
59 TCSETAW const struct termio *argp
61 TCSETAF const struct termio *argp
63 Locking the termios structure
65 The termios structure of a terminal can be locked. The lock is itself
66 a termios structure, with nonzero bits or fields indicating a locked
67 value.
68 TIOCGLCKTRMIOS
70 Argument: struct termios *argp
71 Gets the locking status of the termios structure of the termi‐
73 nal.
74 TIOCSLCKTRMIOS
76 Argument: const struct termios *argp
77 Sets the locking status of the termios structure of the termi‐
79 nal. Only a process with the CAP_SYS_ADMIN capability can do
80 this.
81 Get and set window size
83 Window sizes are kept in the kernel, but not used by the kernel (except
84 in the case of virtual consoles, where the kernel will update the win‐
85 dow size when the size of the virtual console changes, for example, by
86 loading a new font).
87 TIOCGWINSZ
89 Argument: struct winsize *argp
90 Get window size.
92 TIOCSWINSZ
94 Argument: const struct winsize *argp
95 Set window size.
97 The struct used by these ioctls is defined as
99 struct winsize {
101 unsigned short ws_row;
102 unsigned short ws_col;
103 unsigned short ws_xpixel; /* unused */
104 unsigned short ws_ypixel; /* unused */
105 };
106 When the window size changes, a SIGWINCH signal is sent to the fore‐
108 ground process group.
109 Sending a break
111 TCSBRK Argument: int arg
112 Equivalent to tcsendbreak(fd, arg).
114 If the terminal is using asynchronous serial data transmission,
116 and arg is zero, then send a break (a stream of zero bits) for
117 between 0.25 and 0.5 seconds. If the terminal is not using
118 asynchronous serial data transmission, then either a break is
119 sent, or the function returns without doing anything. When arg
120 is nonzero, nobody knows what will happen.
121 (SVr4, UnixWare, Solaris, Linux treat tcsendbreak(fd,arg) with
123 nonzero arg like tcdrain(fd). SunOS treats arg as a multiplier,
124 and sends a stream of bits arg times as long as done for zero
125 arg. DG/UX and AIX treat arg (when nonzero) as a time interval
126 measured in milliseconds. HP-UX ignores arg.)
127 TCSBRKP
129 Argument: int arg
130 So-called "POSIX version" of TCSBRK. It treats nonzero arg as a
132 time interval measured in deciseconds, and does nothing when the
133 driver does not support breaks.
134 TIOCSBRK
136 Argument: void
137 Turn break on, that is, start sending zero bits.
139 TIOCCBRK
141 Argument: void
142 Turn break off, that is, stop sending zero bits.
144 Software flow control
146 TCXONC Argument: int arg
147 Equivalent to tcflow(fd, arg).
149 See tcflow(3) for the argument values TCOOFF, TCOON, TCIOFF,
151 TCION.
152 Buffer count and flushing
154 FIONREAD
155 Argument: int *argp
156 Get the number of bytes in the input buffer.
158 TIOCINQ
160 Argument: int *argp
161 Same as FIONREAD.
163 TIOCOUTQ
165 Argument: int *argp
166 Get the number of bytes in the output buffer.
168 TCFLSH Argument: int arg
170 Equivalent to tcflush(fd, arg).
172 See tcflush(3) for the argument values TCIFLUSH, TCOFLUSH,
174 TCIOFLUSH.
175 Faking input
177 TIOCSTI
178 Argument: const char *argp
179 Insert the given byte in the input queue.
181 Redirecting console output
183 TIOCCONS
184 Argument: void
185 Redirect output that would have gone to /dev/console or
187 /dev/tty0 to the given terminal. If that was a pseudoterminal
188 master, send it to the slave. In Linux before version 2.6.10,
189 anybody can do this as long as the output was not redirected
190 yet; since version 2.6.10, only a process with the CAP_SYS_ADMIN
191 capability may do this. If output was redirected already, then
192 EBUSY is returned, but redirection can be stopped by using this
193 ioctl with fd pointing at /dev/console or /dev/tty0.
194 Controlling terminal
196 TIOCSCTTY
197 Argument: int arg
198 Make the given terminal the controlling terminal of the calling
200 process. The calling process must be a session leader and not
201 have a controlling terminal already. For this case, arg should
202 be specified as zero.
203 If this terminal is already the controlling terminal of a dif‐
205 ferent session group, then the ioctl fails with EPERM, unless
206 the caller has the CAP_SYS_ADMIN capability and arg equals 1, in
207 which case the terminal is stolen, and all processes that had it
208 as controlling terminal lose it.
209 TIOCNOTTY
211 Argument: void
212 If the given terminal was the controlling terminal of the call‐
214 ing process, give up this controlling terminal. If the process
215 was session leader, then send SIGHUP and SIGCONT to the fore‐
216 ground process group and all processes in the current session
217 lose their controlling terminal.
218 Process group and session ID
220 TIOCGPGRP
221 Argument: pid_t *argp
222 When successful, equivalent to *argp = tcgetpgrp(fd).
224 Get the process group ID of the foreground process group on this
226 terminal.
227 TIOCSPGRP
229 Argument: const pid_t *argp
230 Equivalent to tcsetpgrp(fd, *argp).
232 Set the foreground process group ID of this terminal.
234 TIOCGSID
236 Argument: pid_t *argp
237 Get the session ID of the given terminal. This fails with the
239 error ENOTTY if the terminal is not a master pseudoterminal and
240 not our controlling terminal. Strange.
241 Exclusive mode
243 TIOCEXCL
244 Argument: void
245 Put the terminal into exclusive mode. No further open(2) opera‐
247 tions on the terminal are permitted. (They fail with EBUSY, ex‐
248 cept for a process with the CAP_SYS_ADMIN capability.)
249 TIOCGEXCL
251 Argument: int *argp
252 (since Linux 3.8) If the terminal is currently in exclusive
254 mode, place a nonzero value in the location pointed to by argp;
255 otherwise, place zero in *argp.
256 TIOCNXCL
258 Argument: void
259 Disable exclusive mode.
261 Line discipline
263 TIOCGETD
264 Argument: int *argp
265 Get the line discipline of the terminal.
267 TIOCSETD
269 Argument: const int *argp
270 Set the line discipline of the terminal.
272 Pseudoterminal ioctls
274 TIOCPKT
275 Argument: const int *argp
276 Enable (when *argp is nonzero) or disable packet mode. Can be
278 applied to the master side of a pseudoterminal only (and will
279 return ENOTTY otherwise). In packet mode, each subsequent
280 read(2) will return a packet that either contains a single non‐
281 zero control byte, or has a single byte containing zero ('\0')
282 followed by data written on the slave side of the pseudotermi‐
283 nal. If the first byte is not TIOCPKT_DATA (0), it is an OR of
284 one or more of the following bits:
285 TIOCPKT_FLUSHREAD The read queue for the
287 terminal is flushed.
288 TIOCPKT_FLUSHWRITE The write queue for the
289 terminal is flushed.
290 TIOCPKT_STOP Output to the terminal is
291 stopped.
292 TIOCPKT_START Output to the terminal is
293 restarted.
294 TIOCPKT_DOSTOP The start and stop charac‐
295 ters are ^S/^Q.
296 TIOCPKT_NOSTOP The start and stop charac‐
297 ters are not ^S/^Q.
298 While packet mode is in use, the presence of control status in‐
300 formation to be read from the master side may be detected by a
301 select(2) for exceptional conditions or a poll(2) for the POLL‐
302 PRI event.
303 This mode is used by rlogin(1) and rlogind(8) to implement a re‐
305 mote-echoed, locally ^S/^Q flow-controlled remote login.
306 TIOCGPKT
308 Argument: const int *argp
309 (since Linux 3.8) Return the current packet mode setting in the
311 integer pointed to by argp.
312 TIOCSPTLCK
314 Argument: int *argp
315 Set (if *argp is nonzero) or remove (if *argp is zero) the lock
317 on the pseudoterminal slave device. (See also unlockpt(3).)
318 TIOCGPTLCK
320 Argument: int *argp
321 (since Linux 3.8) Place the current lock state of the pseudoter‐
323 minal slave device in the location pointed to by argp.
324 TIOCGPTPEER
326 Argument: int flags
327 (since Linux 4.13) Given a file descriptor in fd that refers to
329 a pseudoterminal master, open (with the given open(2)-style
330 flags) and return a new file descriptor that refers to the peer
331 pseudoterminal slave device. This operation can be performed
332 regardless of whether the pathname of the slave device is acces‐
333 sible through the calling process's mount namespace.
334 Security-conscious programs interacting with namespaces may wish
336 to use this operation rather than open(2) with the pathname re‐
337 turned by ptsname(3), and similar library functions that have
338 insecure APIs. (For example, confusion can occur in some cases
339 using ptsname(3) with a pathname where a devpts filesystem has
340 been mounted in a different mount namespace.)
341 The BSD ioctls TIOCSTOP, TIOCSTART, TIOCUCNTL, TIOCREMOTE have not been
343 implemented under Linux.
344 Modem control
346 TIOCMGET
347 Argument: int *argp
348 Get the status of modem bits.
350 TIOCMSET
352 Argument: const int *argp
353 Set the status of modem bits.
355 TIOCMBIC
357 Argument: const int *argp
358 Clear the indicated modem bits.
360 TIOCMBIS
362 Argument: const int *argp
363 Set the indicated modem bits.
365 The following bits are used by the above ioctls:
367 TIOCM_LE DSR (data set ready/line enable)
369 TIOCM_DTR DTR (data terminal ready)
370 TIOCM_RTS RTS (request to send)
371 TIOCM_ST Secondary TXD (transmit)
372 TIOCM_SR Secondary RXD (receive)
373 TIOCM_CTS CTS (clear to send)
374 TIOCM_CAR DCD (data carrier detect)
375 TIOCM_CD see TIOCM_CAR
376 TIOCM_RNG RNG (ring)
377 TIOCM_RI see TIOCM_RNG
378 TIOCM_DSR DSR (data set ready)
379 TIOCMIWAIT
381 Argument: int arg
382 Wait for any of the 4 modem bits (DCD, RI, DSR, CTS) to change.
384 The bits of interest are specified as a bit mask in arg, by OR‐
385 ing together any of the bit values, TIOCM_RNG, TIOCM_DSR, TI‐
386 OCM_CD, and TIOCM_CTS. The caller should use TIOCGICOUNT to see
387 which bit has changed.
388 TIOCGICOUNT
390 Argument: struct serial_icounter_struct *argp
391 Get counts of input serial line interrupts (DCD, RI, DSR, CTS).
393 The counts are written to the serial_icounter_struct structure
394 pointed to by argp.
395 Note: both 1->0 and 0->1 transitions are counted, except for RI,
397 where only 0->1 transitions are counted.
398 Marking a line as local
400 TIOCGSOFTCAR
401 Argument: int *argp
402 ("Get software carrier flag") Get the status of the CLOCAL flag
404 in the c_cflag field of the termios structure.
405 TIOCSSOFTCAR
407 Argument: const int *argp
408 ("Set software carrier flag") Set the CLOCAL flag in the termios
410 structure when *argp is nonzero, and clear it otherwise.
411 If the CLOCAL flag for a line is off, the hardware carrier detect (DCD)
413 signal is significant, and an open(2) of the corresponding terminal
414 will block until DCD is asserted, unless the O_NONBLOCK flag is given.
415 If CLOCAL is set, the line behaves as if DCD is always asserted. The
416 software carrier flag is usually turned on for local devices, and is
417 off for lines with modems.
418 Linux-specific
420 For the TIOCLINUX ioctl, see ioctl_console(2).
421 Kernel debugging
423 #include <linux/tty.h>
424 TIOCTTYGSTRUCT
426 Argument: struct tty_struct *argp
427 Get the tty_struct corresponding to fd. This command was re‐
429 moved in Linux 2.5.67.
430
432 The ioctl(2) system call returns 0 on success. On error, it returns -1
433 and sets errno to indicate the error.
434
436 EINVAL Invalid command parameter.
437 ENOIOCTLCMD
439 Unknown command.
440 ENOTTY Inappropriate fd.
442 EPERM Insufficient permission.
444
446 Check the condition of DTR on the serial port.
447 #include <termios.h>
449 #include <fcntl.h>
450 #include <sys/ioctl.h>
451 int
453 main(void)
454 {
455 int fd, serial;
456 fd = open("/dev/ttyS0", O_RDONLY);
458 ioctl(fd, TIOCMGET, &serial);
459 if (serial & TIOCM_DTR)
460 puts("TIOCM_DTR is set");
461 else
462 puts("TIOCM_DTR is not set");
463 close(fd);
464 }
465
467 ldattach(1), ioctl(2), ioctl_console(2), termios(3), pty(7)
468
470 This page is part of release 5.12 of the Linux man-pages project. A
471 description of the project, information about reporting bugs, and the
472 latest version of this page, can be found at
473 https://www.kernel.org/doc/man-pages/.
474Linux 2021-03-22 IOCTL_TTY(2)