HP OpenVMS Systems Documentation

1. Declares variable for getnameinfo() return value
2. Declares sockaddr_in6 structures
3. Declares buffers to receive client's name, port number, and address for calls to getnameinfo() .
4. Clears the server sockaddr_in6 structure and sets values for fields of the structure.
5. Creates an AF_INET6 socket.
6. Calls getnameinfo() to retrieve client name. This is for message displaying purposes only and is not necessary for proper functioning of the server.
7. Calls gai_strerror() to convert one of the EAI_xxx return values to a string describing the error.
8. Calls getnameinfo() to retrieve client address and port number. This is for message displaying purposes only and is not necessary for proper functioning of the server.

This section contains sample output from the preceding server and client programs. The server program makes and receives all requests on an AF_INET6 socket using sockaddr_in6 . For requests received over IPv4, sockaddr_in6 contains an IPv4-mapped IPv6 address.

The following example shows a client program running on node hostb6 and sending a request to node hosta6. The program uses an AF_INET6 socket. The node hosta6 has the IPv6 address 3ffe:1200::a00:2bff:fe97:7be0 in the Domain Name System (DNS).

$ run client.exe
Enter remote host: hosta6
Initiated connection to host: hosta6.ipv6.corp.example, port: 12345
Data received: Hello, world!
$

On the server node, the following example shows the server program invocation and the request received from the client node hostb6:

$ run server.exe
Waiting for a client connection on port: 12345
Accepted connection from host: hostb6.ipv6.corp.example
(3ffe:1200::a00:2bff:fe97:7be0), port: 49174
Data sent: Hello, world!
$

The following example shows the client program running on node hostb and sending a request to node hosta. The program uses an AF_INET6 socket. The hosta node has only an IPv4 address in the DNS.

$ run client.exe
Enter remote host: hosta
Initiated connection to host: hosta.corp.example, port 12345
Data received: Hello, world!
$

On the server node, the following example shows the server program invocation and the request received from the client node hostb:

$ run server.exe
Waiting for a client connection on port: 12345
Accepted connection from host: hostb.corp.example (::ffff:10.10.10.251), port: 49175
Data sent: Hello, world!
$

The following example shows the client program running on node hostb6 and sending a request to node hosta6 using its link-local address fe80::a00:2bff:fe97:7be0. The program uses an AF_INET6 socket.

$ run client.exe
Enter remote host: fe80::a00:2bff:fe97:7be0
Initiated connection to host: fe80::a00:2bff:fe97:7be0, port: 12345
Data received: Hello, world!
$

On the server node, the following example shows the server program invocation and the request received from the client node hostb6.

$ run server.exe
Waiting for a client connection on port: 12345
Accepted connection from host: hosta6.ipv6.corp.example%WE0
(fe80::a00:2bff:fe97:7be0%WE0), port: 49177
Data sent: Hello, world!
$

The following are supported IPV6 Request for Comments (RFCs):

• Internet Protocol Version 6 (IPv6) Specification, RFC 2460 (December 1998)
• Internet Control Message Protocol (ICMPv6) for Internet Protocol Version 6 (IPv6), RFC 2463 (December 1998)
• Neighbor Discovery for IP Version 6 (IPv6), RFC 2461 (December 1998)
• IPv6 Stateless Address Autoconfiguration, RFC 2462 (December 1998)
• Path MTU Discovery for IP Version 6, RFC 1981 (August 1996)
• Transition Mechanisms for IPv6 Hosts and Routers, RFC 1933 (April 1996)
• IP Version 6 Addressing Architecture, RFC 3513 (April 2003)
• An IPv6 Aggregatable Global Unicast Address Format, RFC 2374 (July 1998)
• IPv6 Testing Address Allocation, RFC 2471 (December 1998)
• Transmission of IPv6 Packets over Ethernet Networks, RFC 2464 (December 1998)
• Transmission of IPv6 Packets over FDDI Networks, RFC 2467 (December 1998)
• Basic Socket Interface Extensions for IPv6, RFC 3493 (February 2003)
• Advanced Sockets API for IPv6, RFC 3542 (May 2003)
• DNS Extensions to Support IP version 6, RFC 1886 (December 1995)
• Dynamic Updates in the Domain Name System (DNS UPDATE), RFC 2136 (April 1997)
• RIPng, RFC 2080 (January 1997)

This appendix describes deprecated library functions that were provided in previous Early Adopter Kits (EAKs). Do not use these functions if you are developing new applications. If your existing applications use these functions, see Chapter 8 for changes you should make to your code.

The following table shows the deprecated functions and their replacements:

The getipnodebyname function has the following syntax:

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

Parameters:

• name
  Specifies the official network node name, alias, or numeric node address (for example, an IPv4 dotted-decimal address or an IPv6 hexadecimal address).
• addr_family
  Specifies the address family. This can be AF_INET for IPv4 addresses or AF_INET6 for IPv6 addresses.
• flags
  Specifies the type of addresses for which to search and the types of addresses that are returned. Table B-1 describes how the processing is affected by the values of the af parameter and commonly used flag values.
• error_num
  Specifies an error return code value if the function is not successful.

Description

The getipnodebyname() routine is an evolution of the gethostbyname() routine that enables name lookups in address families other than AF_INET.

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

If multiple addresses are found, the h_addr_list field in the hostent structure contains the addresses.

The <netdb.h> header file defines the hostent structure.

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

Table B-1 lists the flags parameters and how the processing is affected by the value of the af parameters.

All flags can be used in any combination to achieve finer control of the translation process. The AI_ADDRCONFIG flag is typically used in combination with other flags to modify the search based on the source address or addresses configured on the system. Table B-2 describes how the AI_ADDRCONFIG flag works by itself.

Most applications will use a combination of the AI_ADDRCONFIG and AI_V4MAPPED flags to control their search. To simplify this for the programmer, the AI_DEFAULT symbol, which is a logical OR of AI_ADDRCONFIG and AI_V4MAPPED, is defined. Table B-3 describes how AI_DEFAULT directs the search.

The hostent structure returned by the getipnodebyname function is dynamically allocated. You should free this structure and dynamic storage by using the freehostent function (see Section B.3).

Errors

If the getipnodebyname() routine call fails, error_num is set to one of the following 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.

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 B.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.

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.