From 58f426abced7b4b5f5ba3e9c46c11536ccdfab0b Mon Sep 17 00:00:00 2001 From: Tachikoma Date: Mon, 3 Aug 2026 06:38:21 -0400 Subject: [PATCH] Document libc wrapper contract Co-authored-by: Andrew Kesterson --- AGENTS.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index b88714b..b4b356f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -76,6 +76,10 @@ return convention and the `PREPARE_ERROR` / `FAIL_*` / `SUCCEED_RETURN` pattern. Four conventions hold across the whole library, and a new wrapper that breaks one of them is wrong even if it compiles and passes: +- **Preserve the libc contract unless there is a compelling, documented reason + not to.** libc behaviour is the standard to meet. This library changes only + the error transport (to `akerror`) and, where libc returns a value, the result + shape (through a caller-provided destination pointer). - **A NULL out-param is a caller error**, not "don't care". - **Finding nothing is success** -- searching functions write NULL or zero and return NULL. @@ -93,6 +97,11 @@ The build is `-Wall -Wextra` and CI adds `-Werror`. `-Wpedantic` is deliberately off: libakerror's `FAIL_*` macros trip "ISO C99 requires at least one argument for the ..." on their own expansion, not on anything at the call site. +**Do not wrap a libc function that cannot fail and provides no failure or +operation-status result.** There is no `akerror` context to carry. A value such +as `umask()`'s previous mask is not an operation-status result, so `umask()` is +not a wrapper candidate. + ## Testing Guidelines Add a new test by creating `tests/test_mything.c` and adding `mything` to the -- 2.43.0