gwatch/README.md

gwatch - Global Variable Watcher

A tool to monitor writes to global integer variables in Linux binaries using ptrace single-stepping.

Features

• Monitors specific global integer variables in a running program
• Detects and reports all writes to the watched variable
• Supports PIE (Position Independent Executable) binaries
• Passes command-line arguments to the target program
• Uses DWARF debug information to locate variables
• Tab-delimited output format for easy parsing

Building

git clone --recurse-submodules https://git.gabriel.md/gabi/gwatch.git
./vcpkg/bootstrap-vcpkg.sh
mkdir build
cd build
cmake --preset debug ..
make

Usage

gwatch --var <symbol> --exec <path> [-- arg1 arg2 ... argN]

Arguments:

• --var <symbol>: Name of the global variable to watch (required)
• --exec <path>: Path to the executable to monitor (required)
• -- arg1 arg2 ...: Optional arguments to pass to the target program

Note: The target binary must be compiled with debug symbols (-g flag).

Performance Considerations

The tool uses single-stepping which executes one CPU instruction at a time. This is:

• Very thorough: Catches every write to the watched variable
• Slow: Adds significant overhead compared to native execution
• Reliable: Works consistently across different systems and configurations

For programs with many instructions (100K+ steps), there will be noticeable slowdown.

Testing

Test programs are provided:

• test_access.c: Program that reads and writes to global_counter
• test_with_args.c: Program that accepts command-line arguments and modifies global_counter

Compile test programs with:

gcc -g -O0 -o test_access test_access.c
gcc -g -O0 -o test_with_args test_with_args.c

Run tests:

# Basic test
./build/gwatch --var global_counter --exec ./test_access

# Test with arguments
./build/gwatch --var global_counter --exec ./test_with_args -- hello world 123

# Run test suite
./autotest.sh