1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
|
================
Socket functions
================
.. code-block:: c
#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. The socket will have
``SOCK_CLOEXEC`` set by default if the platform supports it.
``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. The socket will have ``SOCK_CLOEXEC``
set by default if the platform supports it.
``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. The socket will have ``SOCK_CLOEXEC``
set by default if the platform supports it.
``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
(optionally) intf if the latter is not NULL``. Upon success, the fd
number is returned, or -1 if no file descriptor matched. No errors are
signalled. Before this function returns a file descriptor, it sets
``SOCK_CLOEXEC``.
``HX_sockaddr_is_local``
Attempts to determine if the given socket address refers to a local
address. This function may be helpful in determining whether a process
should spend any time (or not) on compressing data before sending to a
peer. The definition of "local" is generally dependent upon the network
APIs. The ``flags`` parameter can contain ``AI_V4MAPPED`` if
IPv4-mapped IPv6 addresses should be recognized. The function returns
>0 if the address is considered local, 0 if not, and any other
negative value for a system error that makes the result
indeterminate.
``HX_ipaddr_is_local``
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);
|
