Test file metadata failure paths

Co-authored-by: Andrew Kesterson <andrew@aklabs.net>

include/akstdlib.h

@@ -76,6 +76,7 @@
 #include <stddef.h>
 #include <stdint.h>
 #include <stdio.h>
+#include <fcntl.h>
 #include <sys/stat.h>
 #include <sys/statvfs.h>
 /* off_t, for the aksl_fseeko/aksl_ftello pair. POSIX, like aksl_realpath. */
@@ -810,10 +811,25 @@ akerr_ErrorContext AKERR_NOIGNORE *aksl_strhash_djb2_str(const char *str, uint32
 
 /** @} */
 
+/* ====================================================================== */
+/** @name File and filesystem metadata
+ *
+ * The stat family reports into caller-owned POSIX structs rather than a smaller
+ * library-defined copy: the platform owns the fields, and a wrapper should not
+ * discard a field merely because this library does not currently use it. libc
+ * failures retain their errno value as the status, so callers can distinguish
+ * absent paths from inaccessible ones without parsing an error message.
+ *  @{
+ */
+/* ====================================================================== */
+
 /**
  * @brief stat(2).
  * @param[in] pathname Path to inspect. Required.
  * @param[out] dest File metadata. Required.
+ * @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.
  * @return NULL on success, an error context otherwise.
  */
 akerr_ErrorContext AKERR_NOIGNORE *aksl_stat(const char *pathname, struct stat *dest);
@@ -822,6 +838,9 @@ akerr_ErrorContext AKERR_NOIGNORE *aksl_stat(const char *pathname, struct stat *
  * @brief lstat(2), inspecting a symbolic link itself.
  * @param[in] pathname Path to inspect. Required.
  * @param[out] dest File metadata. Required.
+ * @throws AKERR_NULLPOINTER If pathname or dest is NULL.
+ * @throws AKERR_IO If lstat(2) failed and left errno at 0.
+ * @throws (errno) The errno lstat(2) set, reported directly as the status.
  * @return NULL on success, an error context otherwise.
  */
 akerr_ErrorContext AKERR_NOIGNORE *aksl_lstat(const char *pathname, struct stat *dest);
@@ -830,6 +849,9 @@ akerr_ErrorContext AKERR_NOIGNORE *aksl_lstat(const char *pathname, struct stat
  * @brief fstat(2).
  * @param[in] fd Open file descriptor.
  * @param[out] dest File metadata. Required.
+ * @throws AKERR_NULLPOINTER If dest is NULL.
+ * @throws AKERR_IO If fstat(2) failed and left errno at 0.
+ * @throws (errno) The errno fstat(2) set, reported directly as the status.
  * @return NULL on success, an error context otherwise.
  */
 akerr_ErrorContext AKERR_NOIGNORE *aksl_fstat(int fd, struct stat *dest);
@@ -840,6 +862,9 @@ akerr_ErrorContext AKERR_NOIGNORE *aksl_fstat(int fd, struct stat *dest);
  * @param[in] pathname Path to inspect. Required.
  * @param[out] dest File metadata. Required.
  * @param[in] flags libc fstatat flags, passed unchanged.
+ * @throws AKERR_NULLPOINTER If pathname or dest is NULL.
+ * @throws AKERR_IO If fstatat(2) failed and left errno at 0.
+ * @throws (errno) The errno fstatat(2) set, reported directly as the status.
  * @return NULL on success, an error context otherwise.
  */
 akerr_ErrorContext AKERR_NOIGNORE *aksl_fstatat(int dirfd, const char *pathname, struct stat *dest, int flags);
@@ -848,6 +873,9 @@ akerr_ErrorContext AKERR_NOIGNORE *aksl_fstatat(int dirfd, const char *pathname,
  * @brief statvfs(3).
  * @param[in] path Path on the filesystem. Required.
  * @param[out] dest Filesystem metadata. Required.
+ * @throws AKERR_NULLPOINTER If path or dest is NULL.
+ * @throws AKERR_IO If statvfs(3) failed and left errno at 0.
+ * @throws (errno) The errno statvfs(3) set, reported directly as the status.
  * @return NULL on success, an error context otherwise.
  */
 akerr_ErrorContext AKERR_NOIGNORE *aksl_statvfs(const char *path, struct statvfs *dest);
@@ -856,11 +884,15 @@ akerr_ErrorContext AKERR_NOIGNORE *aksl_statvfs(const char *path, struct statvfs
  * @brief fstatvfs(3).
  * @param[in] fd Open file descriptor.
  * @param[out] dest Filesystem metadata. Required.
+ * @throws AKERR_NULLPOINTER If dest is NULL.
+ * @throws AKERR_IO If fstatvfs(3) failed and left errno at 0.
+ * @throws (errno) The errno fstatvfs(3) set, reported directly as the status.
  * @return NULL on success, an error context otherwise.
  */
 akerr_ErrorContext AKERR_NOIGNORE *aksl_fstatvfs(int fd, struct statvfs *dest);
 
 
+/** @} */
 /* ====================================================================== */
 /** @name Streams: open, read, write, close
  *