From dec5ac868cffdef7c84e88b4165c9caf91f18286 Mon Sep 17 00:00:00 2001
From: Linus Vogel <linus@linvogel.ch>
Date: Sun, 15 Mar 2026 22:57:11 +0100
Subject: [PATCH] added readme

---
 Readme.md | 173 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 173 insertions(+)
 create mode 100644 Readme.md

diff --git a/Readme.md b/Readme.md
new file mode 100644
index 0000000..d3e6cd6
--- /dev/null
+++ b/Readme.md
@@ -0,0 +1,173 @@
+# cputild - CPU Idle Time Monitor
+
+## Overview
+
+**cputild** is a lightweight daemon that continuously monitors CPU utilization by reading from `/proc/stat` and writes the current CPU usage percentage to `/tmp/cputild`. It's designed to run as a background service on Linux systems, providing real-time CPU metrics suitable for other tools to consume.
+
+## Features
+
+- **Continuous Monitoring**: Reads CPU statistics every second
+- **Accurate Calculation**: Uses jiffies-based delta calculation for precise utilization
+- **Signal Handling**: Gracefully responds to `SIGINT` (Ctrl+C) for clean shutdown
+- **Daemon Ready**: Includes systemd service configuration for production use
+- **Efficient I/O**: Reopens files on each iteration for volatile data sources
+
+## Requirements
+
+- **Operating System**: Linux (requires `/proc/stat` support)
+- **Build Tools**: CMake 3.31+, GCC or compatible C11 compiler
+- **Systemd**: For service management (optional)
+
+## Building the Project
+
+### Prerequisites
+```bash
+sudo apt install cmake build-essential  # Debian/Ubuntu
+sudo yum install cmake gcc               # Fedora/CentOS
+```
+
+### Build Process
+```bash
+# Using the install script (recommended for production)
+./install.sh
+
+# Or manual build
+mkdir build && cd build
+cmake -S ../.. -DCMAKE_BUILD_TYPE=RelWithDebInfo
+cmake --build .
+# Optional: sudo cmake --install ../.. --prefix /usr/local
+```
+
+### Build Options
+The `CMakeLists.txt` supports multiple build types:
+- **Debug** (default): For development and debugging
+- **Release**: Optimized without debug symbols
+- **RelWithDebInfo** (used by install.sh): Optimized with debug info
+
+```bash
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build
+```
+
+## Installation
+
+### Automated Installation
+The provided `install.sh` script handles the complete installation process:
+```bash
+./install.sh
+```
+
+This script will:
+1. Create a temporary build directory
+2. Configure and build the project with `CMake`
+3. Install the binary to `/usr/local/bin/cputild`
+4. Copy and enable the systemd service
+5. Reload systemd daemon
+
+### Manual Installation
+```bash
+sudo cmake --install build --prefix /usr/local
+sudo cp cputild.service /etc/systemd/system/cputild.service
+sudo systemctl daemon-reload
+sudo systemctl enable cputild.service
+sudo systemctl start cputild.service
+```
+
+## Systemd Service
+
+### Service Behavior
+When running as a systemd service, cputild:
+- Starts automatically on boot (if enabled)
+- Restarts on failure (`Restart=on-failure`)
+- Responds to `SIGINT` for graceful shutdown
+
+### Management Commands
+```bash
+# Enable service (start on boot)
+sudo systemctl enable cputild.service
+
+# Start service
+sudo systemctl start cputild.service
+
+# Check status
+sudo systemctl status cputild.service
+
+# Stop service
+sudo systemctl stop cputild.service
+
+# Restart service
+sudo systemctl restart cputild.service
+
+# View logs
+sudo journalctl -u cputild.service
+```
+
+## How It Works
+
+### Algorithm
+1. **Read** CPU statistics from `/proc/stat` (in jiffies)
+2. **Parse** the first line: `cpu user nice system idle iowait irq softirq steal guest guest_nice`
+3. **Calculate** active time = user + nice + system + irq + softirq + steal + guest + guest_nice
+4. **Calculate** idle time = iowait + idle
+5. **Compute** delta (difference) since last measurement
+6. **Derive** utilization = active_delta / (active_delta + idle_delta) × 100
+7. **Write** result to `/tmp/cputild` (percentage, 2 decimal places)
+
+### Output Format
+```
+/tmp/cputild: 45.23
+```
+The file contains only the number (no newline) for easy parsing by other tools.
+
+## Signal Handling
+
+The program uses a simple volatile flag pattern for signal handling:
+
+| Signal | Effect |
+|--------|--------|
+| `SIGINT` (Ctrl+C) | Gracefully sets `running=0` and terminates |
+
+## Troubleshooting
+
+### Permission Issues
+```bash
+# If you cannot write to /tmp/cputild
+sudo chmod 666 /tmp
+```
+
+### Systemd Service Not Starting
+```bash
+# Check for errors
+sudo systemctl status cputild.service -l
+
+# Check journal logs
+sudo journalctl -xeu cputild.service
+```
+
+### Manual Test
+```bash
+# Test in foreground
+./build/cputild
+
+# Verify output
+cat /tmp/cputild
+```
+
+## File Structure
+```
+cputild/
+├── CMakeLists.txt          # Build configuration
+├── install.sh              # Installation script
+├── cputild.service         # systemd unit file
+└── main.c                  # Source code
+```
+
+## Author
+Linus Vogel <linus@linvogel.ch>
+
+## License
+Free to use and modify.
+
+---
+
+*Last Updated: 2026-03-15*
\ No newline at end of file