summaryrefslogtreecommitdiff
path: root/doc/socket_functions.rst
diff options
context:
space:
mode:
authorJörg Frings-Fürst <debian@jff-webhosting.net>2023-03-11 18:24:13 +0100
committerJörg Frings-Fürst <debian@jff-webhosting.net>2023-03-11 18:24:13 +0100
commit980784c1917f19bfd2e9b11faca76d14e8589daa (patch)
treec9b3988642585cd50af5ec1ffad75331886c0aa4 /doc/socket_functions.rst
parentbfef0924f58eab930bdd826ac0132786abc32220 (diff)
New upstream version 4.12upstream/4.12
Diffstat (limited to 'doc/socket_functions.rst')
-rw-r--r--doc/socket_functions.rst48
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);