diff options
Diffstat (limited to 'doc/socket_functions.rst')
| -rw-r--r-- | doc/socket_functions.rst | 48 |
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); |