GETADDRINFO(3)

NAME
getaddrinfo, freeaddrinfo, gai_strerror, getnameinfo - address information

SYNOPSIS
#include <netdb.h>
void freeaddrinfo(struct addrinfo *ai);
int getaddrinfo(const char *nodename,
       const char *servname,
       const struct addrinfo *hints,
       struct addrinfo **res);
int getnameinfo(const struct sockaddr *sa, socklen_t salen,
       char *node, socklen_t nodelen, char *service,
       socklen_t servicelen, int flags);
const char *gai_strerror(int ecode);

DESCRIPTION
These functions provide to convert between host and service names on the one hand and network addresses and ports on the other.

getaddrinfo converts the hostname specified in nodename and/or the service name in servname into a socket address that can be used to connect to that service or listen for incoming connections. One of the parameters may be NULL. If nodename is NULL, an address for the local host is provided. If servname is NULL, the network port is not filled in (and therefore set to zero). Buffers are allocated to store the results and a pointer to the first element of a linked list of addresses is stored in ai. These buffers must be freed by calling freeaddrinfo on the pointer returned in ai.

getnameinfo converts the specified socket address into a hostname and/or service name. These are stored in the buffers pointed to by node and service resepectively. nodelen and servicelen specify the sizes of these buffers. If the result string including null terminator does not fit in the buffer, the function fails and EAI_OVERFLOW is returned.

For both functions, some flags may be specified to alter their behaviour. For getaddrinfo these flags are specified in the ai_flags field of the optional hints parameter. AI_PASSIVE indicates that an address suitable for the bind function should be returned, otherwise an address suitable for connect is provided. AI_CANONNAME requests that the canonical name of the host be retrieved and stored in the ai_canonname field of the result. AI_NUMERICHOST and AI_NUMERICSERV indicate respectively that nodename is an IP address and servname is a port number, avoiding a lookup. Search can be limited to a specific socket type by setting hints->ai_socktype to SOCK_STREAM or SOCK_DGRAM. hints->ai_family can be set to AF_UNSPEC or AF_INET but this doesn't make a difference as MINIX supports only IPv4. Unused fields of hints must be set to zero.

Flags for getnameinfo are specified in the flags parameter. NI_NUMERICHOST and NI_NUMERICSERV respectively cause node to be set to an IP address and service to be set to a port number. NI_NAMEREQD causes the function to fail with EAI_NONAME if a name is not found for the host (otherwise the IP address is returned). NI_DGRAM indicates that a datagram service is specified, the default being a stream service.

RETURN VALUE
If the functions succeed, they return 0. If they fail, one of the EAI_* values defined in netdb.h is returned. This value can be converted into a string using gai_strerror. The most important ones are EAI_NONAME (host name not found), EAI_SERVICE (service name not found) and EAI_OVERFLOW (buffer too small, only for getnameinfo).

KNOWN ISSUES
Since MINIX does not support IPv6, the related flags are not supported. The NI_NOFQDN flag is also not (yet) supported.