New upstream version 4.12upstream/4.12

1 files changed, 48 insertions, 0 deletions

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);