From 230ec520bc31cc5daf9689adad351f0b2f78bc76 Mon Sep 17 00:00:00 2001
From: Lorenz Stechauner <lorenz.stechauner@necronda.net>
Date: Thu, 2 Jan 2025 11:59:29 +0100
Subject: [PATCH] Update doc/README

---
 doc/README.md | 49 +++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 39 insertions(+), 10 deletions(-)

diff --git a/doc/README.md b/doc/README.md
index 5a1d41d..cfe7fbb 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -1,9 +1,17 @@
 
-Intercepting Function/System Calls in Linux
-===========================================
+Intercepting and Manipulating Function and System Calls in Linux
+================================================================
 
-Option 1: `LD_PRELOAD`
-----------------------
+Option 1: Preloading (`LD_PRELOAD`)
+-----------------------------------
+
+From the [ENVIRONMENT section in the Linux manual page ld.so(8)](https://www.man7.org/linux/man-pages/man8/ld.so.8.html#ENVIRONMENT):
+
+> **`LD_PRELOAD`**
+>
+> A list of additional, user-specified, ELF shared objects  to be loaded before all others.
+> This feature can be used to selectively override functions in other shared objects.
+> [...]
 
 * No need to re-link
 * Works for *all* functions
@@ -36,8 +44,31 @@ LD_PRELOAD="$(pwd)/preload.so" ./main
 ```
 
 
-Option 2: `gcc --wrap`
-----------------------
+Option 2: Wrapper functions (`gcc -Wl,--wrap=`, `ld --wrap=`)
+-------------------------------------------------------------
+
+From the [OPTIONS section in the Linux manual page ld(1)](https://www.man7.org/linux/man-pages/man1/ld.1.html#OPTIONS):
+
+> **`--wrap=symbol`**
+>
+> Use a wrapper function for *symbol*.
+> Any undefined reference to *symbol* will be resolved to `__wrap_<symbol>`.
+> Any undefined reference to `__real_<symbol>` will be resolved to *symbol*.
+>
+> This can be used to provide a wrapper for a system function.
+> The wrapper function should be called `__wrap_<symbol>`.
+> If it wishes to call the system function, it should call `__real_<symbol>`.
+> [...]
+
+From the [OPTIONS section in the Linux manual page gcc(1)](https://www.man7.org/linux/man-pages/man1/gcc.1.html#OPTIONS):
+
+> **`-Wl,option`**
+>
+> Pass *option* as an option to the linker.
+> If *option* contains commas, it is split into multiple options at the commas.
+> You can use this syntax to pass an argument to the option.
+> For example, `-Wl,-Map,output.map` passes `-Map output.map` to the linker.
+> When using the GNU linker, you can also get the same effect with `-Wl,-Map=output.map`.
 
 * Need to re-link(/-comiple)
 * Relatively simple code:
@@ -49,8 +80,6 @@ Option 2: `gcc --wrap`
 
 Example (`wrap.c`):
 ```c
-#include <stdlib.h>
-
 extern void *__real_malloc(size_t size);
 
 void *__wrap_malloc(size_t size) {
@@ -67,8 +96,8 @@ gcc -o main_wrapped main.c wrap.c -Wl,--wrap=malloc
 ```
 
 
-Option 3: Linux kernel
-----------------------
+Option 3: Kernel module
+-----------------------
 
 * Only works with Linux system calls
 * Also works with statically linked executables