8 files changed, 78 insertions, 4 deletions

diff --git a/doc/api.rst b/doc/api.rst
index 84feaa6..5b2161d 100644
--- a/doc/api.rst
+++ b/doc/api.rst
@@ -9,7 +9,13 @@ Function reference
 ======  ======  ======  ========================================
 RMV     MinVer  FirstA  Name
 ======  ======  ======  ========================================
-4.18    4.18    4.18    HX_getopt5
+4.25    inline  4.25    HX_isascii
+4.25    inline  4.25    HX::make_scope_exit
+4.25    inline  4.25    cpu_to_le{16,32,64}p cpu_to_be{16,32,64}p
+4.25    inline  4.25    le{16,32,64}p_to_cpu be{16,32,64}p_to_cpu
+4.25    4.25    4.25    HXSIZEOF_UNITSEC64
+4.24    4.24    4.24    HX_getcwd
+4.19    4.18    4.18    HX_getopt5
 4.16    4.16    4.16    HX_strtoull_nsec
 4.15    4.15    4.15    HX_flpr
 4.15    4.15    4.15    HX_flprf
diff --git a/doc/changelog.rst b/doc/changelog.rst
index f4bf0f1..f6f73f8 100644
--- a/doc/changelog.rst
+++ b/doc/changelog.rst
@@ -1,3 +1,30 @@
+v4.26 (2025-03-08)
+==================
+
+Fixes:
+
+* Resolve integer truncation in HX_unit_seconds's output when the result
+  were to exceeded 2^32 years or months or weeks.
+
+
+v4.25 (2025-03-07)
+==================
+
+Enhancements:
+
+* New headers endian.h and scope.hpp
+* New define HXSIZEOF_UNITSEC64 for the maximum output size of HX_unit_seconds
+
+
+v4.24 (2024-07-17)
+==================
+
+Fixes:
+
+* io: resolve use-after-free and out-of-bounds writes in conjunction
+  with HX_realpath
+
+
 v4.23 (2024-02-15)
 ==================
 
diff --git a/doc/files_and_dirs.rst b/doc/files_and_dirs.rst
index a18b5a4..a1d7090 100644
--- a/doc/files_and_dirs.rst
+++ b/doc/files_and_dirs.rst
@@ -57,9 +57,15 @@ Operation on directory entries
 
 	#include <libHX/io.h>
 
+	int HX_getcwd(hxmc_t **buf);
 	int HX_readlink(hxmc_t **buf, const char *path);
 	int HX_realpath(hxmc_t **buf, const char *path, unsigned int flags);
 
+``HX_getcwd`` is a length-agnostic version of getcwd. On error, a negative
+integer is returned indicating the errno; the contents of ``*buf`` are
+unspecified if that happens. On success, a non-zero positive integer is
+returned.
+
 ``HX_readlink`` calls through to readlink to read the target of a symbolic
 link, and stores the result in the memory container referenced by ``*buf``
 (similar to ``HX_getl`` semantics). If ``*buf`` is ``NULL``, a new container
@@ -91,7 +97,8 @@ actions:
 
 The result is stored in a memory container whose pointer is returned through
 ``*buf``. The return value of the function will be negative to indicate a
-possible system error, or be positive non-zero for success.
+possible system error, or be positive non-zero for success. The contents of the
+buffer are unspecified in case HX_realpath returns an error.
 
 
 Operations on directories
diff --git a/doc/helper_headers.rst b/doc/helper_headers.rst
index 7b4c083..05ded38 100644
--- a/doc/helper_headers.rst
+++ b/doc/helper_headers.rst
@@ -30,6 +30,7 @@ that there is a good reason to do so in the first place.
 
 	bool HX_isalnum(unsigned char c);
 	bool HX_isalpha(unsigned char c);
+	bool HX_isascii(unsigned char c);
 	bool HX_isdigit(unsigned char c);
 	bool HX_islower(unsigned char c);
 	bool HX_isprint(unsigned char c);
diff --git a/doc/macros.rst b/doc/macros.rst
index 752f81e..efc5209 100644
--- a/doc/macros.rst
+++ b/doc/macros.rst
@@ -27,6 +27,13 @@ Expands to the size needed for a buffer (including ``\0``) to hold the base-10
 string representation of 16‑, 32‑ or 64‑bit integer (either signed or
 unsigned), respectively.
 
+.. code-block:: c
+
+	#define HXSIZEOF_UNITSEC64
+
+Expands to the size needed for a buffer (including ``\0``) to hold the largest
+result of ``HX_unit_seconds``.
+
 Locators
 ========
 
diff --git a/doc/option_parsing.rst b/doc/option_parsing.rst
index 2dced82..fa928e0 100644
--- a/doc/option_parsing.rst
+++ b/doc/option_parsing.rst
@@ -12,7 +12,8 @@ Characteristics:
 * recognition of the double dash as option list terminator
 * offers POSIX strictness where the option list terminates at the first
   non-option argument
-* option passthrough
+* option passthrough (conceptuall only works for options taking no argument,
+  or when the argument is joined to a long option with a '=')
 * the parse function is one-shot; there is no context object (like popt),
   no global state (like getopt) and no ``while`` loop (either of the two others)
 * exclusively uses an option table
diff --git a/doc/scope.rst b/doc/scope.rst
new file mode 100644
index 0000000..84ad69b
--- /dev/null
+++ b/doc/scope.rst
@@ -0,0 +1,22 @@
+============
+Scope guards
+============
+
+``scope_exit``
+==============
+
+scope_exit creates an object that runs a predefined function when a scope ends.
+This is useful for augmenting C APIs with something of a destructor without
+wrapping the stuff in an explicit class of its own. For instance,
+
+.. code-block:: c++
+
+	#include <libHX/option.h>
+	#include <libHX/scope.hpp>
+	int main() {
+		auto fa = HXformat_init();
+		if (fa == nullptr)
+			return 0;
+		auto cleanup_fa = HX::make_scope_exit([&]() { HXformat_free(fa); });
+		HXformat_add(fa, "foo", "bar", HXTYPE_STRING);
+	}
diff --git a/doc/string_ops.rst b/doc/string_ops.rst
index 91da2f6..aea4896 100644
--- a/doc/string_ops.rst
+++ b/doc/string_ops.rst
@@ -478,7 +478,10 @@ be 1/12 such a year. This is consistent with the units employed by systemd.
 ``seconds`` into a string representation broken into days, hours, minutes, and
 remaining seconds as appropriate. By default, only the d/h/min/s units are
 emitted. The ``flags`` argument specifies if any other units should be emitted;
-``HXUNIT_YEARS``, ``HXUNIT_MONTHS`` and ``HXUNIT_WEEKS`` are available.
+``HXUNIT_YEARS``, ``HXUNIT_MONTHS`` and ``HXUNIT_WEEKS`` are available. The
+longest string HX_unit_seconds can emit on a contemporary 64-bit POSIX system
+with 1970 epoch is 40 characters (so a buffer should be no less than 41 bytes),
+cf. ``HXSIZEOF_UNITSEC64``.
 
 
 Examples