tcflow() — Suspend or resume data flow 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 tcflow(int fildes, int action);

General description

Suspends or resumes transmission or reception of data on a terminal device.

int fildes

A file descriptor associated with a terminal device.

int action

Indicates the action you want to perform, represented by one of the following symbols defined in the termios.h include file:

Symbol: Meaning
TCOOFF: Suspends output.
TCOON: Resumes suspended output.
TCIOFF: Sends a STOP character to the terminal, to stop the terminal from sending any further input.
TCION: Sends a START character to the terminal, to tell the terminal that it can resume sending input.

If tcflow() 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. tcflow() 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, tcflow() returns 0.

If unsuccessful, tcflow() 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 tcflow().

EINVAL

action had an incorrect value.

EIO

For either of the following reasons:

TCIOFF or TCION was requested, but the other side of the pseudoterminal connection is closed.
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

CELEBT04

⁄* CELEBT04

    This example suspends and then resumes transmission.

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

 main() {
   char Master[]="⁄dev⁄ptyp0010";
   char Slave[]="⁄dev⁄ttyp0010";
   char text[]="tesxt to be written to tty";
   char data[80];
   int master, slave;

   if ((master = open(Master, O_RDWR|O_NONBLOCK)) < 0) {
     perror("open() error for master tty");
     exit(1);
   }
   if ((slave = open(Slave, O_RDWR|O_NONBLOCK)) < 0) {
     perror("open() error for slave tty");
     exit(1);

   if (write(slave, text, strlen(text)+1) == -1) {
     perror("write() error");
     exit(1);
   }
   puts("output is suspended to tty");
   if (read(master, data, sizeof(data)) == -1)
     perror("read() error");
   else printf("read '%s' from the tty\n", data);
   if (tcflow(slave, TCOON) != 0)
     perror("tcflow() error");
   exit(1);
   }
   puts("output is resumed to tty");
   if (read(master, data, sizeof(data)) == -1) {
     perror("read() error");
     exit(1);
   }
   printf("read '%s' from the tty\n", data);
   close(slave);
   close(master);
 }

Output

output is suspended to tty
read() error: Resource temporarily unavailable
output is resumed to tty
read 'text to be written to tty' from the tty