1IOCTL_TTY(2)               Linux Programmer's Manual              IOCTL_TTY(2)
2
3
4

NAME

6       ioctl_tty - ioctls for terminals and serial lines
7

SYNOPSIS

9       #include <termios.h>
10
11       int ioctl(int fd, int cmd, ...);
12

DESCRIPTION

14       The  ioctl(2) call for terminals and serial ports accepts many possible
15       command arguments.  Most require a third  argument,  of  varying  type,
16       here called argp or arg.
17
18       Use  of  ioctl makes for nonportable programs.  Use the POSIX interface
19       described in termios(3) whenever possible.
20
21   Get and set terminal attributes
22       TCGETS    struct termios *argp
23              Equivalent to tcgetattr(fd, argp).
24              Get the current serial port settings.
25
26       TCSETS    const struct termios *argp
27              Equivalent to tcsetattr(fd, TCSANOW, argp).
28              Set the current serial port settings.
29
30       TCSETSW   const struct termios *argp
31              Equivalent to tcsetattr(fd, TCSADRAIN, argp).
32              Allow the output buffer to drain, and  set  the  current  serial
33              port settings.
34
35       TCSETSF   const struct termios *argp
36              Equivalent to tcsetattr(fd, TCSAFLUSH, argp).
37              Allow the output buffer to drain, discard pending input, and set
38              the current serial port settings.
39
40       The following four  ioctls  are  just  like  TCGETS,  TCSETS,  TCSETSW,
41       TCSETSF,  except  that  they take a struct termio * instead of a struct
42       termios *.
43
44              TCGETA    struct termio *argp
45
46              TCSETA    const struct termio *argp
47
48              TCSETAW   const struct termio *argp
49
50              TCSETAF   const struct termio *argp
51
52   Locking the termios structure
53       The termios structure of a terminal can be locked.  The lock is  itself
54       a  termios  structure,  with nonzero bits or fields indicating a locked
55       value.
56
57       TIOCGLCKTRMIOS struct termios *argp
58              Gets the locking status of the termios structure of  the  termi‐
59              nal.
60
61       TIOCSLCKTRMIOS const struct termios *argp
62              Sets  the  locking status of the termios structure of the termi‐
63              nal.  Only a process with the CAP_SYS_ADMIN  capability  can  do
64              this.
65
66   Get and set window size
67       Window sizes are kept in the kernel, but not used by the kernel (except
68       in the case of virtual consoles, where the kernel will update the  win‐
69       dow  size when the size of the virtual console changes, for example, by
70       loading a new font).
71
72       The following constants and structure are defined in <sys/ioctl.h>.
73
74       TIOCGWINSZ     struct winsize *argp
75              Get window size.
76
77       TIOCSWINSZ     const struct winsize *argp
78              Set window size.
79
80       The struct used by these ioctls is defined as
81
82           struct winsize {
83               unsigned short ws_row;
84               unsigned short ws_col;
85               unsigned short ws_xpixel;   /* unused */
86               unsigned short ws_ypixel;   /* unused */
87           };
88
89       When the window size changes, a SIGWINCH signal is sent  to  the  fore‐
90       ground process group.
91
92   Sending a break
93       TCSBRK    int arg
94              Equivalent to tcsendbreak(fd, arg).
95              If  the terminal is using asynchronous serial data transmission,
96              and arg is zero, then send a break (a stream of zero  bits)  for
97              between  0.25  and  0.5  seconds.   If the terminal is not using
98              asynchronous serial data transmission, then either  a  break  is
99              sent,  or the function returns without doing anything.  When arg
100              is nonzero, nobody knows what will happen.
101
102              (SVr4, UnixWare, Solaris, Linux treat  tcsendbreak(fd,arg)  with
103              nonzero arg like tcdrain(fd).  SunOS treats arg as a multiplier,
104              and sends a stream of bits arg times as long as  done  for  zero
105              arg.   DG/UX and AIX treat arg (when nonzero) as a time interval
106              measured in milliseconds.  HP-UX ignores arg.)
107
108       TCSBRKP   int arg
109              So-called "POSIX version" of TCSBRK.  It treats nonzero arg as a
110              timeinterval  measured in deciseconds, and does nothing when the
111              driver does not support breaks.
112
113       TIOCSBRK  void
114              Turn break on, that is, start sending zero bits.
115
116       TIOCCBRK  void
117              Turn break off, that is, stop sending zero bits.
118
119   Software flow control
120       TCXONC    int arg
121              Equivalent to tcflow(fd, arg).
122              See tcflow(3) for the argument  values  TCOOFF,  TCOON,  TCIOFF,
123              TCION.
124
125   Buffer count and flushing
126       FIONREAD  int *argp
127              Get the number of bytes in the input buffer.
128
129       TIOCINQ   int *argp
130              Same as FIONREAD.
131
132       TIOCOUTQ  int *argp
133              Get the number of bytes in the output buffer.
134
135       TCFLSH    int arg
136              Equivalent to tcflush(fd, arg).
137              See  tcflush(3)  for  the  argument  values  TCIFLUSH, TCOFLUSH,
138              TCIOFLUSH.
139
140   Faking input
141       TIOCSTI   const char *argp
142              Insert the given byte in the input queue.
143
144   Redirecting console output
145       TIOCCONS  void
146              Redirect  output  that  would  have  gone  to  /dev/console   or
147              /dev/tty0  to  the given terminal.  If that was a pseudoterminal
148              master, send it to the slave.  In Linux before  version  2.6.10,
149              anybody  can  do  this  as long as the output was not redirected
150              yet; since version 2.6.10, only a process with the CAP_SYS_ADMIN
151              capability  may do this.  If output was redirected already EBUSY
152              is returned, but redirection can be stopped by using this  ioctl
153              with fd pointing at /dev/console or /dev/tty0.
154
155   Controlling terminal
156       TIOCSCTTY int arg
157              Make  the given terminal the controlling terminal of the calling
158              process.  The calling process must be a session leader  and  not
159              have  a controlling terminal already.  For this case, arg should
160              be specified as zero.
161
162              If this terminal is already the controlling terminal of  a  dif‐
163              ferent  session  group,  then the ioctl fails with EPERM, unless
164              the caller has the CAP_SYS_ADMIN capability and arg equals 1, in
165              which case the terminal is stolen, and all processes that had it
166              as controlling terminal lose it.
167
168       TIOCNOTTY void
169              If the given terminal was the controlling terminal of the  call‐
170              ing  process, give up this controlling terminal.  If the process
171              was session leader, then send SIGHUP and SIGCONT  to  the  fore‐
172              ground  process  group  and all processes in the current session
173              lose their controlling terminal.
174
175   Process group and session ID
176       TIOCGPGRP pid_t *argp
177              When successful, equivalent to *argp = tcgetpgrp(fd).
178              Get the process group ID of the foreground process group on this
179              terminal.
180
181       TIOCSPGRP const pid_t *argp
182              Equivalent to tcsetpgrp(fd, *argp).
183              Set the foreground process group ID of this terminal.
184
185       TIOCGSID  pid_t *argp
186              Get  the  session ID of the given terminal.  This fails with the
187              error ENOTTY if the terminal is not a master pseudoterminal  and
188              not our controlling terminal.  Strange.
189
190   Exclusive mode
191       TIOCEXCL  void
192              Put the terminal into exclusive mode.  No further open(2) opera‐
193              tions on the terminal are permitted.   (They  fail  with  EBUSY,
194              except for a process with the CAP_SYS_ADMIN capability.)
195
196       TIOCGEXCL int *argp
197              (since  Linux  3.8)  If  the  terminal is currently in exclusive
198              mode, place a nonzero value in the location pointed to by  argp;
199              otherwise, place zero in *argp.
200
201       TIOCNXCL  void
202              Disable exclusive mode.
203
204   Line discipline
205       TIOCGETD  int *argp
206              Get the line discipline of the terminal.
207
208       TIOCSETD  const int *argp
209              Set the line discipline of the terminal.
210
211   Pseudoterminal ioctls
212       TIOCPKT   const int *argp
213              Enable  (when  *argp is nonzero) or disable packet mode.  Can be
214              applied to the master side of a pseudoterminal  only  (and  will
215              return  ENOTTY  otherwise).   In  packet  mode,  each subsequent
216              read(2) will return a  packet  that  either  contains  a  single
217              nonzero control byte, or has a single byte containing zero (' ')
218              followed by data written on the slave side of  the  pseudotermi‐
219              nal.   If the first byte is not TIOCPKT_DATA (0), it is an OR of
220              one or more of the following bits:
221
222              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      The start and stop characters are ^S/^Q.
227              TIOCPKT_NOSTOP      The start and stop characters are not ^S/^Q.
228
229              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 or a poll(2) for the  POLL‐
232              PRI event.
233
234              This  mode  is  used  by rlogin(1) and rlogind(8) to implement a
235              remote-echoed, locally ^S/^Q flow-controlled remote login.
236
237       TIOCGPKT  const int *argp
238              (since Linux 3.8) Return the current packet mode setting in  the
239              integer pointed to by argp.
240
241       TIOCSPTLCK     int *argp
242              Set (if *argp is nonzero) or remove (if *argp is zero) the pseu‐
243              doterminal slave device.  (See also unlockpt(3).)
244
245       TIOCGPTLCK     int *argp
246              (since Linux 3.8) Place the current lock state of the pseudoter‐
247              minal slave device in the location pointed to by argp.
248
249       TIOCGPTPEER    int flags
250              (since  Linux 4.13) Given a file descriptor in fd that refers to
251              a pseudoterminal master,  open  (with  the  given  open(2)-style
252              flags)  and return a new file descriptor that refers to the peer
253              pseudoterminal slave device.  This operation  can  be  performed
254              regardless of whether the pathname of the slave device is acces‐
255              sible through the calling process's mount namespace.
256
257              Security-conscious programs interacting with namespaces may wish
258              to  use  this  operation  rather  than open(2) with the pathname
259              returned by ptsname(3), and similar library functions that  have
260              insecure  APIs.  (For example, confusion can occur in some cases
261              using ptsname(3) with a pathname where a devpts  filesystem  has
262              been mounted in a different mount namespace.)
263
264       The BSD ioctls TIOCSTOP, TIOCSTART, TIOCUCNTL, TIOCREMOTE have not been
265       implemented under Linux.
266
267   Modem control
268       TIOCMGET  int *argp
269              Get the status of modem bits.
270
271       TIOCMSET  const int *argp
272              Set the status of modem bits.
273
274       TIOCMBIC  const int *argp
275              Clear the indicated modem bits.
276
277       TIOCMBIS  const int *argp
278              Set the indicated modem bits.
279
280       The following bits are used by the above ioctls:
281
282       TIOCM_LE        DSR (data set ready/line enable)
283       TIOCM_DTR       DTR (data terminal ready)
284       TIOCM_RTS       RTS (request to send)
285       TIOCM_ST        Secondary TXD (transmit)
286       TIOCM_SR        Secondary RXD (receive)
287       TIOCM_CTS       CTS (clear to send)
288       TIOCM_CAR       DCD (data carrier detect)
289       TIOCM_CD         see TIOCM_CAR
290       TIOCM_RNG       RNG (ring)
291       TIOCM_RI         see TIOCM_RNG
292       TIOCM_DSR       DSR (data set ready)
293
294       TIOCMIWAIT     int arg
295              Wait for any of the 4 modem bits (DCD, RI, DSR, CTS) to  change.
296              The  bits  of  interest  are  specified as a bit mask in arg, by
297              ORing together any of  the  bit  values,  TIOCM_RNG,  TIOCM_DSR,
298              TIOCM_CD,  and  TIOCM_CTS.  The caller should use TIOCGICOUNT to
299              see which bit has changed.
300
301       TIOCGICOUNT    struct serial_icounter_struct *argp
302              Get counts of input serial line interrupts (DCD, RI, DSR,  CTS).
303              The  counts  are written to the serial_icounter_struct structure
304              pointed to by argp.
305
306              Note: both 1->0 and 0->1 transitions are counted, except for RI,
307              where only 0->1 transitions are counted.
308
309   Marking a line as local
310       TIOCGSOFTCAR   int *argp
311              ("Get  software carrier flag") Get the status of the CLOCAL flag
312              in the c_cflag field of the termios structure.
313
314       TIOCSSOFTCAR   const int *argp
315              ("Set software carrier flag") Set the CLOCAL flag in the termios
316              structure when *argp is nonzero, and clear it otherwise.
317
318       If the CLOCAL flag for a line is off, the hardware carrier detect (DCD)
319       signal is significant, and an open(2)  of  the  corresponding  terminal
320       will  block until DCD is asserted, unless the O_NONBLOCK flag is given.
321       If CLOCAL is set, the line behaves as if DCD is always  asserted.   The
322       software  carrier  flag  is usually turned on for local devices, and is
323       off for lines with modems.
324
325   Linux-specific
326       For the TIOCLINUX ioctl, see ioctl_console(2).
327
328   Kernel debugging
329       #include <linux/tty.h>
330
331       TIOCTTYGSTRUCT struct tty_struct *argp
332              Get the  tty_struct  corresponding  to  fd.   This  command  was
333              removed in Linux 2.5.67.
334

RETURN VALUE

336       The ioctl(2) system call returns 0 on success.  On error, it returns -1
337       and sets errno appropriately.
338

ERRORS

340       EINVAL Invalid command parameter.
341
342       ENOIOCTLCMD
343              Unknown command.
344
345       ENOTTY Inappropriate fd.
346
347       EPERM  Insufficient permission.
348

EXAMPLE

350       Check the condition of DTR on the serial port.
351
352       #include <termios.h>
353       #include <fcntl.h>
354       #include <sys/ioctl.h>
355
356       int
357       main(void)
358       {
359           int fd, serial;
360
361           fd = open("/dev/ttyS0", O_RDONLY);
362           ioctl(fd, TIOCMGET, &serial);
363           if (serial & TIOCM_DTR)
364               puts("TIOCM_DTR is set");
365           else
366               puts("TIOCM_DTR is not set");
367           close(fd);
368       }
369

SEE ALSO

371       ldattach(1), ioctl(2), ioctl_console(2), termios(3), pty(7)
372

COLOPHON

374       This page is part of release 4.16 of the Linux  man-pages  project.   A
375       description  of  the project, information about reporting bugs, and the
376       latest    version    of    this    page,    can     be     found     at
377       https://www.kernel.org/doc/man-pages/.
378
379
380
381Linux                             2017-09-15                      IOCTL_TTY(2)
Impressum