From 56ad622018fcac68e7a716b60465d493067e89ec Mon Sep 17 00:00:00 2001
From: Gabriel Ionita <d9rect@pm.me>
Date: Sun, 26 Oct 2025 21:20:00 +0100
Subject: [PATCH] update README with new usage and remove list mode references

---
 README.md | 48 ++++++++++++++++++++++++++++++++++--------------
 1 file changed, 34 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index 8703e79..093ea10 100644
--- a/README.md
+++ b/README.md
@@ -4,9 +4,10 @@ A tool to monitor reads and writes to global integer variables in Linux binaries
 
 ## Features
 
-- Lists all global integer variables in a binary with their addresses
-- Attempts to set up hardware watchpoints via ptrace to monitor variable access
+- Monitors specific global integer variables in a running program
+- Attempts to set up hardware watchpoints via ptrace to detect variable access
 - Supports PIE (Position Independent Executable) binaries
+- Passes command-line arguments to the target program
 - Uses DWARF debug information to locate variables
 
 ## Building
@@ -18,17 +19,26 @@ cmake --build build
 
 ## Usage
 
-### List all global integer variables:
 ```bash
-./build/gwatch --exec <binary>
+gwatch --var <symbol> --exec <path> [-- arg1 arg2 ... argN]
 ```
 
-### Watch a specific variable:
-```bash
-./build/gwatch --exec <binary> --var <variable_name>
-```
+**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 binary must be compiled with debug symbols (`-g` flag).
+**Note:** The target binary must be compiled with debug symbols (`-g` flag).
+
+**Examples:**
+
+```bash
+# Watch global_counter in test_access
+./build/gwatch --var global_counter --exec ./test_access
+
+# Watch with program arguments
+./build/gwatch --var global_counter --exec ./test_with_args -- hello world 123
+```
 
 ## Implementation Details
 
@@ -69,19 +79,29 @@ But SIGTRAP signals are never generated when the watched variable is accessed.
 
 ## Testing
 
-Test binaries are provided:
-- `test_binary`: Simple binary with global variables (no accesses)
-- `test_access`: Program that reads and writes to `global_counter`
+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
 ```
 
-##Future Work
+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
+```
+
+## Future Work
 
 - Investigate alternative watchpoint implementations
-- Add support for watchingnon-integer types
+- Add support for watching non-integer types
 - Support multiple simultaneous watchpoints (using DR1-DR3)
 - Add filtering options (read-only vs write-only vs read/write)
 - Better error reporting and diagnostics