Standard C Library (libc.a)
#include <libc.a> #include <netdb.h> struct hostent *getipnodebyname(name, af, flags, error_num) const char *name; int af; int flags; int *error_num;
The commonly used functions gethostbyname and gethostbyname2 are inadequate for many applications. You could not specify the type of addresses desired in gethostbyname. In gethostbyname2, a global option (RES_USE_INET6) is required when IPV6 addresses are used. Also, gethostbyname2 needed more control over the type of addresses required.
The getipnodebyname subroutine gives the caller more control over the types of addresses required and is thread safe. It also does not need a global option like RES_USE_INET6.
The name argument can be either a node name or a numeric (either a dotted-decimal IPv4 or colon-seperated IPv6) address.
The flags parameter values include AI_DEFAULT, AI_V4MAPPED, AI_ALL and AI_ADDRCONFIG. The special flags value AI_DEFAULT is designed to handle most applications. Its definition is:
#define AI_DEFAULT (AI_V4MAPPED | AI_ADDRCONFIG)
When porting simple applications to use IPv6, simply replace the call:
hp = gethostbyname(name);
hp = getipnodebyname(name, AF_INET6, AI_DEFAULT, &error_num);
To modify the behavior of the getipnodebyname subroutine, constant values can be logically-ORed into the flags parameter.
A flags value of 0 implies a strict interpretation of the af parameter. If af is AF_INET then only IPv4 addresses are searched for and returned. If af is AF_INET6 then only IPv6 addresses are searched for and returned.
If the AI_V4MAPPED flag is specified along with an af of AF_INET6, then the caller accepts IPv4-mapped IPv6 addresses. That is, if a query for IPv6 addresses fails, then a query for IPv4 addresses is made and if any are found, then they are returned as IPv4-mapped IPv6 addresses. The AI_V4MAPPED flag is only valid with an af of AF_INET6.
If the AI_ALL flag is used in conjunction the AI_V4MAPPED flag and af is AF_INET6, then the caller wants all addresses. The addresses returned are IPv6 addresses and/or IPv4-mapped IPv6 addresses. Only if both queries (IPv6 and IPv4) fail does getipnodebyname return NULL. Again, the AI_ALL flag is only valid with an af of AF_INET6.
The AI_ADDRCONFIG flag is used to specify that a query for IPv6 addresses should only occur if the node has at least one IPv6 source address configured and a query for IPv4 addresses should only occur if the node has at least one IPv4 source address configured. For example, if the node only has IPv4 addresses configured, af equals AF_INET6, and the node name being looked up has both IPv4 and IPv6 addresses, then if only the AI_ADDRCONFIG flag is specified, getipnodebyname will return NULL. If the AI_V4MAPPED flag is specified with the AI_ADDRCONFIG flag (AI_DEFAULT), then any IPv4 addresses found will be returned as IPv4-mapped IPv6 addresses.
There are 4 different situations when the name argument is a literal address string:
|name||Specifies either a node name or a numeric (either a dotted-decimal IPv4 or colon-separated IPv6) address.|
|af||Specifies the address family which is either AF_INET or AF_INET6.|
|flags||Controls the types of addresses searched for and the types of addresses returned.|
|error_num||Returns argument to the caller with the appropriate error code.|
The getipnodebyname subroutine returns a pointer to a hostent structure on success.
The getipnodebyname subroutine returns a null pointer if an error occurs. The error_num parameter is set to indicate the error.
|HOST_NOT_FOUND||The host specified by the name parameter was not found.|
|TRY_AGAIN||The local server did not receive a response from an authoritative server. Try again later.|
|NO_RECOVERY||The host specified by the nameparameter was not found. This error code indicates an unrecoverable error.|
|NO_ADDRESS||The requested name is valid but does not have an Internet address at the name server.|
The freehostent subroutine and getipnodebyaddr subroutine.