Software flow control is a mechanism that lets the terminal (or a program) pause and resume output without dropping data.

In a normal terminal emulator, when you press Ctrl-S, the screen freezes. When you press Ctrl-Q, it unfreezes. The PTY slave handles this internally. But if you are forwarding this session over a network (like telnet/rlogin), the remote side needs to know when output stopped, so it does not keep sending data that cannot be displayed.

Packet mode is enabled on the master fd using the TIOCPKT ioctl:

#include <sys/ioctl.h>

int masterFd;   /* opened earlier with posix_openpt */
int arg;

/* Enable packet mode */
arg = 1;
if (ioctl(masterFd, TIOCPKT, &arg) == -1) {
    perror("ioctl TIOCPKT enable");
    return 1;
}

/* Disable packet mode */
arg = 0;
if (ioctl(masterFd, TIOCPKT, &arg) == -1) {
    perror("ioctl TIOCPKT disable");
    return 1;
}

In normal mode, read(masterFd, buf, N) returns N bytes of data from the slave.

In packet mode, each read() from the master returns one of two things:

So in packet mode, every read from the master starts with one extra byte. If that byte is zero, the rest is data. If it is nonzero, it is a bit mask of control events.

char buf[4096];
int n;

n = read(masterFd, buf, sizeof(buf));
if (n <= 0) {
    /* error or EOF */
    return;
}

if (buf[0] != 0) {
    /* Control event - check which bits are set */
    if (buf[0] & TIOCPKT_FLUSHREAD)
        printf("Input queue was flushed (Ctrl-C effect)\n");
    if (buf[0] & TIOCPKT_FLUSHWRITE)
        printf("Output queue was flushed\n");
    if (buf[0] & TIOCPKT_STOP)
        printf("Output stopped (Ctrl-S pressed)\n");
    if (buf[0] & TIOCPKT_START)
        printf("Output restarted (Ctrl-Q pressed)\n");
    if (buf[0] & TIOCPKT_IOCTL)
        printf("Terminal ioctl happened on slave\n");
} else {
    /* Data event - buf[1..n-1] contains actual data */
    printf("Data received (%d bytes): %.*s\n", n-1, n-1, buf+1);
}

When the control byte (buf[0]) is nonzero, it is a bitmask. Multiple bits can be set at once. The common bit flags defined on Linux (from <sys/ioctl.h>):

In a real application, you do not just sit in a blocking read() loop. You multiplex between the master fd and other fds (like a network socket) using select() or poll().

Packet mode integrates with both:

#include <poll.h>
#include <stdio.h>
#include <sys/ioctl.h>

void packet_mode_loop(int masterFd, int networkFd)
{
    struct pollfd fds[2];
    char buf[4096];
    int n, arg;

    /* Enable packet mode on PTY master */
    arg = 1;
    ioctl(masterFd, TIOCPKT, &arg);

    fds[0].fd     = masterFd;
    fds[0].events = POLLIN | POLLPRI;  /* data + control events */

    fds[1].fd     = networkFd;
    fds[1].events = POLLIN;

    while (1) {
        if (poll(fds, 2, -1) == -1) {
            perror("poll");
            break;
        }

        /* PTY master has something */
        if (fds[0].revents & (POLLIN | POLLPRI)) {
            n = read(masterFd, buf, sizeof(buf));
            if (n <= 0) break;  /* slave closed */

            if (buf[0] != 0) {
                /* Control event - handle flow control */
                if (buf[0] & TIOCPKT_STOP) {
                    /* Tell remote to pause its output */
                    /* send_xoff_to_network(networkFd); */
                }
                if (buf[0] & TIOCPKT_START) {
                    /* Tell remote to resume its output */
                    /* send_xon_to_network(networkFd); */
                }
            } else {
                /* Data: forward buf[1..n-1] to network */
                /* write(networkFd, buf + 1, n - 1); */
            }
        }

        /* Network socket has data */
        if (fds[1].revents & POLLIN) {
            n = read(networkFd, buf, sizeof(buf));
            if (n <= 0) break;  /* connection closed */
            /* Forward to PTY master */
            write(masterFd, buf, n);
        }
    }
}

#include <sys/select.h>
#include <stdio.h>

void select_packet_mode(int masterFd)
{
    fd_set readfds, exceptfds;
    char buf[4096];
    int n;

    while (1) {
        FD_ZERO(&readfds);
        FD_ZERO(&exceptfds);

        FD_SET(masterFd, &readfds);    /* normal data */
        FD_SET(masterFd, &exceptfds);  /* packet mode control events */

        if (select(masterFd + 1, &readfds, NULL, &exceptfds, NULL) == -1) {
            perror("select");
            break;
        }

        /* Either data or control event - read() handles both */
        if (FD_ISSET(masterFd, &readfds) ||
            FD_ISSET(masterFd, &exceptfds)) {

            n = read(masterFd, buf, sizeof(buf));
            if (n <= 0) break;

            if (buf[0] != 0) {
                printf("Control event: 0x%02x\n", (unsigned char)buf[0]);
            } else {
                printf("Data (%d bytes): %.*s\n", n-1, n-1, buf+1);
            }
        }
    }
}

Consider a user connecting via telnet from a remote machine:

This is the exact problem packet mode was designed to solve. Modern SSH does not use XON/XOFF flow control this way (it uses its own windowing), but older protocols like telnet and rlogin relied on packet mode for correct flow-control forwarding.