getipnodebyname Subroutine

Purpose

Nodename-to-address translation.

Library

Standard C Library (libc.a)

(libaixinet)

Syntax

#include <libc.a>
#include <netdb.h>
struct hostent *getipnodebyname(name, af, flags, error_num)
const char *name;
int af;
int flags;
int *error_num;

Description

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);
with 
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:
  1. name is a dotted-decimal IPv4 address and af is AF_INET. If the query is successful, then h_name points to a copy of name, h_addrtype is the af argument, h_length is 4, h_aliases is a NULL pointer, h_addr_list[0] points to the 4-byte binary address and h_addr_list[1] is a NULL pointer.
  2. name is a colon-separated IPv6 address and af is AF_INET6. If the query is successful, then h_name points to a copy of name, h_addrtype is the af parameter, h_length is 16, h_aliases is a NULL pointer, h_addr_list[0] points to the 16-byte binary address and h_addr_list[1] is a NULL pointer.
  3. name is a dotted-decimal IPv4 address and af is AF_INET6. If the AI_V4MAPPED flag is specified and the query is successful, then h_name points to an IPv4-mapped IPv6 address string, h_addrtype is the af argument, h_length is 16, h_aliases is a NULL pointer, h_addr_list[0] points to the 16-byte binary address and h_addr_list[1] is a NULL pointer.
  4. name is a colon-separated IPv6 address and af is AF_INET. This is an error, getipnodebyname returns a NULL pointer and error_num equals HOST_NOT_FOUND.

Parameters

Item Description
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.

Return Values

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.

Error Codes

Item Description
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.