summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorJörg Frings-Fürst <debian@jff-webhosting.net>2023-12-17 14:16:17 +0100
committerJörg Frings-Fürst <debian@jff-webhosting.net>2023-12-17 14:16:17 +0100
commit2543e1e9838e03adb7f4a811815d34ccf65a3026 (patch)
tree92fd5e78541bb9c244741de5940e8332e5e983dc /doc
parent6eddfddeb9da77b6523d8e1ebc2e75c8b5dc5ac9 (diff)
parent08dcb1504d4900cb6230c99fbbf535c63eb3b332 (diff)
Merge branch 'release/debian/4.17-1'
Diffstat (limited to 'doc')
-rw-r--r--doc/api.rst3
-rw-r--r--doc/changelog.rst67
-rw-r--r--doc/files_and_dirs.rst43
-rw-r--r--doc/misc_functions.rst5
-rw-r--r--doc/process_management.rst15
-rw-r--r--doc/socket_functions.rst12
-rw-r--r--doc/string_ops.rst17
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.