diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/api.rst | 4 | ||||
| -rw-r--r-- | doc/changelog.rst | 92 | ||||
| -rw-r--r-- | doc/socket_functions.rst | 48 |
3 files changed, 86 insertions, 58 deletions
diff --git a/doc/api.rst b/doc/api.rst index 5f009cc..5a3efe5 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -9,6 +9,10 @@ Function reference ====== ====== ====== ======================================== RMV MinVer FirstA Name ====== ====== ====== ======================================== +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 +4.11 4.11 4.11 HX_local_listen 4.9 4.9 4.9 HX_sockaddr_is_local 4.9 4.9 4.9 HX_ipaddr_is_local 4.7 4.7 4.7 HXQUOTE_BASE64IMAP diff --git a/doc/changelog.rst b/doc/changelog.rst index 9a1590c..26c4d06 100644 --- a/doc/changelog.rst +++ b/doc/changelog.rst @@ -1,3 +1,37 @@ +v4.14 (2023-07-14) +================== + +Fixes: + +* socket: make HX_addrport_split work on portless bracketed hostspec + + +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 + + +v4.12 (2023-02-27) +================== + +Fixes: + +* Plug a memory leak in HX_inet_listen + + +v4.11 (2023-02-26) +================== + +Enhancements: + +* socket: add HX_addrport_split, HX_inet_connect, HX_inet_listen, + HX_local_listen + + v4.10 (2023-01-29) ================== @@ -116,61 +150,3 @@ Enhancements: Fixes: * proc: re-close pipes when ``HXproc_build_pipes`` failed - - -v3.26 (2021-08-03) -================== - -Fixes: - -* io: cure a potential infinite loop on EOF with HXio_fullread() -* io: HXio_fullread() now returns actual bytes read rather than bytes requested -* time: rectified HX_timeval_sub producing wrong results - -Changes: - -* nullptr checks were added to HXshconfig_free, HXformat_free, HXdeque_free and - HXmap_free to make their behavior be in line with free(3). -* Documentation has been switched to reStructured Text. - - -v3.25 (2020-05-14) -================== - -Fixes: - -* string: fix out-of-bounds access when calling ``HX_strlcpy(x,y,0)`` - -Changes: - -* string: ``HX_split4`` renamed to ``HX_split_inplace`` -* string: ``HX_split5`` renamed to ``HX_split_fixed`` -* defs.h: removed partially implementation of ``FIELD_SIZEOF`` -* defs.h: removed custom ``offsetof`` definition; you will need to include - ``<stddef.h>`` or ``<cstddef>`` now. - - -v3.24 (2018-10-17) -================== - -Fixes: - -* defs: avoid compiler warning when using ``HX_list_for_each`` in C++ -* opt: synchronize ``HXOPT_AUTOHELP`` C behavior to C++ mode - - -v3.23 (2018-08-28) -================== - -Enhancements: - -* opt: the option parser now recognizes long option abbreviations -* io: use modern ``readdir`` rather than ``readdir_r`` - - -v3.22 (2014-08-25) -================== - -Enhancements: - -* string: add the ``HXQUOTE_SQLBQUOTE`` quoting variant diff --git a/doc/socket_functions.rst b/doc/socket_functions.rst index ead0f08..5d55cf8 100644 --- a/doc/socket_functions.rst +++ b/doc/socket_functions.rst @@ -6,10 +6,46 @@ Socket functions #include <libHX/socket.h> + int HX_addrport_split(const char *spec, char *host, size_t hsize, uint16_t *port); + int HX_inet_connect(const char *host, uint16_t port, unsigned int oflags); + int HX_inet_listen(const char *host, uint16_t port); + int HX_local_listen(const char *path); int HX_socket_from_env(const struct addrinfo *ai, const char *intf); int HX_sockaddr_is_local(const struct sockaddr *, socklen_t, unsigned int flags); int HX_ipaddr_is_local(const char *, unsigned int flags); +``HX_addrport_split`` + Splits a host specification like ``[fe80::1]:80`` or ``127.0.0.1:80`` + into a host and port part. The ``host`` parameter should point to a + buffer of size ``hsize``. ``port`` may be NULL. If ``spec`` did not + contain a port part, ``*port`` will *not* be updated, so it is wise to + set a default port first like in the example below. Upon success, the + value 2 is returned if both a host and a port were parsed (irrespective + of ``port`` being NULL or not). The value 1 is returned if only a host + portion was parsed. Upon error, a negative errno value is returned. + +``HX_inet_connect`` + The function first resolves the specified host or IPv6/IPv4 address + (must not be enclosed in square brackets), and then attempts to connect + to one of the addresses. The order of evaluation is dependent upon the + 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. + +``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. + +``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. + ``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 @@ -32,3 +68,15 @@ Socket functions Takes a text representation of an IPv6/IPv4 address and, after transformation, calls ``HX_sockaddr_is_local``. ``flags`` and return value behave the same as that. + +Examples +-------- + +.. code-block:: c + + char host[256]; + uint16_t port = 443; + /* port won't be updated */ + HX_addrport_split("example.de", host, sizeof(host), &port); + /* port will be updated */ + HX_addrport_split("example.de:80", host, sizeof(host), &port); |