# 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

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

## Usage

```bash
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:
```bash
gcc -g -O0 -o test_access test_access.c
gcc -g -O0 -o test_with_args test_with_args.c
```

Run tests:
```bash
# 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
```