diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/api.rst | 3 | ||||
| -rw-r--r-- | doc/changelog.rst | 67 | ||||
| -rw-r--r-- | doc/files_and_dirs.rst | 43 | ||||
| -rw-r--r-- | doc/misc_functions.rst | 5 | ||||
| -rw-r--r-- | doc/process_management.rst | 15 | ||||
| -rw-r--r-- | doc/socket_functions.rst | 12 | ||||
| -rw-r--r-- | doc/string_ops.rst | 17 |
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. |