Building a Self-Scrolling File Viewer in C: Mastering Signal Handling and Terminal Control

Introduction: Why Build a Self-Scrolling File Viewer?

In the world of system programming, combining signals, terminal control, and file I/O is a rite of passage. This tutorial walks you through building an autoscroll file viewer—a program that displays a text file and automatically scrolls it line by line. Think of it as a live feed for log files, similar to how a stock ticker updates on a finance app, or how a real-time leaderboard refreshes during an esports tournament. By the end, you'll have a solid grasp of the Linux kernel API for signal handling and terminal manipulation.

Understanding the Core Concepts

Signal Handling with alarm() and sigwait()

Signals are software interrupts. The alarm() system call sends a SIGALRM signal after a specified number of seconds. Since alarm() is not a repeating timer, the signal handler must re-arm it each time. This is perfect for our scrolling interval—every N seconds, we scroll one line.

For user interaction, we use sigwait() to block until a signal (like SIGTSTP from Ctrl+Z or SIGINT from Ctrl+C) arrives. This allows the main loop to respond to pause/resume commands without busy-waiting.

Terminal Control via ANSI Escape Sequences

We'll use ANSI escape sequences to move the cursor, clear the screen, and display the status bar. For example, \033[2J clears the screen, and \033[H moves the cursor home. The bottom row (row R) is reserved for a status bar showing the current time and line range.

File I/O and Memory Management

The file is read into memory as an array of lines. We track the start and end line indices of the visible window. When scrolling, we increment both indices. For long lines (up to 4KB), we must ensure the entire line fits in the visible area before displaying it, accounting for line wrapping.

Step-by-Step Implementation

1. Parsing Command-Line Arguments

Your program should accept an optional -s secs flag and a filename. Use getopt() to parse. Validate that secs is a positive integer less than 60. If the file is missing or the option is invalid, print a usage message to stderr.

2. Setting Up Signal Handlers

We need handlers for SIGALRM (to scroll), SIGTSTP (to pause), and SIGINT (to resume). Use sigaction() to install handlers. The SIGALRM handler increments the scroll offset and re-arms the alarm. For pause/resume, we use sigwait() in the main loop, so handlers just set flags.

void handle_sigalrm(int sig) {
    if (!paused) {
        scroll_offset++;
        redraw_screen();
    }
    alarm(scroll_interval);
}

3. Reading the File into Memory

Read the entire file into a buffer, then split it into lines by locating newline characters. Store pointers to each line in an array. Determine the number of lines. If the file doesn't end with a newline, add one for consistency.

4. Determining Terminal Size

Use ioctl() with TIOCGWINSZ to get the number of rows (R) and columns (C). The text display area is rows 1 to R-1. The status bar occupies row R.

5. Displaying the Initial Screen

Clear the screen and print the first R-1 lines (or fewer if the file is shorter). For each line, if it's longer than C columns, it wraps to the next line. We must account for wrapping when calculating the visible range. For simplicity, assume no line exceeds 4KB and wrap as needed.

6. Implementing Auto-Scroll Logic

Every N seconds (default 1), the SIGALRM handler increments the start line index. Then redraw the screen: clear the text area (using \033[1J to clear from top to cursor) and re-print the current lines. Update the status bar with the current time and line range.

7. Handling Pause/Resume with sigwait()

In main(), after initialization, block SIGTSTP and SIGINT using sigprocmask(). Then loop on sigwait() to catch these signals. When SIGTSTP is caught, set a paused flag. When SIGINT is caught, clear the flag. The SIGALRM handler checks this flag before scrolling.

sigset_t set;
sigemptyset(&set);
sigaddset(&set, SIGTSTP);
sigaddset(&set, SIGINT);
sigprocmask(SIG_BLOCK, &set, NULL);

int sig;
while (1) {
    sigwait(&set, &sig);
    if (sig == SIGTSTP) paused = 1;
    else if (sig == SIGINT) paused = 0;
}

8. Updating the Status Bar

Every time the screen is redrawn, update the status bar at row R, column 1 with the current time (using time() and localtime()) and the line range. The cursor is then moved to (R, C-2) as required.

9. Cleaning Up on Termination

When a terminating signal (SIGTERM, SIGQUIT, SIGKILL) is received, the default action is to terminate. Before that, we should restore the terminal to a usable state: clear the screen and move the cursor home. Register an atexit() handler or use sigaction() with SA_RESETHAND to restore defaults and clean up.

Testing and Debugging

Debugging signal handlers can be tricky. Use gdb to step through, or print debug messages to a second terminal (e.g., /dev/pts/2) using fprintf(). Also run valgrind to check for memory leaks.

Common Pitfalls

• Re-entrancy: Signal handlers should only call async-signal-safe functions. Avoid printf() inside handlers; instead, set a flag and handle output in the main loop.
• Timer Drift: Since alarm() is set in the handler, the interval may drift. For precise timing, consider using timer_create().
• Long Lines: If a line is longer than the terminal width, it wraps. Ensure you skip displaying a line until the entire wrapped line fits in the visible area.

Real-World Analogies

This program is like a live scoreboard at a basketball game—it updates every second to show the latest scores (lines) and keeps a clock. In esports, a tournament bracket auto-refreshes as matches conclude. In finance, a stock ticker scrolls new prices. The concepts you learn here apply to any real-time data display system.

Conclusion

Building an autoscroll file viewer teaches you the essentials of signal-driven programming and terminal control. You've learned to handle timers, respond to user input without polling, and manipulate the terminal screen. These skills are foundational for developing system utilities, monitoring tools, and even games. Now go ahead and implement your own version—your terminal will never be the same!