The getipnodebyname() function searches the ipnodes database from the beginning and finds the first entry for which the hostname specified by name matches the h_name member. It takes an af argument that specifies the address family, which can be either AF_INET for IPv4 addresses or AF_INET6 for IPv6 addresses. The flags argument determines what results will be returned based on the value of flags. If the flags argument is set to 0 (zero), then the default operation of this function is specified as follows:

• If the af argument is AF_INET, then a query is made for an IPv4 address. If successful, IPv4 addresses are returned and the h_length member of the hostent structure will be 4. Otherwise, the function returns a null pointer.
• If the af argument is AF_INET6, then a query is made for an IPv6 address. If successful, IPv6 addresses are returned and the h_length member of the hostent structure will be 16. Otherwise, the function returns a null pointer.

The flags argument changes the default actions of the function. You can set the flags argument by logically ORing any of the following values together:

• AI_V4MAPPED
• AI_ALL
• AI_ADDRCONFIG

Note that a special flags value of AI_DEFAULT, as defined below, should handle most applications. In other words, porting simple applications to use IPv6 replaces the call

hptr = gethostbyname(name);

with

hptr = getipnodebyname(name, AF_INET6, AI_DEFAULT, &error_num);

A flags of 0 implies a strict interpretation of the af argument:

• If flags is 0 and af is AF_INET, then the caller wants only IPv4 addresses. A query is made for A records. If successful, the IPv4 addresses are returned and the h_length member of the hostent structure will be 4; otherwise, the function returns a null pointer.
• If flags is 0, and if af is AF_INET6, then the caller wants only IPv6 addresses. A query is made for AAAA records. If successful, the IPv6 addresses are returned and the h_length member of the hostent structure will be 16; otherwise, the function returns a null pointer.

Other constants can be logically-ORed into the flags argument, to modify the behavior of the function.

• If the AI_V4MAPPED flag is specified along with an af of AF_INET6, then the caller can accept IPv4-mapped IPv6 addresses. That is, if no AAAA records are found, then a query is made for A records, and any found are returned as IPv4-mapped IPv6 addresses (h_length is 16). The AI_V4MAPPED flag is ignored unless af equals AF_INET6.
• The AI_ALL flag is used in conjunction with the AI_V4MAPPED flag, and is only used with the IPv6 address family. When AI_ALL is logically ORed with AI_V4MAPPED flag then the caller wants all addresses: IPv6 and IPv4-mapped IPv6. A query is first made for AAAA records and if successful, the IPv6 addresses are returned. Another query is then made for A records, and any found are returned as IPv4-mapped IPv6 addresses. h_length is 16. Only if both queries fail does the function return a null pointer. This flag is ignored unless af equals AF_INET6.
• The AI_ADDRCONFIG flag specifies that a query for AAAA records should occur only if the node has at least one IPv6 source address configured. A query for A records should occur only if the node has at least one IPv4 source address configured. For example, if the node has no IPv6 source addresses configured, and af equals AF_INET6, and the node name being looked up has both AAAA and A records, then:
  1. If only AI_ADDRCONFIG is specified, the function returns a null pointer.
  2. If AI_ADDRCONFIG or AI_V4MAPPED is specified, the A records are returned as IPv4-mapped IPv6 addresses.

The special flags value of AI_DEFAULT is defined as

#define  AI_DEFAULT  (AI_V4MAPPED | AI_ADDRCONFIG)

The getipnodebyname() function must allow the name argument to be either a node name or a literal address string, that is, a dotted-decimal IPv4 address or an IPv6 hex address. This saves applications from having to call inet_pton(3SOCKET) to handle literal address strings.

Four scenarios arise based on the type of literal address string and the value of the af argument. The two simple cases are when name is a dotted-decimal IPv4 address and af equals AF_INET, or when name is an IPv6 hex address and af equals AF_INET6. The members of the returned hostent structure are:

h_name

Points to a copy of the name argument

h_aliases

Is a null pointer.

h_addrtype

Is a copy of the af argument.

h_length

Is either 4 (for AF_INET) or 16 (for AF_INET6).

h_addr_list[0]

Is a pointer to the 4-byte or 16-byte binary address.

h_addr_list[1]

Is a null pointer

af

Address family

flags

Various flags

name

Name of host

error_num

Error storage

src

Address for lookup

len

Length of address

ptr

Pointer to hostent structure

Upon successful completion, getipnodebyname() and getipnodebyaddr() return a hostent structure. Otherwise they return NULL.

The hostent structure does not change from its existing definition when used with gethostbyname(3NSL). For example, host entries are represented by the struct hostent structure defined in <netdb.h>:

struct hostent {
               char   *h_name;         /* canonical name of host */
               char   **h_aliases;     /* alias list */
               int    h_addrtype;      /* host address type */
               int    h_length;        /* length of address */
               char   **h_addr_list;   /* list of addresses */
          };

An error occurs when name is an IPv6 hex address and af equals AF_INET. The function's return value is a null pointer and error_num equals HOST_NOT_FOUND.

The getipnodebyaddr() function has the same arguments as the existing gethostbyaddr(3NSL) function, but adds an error number. As with getipnodebyname(), getipnodebyaddr() is thread safe. The error_num value is returned to the caller with the appropriate error code to support thread safe error code returns. The following error conditions can be returned for error_num:

HOST_NOT_FOUND

Host is unknown.

NO_DATA

No address is available for the name specified in the server request. This error is not a soft error. Another type of name server request might be successful.

NO_RECOVERY

An unexpected server failure occurred, which is a nonrecoverable error.

TRY_AGAIN

This error is a soft error that indicates that the local server did not receive a response from an authoritative server. A retry at some later time might be successful.

One possible source of confusion is the handling of IPv4-mapped IPv6 addresses and IPv4-compatible IPv6 addresses, but the following logic should apply:

1. If af is AF_INET6, and if len equals 16, and if the IPv6 address is an IPv4-mapped IPv6 address or an IPv4-compatible IPv6 address, then skip over the first 12 bytes of the IPv6 address, set af to AF_INET, and set len to 4.
2. If af is AF_INET, lookup the name for the given IPv4 address.
3. If af is AF_INET6, lookup the name for the given IPv6 address.
4. If the function is returning success, then the single address that is returned in the hostent structure is a copy of the first argument to the function with the same address family that was passed as an argument to this function.

All four steps listed are performed in order.

This structure, and the information pointed to by this structure, are dynamically allocated by getipnodebyname() and getipnodebyaddr(). The freehostent() function frees this memory.

/etc/inet/hosts

/etc/inet/ipnodes

/etc/netconfig

/etc/nsswitch.conf

See attributes(5) for descriptions of the following attributes:

getaddrinfo(3SOCKET), gethostbyname(3NSL), htonl(3SOCKET), inet(3SOCKET), netdb(3HEAD), hosts(4), ipnodes(4), nsswitch.conf(4), attributes(5)

Programs that use the interfaces described in this manual page cannot be linked statically since the implementations of these functions employ dynamic loading and linking of shared objects at run time.

No enumeration functions are provided for IPv6. Existing enumeration functions, for example, sethostent(3NSL) does not work in combination with getipnodebyname() and getipnodebyaddr().

All the functions that return a struct hostent must always return the canonical in the h_name field. This name, by definition, is the well-known and official hostname shared between all aliases and all addresses. The underlying source that satisfies the request determines the mapping of the input name or address into the set of names and addresses in hostent. Different sources might do that in different ways. If more than one alias and more than one address in hostent exist, no pairing is implied between them.

The current implementations of these functions only return or accept addresses for the Internet address family (type AF_INET) or the Internet address family Version 6 (type AF_INET6).

The form for an address of type AF_INET is a struct in_addr defined in <netinet/in.h>. The form for an address of type AF_INET6 is a struct in6_addr, defined also in <netinet/in.h>. The functions described in inet_ntop(3SOCKET) and inet_pton(3SOCKET) that are illustrated in the EXAMPLES section are helpful in constructing and manipulating addresses in either of these forms.