1TTY_IOCTL(4) Linux Programmer's Manual TTY_IOCTL(4)
2
6 tty ioctl - ioctls for terminals and serial lines
7
9 #include <termios.h>
10 int ioctl(int fd, int cmd, ...);
12
15 The ioctl() call for terminals and serial ports accepts many possible
16 command arguments. Most require a third argument, of varying type,
17 here called argp or arg.
18 Use of ioctl makes for non-portable programs. Use the POSIX interface
20 described in termios(3) whenever possible.
21 Get and Set Terminal Attributes
24 TCGETS struct termios *argp
25 Equivalent to tcgetattr(fd, argp).
26 Get the current serial port settings.
27 TCSETS const struct termios *argp
29 Equivalent to tcsetattr(fd, TCSANOW, argp).
30 Set the current serial port settings.
31 TCSETSW const struct termios *argp
33 Equivalent to tcsetattr(fd, TCSADRAIN, argp).
34 Allow the output buffer to drain, and set the current serial
35 port settings.
36 TCSETSF const struct termios *argp
38 Equivalent to tcsetattr(fd, TCSAFLUSH, argp).
39 Allow the output buffer to drain, discard pending input, and set
40 the current serial port settings.
41 The following four ioctls are just like TCGETS, TCSETS, TCSETSW,
43 TCSETSF, except that they take a struct termio * instead of a struct
44 termios *.
45 TCGETA struct termio *argp
47 TCSETA const struct termio *argp
49 TCSETAW const struct termio *argp
51 TCSETAF const struct termio *argp
53 Locking the termios structure
56 The termios structure of a tty can be locked. The lock is itself a
57 termios structure, with non-zero bits or fields indicating a locked
58 value.
59 TIOCGLCKTRMIOS struct termios *argp
61 Gets the locking status of the termios structure of the termi‐
62 nal.
63 TIOCSLCKTRMIOS const struct termios *argp
65 Sets the locking status of the termios structure of the termi‐
66 nal. Only root can do this.
67 Get and Set Window Size
70 Window sizes are kept in the kernel, but not used by the kernel (except
71 in the case of virtual consoles, where the kernel will update the win‐
72 dow size when the size of the virtual console changes, e.g. by loading
73 a new font).
74 TIOCGWINSZ struct winsize *argp
76 Get window size.
77 TIOCSWINSZ const struct winsize *argp
79 Set window size.
80 The struct used by these ioctls is defined as
82 struct winsize {
84 unsigned short ws_row;
85 unsigned short ws_col;
86 unsigned short ws_xpixel; /* unused */
87 unsigned short ws_ypixel; /* unused */
88 };
89 When the window size changes, a SIGWINCH signal is sent to the fore‐
91 ground process group.
92 Sending a Break
95 TCSBRK int arg
96 Equivalent to tcsendbreak(fd, arg).
97 If the terminal is using asynchronous serial data transmission,
98 and arg is zero, then send a break (a stream of zero bits) for
99 between 0.25 and 0.5 seconds. If the terminal is not using asyn‐
100 chronous serial data transmission, then either a break is sent,
101 or the function returns without doing anything. When arg is
102 non-zero, nobody knows what will happen.
103 (SVr4, UnixWare, Solaris, Linux treat tcsendbreak(fd,arg) with
105 non-zero arg like tcdrain(fd). SunOS treats arg as a multi‐
106 plier, and sends a stream of bits arg times as long as done for
107 zero arg. DG/UX and AIX treat arg (when non-zero) as a timein‐
108 terval measured in milliseconds. HP-UX ignores arg.)
109 TCSBRKP int arg
111 So-called "POSIX version" of TCSBRK. It treats non-zero arg as a
112 timeinterval measured in deciseconds, and does nothing when the
113 driver does not support breaks.
114 TIOCSBRK void
116 Turn break on, that is, start sending zero bits.
117 TIOCCBRK void
119 Turn break off, that is, stop sending zero bits.
120 Software flow control
123 TCXONC int arg
124 Equivalent to tcflow(fd, arg).
125 See tcflow(3) for the argument values TCOOFF, TCOON, TCIOFF,
126 TCION.
127 Buffer count and flushing
130 FIONREAD int *argp
131 Get the number of bytes in the input buffer.
132 TIOCINQ int *argp
134 Same as FIONREAD.
135 TIOCOUTQ int *argp
137 Get the number of bytes in the output buffer.
138 TCFLSH int arg
140 Equivalent to tcflush(fd, arg).
141 See tcflush(3) for the argument values TCIFLUSH, TCOFLUSH,
142 TCIOFLUSH.
143 Faking input
146 TIOCSTI const char *argp
147 Insert the given byte in the input queue.
148 Redirecting console output
151 TIOCCONS void
152 Redirect output that would have gone to /dev/console or
153 /dev/tty0 to the given tty. If that was a pty master, send it to
154 the slave. Anybody can do this as long as the output was not
155 redirected yet. If it was redirected already EBUSY is returned,
156 but root may stop redirection by using this ioctl with fd point‐
157 ing at /dev/console or /dev/tty0.
158 Controlling tty
161 TIOCSCTTY int arg
162 Make the given tty the controlling tty of the current process.
163 The current process must be a session leader and not have a con‐
164 trolling tty already. If this tty is already the controlling tty
165 of a different session group then the ioctl fails with EPERM,
166 unless the caller is root and arg equals 1, in which case the
167 tty is stolen, and all processes that had it as controlling tty
168 lose it.
169 TIOCNOTTY void
171 If the given tty was the controlling tty of the current process,
172 give up this controlling tty. If the process was session leader,
173 then send SIGHUP and SIGCONT to the foreground process group and
174 all processes in the current session lose their controlling tty.
175 Process group and session ID
178 TIOCGPGRP pid_t *argp
179 When successful, equivalent to *argp = tcgetpgrp(fd).
180 Get the process group ID of the foreground process group on this
181 tty.
182 TIOCSPGRP const pid_t *argp
184 Equivalent to tcsetpgrp(fd, *argp).
185 Set the foreground process group ID of this tty.
186 TIOCGSID pid_t *argp
188 Get the session ID of the given tty. This will fail with ENOTTY
189 in case the tty is not a master pty and not our controlling tty.
190 Strange.
191 Exclusive mode
194 TIOCEXCL void
195 Put the tty into exclusive mode. No further open(2) operations
196 on the terminal are permitted. (They will fail with EBUSY,
197 except for root.)
198 TIOCNXCL void
200 Disable exclusive mode.
201 Line discipline
204 TIOCGETD int *argp
205 Get the line discipline of the tty.
206 TIOCSETD const int *argp
208 Set the line discipline of the tty.
209 Pseudo-tty ioctls
212 TIOCPKT const int *argp
213 Enable (when *argp is non-zero) or disable packet mode. Can be
214 applied to the master side of a pseudo-terminal only (and will
215 return ENOTTY otherwise). In packet mode, each subsequent
216 read(2) will return a packet that either contains a single non-
217 zero control byte, or has a single byte containing zero ('' ')
218 followed by data written on the slave side of the pty. If the
219 first byte is not TIOCPKT_DATA (0), it is an OR of one or more
220 of the following bits:
221 TIOCPKT_FLUSHREAD The read queue for the terminal is flushed.
223 TIOCPKT_FLUSHWRITE The write queue for the terminal is flushed.
224 TIOCPKT_STOP Output to the terminal is stopped.
225 TIOCPKT_START Output to the terminal is restarted.
226 TIOCPKT_DOSTOP t_stopc is `^S' and t_startc is `^Q'.
227 TIOCPKT_NOSTOP the start and stop characters are not `^S/^Q'.
228 While this mode is in use, the presence of control status infor‐
230 mation to be read from the master side may be detected by a
231 select(2) for exceptional conditions.
232 This mode is used by rlogin(1) and rlogind(8) to implement a
234 remote-echoed, locally `^S/^Q' flow-controlled remote login.
235 The BSD ioctls TIOCSTOP, TIOCSTART, TIOCUCNTL, TIOCREMOTE have
237 not been implemented under Linux.
238 Modem control
241 TIOCMGET int *argp
242 get the status of modem bits.
243 TIOCMSET const int *argp
245 set the status of modem bits.
246 TIOCMBIC const int *argp
248 clear the indicated modem bits.
249 TIOCMBIS const int *argp
251 set the indicated modem bits.
252 Bits used by these four ioctls:
254 TIOCM_LE DSR (data set ready/line enable)
256 TIOCM_DTR DTR (data terminal ready)
257 TIOCM_RTS RTS (request to send)
258 TIOCM_ST Secondary TXD (transmit)
259 TIOCM_SR Secondary RXD (receive)
260 TIOCM_CTS CTS (clear to send)
261 TIOCM_CAR DCD (data carrier detect)
262 TIOCM_CD see TIOCM_CAR
263 TIOCM_RNG RNG (ring)
264 TIOCM_RI see TIOCM_RNG
265 TIOCM_DSR DSR (data set ready)
266 Marking a line as local
269 TIOCGSOFTCAR int *argp
270 ("Get software carrier flag") Get the status of the CLOCAL flag
271 in the c_cflag field of the termios structure.
272 TIOCSSOFTCAR const int *argp
274 ("Set software carrier flag") Set the CLOCAL flag in the termios
275 structure when *argp is non-zero, and clear it otherwise.
276 If the CLOCAL flag for a line is off, the hardware carrier detect (DCD)
278 signal is significant, and an open(2) of the corresponding tty will
279 block until DCD is asserted, unless the O_NONBLOCK flag is given. If
280 CLOCAL is set, the line behaves as if DCD is always asserted. The
281 software carrier flag is usually turned on for local devices, and is
282 off for lines with modems.
283 Linux specific
286 For the TIOCLINUX ioctl, see console_ioctl(4).
287 Kernel debugging
290 #include <linux/tty.h>
291 TIOCTTYGSTRUCT struct tty_struct *argp
294 Get the tty_struct corresponding to fd.
295
298 The ioctl() system call returns 0 on success. On error it returns -1
299 and sets errno appropriately.
300
303 ENOIOCTLCMD
304 Unknown command.
305 EINVAL Invalid command parameter.
307 EPERM Insufficient permission.
309 ENOTTY Inappropriate fd.
311
313 Check the condition of DTR on the serial port.
314 #include <termios.h>
316 #include <fcntl.h>
317 #include <sys/ioctl.h>
318 main() {
320 int fd, serial;
321 fd = open("/dev/ttyS0", O_RDONLY);
323 ioctl(fd, TIOCMGET, &serial);
324 if (serial & TIOCM_DTR)
325 puts("TIOCM_DTR is not set");
326 else
327 puts("TIOCM_DTR is set");
328 close(fd);
329 }
330
333 ioctl(2), termios(3), console_ioctl(4), pty(7)
334Linux 2002-12-29 TTY_IOCTL(4)