71 lines
2.0 KiB
Markdown
71 lines
2.0 KiB
Markdown
# 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
|
|
```
|
|
|