# Compaq TCP/IP Services for OpenVMS
Guide to IPv6

Previous | Contents

# C.2 getipnodebyaddr Function

The `getipnodebyaddr` function has the following syntax:

    #include <netdb.h>

    struct hostent *getipnodebyaddr(
              const void *src,
              size_t len,
              int af,
              int *error_num);

Parameters

- src
  Specifies an Internet address in network order.
- len
  Specifies the number of bytes in an Internet address.
- af
  Specifies the Internet domain address format. Valid values are AF_INET and AF_INET6.
- error_num
  Specifies an error return code value if the function is not successful.

Description

The `getipnodebyaddr()` routine is an evolution of the `gethostbyaddr()` routine that enables address lookups in address families other than AF_INET.

The `getipnodebyaddr()` routine returns a pointer to a structure of type `hostent` . Its members specify data obtained from the local TCPIP$ETC:IPNODES.DAT file, the TCPIP$HOSTS.DAT file, or one of the files distributed by DNS/BIND.

The `getipnodebyaddr()` routine searches the network host database sequentially until a match with the src and af parameters occurs. The len parameter must specify the number of bytes in an Internet address. The src parameter must specify the address in network order. The af parameter can be either the constant AF_INET or AF_INET6, which specifies the IPv4 address format or the IPv6 address format, respectively. When EOF (end-of-file) is reached without a match, an error value is returned.

If the src parameter is either an IPv4-mapped IPv6 address or an IPv4-compatible IPv6 address, the routine performs the following steps:

1. If the af parameter is AF_INET6, the len parameter is 16, and the src parameter is either an IPV4-mapped IPv6 address or an IPv4-compatible IPv6 address, the routine skips the first 12 bytes of the address, sets af to AF_INET and len to 4.
2. If the af parameter is AF_INET, the routine queries for a PTR record in the `in-addr.arpa` domain.
3. If the af parameter is AF_INET6, the routine queries for a PTR record in the `ip6.int` domain.
4. If the routine returns success, the single address and address family returned in the `hostent` structure are copies of the src parameter and the af parameter, respectively, that were passed to the routine.

   Note The double colon (::) and ::1 IPv6 addresses are not considered IPv4-compatible addresses.

If you are using DNS/BIND, the address is obtained from a name server as configured. When the name server is not running, the `getipnodebyaddr()` routine searches the local TCPIP$ETC:IPNODES.DAT name file for IPv6 and IPv4 addresses and the hosts name file for IPv4 addresses, if the addresses are not found in the TCPIP$ETC:IPNODES.DAT file.

The `getipnodebyaddr()` routine dynamically allocates the `hostent` structure. Use the `freehostent()` routine to free the allocated memory. (See Section C.3.

Errors

If the `getipnodebyaddr()` routine call fails, error_num is set to one of the following the values:

- HOST_NOT_FOUND
  The name you have used is not an official node name or alias; another type of name server request may be successful.
- NO_ADDRESS
  The server recognized the request and the name, but no address is available for the name. Another type of name server request may be successful.
- NO_RECOVERY
  An unexpected server failure occurred. This is a nonrecoverable error.
- TRY_AGAIN
  A transient error occurred, for example, the server did not respond. A retry at some later time may be successful.

# C.3 freehostent Function

The `freehostrent` function returns `hostent` structures and dynamic storage to the system. You should use this function to free `hostent` structures and storage that were returned by `getipnodebyname` and `getipnodebyaddr` .

This function has the following syntax:

    void freehostent(
            struct hostent *ptr );

The ptr parameter is a pointer to the `hostent` structure to be freed.

Note Do not use the `freehostent` function with `hostent` structures returned by `gethostbyname` and `gethostbyaddr` .

Previous | Contents | Contents