libgslutil  1.2.3
Macros | Functions | Variables
Name and address resolution

Macros

#define IPADDR_COMPARE_PROTO   (0x00000001)
 Address structure comparison: consider socket type and protocol. More...
 
#define IPADDR_COMPARE_PORTS   (0x00000002)
 Address structure comparison: consider protocol ports. More...
 

Functions

struct addrinfo * ipaddr_resolve (const char *host, const char *service, int ip_version, enum ip_subproto_t subproto))
 Resolve an IP address and port number for a given host/service. More...
 
struct addrinfo * ipaddr_resolve2 (const char *address, int ip_version, enum ip_subproto_t subproto))
 Resolve an IP address and port number for a given host and service. More...
 
struct addrinfo * ipaddr_copy (const struct addrinfo *addr))
 Deep copy of an address info structure. More...
 
struct addrinfo * ipaddr_alloc_empty (void))
 Allocate an empty IP address structure. More...
 
void sockaddr_to_addrinfo (const struct sockaddr *__restrict__ from, socklen_t from_len, struct addrinfo *__restrict__ addr))
 Convert a sockaddr structure to an addrinfo structure, with readable name. More...
 
void addrinfo_set_canonname (struct addrinfo *ai))
 Sets canonname to consistent value. More...
 
int ipaddr_compare (const struct addrinfo *a1, const struct addrinfo *a2, int flags))
 Compare two address structures. More...
 

Variables

const char * ipaddr_resolve_errstr
 String describing last error from ip_resolve().
 

Detailed Description

ipaddr_resolve() and ipaddr_copy() provide a convenient (but blocking) name resolution service; see getaddrinfo(3).

Macro Definition Documentation

◆ IPADDR_COMPARE_PROTO

#define IPADDR_COMPARE_PROTO   (0x00000001)

Address structure comparison: consider socket type and protocol.

When comparing two address structures (struct addrinfo, see getaddrinfo(3)), also consider the ai_socktype and ai_protocol fields. Depending on what filled out the address info structure, these fields may be unset, and so are not considered by default.

◆ IPADDR_COMPARE_PORTS

#define IPADDR_COMPARE_PORTS   (0x00000002)

Address structure comparison: consider protocol ports.

When comparing two IP addresses, also consider the protocol port field (sin_port or sin6_port). This has no effect if the address info structures do not contain IP addresses.

Function Documentation

◆ ipaddr_resolve()

struct addrinfo* ipaddr_resolve ( const char *  host,
const char *  service,
int  ip_version,
enum ip_subproto_t  subproto 
)

Resolve an IP address and port number for a given host/service.

Parameters
hostHostname or IP address to resolve (may be 0 for 'any').
serviceService name (e.g. 'smtp') or port number to resolve. May be 0.
ip_versionIP version number (0 for unspecified, otherwise 4 or 6).
subprotoIP sub-protocol.
Returns
Address info structure (as per getaddrinfo(3)).
Return values
0on error (and see ipaddr_resolve_errstr).

This function will resolve a hostname/IP address string and a service string. It is a thin wrapper around getaddrinfo(3). Either host or service may be 0 (but not both). The returned structure is a linked list that must be freed with freeaddrinfo(3).

Leaving host as 0 will return the 'any' address. Servers binding to this address will accept connections from any network interface, including loopback.

You can force the address family of the result to AF_INET by setting ip_version to 4, or to AF_INET6 by setting ip_version to 6. Leaving ip_version as 0 will not force the address family of the result.

On failure, a string describing the error may be found in ‘ipaddr_resolve_errstr’. This string will only persist until the next call to ipaddr_resolve() (see gai_strerror()).

◆ ipaddr_resolve2()

struct addrinfo* ipaddr_resolve2 ( const char *  address,
int  ip_version,
enum ip_subproto_t  subproto 
)

Resolve an IP address and port number for a given host and service.

Parameters
addressComma-separated host and service addresses.
ip_versionIP version number (0 for unspecified, otherwise 4 or 6).
subprotoIP sub-protocol.
Returns
Address info structure (as per getaddrinfo(3)).
Return values
0on error (and see ipaddr_resolve_errstr).

This function is a convenience wrapper for ipaddr_resolve() . Rather than specifying the host and service names separately, they may be specified together, separated by a comma.

◆ ipaddr_copy()

struct addrinfo* ipaddr_copy ( const struct addrinfo *  addr)

Deep copy of an address info structure.

Parameters
addrAddress structure to copy.
Returns
A newly-allocated address structure.

This function will perform a deep copy of an address info structure, allowing the original to be freed. The entire linked list will be copied. Uses safe_malloc().

◆ ipaddr_alloc_empty()

struct addrinfo* ipaddr_alloc_empty ( void  )

Allocate an empty IP address structure.

Returns
Pointer to new structure.

Allocates and returns a struct addrinfo suitable for ip_accept() or membuf_recvfrom(). The structure will initially be empty, though with enough space allocated to hold the client address. The structure can be freed with freeaddrinfo().

◆ sockaddr_to_addrinfo()

void sockaddr_to_addrinfo ( const struct sockaddr *__restrict__  from,
socklen_t  from_len,
struct addrinfo *__restrict__  addr 
)

Convert a sockaddr structure to an addrinfo structure, with readable name.

Parameters
fromThe sockaddr structure.
from_lenLength of from, in bytes.
[out]addrThe address info structure to write to, allocated with ipaddr_alloc_empty().

This function converts the address in from (a structure of from_len bytes) into an addrinfo structure, addr. addr must already have been allocated with e.g. ipaddr_alloc_empty(). This function will set addr->ai_family, addr->ai_addrlen and addr->ai_addr. It may also set addr->ai_canonname.

If the address family is IPv4 or IPv6, addr->ai_canonname will be set to the string representation of the IP address, followed by a space, the (decimal) port number, and null terminated. If the address is a Unix socket, addr->ai_canonname will be the source path. In any other case, the string will be empty.

See also
addrinfo_set_canonname()

◆ addrinfo_set_canonname()

void addrinfo_set_canonname ( struct addrinfo *  ai)

Sets canonname to consistent value.

Parameters
aiThe address info structure to operate on.

Sets the member variable ai->ai_canonname to be the string representation of the address used in sockaddr_to_addrinfo(). Useful if you want to have a consistent string with which to label client connections.

Requires that ai->ai_canonname have sufficient length if it is a valid pointer (i.e. from ipaddr_alloc_empty()), or that it be null (in which case the required memory is allocated).

See also
sockaddr_to_addrinfo()

◆ ipaddr_compare()

int ipaddr_compare ( const struct addrinfo *  a1,
const struct addrinfo *  a2,
int  flags 
)

Compare two address structures.

Parameters
a1First address structure.
a2Second address structure.
flagsFlags for comparison.
Return values
0if identical
non-0if different

This function performs a comparison of two address structures a1 and a2. The comparison may be controlled by the flags argument. This function takes special care to deal with IPv4 mapped IPv6 addresses (i.e. it will consider

::ffff:192.168.0.1 

and 192.168.0.1 to be equivalent).

This function can be used to compare Unix or other sorts of addresses, for which it does just a simple memory comparison, but its primary purpose is to compare IP addresses, for which its behaviour may be somewhat customised.

flags is a bitfield which may contain the following:

  • IPADDR_COMPARE_PROTO consider the ai_socktype and ai_protocol fields of the two address structures