Merge branch 'release/debian/4.17-1'HEADmaster

7 files changed, 127 insertions, 35 deletions

diff --git a/doc/api.rst b/doc/api.rst
index 5a3efe5..a645fdd 100644
--- a/doc/api.rst
+++ b/doc/api.rst
@@ -9,6 +9,9 @@ Function reference
 ======  ======  ======  ========================================
 RMV     MinVer  FirstA  Name
 ======  ======  ======  ========================================
+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
 4.11    4.11    4.11    HX_addrport_split
 4.11    4.11    4.11    HX_inet_connect
 4.11    4.11    4.11    HX_inet_listen
diff --git a/doc/changelog.rst b/doc/changelog.rst
index 26c4d06..2e0cf0f 100644
--- a/doc/changelog.rst
+++ b/doc/changelog.rst
@@ -1,9 +1,39 @@
+v4.17 (2023-11-12)
+==================
+
+Changes:
+
+* socket: set SOCK_CLOEXEC on all sockets
+
+
+v4.16 (2023-11-02)
+==================
+
+Enhancements:
+
+* Add ``HX_strtoull_nsec`` to parse time period and emit nanoseconds
+* doc: specify return value and semantics for ``HXio_fullread``,
+  ``HXio_fullwrite``, ``HX_sendfile``
+
+
+v4.15 (2023-09-24)
+==================
+
+Enhancements:
+
+* Add functions to compute Least Positive Residue (``HX_flpr``, ``HX_flprf``)
+
+Fixes:
+
+* Make ``HX_strrtrim`` work on strings longer than ``INT_MAX``
+
+
 v4.14 (2023-07-14)
 ==================
 
 Fixes:
 
-* socket: make HX_addrport_split work on portless bracketed hostspec
+* socket: make ``HX_addrport_split`` work on portless bracketed hostspec
 
 
 v4.13 (2023-06-21)
@@ -11,8 +41,8 @@ v4.13 (2023-06-21)
 
 Fixes:
 
-* io: do not fail HX_mkdir when a component is a symlink to a directory
-* xml_helper: fix infinite recursion in xml_getnsprop
+* io: do not fail ``HX_mkdir`` when a component is a symlink to a directory
+* xml_helper: fix infinite recursion in ``xml_getnsprop``
 
 
 v4.12 (2023-02-27)
@@ -20,7 +50,7 @@ v4.12 (2023-02-27)
 
 Fixes:
 
-* Plug a memory leak in HX_inet_listen
+* Plug a memory leak in ``HX_inet_listen``
 
 
 v4.11 (2023-02-26)
@@ -28,8 +58,8 @@ v4.11 (2023-02-26)
 
 Enhancements:
 
-* socket: add HX_addrport_split, HX_inet_connect, HX_inet_listen,
-  HX_local_listen
+* socket: add ``HX_addrport_split``, ``HX_inet_connect``, ``HX_inet_listen``,
+  ``HX_local_listen``
 
 
 v4.10 (2023-01-29)
@@ -37,7 +67,7 @@ v4.10 (2023-01-29)
 
 Fixes:
 
-* format: plug a memory leak relating to func_entry_clone
+* format: plug a memory leak relating to ``func_entry_clone``
 * Resolve mingw build failure
 
 
@@ -46,13 +76,14 @@ v4.9 (2023-01-23)
 
 Enhancements:
 
-* socket: add sockaddr_is_local, ipaddr_is_local functions
+* socket: add ``sockaddr_is_local``, ``ipaddr_is_local`` functions
 
 Fixes:
 
-* format: avoid return value truncation from HXformat_aprintf, HXformat_sprintf
-* format: avoid calling HXmc_length on a non-hxmc object
-* format: add new variations of printf functions returning ssize_t
+* format: avoid return value truncation from ``HXformat_aprintf``,
+  ``HXformat_sprintf``
+* format: avoid calling ``HXmc_length`` on a non-hxmc object
+* format: add new variations of printf functions returning ``ssize_t``
 * Resolve Coverity-SCAN reports
 
 
@@ -61,7 +92,7 @@ v4.8 (2022-12-03)
 
 Enhancements:
 
-* io: call posix_fadvise when slurping files
+* io: call ``posix_fadvise`` when slurping files
 
 Fixes:
 
@@ -73,11 +104,11 @@ v4.7 (2022-10-21)
 
 Enhancements:
 
-* string: new quoting modes HXQUOTE_BASE64URL & HXQUOTE_BASE64IMAP
+* string: new quoting modes ``HXQUOTE_BASE64URL`` & ``HXQUOTE_BASE64IMAP``
 
 Fixes:
 
-* socket: make HX_socket_from_env functional on OpenBSD
+* socket: make ``HX_socket_from_env`` functional on OpenBSD
 
 
 v4.6 (2022-06-27)
@@ -85,8 +116,8 @@ v4.6 (2022-06-27)
 
 Enhancements:
 
-* HX_slurp_fd/HX_slurp_file now supports reading from files reporting their
-  own size as 0 (e.g. ttys, /proc special files).
+* ``HX_slurp_fd``/``HX_slurp_file`` now supports reading from files reporting
+  their own size as 0 (e.g. ttys, ``/proc`` special files).
 
 
 v4.5 (2022-04-10)
@@ -132,8 +163,8 @@ v4.1 (2021-10-13)
 
 Fixes:
 
-* io: fix a use-after-free in conjunction with HX_realpath /
-  fix missing NULLing of a pointer within HX_readlink
+* io: fix a use-after-free in conjunction with ``HX_realpath`` /
+  fix missing NULLing of a pointer within ``HX_readlink``
 
 
 v4.0 (2021-10-03)
diff --git a/doc/files_and_dirs.rst b/doc/files_and_dirs.rst
index a4fdc59..a18b5a4 100644
--- a/doc/files_and_dirs.rst
+++ b/doc/files_and_dirs.rst
@@ -180,11 +180,44 @@ Filedescriptor helpers
 	ssize_t HXio_fullwrite(int fd, const void *buf, size_t size, unsigned int flags);
 	ssize_t HX_sendfile(int dst, int src, size_t count);
 
-Since plain ``read``(2) and ``write``(2) may process only part of the buffer —
-even more likely so with sockets —, libHX provides two functions that calls
-these in a loop to retry said operations until the full amount has been
-processed. Since read and write can also be used with socket file descriptors,
-so can these.
+``HXio_fullread`` calls ``read``(2) in a loop so long as to completely read
+``size`` bytes, and thereby masking short read behavior that the *read* system
+call is allowed to exhibit. On success, the return value indicates the number
+of bytes read, which may be shorter than ``size`` if EOF was encountered. On
+error, the return value is negative (but no particular one value).
+
+``HXio_fullwrite`` calls ``write``(2) in a loop so long as to completely write
+``size`` bytes, and thereby masking short write behavior that the *write*
+system call is allowed to exhibit. On success, the return value is the same as
+``size``, as there is never an EOF condition for writes. On error, the return
+value is negative.
+
+There is no way with just HXio_fullwrite to know the number of bytes that were
+read up to the point that the error occurred. This was a subconscious design
+choice in 2010. The reasoning (as of 2023) goes: If the file descriptor is not
+seekable, like a socket or pipe, what are you going to do anyway but abort? You
+cannot recall the data that was sent, the peer already knows how much was sent
+thanks to their socket interface. The peer also either caused the abort itself
+(e.g. by closing the read end of a pipe), or is made aware of connection
+severing (will see EOF). If the file descriptor is seekable, there is no "peer"
+and one can ``lseek`` back and retract the data.
+
+The HXio_fullread API mirrors that of HXio_fullwrite for API consistency. Input
+is often discarded and an error shown instead. However, we acknowledge there
+might be a legitimate case (e.g. wanting to render an incoming image even if
+incomplete), but in this case, HXio_fullread is not for you.
 
 ``HX_sendfile`` wraps ``sendfile``(2) for the same reason; in addition, it
 falls back to a read-write loop on platforms which do not offer sendfile.
+``HX_sendfile`` will transfer at most ``SSIZE_MAX`` bytes in one call. A user
+wishing to emit somewhat more (e.g. still less than ``SIZE_MAX``) will have to
+write a loop around HXio_sendfile, just like for sendfile. On success, the
+return value is the request number of bytes. On error, the return value may be
+a negative errno (``errno`` is set too), or it may be the number of bytes from
+a partially-completed send.
+
+	.. code-block:: c
+
+	ssize_t ret = HX_sendfile(dst, src, count);
+	if (ret < 0 || (ssize_t)ret < count)
+		fprintf(stderr, "sendfile: %s\n", strerror(errno));
diff --git a/doc/misc_functions.rst b/doc/misc_functions.rst
index 43dacfe..c988f37 100644
--- a/doc/misc_functions.rst
+++ b/doc/misc_functions.rst
@@ -8,6 +8,8 @@ Miscellaneous functions
 
 	int HX_ffs(unsigned long z);
 	int HX_fls(unsigned long z);
+	float HX_flprf(float x, float y);
+	double HX_flpr(double x, double y);
 
 	void HX_zvecfree(char **);
 	unsigned int HX_zveclen(const char *const *);
@@ -20,6 +22,9 @@ Miscellaneous functions
 	Finds the last (most-significant) bit in a value and returns its
 	position, or ``-1`` to indicate failure.
 
+``HX_flpr``, ``HX_flprf``
+	Computes the Least Positive Residue of the modulo operation x % y.
+
 ``HX_zvecfree``
 	Frees the supplied Z-vector array. (Frees all array elements from the
 	first element to (excluding) the first ``NULL`` element.)
diff --git a/doc/process_management.rst b/doc/process_management.rst
index 8fe282b..d999608 100644
--- a/doc/process_management.rst
+++ b/doc/process_management.rst
@@ -202,7 +202,17 @@ User identity control
 
 	#include <libHX/proc.h>
 
-	int HXproc_switch_user(const char *user, const char *group);
+	enum HXproc_su_status {
+		HXPROC_INITGROUPS_FAILED = -5,
+		HXPROC_SETGID_FAILED = -4,
+		HXPROC_SETUID_FAILED = -3,
+		HXPROC_GROUP_NOT_FOUND = -2,
+		HXPROC_USER_NOT_FOUND = -1,
+		HXPROC_SU_NOOP = 0,
+		HXPROC_SU_SUCCESS = 1,
+	};
+
+	enum HXproc_su_status HXproc_switch_user(const char *user, const char *group);
 
 ``HXproc_switch_user`` is a wrapper for changing process identity to an
 unprivileged user. This utilizes ``setuid``, and possibly ``setgid`` plus
@@ -217,6 +227,9 @@ process group(s) will change to the the user's group(s) — both primary and
 secondary — provided a user was specified (see above). When ``gruop`` is the
 empty string, no change of process group identity occurs.
 
+The return value is an enum indicating failure with values <0, and success with
+>=0.
+
 
 Process information
 ===================
diff --git a/doc/socket_functions.rst b/doc/socket_functions.rst
index 5d55cf8..fef6e7c 100644
--- a/doc/socket_functions.rst
+++ b/doc/socket_functions.rst
@@ -31,27 +31,31 @@ Socket functions
 	system defaults. (It may choose whatever protocol is offered by the
 	system.) ``oflags`` is a bitset which may contain ``O_NONBLOCK``, else
 	must be 0. Upon success, a socket file descriptor is returned. Upon
-	failure, a negative errno code is returned.
+	failure, a negative errno code is returned. The socket will have
+	``SOCK_CLOEXEC`` set by default if the platform supports it.
 
 ``HX_inet_listen``
 	The function first resolves ``host`` using ``getaddrinfo()` with
 	``AI_PASSIVE``, then using ``HX_socket_from_env`` looks in the
 	environment for a matching socket to pick up, and otherwise uses the
 	first result from getaddrinfo to create a new socket. Upon error, a
-	negative errno value is returned.
+	negative errno value is returned. The socket will have ``SOCK_CLOEXEC``
+	set by default if the platform supports it.
 
 ``HX_local_listen``
 	The function creates a local system-specific socket. Using
 	``HX_socket_from_env``, it will attempt to pick up a matching socket
 	from the environment, and otherwise create a new socket. Upon error, a
-	negative errno value is returned.
+	negative errno value is returned. The socket will have ``SOCK_CLOEXEC``
+	set by default if the platform supports it.
 
 ``HX_socket_from_env``
 	The function looks up the current process's file descriptors for a
 	socket that is listening and which matches the given addrinfo and
 	(optionally) intf if the latter is not NULL``. Upon success, the fd
 	number is returned, or -1 if no file descriptor matched. No errors are
-	signalled.
+	signalled. Before this function returns a file descriptor, it sets
+	``SOCK_CLOEXEC``.
 
 ``HX_sockaddr_is_local``
 	Attempts to determine if the given socket address refers to a local
diff --git a/doc/string_ops.rst b/doc/string_ops.rst
index 9bb711f..d818d2d 100644
--- a/doc/string_ops.rst
+++ b/doc/string_ops.rst
@@ -456,17 +456,20 @@ Conversion from/to human-readable durations with units
 	#include <libHX/string.h>
 
 	unsigned long long HX_strtoull_sec(const char *s, char **end);
+	unsigned long long HX_strtoull_nsec(const char *s, char **end);
 	char *HX_unit_seconds(char *out, size_t outsize,
 	                      unsigned long long seconds,
 	                      unsigned int flags);
 
-``HX_strtoull_sec`` converts a time duration with units, such as ``"15min30s"``
-into an all-seconds value. The recognized unit strings are: ``years``,
-``year``, ``y``, ``months``, ``month``, ``days``, ``day``, ``d``, ``hours``,
-``hour``, ``h``, ``minutes``, ``minute``, ``min``, ``seconds``, ``second``,
-``s`` and the empty string (for seconds). When parsing stops at any point,
-``*end`` is set to the location, similar to how the ``strtoull`` C function
-would.
+``HX_strtoull_sec`` and ``HX_strtoull_nsec`` convert a time duration with
+units, such as ``"15min30s"`` into an all-seconds and all-nanoseconds value,
+respectively. The recognized unit strings are: ``years``, ``year``, ``y``,
+``months``, ``month``, ``days``, ``day``, ``d``, ``hours``, ``hour``, ``h``,
+``minutes``, ``minute``, ``min``, ``seconds``, ``second``, ``s``, the empty
+string (to mean seconds), ``msec``, ``ms``, ``µsec``, ``µs``, ``nsec`` and
+``ns``. Negative durations are not supported. Support for fractions is
+implementation-defined. When parsing stops at any point, ``*end`` is set to the
+location, similar to how the ``strtoull`` C function would.
 
 One year is defined to be 365.25 days of 86400 seconds; one month is defined to
 be 1/12 such a year. This is consistent with the units employed by systemd.