tcflush() — Flush input or output on a terminal

Standards

Standards / Extensions	C or C++	Dependencies
POSIX.1 XPG4 XPG4.2 Single UNIX Specification, Version 3	both

Format

#define _POSIX_SOURCE
#include <termios.h>

int tcflush(int fildes, int where);

General description

Flushes input or output on a terminal.

int fildes;

Indicates a file descriptor associated with a terminal device.

int where;

Indicates whether the system is to flush input or output, represented by one of the following symbols defined in the termios.h header file.

Symbol: Meaning
TCIFLUSH: Flushes input data that has been received by the system but not read by an application.
TCOFLUSH: Flushes output data that has been written by an application but not sent to the terminal.
TCIOFLUSH: Flushes both input and output data.

If tcflush() is called from a background process group against the caller's controlling terminal, a SIGTTOU signal may be generated depending how the process is handling SIGTTOUs:

Processing for SIGTTOU	System Behavior
Default or signal handler	The SIGTTOU signal is generated, and the function is not performed. tcflush() returns -1 and sets errno to EINTR.
Ignored or blocked	The SIGTTOU signal is not sent, and the function continues normally.

Returned value

If successful, tcflush() returns 0.

If unsuccessful, tcflush() returns -1 and sets errno to one of the following values:

Error Code: Description
EBADF: fildes is not a valid open file descriptor.
EINTR: A signal interrupted tcflush().
EINVAL: where has an incorrect value.
EIO: The process group of the process issuing the function is an orphaned, background process group, and the process issuing the function is not ignoring or blocking SIGTTOU.
ENOTTY: fildes is not associated with a terminal.

Example

CELEBT05

⁄* CELEBT05

   This example flushes a string.

 *⁄
#define _POSIX_SOURCE
#include <termios.h>
#include <stdio.h>
#include <fcntl.h>
#include <unistd.h>
#include <sys⁄stat.h>

main() {
  char Master[]="master.tty";
  char Slave[]="slave.tty";
  char text1[]="string that will be flushed from buffer";
  char text2[]="string that will not be flushed from buffer";
  char data[80];
  int  master, slave;

  if (mknod(Master, S_IFCHR|S_IRUSR|S_IWUSR, 0x00010000 + 10) != 0)
    perror("mknod() error for master tty");
  else {
    if (mknod(Slave, S_IFCHR|S_IRUSR|S_IWUSR, 0x00020000 + 10) != 0)
      perror("mknod() error for slave tty");
    else {
      if ((master = open(Master, O_RDWR|O_NONBLOCK)) < 0)
        perror("open() error for master tty");
      else {
        if ((slave = open(Slave, O_RDWR|O_NONBLOCK)) < 0)
          perror("open() error for slave tty");
        else {
          if (write(slave, text1, strlen(text1)+1) == -1)
            perror("write() error");
          else if (tcflush(slave, TCOFLUSH) != 0)
            perror("tcflush() error");
          else {
            puts("first string is written and tty flushed");
            puts("now writing string that will not be flushed");
            if (write(slave, text2, strlen(text2)+1) == -1)
              perror("write() error");
            else if (read(master, data, sizeof(data)) == -1)
              perror("read() error");
            else printf("read '%s' from the tty\n", data);
          }
          close(slave);
        }
        close(master);
      }
      unlink(Slave);
    }
    unlink(Master);
  }
}

Output

first string is written and tty flushed
now writing string that will not be flushed
read 'string that will not be flushed from buffer' from the tty