summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/api.rst4
-rw-r--r--doc/changelog.rst75
-rw-r--r--doc/socket_functions.rst48
3 files changed, 69 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..30f2d28 100644
--- a/doc/changelog.rst
+++ b/doc/changelog.rst
@@ -1,3 +1,20 @@
+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 +133,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);