1ioctl_tty(2)                  System Calls Manual                 ioctl_tty(2)
2
3
4

NAME

6       ioctl_tty - ioctls for terminals and serial lines
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <sys/ioctl.h>
13       #include <asm/termbits.h>   /* Definition of struct termios,
14                                      struct termios2, and
15                                      Bnnn, BOTHER, CBAUD, CLOCAL,
16                                      TC*{FLUSH,ON,OFF} and other constants */
17
18       int ioctl(int fd, int cmd, ...);
19

DESCRIPTION

21       The  ioctl(2) call for terminals and serial ports accepts many possible
22       command arguments.  Most require a third  argument,  of  varying  type,
23       here called argp or arg.
24
25       Use of ioctl() makes for nonportable programs.  Use the POSIX interface
26       described in termios(3) whenever possible.
27
28       Please note that struct termios from <asm/termbits.h> is different  and
29       incompatible  with  struct termios from <termios.h>.  These ioctl calls
30       require struct termios from <asm/termbits.h>.
31
32   Get and set terminal attributes
33       TCGETS Argument: struct termios *argp
34
35              Equivalent to tcgetattr(fd, argp).
36
37              Get the current serial port settings.
38
39       TCSETS Argument: const struct termios *argp
40
41              Equivalent to tcsetattr(fd, TCSANOW, argp).
42
43              Set the current serial port settings.
44
45       TCSETSW
46              Argument: const struct termios *argp
47
48              Equivalent to tcsetattr(fd, TCSADRAIN, argp).
49
50              Allow the output buffer to drain, and  set  the  current  serial
51              port settings.
52
53       TCSETSF
54              Argument: const struct termios *argp
55
56              Equivalent to tcsetattr(fd, TCSAFLUSH, argp).
57
58              Allow the output buffer to drain, discard pending input, and set
59              the current serial port settings.
60
61       The following four ioctls, added in Linux 2.6.20, are just like TCGETS,
62       TCSETS, TCSETSW, TCSETSF, except that they take a struct termios2 * in‐
63       stead of a struct termios *.  If the structure member c_cflag  contains
64       the  flag BOTHER, then the baud rate is stored in the structure members
65       c_ispeed and c_ospeed as integer values.  These  ioctls  are  not  sup‐
66       ported on all architectures.
67
68              TCGETS2    struct termios2 *argp
69              TCSETS2    const struct termios2 *argp
70              TCSETSW2   const struct termios2 *argp
71              TCSETSF2   const struct termios2 *argp
72
73       The  following  four  ioctls are just like TCGETS, TCSETS, TCSETSW, TC‐
74       SETSF, except that they take a struct termio  *  instead  of  a  struct
75       termios *.
76
77              TCGETA    struct termio *argp
78              TCSETA    const struct termio *argp
79              TCSETAW   const struct termio *argp
80              TCSETAF   const struct termio *argp
81
82   Locking the termios structure
83       The  termios structure of a terminal can be locked.  The lock is itself
84       a termios structure, with nonzero bits or fields  indicating  a  locked
85       value.
86
87       TIOCGLCKTRMIOS
88              Argument: struct termios *argp
89
90              Gets  the  locking status of the termios structure of the termi‐
91              nal.
92
93       TIOCSLCKTRMIOS
94              Argument: const struct termios *argp
95
96              Sets the locking status of the termios structure of  the  termi‐
97              nal.   Only  a  process with the CAP_SYS_ADMIN capability can do
98              this.
99
100   Get and set window size
101       Window sizes are kept in the kernel, but not used by the kernel (except
102       in  the case of virtual consoles, where the kernel will update the win‐
103       dow size when the size of the virtual console changes, for example,  by
104       loading a new font).
105
106       TIOCGWINSZ
107              Argument: struct winsize *argp
108
109              Get window size.
110
111       TIOCSWINSZ
112              Argument: const struct winsize *argp
113
114              Set window size.
115
116       The struct used by these ioctls is defined as
117
118           struct winsize {
119               unsigned short ws_row;
120               unsigned short ws_col;
121               unsigned short ws_xpixel;   /* unused */
122               unsigned short ws_ypixel;   /* unused */
123           };
124
125       When  the  window  size changes, a SIGWINCH signal is sent to the fore‐
126       ground process group.
127
128   Sending a break
129       TCSBRK Argument: int arg
130
131              Equivalent to tcsendbreak(fd, arg).
132
133              If the terminal is using asynchronous serial data  transmission,
134              and  arg  is zero, then send a break (a stream of zero bits) for
135              between 0.25 and 0.5 seconds.  If  the  terminal  is  not  using
136              asynchronous  serial  data  transmission, then either a break is
137              sent, or the function returns without doing anything.  When  arg
138              is nonzero, nobody knows what will happen.
139
140              (SVr4,  UnixWare,  Solaris,  and Linux treat tcsendbreak(fd,arg)
141              with nonzero arg like tcdrain(fd).  SunOS treats arg as a multi‐
142              plier,  and sends a stream of bits arg times as long as done for
143              zero arg.  DG/UX and AIX treat arg (when nonzero) as a time  in‐
144              terval measured in milliseconds.  HP-UX ignores arg.)
145
146       TCSBRKP
147              Argument: int arg
148
149              So-called "POSIX version" of TCSBRK.  It treats nonzero arg as a
150              time interval measured in deciseconds, and does nothing when the
151              driver does not support breaks.
152
153       TIOCSBRK
154              Argument: void
155
156              Turn break on, that is, start sending zero bits.
157
158       TIOCCBRK
159              Argument: void
160
161              Turn break off, that is, stop sending zero bits.
162
163   Software flow control
164       TCXONC Argument: int arg
165
166              Equivalent to tcflow(fd, arg).
167
168              See  tcflow(3)  for  the  argument values TCOOFF, TCOON, TCIOFF,
169              TCION.
170
171   Buffer count and flushing
172       FIONREAD
173              Argument: int *argp
174
175              Get the number of bytes in the input buffer.
176
177       TIOCINQ
178              Argument: int *argp
179
180              Same as FIONREAD.
181
182       TIOCOUTQ
183              Argument: int *argp
184
185              Get the number of bytes in the output buffer.
186
187       TCFLSH Argument: int arg
188
189              Equivalent to tcflush(fd, arg).
190
191              See tcflush(3)  for  the  argument  values  TCIFLUSH,  TCOFLUSH,
192              TCIOFLUSH.
193
194       TIOCSERGETLSR
195              Argument: int *argp
196
197              Get  line status register.  Status register has TIOCSER_TEMT bit
198              set when output buffer is empty and also hardware transmitter is
199              physically empty.
200
201              Does not have to be supported by all serial tty drivers.
202
203              tcdrain(3)  does  not  wait  and  returns  immediately  when TI‐
204              OCSER_TEMT bit is set.
205
206   Faking input
207       TIOCSTI
208              Argument: const char *argp
209
210              Insert the given byte in the input queue.
211
212   Redirecting console output
213       TIOCCONS
214              Argument: void
215
216              Redirect  output  that  would  have  gone  to  /dev/console   or
217              /dev/tty0  to  the given terminal.  If that was a pseudoterminal
218              master, send it to the slave.  Before Linux 2.6.10, anybody  can
219              do  this  as  long  as  the output was not redirected yet; since
220              Linux 2.6.10, only a process with the  CAP_SYS_ADMIN  capability
221              may  do  this.   If output was redirected already, then EBUSY is
222              returned, but redirection can be stopped  by  using  this  ioctl
223              with fd pointing at /dev/console or /dev/tty0.
224
225   Controlling terminal
226       TIOCSCTTY
227              Argument: int arg
228
229              Make  the given terminal the controlling terminal of the calling
230              process.  The calling process must be a session leader  and  not
231              have  a controlling terminal already.  For this case, arg should
232              be specified as zero.
233
234              If this terminal is already the controlling terminal of  a  dif‐
235              ferent  session  group,  then the ioctl fails with EPERM, unless
236              the caller has the CAP_SYS_ADMIN capability and arg equals 1, in
237              which case the terminal is stolen, and all processes that had it
238              as controlling terminal lose it.
239
240       TIOCNOTTY
241              Argument: void
242
243              If the given terminal was the controlling terminal of the  call‐
244              ing  process, give up this controlling terminal.  If the process
245              was session leader, then send SIGHUP and SIGCONT  to  the  fore‐
246              ground  process  group  and all processes in the current session
247              lose their controlling terminal.
248
249   Process group and session ID
250       TIOCGPGRP
251              Argument: pid_t *argp
252
253              When successful, equivalent to *argp = tcgetpgrp(fd).
254
255              Get the process group ID of the foreground process group on this
256              terminal.
257
258       TIOCSPGRP
259              Argument: const pid_t *argp
260
261              Equivalent to tcsetpgrp(fd, *argp).
262
263              Set the foreground process group ID of this terminal.
264
265       TIOCGSID
266              Argument: pid_t *argp
267
268              When successful, equivalent to *argp = tcgetsid(fd).
269
270              Get  the  session ID of the given terminal.  This fails with the
271              error ENOTTY if the terminal is not a master pseudoterminal  and
272              not our controlling terminal.  Strange.
273
274   Exclusive mode
275       TIOCEXCL
276              Argument: void
277
278              Put the terminal into exclusive mode.  No further open(2) opera‐
279              tions on the terminal are permitted.  (They fail with EBUSY, ex‐
280              cept for a process with the CAP_SYS_ADMIN capability.)
281
282       TIOCGEXCL
283              Argument: int *argp
284
285              (since  Linux  3.8)  If  the  terminal is currently in exclusive
286              mode, place a nonzero value in the location pointed to by  argp;
287              otherwise, place zero in *argp.
288
289       TIOCNXCL
290              Argument: void
291
292              Disable exclusive mode.
293
294   Line discipline
295       TIOCGETD
296              Argument: int *argp
297
298              Get the line discipline of the terminal.
299
300       TIOCSETD
301              Argument: const int *argp
302
303              Set the line discipline of the terminal.
304
305   Pseudoterminal ioctls
306       TIOCPKT
307              Argument: const int *argp
308
309              Enable  (when  *argp is nonzero) or disable packet mode.  Can be
310              applied to the master side of a pseudoterminal  only  (and  will
311              return  ENOTTY  otherwise).   In  packet  mode,  each subsequent
312              read(2) will return a packet that either contains a single  non‐
313              zero  control  byte, or has a single byte containing zero ('\0')
314              followed by data written on the slave side of  the  pseudotermi‐
315              nal.   If the first byte is not TIOCPKT_DATA (0), it is an OR of
316              one or more of the following bits:
317
318              TIOCPKT_FLUSHREAD    The read queue for the
319                                   terminal is flushed.
320              TIOCPKT_FLUSHWRITE   The write queue for the
321                                   terminal is flushed.
322              TIOCPKT_STOP         Output to the terminal is
323                                   stopped.
324              TIOCPKT_START        Output to the terminal is
325                                   restarted.
326              TIOCPKT_DOSTOP       The start and stop charac‐
327                                   ters are ^S/^Q.
328              TIOCPKT_NOSTOP       The start and stop charac‐
329                                   ters are not ^S/^Q.
330
331              While packet mode is in use, the presence of control status  in‐
332              formation  to  be read from the master side may be detected by a
333              select(2) for exceptional conditions or a poll(2) for the  POLL‐
334              PRI event.
335
336              This mode is used by rlogin(1) and rlogind(8) to implement a re‐
337              mote-echoed, locally ^S/^Q flow-controlled remote login.
338
339       TIOCGPKT
340              Argument: const int *argp
341
342              (since Linux 3.8) Return the current packet mode setting in  the
343              integer pointed to by argp.
344
345       TIOCSPTLCK
346              Argument: int *argp
347
348              Set  (if *argp is nonzero) or remove (if *argp is zero) the lock
349              on the pseudoterminal slave device.  (See also unlockpt(3).)
350
351       TIOCGPTLCK
352              Argument: int *argp
353
354              (since Linux 3.8) Place the current lock state of the pseudoter‐
355              minal slave device in the location pointed to by argp.
356
357       TIOCGPTPEER
358              Argument: int flags
359
360              (since  Linux 4.13) Given a file descriptor in fd that refers to
361              a pseudoterminal master,  open  (with  the  given  open(2)-style
362              flags)  and return a new file descriptor that refers to the peer
363              pseudoterminal slave device.  This operation  can  be  performed
364              regardless of whether the pathname of the slave device is acces‐
365              sible through the calling process's mount namespace.
366
367              Security-conscious programs interacting with namespaces may wish
368              to  use this operation rather than open(2) with the pathname re‐
369              turned by ptsname(3), and similar library  functions  that  have
370              insecure  APIs.  (For example, confusion can occur in some cases
371              using ptsname(3) with a pathname where a devpts  filesystem  has
372              been mounted in a different mount namespace.)
373
374       The  BSD ioctls TIOCSTOP, TIOCSTART, TIOCUCNTL, and TIOCREMOTE have not
375       been implemented under Linux.
376
377   Modem control
378       TIOCMGET
379              Argument: int *argp
380
381              Get the status of modem bits.
382
383       TIOCMSET
384              Argument: const int *argp
385
386              Set the status of modem bits.
387
388       TIOCMBIC
389              Argument: const int *argp
390
391              Clear the indicated modem bits.
392
393       TIOCMBIS
394              Argument: const int *argp
395
396              Set the indicated modem bits.
397
398       The following bits are used by the above ioctls:
399
400       TIOCM_LE    DSR (data set ready/line enable)
401       TIOCM_DTR   DTR (data terminal ready)
402       TIOCM_RTS   RTS (request to send)
403       TIOCM_ST    Secondary TXD (transmit)
404       TIOCM_SR    Secondary RXD (receive)
405       TIOCM_CTS   CTS (clear to send)
406       TIOCM_CAR   DCD (data carrier detect)
407       TIOCM_CD    see TIOCM_CAR
408       TIOCM_RNG   RNG (ring)
409       TIOCM_RI    see TIOCM_RNG
410       TIOCM_DSR   DSR (data set ready)
411
412       TIOCMIWAIT
413              Argument: int arg
414
415              Wait for any of the 4 modem bits (DCD, RI, DSR, CTS) to  change.
416              The  bits of interest are specified as a bit mask in arg, by OR‐
417              ing together any of the bit values,  TIOCM_RNG,  TIOCM_DSR,  TI‐
418              OCM_CD, and TIOCM_CTS.  The caller should use TIOCGICOUNT to see
419              which bit has changed.
420
421       TIOCGICOUNT
422              Argument: struct serial_icounter_struct *argp
423
424              Get counts of input serial line interrupts (DCD, RI, DSR,  CTS).
425              The  counts  are written to the serial_icounter_struct structure
426              pointed to by argp.
427
428              Note: both 1->0 and 0->1 transitions are counted, except for RI,
429              where only 0->1 transitions are counted.
430
431   Marking a line as local
432       TIOCGSOFTCAR
433              Argument: int *argp
434
435              ("Get  software carrier flag") Get the status of the CLOCAL flag
436              in the c_cflag field of the termios structure.
437
438       TIOCSSOFTCAR
439              Argument: const int *argp
440
441              ("Set software carrier flag") Set the CLOCAL flag in the termios
442              structure when *argp is nonzero, and clear it otherwise.
443
444       If the CLOCAL flag for a line is off, the hardware carrier detect (DCD)
445       signal is significant, and an open(2)  of  the  corresponding  terminal
446       will  block until DCD is asserted, unless the O_NONBLOCK flag is given.
447       If CLOCAL is set, the line behaves as if DCD is always  asserted.   The
448       software  carrier  flag  is usually turned on for local devices, and is
449       off for lines with modems.
450
451   Linux-specific
452       For the TIOCLINUX ioctl, see ioctl_console(2).
453
454   Kernel debugging
455       #include <linux/tty.h>
456
457       TIOCTTYGSTRUCT
458              Argument: struct tty_struct *argp
459
460              Get the tty_struct corresponding to fd.  This  command  was  re‐
461              moved in Linux 2.5.67.
462

RETURN VALUE

464       The ioctl(2) system call returns 0 on success.  On error, it returns -1
465       and sets errno to indicate the error.
466

ERRORS

468       EINVAL Invalid command parameter.
469
470       ENOIOCTLCMD
471              Unknown command.
472
473       ENOTTY Inappropriate fd.
474
475       EPERM  Insufficient permission.
476

EXAMPLES

478       Check the condition of DTR on the serial port.
479
480       #include <fcntl.h>
481       #include <stdio.h>
482       #include <sys/ioctl.h>
483       #include <unistd.h>
484
485       int
486       main(void)
487       {
488           int fd, serial;
489
490           fd = open("/dev/ttyS0", O_RDONLY);
491           ioctl(fd, TIOCMGET, &serial);
492           if (serial & TIOCM_DTR)
493               puts("TIOCM_DTR is set");
494           else
495               puts("TIOCM_DTR is not set");
496           close(fd);
497       }
498
499       Get or set arbitrary baudrate on the serial port.
500
501       /* SPDX-License-Identifier: GPL-2.0-or-later */
502
503       #include <asm/termbits.h>
504       #include <fcntl.h>
505       #include <stdio.h>
506       #include <stdlib.h>
507       #include <sys/ioctl.h>
508       #include <unistd.h>
509
510       int
511       main(int argc, char *argv[])
512       {
513       #if !defined BOTHER
514           fprintf(stderr, "BOTHER is unsupported\n");
515           /* Program may fallback to TCGETS/TCSETS with Bnnn constants */
516           exit(EXIT_FAILURE);
517       #else
518           /* Declare tio structure, its type depends on supported ioctl */
519       # if defined TCGETS2
520           struct termios2 tio;
521       # else
522           struct termios tio;
523       # endif
524           int fd, rc;
525
526           if (argc != 2 && argc != 3 && argc != 4) {
527               fprintf(stderr, "Usage: %s device [output [input] ]\n", argv[0]);
528               exit(EXIT_FAILURE);
529           }
530
531           fd = open(argv[1], O_RDWR | O_NONBLOCK | O_NOCTTY);
532           if (fd < 0) {
533               perror("open");
534               exit(EXIT_FAILURE);
535           }
536
537           /* Get the current serial port settings via supported ioctl */
538       # if defined TCGETS2
539           rc = ioctl(fd, TCGETS2, &tio);
540       # else
541           rc = ioctl(fd, TCGETS, &tio);
542       # endif
543           if (rc) {
544               perror("TCGETS");
545               close(fd);
546               exit(EXIT_FAILURE);
547           }
548
549           /* Change baud rate when more arguments were provided */
550           if (argc == 3 || argc == 4) {
551               /* Clear the current output baud rate and fill a new value */
552               tio.c_cflag &= ~CBAUD;
553               tio.c_cflag |= BOTHER;
554               tio.c_ospeed = atoi(argv[2]);
555
556               /* Clear the current input baud rate and fill a new value */
557               tio.c_cflag &= ~(CBAUD << IBSHIFT);
558               tio.c_cflag |= BOTHER << IBSHIFT;
559               /* When 4th argument is not provided reuse output baud rate */
560               tio.c_ispeed = (argc == 4) ? atoi(argv[3]) : atoi(argv[2]);
561
562               /* Set new serial port settings via supported ioctl */
563       # if defined TCSETS2
564               rc = ioctl(fd, TCSETS2, &tio);
565       # else
566               rc = ioctl(fd, TCSETS, &tio);
567       # endif
568               if (rc) {
569                   perror("TCSETS");
570                   close(fd);
571                   exit(EXIT_FAILURE);
572               }
573
574               /* And get new values which were really configured */
575       # if defined TCGETS2
576               rc = ioctl(fd, TCGETS2, &tio);
577       # else
578               rc = ioctl(fd, TCGETS, &tio);
579       # endif
580               if (rc) {
581                   perror("TCGETS");
582                   close(fd);
583                   exit(EXIT_FAILURE);
584               }
585           }
586
587           close(fd);
588
589           printf("output baud rate: %u\n", tio.c_ospeed);
590           printf("input baud rate: %u\n", tio.c_ispeed);
591
592           exit(EXIT_SUCCESS);
593       #endif
594       }
595

SEE ALSO

597       ldattach(8), ioctl(2), ioctl_console(2), termios(3), pty(7)
598
599
600
601Linux man-pages 6.04              2023-02-05                      ioctl_tty(2)
Impressum