andrew/libakstdlib
1
0
Fork 0
Code Issues 33 Pull Requests 3 Actions 2 Packages Projects Releases Wiki Activity

Wrap file metadata calls #31

Merged
andrew merged 3 commits from 9 into main 2026-08-03 11:05:45 -04:00
Conversation 10 Commits 3 Files Changed 4 +192
4 changed files with 192 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 8c94231167 - Show all commits

2
CMakeLists.txt
View File

@@ -207,6 +207,7 @@ add_library(akstdlib SHARED
src/stdlib.c
src/string.c
src/stream.c
src/stat.c
src/collections.c
)
@@ -317,6 +318,7 @@ set(AKSL_TESTS
strbuf
stream
streamio
stat
strhash
string
strto

53
include/akstdlib.h
View File

@@ -76,6 +76,8 @@
#include <stddef.h>
#include <stdint.h>
#include <stdio.h>
#include <sys/stat.h>
#include <sys/statvfs.h>
logikoma marked this conversation as resolved
tachikoma commented 2026-08-03 09:59:20 -04:00
Review
Copy Link

DEFECT (high) — the header is not self-contained for aksl_fstatat.

Line 79-80 add <sys/stat.h> and <sys/statvfs.h>, but not <fcntl.h>. POSIX declares AT_FDCWD, AT_SYMLINK_NOFOLLOW, AT_EMPTY_PATH and AT_NO_AUTOMOUNT in <fcntl.h>, not in <sys/stat.h>. The aksl_fstatat doc block on line 838-844 tells the caller to pass AT_FDCWD and "libc fstatat flags", and then does not give them a way to spell either one.

Verified. A translation unit whose only include is <akstdlib.h>:

#include <akstdlib.h>
int main(void)
{
    struct stat st;
    akerr_ErrorContext *e = aksl_fstatat(AT_FDCWD, ".", &st, AT_SYMLINK_NOFOLLOW);
    (void)e;
    return 0;
}

error: 'AT_FDCWD' undeclared (first use in this function)
error: 'AT_SYMLINK_NOFOLLOW' undeclared (first use in this function)

Adding #include <fcntl.h> to the test file compiles it clean. The suite never caught this because tests/test_stat.c:4 includes <fcntl.h> itself, so the test is not testing the header the way a consumer sees it.

Fix: add #include <fcntl.h> here, beside the other two.

**DEFECT (high) — the header is not self-contained for `aksl_fstatat`.** Line 79-80 add `<sys/stat.h>` and `<sys/statvfs.h>`, but not `<fcntl.h>`. POSIX declares `AT_FDCWD`, `AT_SYMLINK_NOFOLLOW`, `AT_EMPTY_PATH` and `AT_NO_AUTOMOUNT` in `<fcntl.h>`, not in `<sys/stat.h>`. The `aksl_fstatat` doc block on line 838-844 tells the caller to pass `AT_FDCWD` and "libc fstatat flags", and then does not give them a way to spell either one. Verified. A translation unit whose only include is `<akstdlib.h>`: ```c #include <akstdlib.h> int main(void) { struct stat st; akerr_ErrorContext *e = aksl_fstatat(AT_FDCWD, ".", &st, AT_SYMLINK_NOFOLLOW); (void)e; return 0; } ``` ``` error: 'AT_FDCWD' undeclared (first use in this function) error: 'AT_SYMLINK_NOFOLLOW' undeclared (first use in this function) ``` Adding `#include <fcntl.h>` to the test file compiles it clean. The suite never caught this because `tests/test_stat.c:4` includes `<fcntl.h>` itself, so the test is not testing the header the way a consumer sees it. **Fix:** add `#include <fcntl.h>` here, beside the other two.
/* off_t, for the aksl_fseeko/aksl_ftello pair. POSIX, like aksl_realpath. */
#include <sys/types.h>
@@ -808,6 +810,57 @@ akerr_ErrorContext AKERR_NOIGNORE *aksl_strhash_djb2_str(const char *str, uint32
/** @} */
/**
* @brief stat(2).
* @param[in] pathname Path to inspect. Required.
* @param[out] dest File metadata. Required.
* @return NULL on success, an error context otherwise.
*/
akerr_ErrorContext AKERR_NOIGNORE *aksl_stat(const char *pathname, struct stat *dest);
logikoma marked this conversation as resolved Outdated
tachikoma commented 2026-08-03 09:59:20 -04:00
Outdated
Review
Copy Link

DEFECT (medium) — no @throws on any of the six.

The header carries 293 @throws tags across 146 aksl_ declarations. The declaration immediately above this one, aksl_strhash_djb2_str on line 810, documents @throws AKERR_NULLPOINTER If either pointer is NULL. These six document none.

That leaves the only non-obvious half of the contract undocumented. A consumer reading the header cannot learn from it that a NULL argument yields AKERR_NULLPOINTER, or — much more importantly — that a libc failure surfaces the raw errno value as the status with AKERR_IO only as a fallback when errno is 0. That second one is the whole design decision the PR body is announcing, and the header is where a consumer would look for it.

Fix: on each of the six, add the statuses. For example:

 * @throws AKERR_NULLPOINTER If pathname or dest is NULL.
 * @throws AKERR_IO If stat(2) failed and left errno at 0.
 * @throws (errno) The errno stat(2) set, reported directly as the status.
**DEFECT (medium) — no `@throws` on any of the six.** The header carries 293 `@throws` tags across 146 `aksl_` declarations. The declaration immediately above this one, `aksl_strhash_djb2_str` on line 810, documents `@throws AKERR_NULLPOINTER If either pointer is NULL.` These six document none. That leaves the only non-obvious half of the contract undocumented. A consumer reading the header cannot learn from it that a NULL argument yields `AKERR_NULLPOINTER`, or — much more importantly — that a libc failure surfaces the **raw errno value** as the status with `AKERR_IO` only as a fallback when errno is 0. That second one is the whole design decision the PR body is announcing, and the header is where a consumer would look for it. **Fix:** on each of the six, add the statuses. For example: ``` * @throws AKERR_NULLPOINTER If pathname or dest is NULL. * @throws AKERR_IO If stat(2) failed and left errno at 0. * @throws (errno) The errno stat(2) set, reported directly as the status. ```
/**
* @brief lstat(2), inspecting a symbolic link itself.
* @param[in] pathname Path to inspect. Required.
* @param[out] dest File metadata. Required.
* @return NULL on success, an error context otherwise.
*/
akerr_ErrorContext AKERR_NOIGNORE *aksl_lstat(const char *pathname, struct stat *dest);
/**
* @brief fstat(2).
* @param[in] fd Open file descriptor.
* @param[out] dest File metadata. Required.
* @return NULL on success, an error context otherwise.
*/
akerr_ErrorContext AKERR_NOIGNORE *aksl_fstat(int fd, struct stat *dest);
/**
* @brief fstatat(2).
* @param[in] dirfd Directory descriptor, or AT_FDCWD.
* @param[in] pathname Path to inspect. Required.
* @param[out] dest File metadata. Required.
* @param[in] flags libc fstatat flags, passed unchanged.
* @return NULL on success, an error context otherwise.
*/
akerr_ErrorContext AKERR_NOIGNORE *aksl_fstatat(int dirfd, const char *pathname, struct stat *dest, int flags);
/**
* @brief statvfs(3).
* @param[in] path Path on the filesystem. Required.
* @param[out] dest Filesystem metadata. Required.
* @return NULL on success, an error context otherwise.
*/
akerr_ErrorContext AKERR_NOIGNORE *aksl_statvfs(const char *path, struct statvfs *dest);
/**
* @brief fstatvfs(3).
* @param[in] fd Open file descriptor.
* @param[out] dest Filesystem metadata. Required.
* @return NULL on success, an error context otherwise.
*/
akerr_ErrorContext AKERR_NOIGNORE *aksl_fstatvfs(int fd, struct statvfs *dest);
logikoma marked this conversation as resolved
tachikoma commented 2026-08-03 09:59:20 -04:00
Review
Copy Link

DEFECT (medium) — these six declarations are outside every Doxygen group.

They sit between the /** @} */ on line 811 that closes Paths and hashing and the /* ==== */ /** @name Streams ... @{ banner on line 864-872. Every other one of the 146 aksl_ declarations in this header is inside a @name ... @{ ... @} group with a separator banner — there are 15 such groups. These six are the only ungrouped declarations in 2300 lines, so in the generated documentation they fall outside the module structure the rest of the API is organised by.

Fix: wrap them the way every neighbouring block is wrapped:

/* ====================================================================== */
/** @name File and filesystem metadata
 *
 *  ...rationale...
 *  @{
 */
/* ====================================================================== */

...declarations...

/** @} */

Also, line 862-863 is a double blank line before the Streams banner; every other group boundary in the file uses one.

**DEFECT (medium) — these six declarations are outside every Doxygen group.** They sit between the `/** @} */` on line 811 that closes *Paths and hashing* and the `/* ==== */ /** @name Streams ... @{` banner on line 864-872. Every other one of the 146 `aksl_` declarations in this header is inside a `@name ... @{ ... @}` group with a separator banner — there are 15 such groups. These six are the only ungrouped declarations in 2300 lines, so in the generated documentation they fall outside the module structure the rest of the API is organised by. **Fix:** wrap them the way every neighbouring block is wrapped: ```c /* ====================================================================== */ /** @name File and filesystem metadata * * ...rationale... * @{ */ /* ====================================================================== */ ``` ...declarations... ```c /** @} */ ``` Also, line 862-863 is a double blank line before the Streams banner; every other group boundary in the file uses one.
/* ====================================================================== */
/** @name Streams: open, read, write, close
*

51
src/stat.c Normal file
View File

@@ -0,0 +1,51 @@
/* sys/stat.h and sys/statvfs.h metadata wrappers. */
logikoma marked this conversation as resolved Outdated
tachikoma commented 2026-08-03 09:59:20 -04:00
Outdated
Review
Copy Link

Style — no file-level rationale block.

One line, where the three most recently added wrapper files all open with a paragraph explaining why the wrappers are worth having and what conventions run through the file:

file file-level block
src/stream.c:1-17 17 lines: "the recurring theme, and the reason most of these are worth wrapping at all, is that stdio reports failure through a return value that is easy to mistake for data..."
src/string.c:1-12+ counts the raw call sites in akbasic that motivated it
src/collections.c:1-12+ states what it is not, then the two conventions that hold throughout
src/stat.c:1 /* sys/stat.h and sys/statvfs.h metadata wrappers. */

The per-function blocks added in 01034fc are genuinely good — aksl_fstat's "no path lookup race and remains useful after the file has been renamed or unlinked" is exactly the right kind of note. The file just has no equivalent at the top saying why a caller reaches for this file at all, and where the errno-as-status policy is stated once for all six.

**Style — no file-level rationale block.** One line, where the three most recently added wrapper files all open with a paragraph explaining why the wrappers are worth having and what conventions run through the file: | file | file-level block | |---|---| | `src/stream.c:1-17` | 17 lines: "the recurring theme, and the reason most of these are worth wrapping at all, is that stdio reports failure through a return value that is easy to mistake for data..." | | `src/string.c:1-12+` | counts the raw call sites in akbasic that motivated it | | `src/collections.c:1-12+` | states what it is *not*, then the two conventions that hold throughout | | `src/stat.c:1` | `/* sys/stat.h and sys/statvfs.h metadata wrappers. */` | The per-function blocks added in 01034fc are genuinely good — `aksl_fstat`'s "no path lookup race and remains useful after the file has been renamed or unlinked" is exactly the right kind of note. The file just has no equivalent at the top saying why a caller reaches for this file at all, and where the errno-as-status policy is stated once for all six.
#include <akstdlib.h>
#include <errno.h>
#include "aksl_internal.h"
logikoma marked this conversation as resolved Outdated
tachikoma commented 2026-08-03 09:59:20 -04:00
Outdated
Review
Copy Link

Style — include-what-you-use.

stat, lstat, fstat, fstatat, statvfs and fstatvfs are all declared in <sys/stat.h> / <sys/statvfs.h>, and this file gets both only transitively through <akstdlib.h>. src/stream.c:19-27 re-includes <stdio.h>, <stdlib.h>, <string.h> and <sys/types.h> explicitly even though akstdlib.h already supplies every one of them.

Same file, the grouping differs too: stream.c separates the project header, the system headers, and "aksl_internal.h" with blank lines. Here all four run together.

Fix:

#include <akstdlib.h>

#include <errno.h>
#include <sys/stat.h>
#include <sys/statvfs.h>

#include "aksl_internal.h"
**Style — include-what-you-use.** `stat`, `lstat`, `fstat`, `fstatat`, `statvfs` and `fstatvfs` are all declared in `<sys/stat.h>` / `<sys/statvfs.h>`, and this file gets both only transitively through `<akstdlib.h>`. `src/stream.c:19-27` re-includes `<stdio.h>`, `<stdlib.h>`, `<string.h>` and `<sys/types.h>` explicitly even though `akstdlib.h` already supplies every one of them. Same file, the grouping differs too: `stream.c` separates the project header, the system headers, and `"aksl_internal.h"` with blank lines. Here all four run together. **Fix:** ```c #include <akstdlib.h> #include <errno.h> #include <sys/stat.h> #include <sys/statvfs.h> #include "aksl_internal.h" ```
akerr_ErrorContext AKERR_NOIGNORE *aksl_stat(const char *pathname, struct stat *dest)
andrew marked this conversation as resolved Outdated
andrew commented 2026-08-03 07:39:37 -04:00
Outdated
Review
Copy Link

@tachikoma none of these functions have documentation blocks. Follow the documentation style present in other files like stdlib.c; even though the headers contain doxygen blocks, the C source maintains additional information. Rephrase the exisitng documentation from the libc man page for this call.

@tachikoma none of these functions have documentation blocks. Follow the documentation style present in other files like stdlib.c; even though the headers contain doxygen blocks, the C source maintains additional information. Rephrase the exisitng documentation from the libc `man` page for this call.
👀 1
{
PREPARE_ERROR(e);
FAIL_ZERO_RETURN(e, pathname, AKERR_NULLPOINTER, "pathname=%p, dest=%p", (void *)pathname, (void *)dest);
FAIL_ZERO_RETURN(e, dest, AKERR_NULLPOINTER, "pathname=%p, dest=%p", (void *)pathname, (void *)dest);
errno = 0;
FAIL_NONZERO_RETURN(e, stat(pathname, dest), AKSL_ERRNO_OR(AKERR_IO), "pathname=%s", pathname);
SUCCEED_RETURN(e);
}
akerr_ErrorContext AKERR_NOIGNORE *aksl_lstat(const char *pathname, struct stat *dest)
{
PREPARE_ERROR(e);
FAIL_ZERO_RETURN(e, pathname, AKERR_NULLPOINTER, "pathname=%p, dest=%p", (void *)pathname, (void *)dest);
FAIL_ZERO_RETURN(e, dest, AKERR_NULLPOINTER, "pathname=%p, dest=%p", (void *)pathname, (void *)dest);
errno = 0;
FAIL_NONZERO_RETURN(e, lstat(pathname, dest), AKSL_ERRNO_OR(AKERR_IO), "pathname=%s", pathname);
SUCCEED_RETURN(e);
}
akerr_ErrorContext AKERR_NOIGNORE *aksl_fstat(int fd, struct stat *dest)
{
PREPARE_ERROR(e); FAIL_ZERO_RETURN(e, dest, AKERR_NULLPOINTER, "fd=%d, dest=%p", fd, (void *)dest);
errno = 0; FAIL_NONZERO_RETURN(e, fstat(fd, dest), AKSL_ERRNO_OR(AKERR_IO), "fd=%d", fd); SUCCEED_RETURN(e);
andrew marked this conversation as resolved
andrew commented 2026-08-03 07:40:27 -04:00
Review
Copy Link

Missing newline

Missing newline
}
akerr_ErrorContext AKERR_NOIGNORE *aksl_fstatat(int dirfd, const char *pathname, struct stat *dest, int flags)
{
PREPARE_ERROR(e);
FAIL_ZERO_RETURN(e, pathname, AKERR_NULLPOINTER, "dirfd=%d, pathname=%p, dest=%p", dirfd, (void *)pathname, (void *)dest);
FAIL_ZERO_RETURN(e, dest, AKERR_NULLPOINTER, "dirfd=%d, pathname=%p, dest=%p", dirfd, (void *)pathname, (void *)dest);
logikoma marked this conversation as resolved
tachikoma commented 2026-08-03 09:59:20 -04:00
Review
Copy Link

DEFECT (high) — this failure branch is never executed by any test in the suite.

Measured, not guessed. -DAKSL_COVERAGE=ON, full 20-test ctest run, gcov -b on src/stat.c:

line function libc-failure branch
18 aksl_stat taken 50%
33 aksl_lstat taken 0%
45 aksl_fstat taken 50%
60 aksl_fstatat taken 50%
75 aksl_statvfs taken 0%
87 aksl_fstatvfs taken 0%

Every branch inside the FAIL body on this line reports never executed.

Line coverage hides this completely — it reads Lines executed:100.00% of 34, because the line is reached by the success path. Branch coverage is Taken at least once: 46.77% of 248.

The functional consequence: AKSL_ERRNO_OR(AKERR_IO) on this line is dead code as far as the suite is concerned. That macro is the one src/aksl_internal.h documents as the fix for a FAIL "whose status is 0, which every downstream DETECT and CATCH reads as success while the context still holds a pool slot: an error that is invisible and leaks at the same time." Half the wrappers in this PR ship that mechanism with it never having run once. Drop the errno = 0 on line 32, or write AKERR_IO bare instead of the macro, and the suite stays green.

Fix (one line, next to the existing aksl_stat ENOENT check at tests/test_stat.c:46):

AKSL_CHECK_STATUS(aksl_lstat("/nonexistent/aksl/stat", &ldest), ENOENT);
**DEFECT (high) — this failure branch is never executed by any test in the suite.** Measured, not guessed. `-DAKSL_COVERAGE=ON`, full 20-test `ctest` run, `gcov -b` on `src/stat.c`: | line | function | libc-failure branch | |---|---|---| | 18 | `aksl_stat` | `taken 50%` | | **33** | **`aksl_lstat`** | **`taken 0%`** | | 45 | `aksl_fstat` | `taken 50%` | | 60 | `aksl_fstatat` | `taken 50%` | | **75** | **`aksl_statvfs`** | **`taken 0%`** | | **87** | **`aksl_fstatvfs`** | **`taken 0%`** | Every branch inside the `FAIL` body on this line reports `never executed`. Line coverage hides this completely — it reads `Lines executed:100.00% of 34`, because the *line* is reached by the success path. Branch coverage is `Taken at least once: 46.77% of 248`. The functional consequence: `AKSL_ERRNO_OR(AKERR_IO)` on this line is dead code as far as the suite is concerned. That macro is the one `src/aksl_internal.h` documents as the fix for a FAIL "whose status is 0, which every downstream DETECT and CATCH reads as success while the context still holds a pool slot: an error that is invisible and leaks at the same time." Half the wrappers in this PR ship that mechanism with it never having run once. Drop the `errno = 0` on line 32, or write `AKERR_IO` bare instead of the macro, and the suite stays green. **Fix (one line, next to the existing `aksl_stat` ENOENT check at `tests/test_stat.c:46`):** ```c AKSL_CHECK_STATUS(aksl_lstat("/nonexistent/aksl/stat", &ldest), ENOENT); ```
errno = 0;
FAIL_NONZERO_RETURN(e, fstatat(dirfd, pathname, dest, flags), AKSL_ERRNO_OR(AKERR_IO), "dirfd=%d pathname=%s flags=%d", dirfd, pathname, flags);
SUCCEED_RETURN(e);
}
akerr_ErrorContext AKERR_NOIGNORE *aksl_statvfs(const char *path, struct statvfs *dest)
{
PREPARE_ERROR(e);
FAIL_ZERO_RETURN(e, path, AKERR_NULLPOINTER, "path=%p, dest=%p", (void *)path, (void *)dest);
FAIL_ZERO_RETURN(e, dest, AKERR_NULLPOINTER, "path=%p, dest=%p", (void *)path, (void *)dest);
errno = 0;
FAIL_NONZERO_RETURN(e, statvfs(path, dest), AKSL_ERRNO_OR(AKERR_IO), "path=%s", path);
SUCCEED_RETURN(e);
logikoma marked this conversation as resolved
tachikoma commented 2026-08-03 09:59:20 -04:00
Review
Copy Link

Style — multiple statements per line, and it is not only a style question here.

Lines 44-45 put five statements on two lines. src/stat.c:86-87 in aksl_fstatvfs does the same. The other four wrappers in this file, and every wrapper in src/stream.c, put one statement per line.

Worth separating the cosmetic part from the real part. PREPARE_ERROR, FAIL_ZERO_RETURN, FAIL_NONZERO_RETURN and SUCCEED_RETURN are all multi-statement macros with no wrapping braces — FAIL_ZERO_RETURN expands to a bare if ( __x == 0 ) { FAIL(...); return __err_context; } and SUCCEED_RETURN expands to RELEASE_ERROR(e); return NULL;, which is itself two statements including an if. PREPARE_ERROR expands to a function call plus a declaration.

The code as written is correct — I checked the expansion. But collapsing unbraced control-flow macros onto a shared line is the exact shape that makes the next edit here go wrong silently, and the one-statement-per-line rule exists to stop it. This is also the only place in the file where the visual structure does not match the other five wrappers, which is what makes a reviewer stop.

Fix:

    PREPARE_ERROR(e);
    FAIL_ZERO_RETURN(e, dest, AKERR_NULLPOINTER, "fd=%d, dest=%p", fd, (void *)dest);
    errno = 0;
    FAIL_NONZERO_RETURN(e, fstat(fd, dest), AKSL_ERRNO_OR(AKERR_IO), "fd=%d", fd);
    SUCCEED_RETURN(e);
**Style — multiple statements per line, and it is not only a style question here.** Lines 44-45 put five statements on two lines. `src/stat.c:86-87` in `aksl_fstatvfs` does the same. The other four wrappers in this file, and every wrapper in `src/stream.c`, put one statement per line. Worth separating the cosmetic part from the real part. `PREPARE_ERROR`, `FAIL_ZERO_RETURN`, `FAIL_NONZERO_RETURN` and `SUCCEED_RETURN` are all **multi-statement macros with no wrapping braces** — `FAIL_ZERO_RETURN` expands to a bare `if ( __x == 0 ) { FAIL(...); return __err_context; }` and `SUCCEED_RETURN` expands to `RELEASE_ERROR(e); return NULL;`, which is itself two statements including an `if`. `PREPARE_ERROR` expands to a function call *plus a declaration*. The code as written is correct — I checked the expansion. But collapsing unbraced control-flow macros onto a shared line is the exact shape that makes the next edit here go wrong silently, and the one-statement-per-line rule exists to stop it. This is also the only place in the file where the visual structure does not match the other five wrappers, which is what makes a reviewer stop. **Fix:** ```c PREPARE_ERROR(e); FAIL_ZERO_RETURN(e, dest, AKERR_NULLPOINTER, "fd=%d, dest=%p", fd, (void *)dest); errno = 0; FAIL_NONZERO_RETURN(e, fstat(fd, dest), AKSL_ERRNO_OR(AKERR_IO), "fd=%d", fd); SUCCEED_RETURN(e); ```
}
akerr_ErrorContext AKERR_NOIGNORE *aksl_fstatvfs(int fd, struct statvfs *dest)
{
PREPARE_ERROR(e); FAIL_ZERO_RETURN(e, dest, AKERR_NULLPOINTER, "fd=%d, dest=%p", fd, (void *)dest);
errno = 0; FAIL_NONZERO_RETURN(e, fstatvfs(fd, dest), AKSL_ERRNO_OR(AKERR_IO), "fd=%d", fd); SUCCEED_RETURN(e);
andrew marked this conversation as resolved Outdated
andrew commented 2026-08-03 07:40:37 -04:00
Outdated
Review
Copy Link

Missing newline

Missing newline
}

86
tests/test_stat.c Normal file
View File

@@ -0,0 +1,86 @@
/* File metadata wrapper tests. */
#include "aksl_capture.h"
#include <errno.h>
#include <fcntl.h>
static int test_stat_success_and_fstat(void)
{
char path[AKSL_TMP_MAX];
int fd = -1;
struct stat path_dest;
struct stat fd_dest;
struct statvfs vfs_dest;
AKSL_CHECK(aksl_temp_file(path, sizeof(path)) == 0);
andrew marked this conversation as resolved Outdated
andrew commented 2026-08-03 07:37:17 -04:00
Outdated
Review
Copy Link

@tachikoma these tests need some descriptive comments explaining the actual conditions they are testing.

@tachikoma these tests need some descriptive comments explaining the actual conditions they are testing.
👀 1
fd = open(path, O_RDWR);
AKSL_CHECK(fd >= 0);
AKSL_CHECK(write(fd, "stat", 4) == 4);
AKSL_CHECK_OK(aksl_stat(path, &path_dest));
AKSL_CHECK(S_ISREG(path_dest.st_mode));
AKSL_CHECK(path_dest.st_size == 4);
AKSL_CHECK_OK(aksl_fstat(fd, &fd_dest));
AKSL_CHECK(fd_dest.st_ino == path_dest.st_ino);
AKSL_CHECK_OK(aksl_fstatvfs(fd, &vfs_dest));
AKSL_CHECK(vfs_dest.f_frsize != 0);
AKSL_CHECK(close(fd) == 0);
AKSL_CHECK_STATUS(aksl_fstat(fd, &fd_dest), EBADF);
AKSL_CHECK(unlink(path) == 0);
return 0;
}
static int test_stat_paths_and_fstatat(void)
{
char path[AKSL_TMP_MAX];
char child[AKSL_TMP_MAX * 2];
char linkpath[AKSL_TMP_MAX * 2];
struct stat dest;
struct stat ldest;
struct statvfs vdest;
AKSL_CHECK_STATUS(aksl_stat("/nonexistent/aksl/stat", &dest), ENOENT);
AKSL_CHECK(aksl_temp_file(path, sizeof(path)) == 0);
AKSL_CHECK(snprintf(child, sizeof(child), "%s/child", path) < (int)sizeof(child));
AKSL_CHECK_STATUS(aksl_stat(child, &dest), ENOTDIR);
AKSL_CHECK(snprintf(linkpath, sizeof(linkpath), "%s.link", path) < (int)sizeof(linkpath));
AKSL_CHECK(symlink(path, linkpath) == 0);
AKSL_CHECK_OK(aksl_stat(linkpath, &dest));
AKSL_CHECK_OK(aksl_lstat(linkpath, &ldest));
AKSL_CHECK(S_ISREG(dest.st_mode));
AKSL_CHECK(S_ISLNK(ldest.st_mode));
AKSL_CHECK_OK(aksl_fstatat(AT_FDCWD, path, &dest, 0));
errno = E2BIG;
AKSL_CHECK_STATUS(aksl_fstatat(AT_FDCWD, path, &dest, 0x40000000), EINVAL);
AKSL_CHECK(errno == EINVAL);
AKSL_CHECK_OK(aksl_statvfs(".", &vdest));
AKSL_CHECK(vdest.f_frsize != 0);
AKSL_CHECK(unlink(linkpath) == 0);
AKSL_CHECK(unlink(path) == 0);
return 0;
}
static int test_stat_null_arguments(void)
{
char path[AKSL_TMP_MAX];
logikoma marked this conversation as resolved Outdated
tachikoma commented 2026-08-03 09:59:20 -04:00
Outdated
Review
Copy Link

DEFECT (medium) — the two things that make fstatat worth wrapping are both untested.

Across the whole file, every aksl_fstatat call passes AT_FDCWD — lines 61, 65, 89, 90. No test ever opens a directory and passes a real directory descriptor. And no test passes a valid non-zero flag: line 61 passes 0, line 65 passes 0x40000000 which is deliberately invalid.

src/stat.c:49-52 states the contract in its own words:

pathname is resolved relative to dirfd unless it is absolute, and flags retain the libc choices such as inspecting a link itself.

Neither clause is under test. Concretely: a aksl_fstatat that ignored dirfd and passed AT_FDCWD unconditionally would pass this suite. So would one that passed 0 for flags regardless of what the caller asked for — which would silently turn every AT_SYMLINK_NOFOLLOW caller into a symlink-following one, and that is a security-relevant behaviour to get wrong quietly.

The file already builds a symlink at line 52, so the second case is nearly free.

Fix:

    /* A real dirfd must resolve a relative name against that directory. */
    dirfd = open("/tmp", O_RDONLY | O_DIRECTORY);
    AKSL_CHECK(dirfd >= 0);
    AKSL_CHECK_OK(aksl_fstatat(dirfd, strrchr(path, '/') + 1, &dest, 0));
    AKSL_CHECK(dest.st_ino == ldest.st_ino);
    AKSL_CHECK(close(dirfd) == 0);

    /* AT_SYMLINK_NOFOLLOW must reach libc unchanged, making this an lstat. */
    AKSL_CHECK_OK(aksl_fstatat(AT_FDCWD, linkpath, &dest, AT_SYMLINK_NOFOLLOW));
    AKSL_CHECK(S_ISLNK(dest.st_mode));

(path comes from aksl_temp_file, which builds it under $TMPDIR or /tmp; pull the directory from the same source rather than hardcoding /tmp.)

**DEFECT (medium) — the two things that make `fstatat` worth wrapping are both untested.** Across the whole file, every `aksl_fstatat` call passes `AT_FDCWD` — lines 61, 65, 89, 90. No test ever opens a directory and passes a real directory descriptor. And no test passes a *valid non-zero* flag: line 61 passes 0, line 65 passes `0x40000000` which is deliberately invalid. `src/stat.c:49-52` states the contract in its own words: > pathname is resolved relative to dirfd unless it is absolute, and flags retain the libc choices such as inspecting a link itself. Neither clause is under test. Concretely: a `aksl_fstatat` that ignored `dirfd` and passed `AT_FDCWD` unconditionally would pass this suite. So would one that passed `0` for `flags` regardless of what the caller asked for — which would silently turn every `AT_SYMLINK_NOFOLLOW` caller into a symlink-following one, and that is a security-relevant behaviour to get wrong quietly. The file already builds a symlink at line 52, so the second case is nearly free. **Fix:** ```c /* A real dirfd must resolve a relative name against that directory. */ dirfd = open("/tmp", O_RDONLY | O_DIRECTORY); AKSL_CHECK(dirfd >= 0); AKSL_CHECK_OK(aksl_fstatat(dirfd, strrchr(path, '/') + 1, &dest, 0)); AKSL_CHECK(dest.st_ino == ldest.st_ino); AKSL_CHECK(close(dirfd) == 0); /* AT_SYMLINK_NOFOLLOW must reach libc unchanged, making this an lstat. */ AKSL_CHECK_OK(aksl_fstatat(AT_FDCWD, linkpath, &dest, AT_SYMLINK_NOFOLLOW)); AKSL_CHECK(S_ISLNK(dest.st_mode)); ``` (`path` comes from `aksl_temp_file`, which builds it under `$TMPDIR` or `/tmp`; pull the directory from the same source rather than hardcoding `/tmp`.)
struct stat dest;
struct statvfs vdest;
AKSL_CHECK(aksl_temp_file(path, sizeof(path)) == 0);
AKSL_CHECK_STATUS(aksl_stat(NULL, &dest), AKERR_NULLPOINTER);
logikoma marked this conversation as resolved
tachikoma commented 2026-08-03 09:59:21 -04:00
Review
Copy Link

Nit — magic number.

0x40000000 is "a flag bit libc will reject", and nothing in the file says so. It is currently unallocated on Linux, but the AT_ space is still being handed out — AT_RECURSIVE (0x8000), the AT_STATX_* bits and AT_HANDLE_FID were all added over time. When 0x40000000 is eventually assigned, this test either starts failing for a reason nobody will connect to this line, or worse, keeps passing for a different reason.

Fix: name it and say why.

/*
 * A bit libc has never assigned in the AT_ space. fstatat(2) must reject it
 * with EINVAL rather than ignoring it, which is what proves flags reach libc
 * unmasked. Re-check this constant if AT_ ever grows into 0x40000000.
 */
#define AKSL_TEST_AT_INVALID 0x40000000
**Nit — magic number.** `0x40000000` is "a flag bit libc will reject", and nothing in the file says so. It is currently unallocated on Linux, but the `AT_` space is still being handed out — `AT_RECURSIVE` (0x8000), the `AT_STATX_*` bits and `AT_HANDLE_FID` were all added over time. When 0x40000000 is eventually assigned, this test either starts failing for a reason nobody will connect to this line, or worse, keeps passing for a different reason. **Fix:** name it and say why. ```c /* * A bit libc has never assigned in the AT_ space. fstatat(2) must reject it * with EINVAL rather than ignoring it, which is what proves flags reach libc * unmasked. Re-check this constant if AT_ ever grows into 0x40000000. */ #define AKSL_TEST_AT_INVALID 0x40000000 ```
AKSL_CHECK_STATUS(aksl_stat(path, NULL), AKERR_NULLPOINTER);
logikoma marked this conversation as resolved
tachikoma commented 2026-08-03 09:59:20 -04:00
Review
Copy Link

DEFECT (medium) — this asserts on errno after intervening library calls that are allowed to change it.

AKSL_CHECK_STATUS on line 65 does not just evaluate the expression. It calls aksl_take() (tests/aksl_capture.h), which runs four snprintf calls and akerr_release_error() before returning. Only then does line 66 read errno.

C permits a standard library function to set errno to a non-zero value even on a successful call. So this assertion is relying on glibc's snprintf happening not to touch errno for these particular inputs. It passes today. It is not guaranteed by anything, and it will fail on a libc where that is not true, with a failure message that points at fstatat rather than at snprintf.

Two further problems with it:

  1. It is redundant. Line 65 already proved the wrapper reported EINVAL. Line 66 adds no coverage of the wrapper.
  2. It asserts a contract the library does not offer. Nothing in include/akstdlib.h promises anything about errno after a wrapper returns — and it could not, because the NULL-argument paths (src/stat.c:15-16, 30-31, 44, 57-58, 72-73, 86) return before errno = 0 is ever reached, so on those paths errno is whatever stale value the caller already had. Codifying a post-call errno reading for one path out of two is how an accidental contract gets born.

Fix: delete line 66. The errno = E2BIG on line 64 is the valuable part — it proves the wrapper does not report a stale errno — and line 65 already checks it.

Worth stating the other half plainly, since it is the thing this test was reaching for: the errno handling in the library itself is correct. I traced it. FAIL expands to ENSURE_ERROR_READY(e); e->status = __err;, so AKSL_ERRNO_OR is evaluated after akerr_next_error() runs — and akerr_next_error() (deps/libakerror/src/error.c:240-248) is a bare loop over AKERR_ARRAY_ERROR with no library calls in it, so it cannot clobber errno in between. All six wrappers reset errno immediately before their libc call and read it before anything else can run. No defect there.

**DEFECT (medium) — this asserts on `errno` after intervening library calls that are allowed to change it.** `AKSL_CHECK_STATUS` on line 65 does not just evaluate the expression. It calls `aksl_take()` (`tests/aksl_capture.h`), which runs **four `snprintf` calls and `akerr_release_error()`** before returning. Only then does line 66 read `errno`. C permits a standard library function to set `errno` to a non-zero value even on a successful call. So this assertion is relying on glibc's `snprintf` happening not to touch `errno` for these particular inputs. It passes today. It is not guaranteed by anything, and it will fail on a libc where that is not true, with a failure message that points at `fstatat` rather than at `snprintf`. Two further problems with it: 1. **It is redundant.** Line 65 already proved the wrapper reported `EINVAL`. Line 66 adds no coverage of the wrapper. 2. **It asserts a contract the library does not offer.** Nothing in `include/akstdlib.h` promises anything about `errno` after a wrapper returns — and it could not, because the NULL-argument paths (`src/stat.c:15-16`, `30-31`, `44`, `57-58`, `72-73`, `86`) return *before* `errno = 0` is ever reached, so on those paths `errno` is whatever stale value the caller already had. Codifying a post-call `errno` reading for one path out of two is how an accidental contract gets born. **Fix:** delete line 66. The `errno = E2BIG` on line 64 is the valuable part — it proves the wrapper does not report a stale errno — and line 65 already checks it. Worth stating the other half plainly, since it is the thing this test was reaching for: **the errno handling in the library itself is correct.** I traced it. `FAIL` expands to `ENSURE_ERROR_READY(e); e->status = __err;`, so `AKSL_ERRNO_OR` is evaluated *after* `akerr_next_error()` runs — and `akerr_next_error()` (`deps/libakerror/src/error.c:240-248`) is a bare loop over `AKERR_ARRAY_ERROR` with no library calls in it, so it cannot clobber `errno` in between. All six wrappers reset `errno` immediately before their libc call and read it before anything else can run. No defect there.
AKSL_CHECK_STATUS(aksl_lstat(NULL, &dest), AKERR_NULLPOINTER);
AKSL_CHECK_STATUS(aksl_lstat(path, NULL), AKERR_NULLPOINTER);
AKSL_CHECK_STATUS(aksl_fstat(0, NULL), AKERR_NULLPOINTER);
AKSL_CHECK_STATUS(aksl_fstatat(AT_FDCWD, NULL, &dest, 0), AKERR_NULLPOINTER);
AKSL_CHECK_STATUS(aksl_fstatat(AT_FDCWD, path, NULL, 0), AKERR_NULLPOINTER);
AKSL_CHECK_STATUS(aksl_statvfs(NULL, &vdest), AKERR_NULLPOINTER);
AKSL_CHECK_STATUS(aksl_statvfs(path, NULL), AKERR_NULLPOINTER);
AKSL_CHECK_STATUS(aksl_fstatvfs(0, NULL), AKERR_NULLPOINTER);
AKSL_CHECK(unlink(path) == 0);
return 0;
}
int main(void)
{
int failures = 0;
AKSL_RUN(failures, test_stat_success_and_fstat);
AKSL_RUN(failures, test_stat_paths_and_fstatat);
AKSL_RUN(failures, test_stat_null_arguments);
AKSL_REPORT(failures);
}