Add directory stream wrappers

UPGRADING.md

@@ -83,10 +83,11 @@ having visited nothing.
 /* before */
 aksl_sprintf(&count, buf, "%s=%d", key, value);
 /* after */
-aksl_snprintf(buf, sizeof(buf), "%s=%d", key, value);
+aksl_snprintf(&count, buf, sizeof(buf), "%s=%d", key, value);
 ```
 
-Truncation is `AKERR_OUTOFBOUNDS` rather than a short success.
+Truncation is `AKERR_OUTOFBOUNDS` rather than a short success, and `*count` is
+`0` on any failure rather than `vsprintf`'s `-1`.
 
 **`aksl_realpath` takes the destination's length.**
 

include/akstdlib.h

@@ -444,8 +444,9 @@ akerr_ErrorContext AKERR_NOIGNORE *aksl_memchr(const void *s, int c, size_t n, v
 /* ====================================================================== */
 /** @name Formatted output
  *
- * Bounded output is checked for truncation and reports an error when the result
- * does not fit.
+ * `*count` is the byte count written excluding the terminating NUL, and is 0 on
+ * every failure path -- never vsnprintf's -1, and never the length the output
+ * *would* have been.
  *
  * There is no aksl_sprintf. It wrapped vsprintf, which cannot be bounded, and an
  * error-handling wrapper around an unbounded write is the sharp edge this
@@ -482,15 +483,16 @@ akerr_ErrorContext AKERR_NOIGNORE *aksl_fprintf(int *count, FILE *restrict strea
  * written, leaving the caller to notice by comparing that against the buffer
  * size -- the check this library exists to stop people forgetting.
  *
+ * @param[out] count  Bytes written excluding the NUL; 0 on failure. Required.
  * @param[out] str    Destination buffer. Required.
  * @param[in]  size   Size of `str` including the terminator. Must be non-zero.
  * @param[in]  format printf format string. Required. Checked at compile time.
- * @throws AKERR_NULLPOINTER If str or format is NULL.
+ * @throws AKERR_NULLPOINTER If any pointer is NULL.
  * @throws AKERR_VALUE If size is 0.
  * @throws AKERR_OUTOFBOUNDS If the output does not fit, naming both lengths.
  * @return NULL on success, an error context otherwise.
  */
-akerr_ErrorContext AKERR_NOIGNORE *aksl_snprintf(char *restrict str, size_t size, const char *restrict format, ...) AKSL_PRINTF_FORMAT(3, 4);
+akerr_ErrorContext AKERR_NOIGNORE *aksl_snprintf(int *count, char *restrict str, size_t size, const char *restrict format, ...) AKSL_PRINTF_FORMAT(4, 5);
 
 /**
  * @brief Format into a freshly allocated string.
@@ -549,6 +551,7 @@ akerr_ErrorContext AKERR_NOIGNORE *aksl_vfprintf(int *count, FILE *restrict stre
 
 /**
  * @brief vsnprintf(3) into a bounded buffer. The va_list form of aksl_snprintf.
+ * @param[out] count  Bytes written excluding the NUL; 0 on failure. Required.
  * @param[out] str    Destination buffer. Required.
  * @param[in]  size   Size of `str` including the terminator. Must be non-zero.
  * @param[in]  format printf format string. Required.
@@ -558,7 +561,7 @@ akerr_ErrorContext AKERR_NOIGNORE *aksl_vfprintf(int *count, FILE *restrict stre
  * @throws AKERR_OUTOFBOUNDS If the output does not fit.
  * @return NULL on success, an error context otherwise.
  */
-akerr_ErrorContext AKERR_NOIGNORE *aksl_vsnprintf(char *restrict str, size_t size, const char *restrict format, va_list args);
+akerr_ErrorContext AKERR_NOIGNORE *aksl_vsnprintf(int *count, char *restrict str, size_t size, const char *restrict format, va_list args);
 
 /** @} */
 

src/dir.c

@@ -1,20 +1,10 @@
-/*
- * POSIX directory-stream wrappers.
- *
- * opendir(3), fdopendir(3), readdir(3), closedir(3), and rewinddir(3) expose
- * three different failure conventions between them. These wrappers turn all
- * three into error contexts and make end-of-directory an explicit AKERR_EOF.
- */
+/* POSIX directory-stream wrappers. */
 #include <akstdlib.h>
 
 #include <errno.h>
 
 #include "aksl_internal.h"
 
-/*
- * opendir(3) returns NULL for failure. Clear *dest first so a failed open
- * cannot leave the caller holding a stale directory stream.
- */
 akerr_ErrorContext AKERR_NOIGNORE *aksl_opendir(const char *pathname, DIR **dest)
 {
     PREPARE_ERROR(e);
@@ -29,10 +19,6 @@ akerr_ErrorContext AKERR_NOIGNORE *aksl_opendir(const char *pathname, DIR **dest
     SUCCEED_RETURN(e);
 }
 
-/*
- * fdopendir(3) takes ownership of fd only when it succeeds. On success the
- * matching aksl_closedir call closes both the stream and its descriptor.
- */
 akerr_ErrorContext AKERR_NOIGNORE *aksl_fdopendir(int fd, DIR **dest)
 {
     PREPARE_ERROR(e);
@@ -44,10 +30,6 @@ akerr_ErrorContext AKERR_NOIGNORE *aksl_fdopendir(int fd, DIR **dest)
     SUCCEED_RETURN(e);
 }
 
-/*
- * readdir(3) owns and may reuse its returned storage. Copy the entry into the
- * caller's destination, and use errno to distinguish failure from exhaustion.
- */
 akerr_ErrorContext AKERR_NOIGNORE *aksl_readdir(DIR *dirp, struct dirent *dest)
 {
     struct dirent *entry = NULL;
@@ -68,7 +50,6 @@ akerr_ErrorContext AKERR_NOIGNORE *aksl_readdir(DIR *dirp, struct dirent *dest)
     SUCCEED_RETURN(e);
 }
 
-/* closedir(3) reports its failure directly and invalidates dirp on success. */
 akerr_ErrorContext AKERR_NOIGNORE *aksl_closedir(DIR *dirp)
 {
     PREPARE_ERROR(e);
@@ -79,10 +60,6 @@ akerr_ErrorContext AKERR_NOIGNORE *aksl_closedir(DIR *dirp)
     SUCCEED_RETURN(e);
 }
 
-/*
- * rewinddir(3) has no failure return. Preserve that contract after rejecting
- * a NULL stream, which would otherwise be undefined behaviour.
- */
 akerr_ErrorContext AKERR_NOIGNORE *aksl_rewinddir(DIR *dirp)
 {
     PREPARE_ERROR(e);

src/stdlib.c

@@ -416,6 +416,10 @@ akerr_ErrorContext AKERR_NOIGNORE *aksl_fclose(FILE *stream)
  *     register-save state on some ABIs. akbasic's text sink ran this UB on every
  *     line of program output without anything visibly misbehaving, which is
  *     exactly what made it worth fixing before something did.
+ *   - *count is written on every path. It used to be left holding vprintf's -1
+ *     after a failure, so a caller who read the length rather than the status got
+ *     a negative byte count out of a function that had already failed. It is now
+ *     0 whenever an error is raised.
  *   - errno is cleared before the call and read back through AKSL_ERRNO_OR, so a
  *     failure can never be reported with a stale -- or with a zero -- status.
  *
@@ -481,31 +485,34 @@ akerr_ErrorContext AKERR_NOIGNORE *aksl_fprintf(int *count, FILE *restrict strea
  * *would* have written and silently drops the rest, which is the single most
  * common way a bounded write goes wrong unnoticed; a caller who wanted to know
  * would have had to compare the return against the buffer size by hand, which is
- * the check this library exists to stop people forgetting. The bounded wrapper
- * reports truncation instead.
+ * the check this library exists to stop people forgetting. *count is the number
+ * of bytes written excluding the terminating NUL, and is 0 on any failure.
  */
-akerr_ErrorContext AKERR_NOIGNORE *aksl_vsnprintf(char *restrict str, size_t size, const char *restrict format, va_list args)
+akerr_ErrorContext AKERR_NOIGNORE *aksl_vsnprintf(int *count, char *restrict str, size_t size, const char *restrict format, va_list args)
 {
     int needed = 0;
     PREPARE_ERROR(e);
-    FAIL_ZERO_RETURN(e, str, AKERR_NULLPOINTER, "str=%p, format=%p", (void *)str, (void *)format);
-    FAIL_ZERO_RETURN(e, format, AKERR_NULLPOINTER, "str=%p, format=%p", (void *)str, (void *)format);
+    FAIL_ZERO_RETURN(e, count, AKERR_NULLPOINTER, "count=%p, str=%p, format=%p", (void *)count, (void *)str, (void *)format);
+    *count = 0;
+    FAIL_ZERO_RETURN(e, str, AKERR_NULLPOINTER, "count=%p, str=%p, format=%p", (void *)count, (void *)str, (void *)format);
+    FAIL_ZERO_RETURN(e, format, AKERR_NULLPOINTER, "count=%p, str=%p, format=%p", (void *)count, (void *)str, (void *)format);
     FAIL_ZERO_RETURN(e, size, AKERR_VALUE, "size=0 leaves no room even for the terminating NUL");
     errno = 0;
     needed = vsnprintf(str, size, format, args);
     FAIL_NONZERO_RETURN(e, (needed < 0), AKSL_ERRNO_OR(AKERR_IO), "Output error");
     FAIL_NONZERO_RETURN(e, ((size_t)needed >= size), AKERR_OUTOFBOUNDS,
 			"output truncated: %d bytes needed, %zu available", needed, size);
+    *count = needed;
     SUCCEED_RETURN(e);
 }
 
-akerr_ErrorContext AKERR_NOIGNORE *aksl_snprintf(char *restrict str, size_t size, const char *restrict format, ...)
+akerr_ErrorContext AKERR_NOIGNORE *aksl_snprintf(int *count, char *restrict str, size_t size, const char *restrict format, ...)
 {
     va_list args;
     akerr_ErrorContext *raised = NULL;
 
     va_start(args, format);
-    raised = aksl_vsnprintf(str, size, format, args);
+    raised = aksl_vsnprintf(count, str, size, format, args);
     va_end(args);
     return raised;
 }

tests/negative/format_mismatch.c

@@ -16,10 +16,11 @@
 int main(void)
 {
     char buf[64];
+    int count = 0;
     akerr_ErrorContext *raised = NULL;
 
     /* %d against a string. This is the line that must not build. */
-    raised = aksl_snprintf(buf, sizeof(buf), "%d", "not an int");
+    raised = aksl_snprintf(&count, buf, sizeof(buf), "%d", "not an int");
 
     return raised == NULL ? 0 : 1;
 }

tests/test_dir.c

@@ -23,21 +23,14 @@ static int test_open_errors_and_nulls(void)
     DIR *dirp = (DIR *)1;
     struct dirent entry;
 
-    /* opendir propagates missing-path and non-directory failures. */
     AKSL_CHECK_STATUS(aksl_opendir("/nonexistent/aksl/dir", &dirp), ENOENT);
     AKSL_CHECK(dirp == NULL);
     AKSL_CHECK(aksl_temp_file(file, sizeof(file)) == 0);
     AKSL_CHECK_STATUS(aksl_opendir(file, &dirp), ENOTDIR);
-
-    /* Every pointer required by the wrapped operation rejects NULL. */
     AKSL_CHECK_STATUS(aksl_opendir(NULL, &dirp), AKERR_NULLPOINTER);
     AKSL_CHECK_STATUS(aksl_opendir(".", NULL), AKERR_NULLPOINTER);
-
-    /* fdopendir propagates an invalid descriptor and validates its out-param. */
     AKSL_CHECK_STATUS(aksl_fdopendir(-1, &dirp), EBADF);
     AKSL_CHECK_STATUS(aksl_fdopendir(0, NULL), AKERR_NULLPOINTER);
-
-    /* The remaining wrappers reject NULL streams and destinations. */
     AKSL_CHECK_STATUS(aksl_readdir(NULL, &entry), AKERR_NULLPOINTER);
     AKSL_CHECK_OK(aksl_opendir(".", &dirp));
     AKSL_CHECK_STATUS(aksl_readdir(dirp, NULL), AKERR_NULLPOINTER);

tests/test_format.c

@@ -2,8 +2,10 @@
  * Formatted-output wrappers: aksl_printf / aksl_fprintf / aksl_snprintf and
  * their va_list forms.
  *
- * Formatted output, complete. Each happy path asserts the text that actually
- * landed somewhere, and every pointer argument is checked for its NULL guard.
+ * Formatted output, complete. Each happy path asserts both halves of the
+ * contract -- the byte count handed back through *count and the text that
+ * actually landed somewhere -- and every pointer argument is checked for its
+ * NULL guard.
  *
  * Readback goes through plain libc rather than aksl_fread so that a failure here
  * points at the formatted-output wrapper under test and not at the stream
@@ -37,12 +39,14 @@ static long read_file(const char *path, char *buf, size_t n)
     return (long)got;
 }
 
-static int test_snprintf_writes_text(void)
+static int test_snprintf_writes_text_and_count(void)
 {
     char buf[64];
+    int count = -1;
 
     memset(buf, 0x00, sizeof(buf));
-    AKSL_CHECK_OK(aksl_snprintf(buf, sizeof(buf), "%s=%d", "x", 7));
+    AKSL_CHECK_OK(aksl_snprintf(&count, buf, sizeof(buf), "%s=%d", "x", 7));
+    AKSL_CHECK(count == 3);
     AKSL_CHECK(strcmp(buf, "x=7") == 0);
     return 0;
 }
@@ -50,8 +54,10 @@ static int test_snprintf_writes_text(void)
 static int test_snprintf_empty_format_writes_nothing(void)
 {
     char buf[8] = { 'z', 'z', 'z', 'z', 'z', 'z', 'z', 'z' };
+    int count = -1;
 
-    AKSL_CHECK_OK(aksl_snprintf(buf, sizeof(buf), "%s", ""));
+    AKSL_CHECK_OK(aksl_snprintf(&count, buf, sizeof(buf), "%s", ""));
+    AKSL_CHECK(count == 0);
     AKSL_CHECK(buf[0] == '\0');
     return 0;
 }
@@ -60,17 +66,18 @@ static int test_snprintf_empty_format_writes_nothing(void)
  * The case that could not be written while the wrapper was aksl_sprintf: output
  * longer than the destination. snprintf(3) would truncate, NUL-terminate and
  * report the length it *would* have written, leaving the caller to notice; here
- * it is an error.
+ * it is an error, and *count is 0 rather than the would-have-been length.
  */
 static int test_snprintf_truncation_is_an_error(void)
 {
     char buf[8];
+    int count = -1;
 
     memset(buf, 0x00, sizeof(buf));
     AKSL_CHECK_STATUS_MSG_CONTAINS(
-	aksl_snprintf(buf, sizeof(buf), "%s", "far too long for eight bytes"),
+	aksl_snprintf(&count, buf, sizeof(buf), "%s", "far too long for eight bytes"),
 	AKERR_OUTOFBOUNDS, "truncated");
-    AKSL_CHECK(strcmp(buf, "far too") == 0);
+    AKSL_CHECK(count == 0);
     return 0;
 }
 
@@ -78,27 +85,34 @@ static int test_snprintf_truncation_is_an_error(void)
 static int test_snprintf_boundary_is_exact(void)
 {
     char buf[8];
+    int count = -1;
 
     /* 7 characters plus the NUL is exactly sizeof(buf). */
-    AKSL_CHECK_OK(aksl_snprintf(buf, sizeof(buf), "%s", "1234567"));
+    AKSL_CHECK_OK(aksl_snprintf(&count, buf, sizeof(buf), "%s", "1234567"));
+    AKSL_CHECK(count == 7);
     AKSL_CHECK(strcmp(buf, "1234567") == 0);
 
-    AKSL_CHECK_STATUS(aksl_snprintf(buf, sizeof(buf), "%s", "12345678"),
+    count = -1;
+    AKSL_CHECK_STATUS(aksl_snprintf(&count, buf, sizeof(buf), "%s", "12345678"),
 		      AKERR_OUTOFBOUNDS);
+    AKSL_CHECK(count == 0);
     return 0;
 }
 
 static int test_snprintf_rejects_null_arguments_and_zero_size(void)
 {
     char buf[8];
+    int count = 0;
 
     memset(buf, 0x00, sizeof(buf));
-	AKSL_CHECK_STATUS_MSG_CONTAINS(aksl_snprintf(NULL, 8, "x"),
+    AKSL_CHECK_STATUS_MSG_CONTAINS(aksl_snprintf(NULL, buf, sizeof(buf), "x"),
+				   AKERR_NULLPOINTER, "count=");
+    AKSL_CHECK_STATUS_MSG_CONTAINS(aksl_snprintf(&count, NULL, 8, "x"),
 				   AKERR_NULLPOINTER, "str=");
-	AKSL_CHECK_STATUS_MSG_CONTAINS(aksl_snprintf(buf, sizeof(buf), NULL),
+    AKSL_CHECK_STATUS_MSG_CONTAINS(aksl_snprintf(&count, buf, sizeof(buf), NULL),
 				   AKERR_NULLPOINTER, "format=");
     /* size 0 leaves no room even for the terminator, so there is nothing to do. */
-	AKSL_CHECK_STATUS_MSG_CONTAINS(aksl_snprintf(buf, 0, "x"),
+    AKSL_CHECK_STATUS_MSG_CONTAINS(aksl_snprintf(&count, buf, 0, "x"),
 				   AKERR_VALUE, "size=0");
     return 0;
 }
@@ -260,14 +274,14 @@ static int test_asprintf_allocates_to_fit(void)
  * wanted them exposed so consumers can write their own variadic wrappers. This
  * is a consumer doing exactly that.
  */
-static akerr_ErrorContext AKERR_NOIGNORE *consumer_wrapper(char *buf, size_t n,
+static akerr_ErrorContext AKERR_NOIGNORE *consumer_wrapper(int *count, char *buf, size_t n,
 							   const char *fmt, ...)
 {
     va_list args;
     akerr_ErrorContext *raised = NULL;
 
     va_start(args, fmt);
-    raised = aksl_vsnprintf(buf, n, fmt, args);
+    raised = aksl_vsnprintf(count, buf, n, fmt, args);
     va_end(args);
     return raised;
 }
@@ -275,14 +289,17 @@ static akerr_ErrorContext AKERR_NOIGNORE *consumer_wrapper(char *buf, size_t n,
 static int test_va_list_forms_are_usable_from_outside(void)
 {
     char buf[32];
+    int count = -1;
 
     memset(buf, 0x00, sizeof(buf));
-    AKSL_CHECK_OK(consumer_wrapper(buf, sizeof(buf), "%s/%d", "via", 3));
+    AKSL_CHECK_OK(consumer_wrapper(&count, buf, sizeof(buf), "%s/%d", "via", 3));
+    AKSL_CHECK(count == 5);
     AKSL_CHECK(strcmp(buf, "via/3") == 0);
 
     /* The error contract survives the extra layer intact. */
-    AKSL_CHECK_STATUS(consumer_wrapper(buf, 4, "%s", "too long"),
+    AKSL_CHECK_STATUS(consumer_wrapper(&count, buf, 4, "%s", "too long"),
 		      AKERR_OUTOFBOUNDS);
+    AKSL_CHECK(count == 0);
     return 0;
 }
 
@@ -295,12 +312,14 @@ static int test_va_list_forms_are_usable_from_outside(void)
 static int test_variadic_wrappers_survive_repeated_calls(void)
 {
     char buf[128];
+    int count = 0;
     int i = 0;
 
     for ( i = 0; i < 512; i++ ) {
-	AKSL_CHECK_OK(aksl_snprintf(buf, sizeof(buf), "%d %s %ld %c %f",
+	AKSL_CHECK_OK(aksl_snprintf(&count, buf, sizeof(buf), "%d %s %ld %c %f",
 				    i, "iteration", (long)i, 'x', (double)i));
-	AKSL_CHECK(strlen(buf) > 0);
+	AKSL_CHECK(count > 0);
+	AKSL_CHECK((size_t)count == strlen(buf));
     }
     return 0;
 }
@@ -311,7 +330,7 @@ int main(void)
 
     akerr_init();
 
-    AKSL_RUN(failures, test_snprintf_writes_text);
+    AKSL_RUN(failures, test_snprintf_writes_text_and_count);
     AKSL_RUN(failures, test_snprintf_empty_format_writes_nothing);
     AKSL_RUN(failures, test_snprintf_truncation_is_an_error);
     AKSL_RUN(failures, test_snprintf_boundary_is_exact);

tests/test_pool.c

@@ -109,13 +109,14 @@ static int test_stream_wrappers_do_not_leak_slots(void)
 static int test_format_wrappers_do_not_leak_slots(void)
 {
     char buf[16];
+    int count = 0;
     int i = 0;
 
     for ( i = 0; i < ROUNDS; i++ ) {
 	AKSL_CHECK_STATUS(aksl_printf(NULL, "x"), AKERR_NULLPOINTER);
 	AKSL_CHECK_STATUS(aksl_fprintf(NULL, stdout, "x"), AKERR_NULLPOINTER);
-	AKSL_CHECK_OK(aksl_snprintf(buf, sizeof(buf), "x"));
-	AKSL_CHECK_STATUS(aksl_snprintf(buf, 4, "%s", "far too long"),
+	AKSL_CHECK_STATUS(aksl_snprintf(NULL, buf, sizeof(buf), "x"), AKERR_NULLPOINTER);
+	AKSL_CHECK_STATUS(aksl_snprintf(&count, buf, 4, "%s", "far too long"),
 			  AKERR_OUTOFBOUNDS);
 	AKSL_CHECK(aksl_slots_in_use() == 0);
     }
@@ -265,6 +266,7 @@ static int test_traversal_failures_do_not_leak_slots(void)
 static int test_errors_name_their_origin_in_stdlib(void)
 {
     void *ptr = NULL;
+    int count = 0;
     char resolved[PATH_MAX];
     uint32_t h = 0;
     aksl_ListNode node;
@@ -293,7 +295,7 @@ static int test_errors_name_their_origin_in_stdlib(void)
     AKSL_CHECK_STATUS(aksl_printf(NULL, "x"), AKERR_NULLPOINTER);
     AKSL_CHECK(came_from("aksl_vprintf", "src/stdlib.c") == 0);
 
-    AKSL_CHECK_STATUS(aksl_snprintf(NULL, 8, "x"), AKERR_NULLPOINTER);
+    AKSL_CHECK_STATUS(aksl_snprintf(&count, NULL, 8, "x"), AKERR_NULLPOINTER);
     AKSL_CHECK(came_from("aksl_vsnprintf", "src/stdlib.c") == 0);
 
     /* Likewise, the ato* forms are calls into the strto* ones. */