Getnameinfo

In C programming, the functions ''getaddrinfo()'' and ''getnameinfo()'' convert domain names, hostnames, and IP addresses between human-readable text representations and structured binary formats for the operating system's networking API. Both functions are contained in the POSIX standard application programming interface (API).

getaddrinfo and getnameinfo are inverse functions of each other. They are network protocol agnostic, and support both IPv4 and IPv6. It is the recommended interface for name resolution in building protocol independent applications and for transitioning legacy IPv4 code to the IPv6 Internet.

Internally, the functions perform resolutions using the Domain Name System (DNS) by calling other, lower level functions, such as gethostbyname().

On February 16 2016 a security bug was announced in the glibc implementation of getaddrinfo(), using a buffer overflow technique, that may allow execution of arbitrary code by the attacker.

struct addrinfo

The C data structure used to represent addresses and hostnames within the networking API is the following:

struct addrinfo ;

In some older systems the type of ''ai_addrlen'' is ''size_t'' instead of ''socklen_t''. Most socket functions, such as ''accept()'' and ''getpeername()'', require the parameter to have type ''socklen_t * '' and programmers often pass the address to the ''ai_addrlen'' element of the ''addrinfo'' structure. If the types are incompatible, e.g., on a 64-bit Solaris 9 system where ''size_t'' is 8 bytes and ''socklen_t'' is 4 bytes, then run-time errors may result.

The structure contains structures ''ai_family'' and ''sockaddr'' with its own ''sa_family'' field. These are set to the same value when the structure is created with function ''getaddrinfo'' in some implementations.

getaddrinfo()

getaddrinfo() converts human-readable text strings representing hostnames or IP addresses into a dynamically allocated linked list of struct addrinfo structures.
The function prototype for this function is specified as follows:

int getaddrinfo(const char* hostname,
const char* service,
const struct addrinfo* hints,
struct addrinfo** res);

; hostname
: can be either a domain name, such as "example.com", an address string, such as "127.0.0.1", or NULL, in which case the address 0.0.0.0 or 127.0.0.1 is assigned depending on the hints flags.
; service
: can be a port number passed as string, such as "80", or a service name, e.g. "echo". In the latter case a typical implementation uses ''getservbyname()'' to query the file ''/etc/services'' to resolve the service to a port number.
; hints
: can be either NULL or an ''addrinfo'' structure with the type of service requested.
; res
: is a pointer that points to a new ''addrinfo'' structure with the information requested after successful completion of the function. The function returns 0 upon success and non-zero error value if it fails.

Although implementations vary among platforms, the function first attempts to obtain a port number usually by branching on ''service''. If the string value is a number, it converts it to an integer and calls ''htons()''. If it is a service name, such as ''www'', the service is looked up with ''getservbyname()'', using the protocol derived from ''hints->ai_socktype'' as the second parameter to that function. Then, if ''hostname'' is given (not NULL), a call to ''gethostbyname()'' resolves it, or otherwise the address ''0.0.0.0'' is used, if ''hints->ai_flags'' is set to ''AI_PASSIVE'', and ''127.0.0.1'' otherwise. It allocated a new ''addrinfo'' structure filled with the appropriate ''sockaddr_in'' in one of these conditions and also adds the port retrieved at the beginning to it. Finally, the ''**res'' parameter is dereferenced to make it point to a newly allocated ''addrinfo'' structure.Hajimu UMEMOTO 000getaddrinfo.c Accessed from: https://opensource.apple.com/source/passwordserver_sasl/passwordserver_sasl-14/cyrus_sasl/lib/getaddrinfo.c In some implementations, such as the Unix version for Mac OS, the ''hints->ai_protocol '' overrides the ''hints->ai_socktype'' value while in others it is the opposite, so both need to be defined with equivalent values for the code to be work across multiple platforms.

freeaddrinfo()

This function frees the memory allocated by function ''getaddrinfo()''. As the result of the latter is a linked list of addrinfo structures starting at the address ''ai'', ''freeaddrinfo()'' loops through the list and frees each one in turn.

void freeaddrinfo(struct addrinfo *ai);

getnameinfo()

The function ''getnameinfo()'' converts the internal binary representation of an IP address in the form of a pointer to a ''struct sockaddr'' into text strings consisting of the hostname or, if the address cannot be resolved into a name, a textual IP address representation, as well as the service port name or number. The function prototype is specified as follows:

int getnameinfo(const struct sockaddr* sa, socklen_t salen,
char* host, size_t hostlen,
char* serv, size_t servlen,
int flags);

Example

The following example uses ''getaddrinfo()'' to resolve the domain name ''www.example.com'' into its list of addresses and then calls ''getnameinfo()'' on each result to return the canonical name for the address. In general, this produces the original hostname, unless the particular address has multiple names, in which case the ''canonical'' name is returned. In this example, the domain name is printed three times, once for each of the three results obtained.

#include
#include
#include
#include
#include

#ifndef NI_MAXHOST
#define NI_MAXHOST 1025
#endif

int main(void)

See also

*Network address

References

{{reflist

External links

freeaddrinfo and getaddrinfo specifications in POSIX.1-2017
''The Open Group Base Specifications Issue 7, 2018 edition''

RFC 3493, Basic Socket Interface Extensions for IPv6

Internet Protocol
Network addressing
Domain Name System
C POSIX library
Articles with example C code