HP OpenVMS Systems Documentation

Returns the number of bytes required for an IPv6 routing header.

Format

#include <ip6.h>

size_t inet6_rth_space ( int type, int segments );

Arguments

type

Specifies the type of routing header. The valid value is IPV6_RTHDR_TYPE_0 for IPv6 routing header type 0.

segments

Specifies the number of segments or addresses that are to be included in the routing header. The valid value is from 0 to 127, inclusive.

Description

The inet6_rth_space() function determines the amount of space, in bytes, required for a routing header. Although the function returns the amount of space required, it does not allocate buffer space. This enables the application to allocate a larger buffer.

If the application uses ancillary data, it must pass the returned length to CMSG_LEN() to determine the amount of memory required for the ancillary data object, including the cmsghdr structure.

Note If an application wants to send other ancillary data objects, it must specify them to sendmsg() as a single msg_control buffer.

Return Values

x	Upon successful completion, the inet6_rth_space() function returns the length, in bytes, of the routing header and the specified number of segments.
0 (zero)	Failure, if the type is not supported or the number of segments is invalid for the type of routing header

Converts a numeric address to a text string suitable for presentation.

Format

#include <inet.h>

const char *inet_ntop ( int af, const void *src, char *dst, size_t size );

Arguments

af

Specifies the address family. Valid values are AF_INET for an IPv4 address and AF_INET6 for an IPv6 address.

src

Points to a buffer that contains the numeric Internet address.

dst

Points to a buffer that is to contain the text string.

size

Specifies the size of the buffer pointed to by the dst parameter. For IPv4 addresses, the minimum buffer size is 16 octets; for IPv6 addresses, the minimum buffer size is 46 octets. The <in.h> header file defines the INET_ADDRSTRLEN and INET6_ADDRSTRLEN constants, respectively, for these values.

Description

The inet_ntop() function converts a numeric Internet address value to a text string.

Return Values

Pointer to the buffer containing the text string.	Success
Pointer to the buffer containing NULL.	Failure

Converts an address in its standard text presentation form its numeric binary form, in network byte order.

Format

#include <inet.h>

int inet_pton ( int af, const char *src, void *dst );

Arguments

af

Specifies the address family. Valid values are AF_INET for an IPv4 address and AF_INET6 for an IPv6 address.

src

Points to the address text string to be converted.

dst

Points to a buffer that is to contain the numeric address.

Description

The inet_pton() function converts a text string to a numeric value in Internet network byte order.

• If the af parameter is AF_INET, the function accepts a string in the standard IPv4 dotted-decimal format:

  ddd.ddd.ddd.ddd

  
  In this format, ddd is a one- to three-digit decimal number between 0 and 255.
• If the af parameter is AF_INET6, the function accepts a string in the following format:

  x:x:x:x:x:x:x:x

  
  In this format, x is the hexadecimal value of a 16-bit piece of the address.
  IPv6 addresses can contain long strings of zero (0) bits. To make it easier to write these addresses, you can use double-colon characters (::) one time in an address to represent 1 or more 16-bit groups of zeros.
• For mixed IPv4 and IPv6 environments, the following format is also accepted:

  x:x:x:x:x:x:ddd.ddd.ddd.ddd

  
  In this format, x is the hexadecimal value of a 16-bit piece of the address, and ddd is a one- to three-digit decimal value between 0 and 255 that represents the IPv4 address. See RFC 2373 for more information about IPv6 addressing formats.

The calling application is responsible for ensuring that the buffer referred to by the dst parameter is large enough to hold the numeric address. AF_INET addresses require 4 bytes and AF_INET6 addresses require 16 bytes.

Return Values

1	Success
0 (zero)	If the input string is neither a valid IPv4 dotted-decimal string nor a valid IPv6 address string, the function returns a 0.
-1	Failure. errno is set to the following value.

Errors

EAFNOSUPPORT

The address family specified in the af parameter is unknown.

This chapter describes the changes you must make in your application code to operate in an IPv6 networking environment.

• Name changes
• Structure changes
• Other changes

You can also use this information as guidelines for creating new IPv6-ready applications.

See RFC 3493, Basic Socket Interface Extensions for IPv6, for complete information on the changes to the BSD socket applications programming interface (API). See RFC 3542, Advanced Sockets API for IPv6 for complete information on how to use raw sockets and header information in IPv6 applications.

8.1 Using AF_INET6 Sockets

At present, applications use AF_INET sockets for IPv4 communications. Figure 8-1 shows a sample sequence of events for an application that uses an AF_INET socket to send IPv4 packets.

Figure 8-1 Using AF_INET Socket for IPv4 Communications

1. Application calls gethostbyname() and passes the host name, host1.
2. The search finds host1 in the hosts database and gethostbyname returns the IPv4 address 1.2.3.4.
3. The application opens an AF_INET socket.
4. The application sends information to the 1.2.3.4 address.
5. The socket layer passes the information and address to the UDP module.
6. The UDP module puts the 1.2.3.4 address into the packet header and passes the information to the IPv4 module for transmission.

Section 8.6.1.1 contains sample program code that demonstrates these steps.

You can use the AF_INET6 socket for both IPv6 and IPv4 communications. For IPv4 communications, create an AF_INET6 socket and pass it a sockaddr_in6 structure that contains an IPv4-mapped IPv6 address (for example, ::ffff:1.2.3.4 ). Figure 8-2 shows the sequence of events for an application that uses an AF_INET6 socket to send IPv4 packets.

Figure 8-2 Using AF_INET6 Socket to Send IPv4 Communications

1. Application calls getaddrinfo() and passes the host name (host1), the AF_INET6 address family hint, and the (AI_V4MAPPED | AI_ADDRCONFIG) flag hint. The flag tells the function that if an IPv4 address is found for host1, return the address as an IPv4-mapped IPv6 address.
2. The search finds an IPv4 address, 1.2.3.4, for host1 in the hosts database and getaddrinfo() returns the IPv4-mapped IPv6 address ::ffff:1.2.3.4 .
3. The application opens an AF_INET6 socket.
4. The application sends information to the ::ffff:1.2.3.4 address.
5. The socket layer passes the information and address to the UDP module.
6. The UDP module identifies the IPv4-mapped IPv6 address, puts the 1.2.3.4 address into the packet header, and passes the information to the IPv4 module for transmission.

AF_INET6 sockets can receive messages sent to either IPv4 or IPv6 addresses on the system. An AF_INET6 socket uses the IPv4-mapped IPv6 address format to represent IPv4 addresses. Figure 8-3 shows the sequence of events for an application that uses an AF_INET6 socket to receive IPv4 packets.

Figure 8-3 Using AF_INET6 Socket to Receive IPv4 Communications

1. The application opens an AF_INET6 socket, binds to it, and listens on it.
2. An IPv4 packet arrives and passes through the IPv4 module.
3. The TCP layer strips off the packet header and passes the information and the IPv4-mapped IPv6 address ::ffff:1.2.3.4 to the socket layer.
4. The application calls accept() and retrieves the information from the socket.
5. The application calls getnameinfo() and passes the ::ffff:1.2.3.4 address and the NI_NAMEREQD flag. The flag tells the function to return the host name for the address. See Table 7-9 for a description of the flag bits and their meanings.
6. The search finds the host name for the 1.2.3.4 address in the hosts database, and getnameinfo() returns the host name.

For IPv6 communications, create an AF_INET6 socket and pass it a sockaddr_in6 structure that contains an IPv6 address (for example, 3ffe:1200::a00:2bff:fe2d:02b2 ). Figure 8-4 shows the sequence of events for an application that uses an AF_INET6 socket to send IPv6 packets.

Figure 8-4 Using AF_INET6 Socket for IPv6 Communications

1. Application calls getaddrinfo() and passes the host name (host1), the AF_INET6 address family hint, and the (AI_V4MAPPED | AI_ADDRCONFIG) flag hint. The flag tells the function that if an IPv4 address is found for host1, to return it.
2. The search finds an IPv6 address for host1 in the hosts database, and getaddrinfo() returns the IPv6 address 3ffe:1200::a00:2bff:fe2d:02b2 .
3. The application opens an AF_INET6 socket.
4. The application sends information to the 3ffe:1200::a00:2bff:fe2d:02b2 address.
5. The socket layer passes the information and address to the UDP module.
6. The UDP module identifies the IPv6 address and puts the 3ffe:1200::a00:2bff:fe2d:02b2 address into the packet header and passes the information to the IPv6 module for transmission.

Section 8.6.2.1 contains sample program code that demonstrates these steps.

The following sections show how to convert an existing AF_INET application to an AF_INET6 application that is capable of communicating over both IPv4 and IPv6.

8.2 Name Changes

Most of the changes required are straightforward and mechanical, though some may require a bit of code restructuring. For example, a routine that returns an int data type holding an IPv4 address may need to be modified to take as an extra parameter a pointer to an in6_addr into which it writes the IPv6 address.

Table 8-1 summarizes the changes you must make to your application's code.

The structure names and field names have changed for the following structures:

• in_addr
• sockaddr_in
• sockaddr
• hostent

The following sections discuss these changes.

8.3.1 in_addr Structure

Applications that use the IPv4 in_addr structure must be changed to use the IPv6 in6_addr structure, as follows:

Make the following changes to your application, as needed:

1. Change the structure name in_addr to in6_addr .
2. Change the data type from unsigned int to uint8_t and the field name s_addr to s6_addr .

Applications that use the generic socket address structure (sockaddr) to hold an AF_INET socket address ( sockaddr_in ) must be changed to use the AF_INET6 sockaddr_in6 structure, as follows:

Make the following change to your application, as needed:

1. Change structure name sockaddr to sockaddr_in6 .

   Note A sockaddr_in6 structure is larger than a sockaddr structure.

Applications that use the BSD Version 4.4 IPv4 sockaddr_in structure must be changed to use the IPv6 sockaddr_in6 structure, as follows:

Make the following changes to your application, as needed:

1. Change structure name sockaddr_in to sockaddr_in6 . Initialize the entire sockaddr_in6 structure to zero after your structure declarations.
2. Change the data type unsigned char to uint8_t and the field name sin_len to sin6_len .
3. Change the field name sin_family to sin6_family .
4. Change the field name sin_port to sin6_port .
5. Change the field name sin_addr to sin6_addr .

Applications that use the hostent structure must be changed to use the addrinfo structure, as follows:

Make the following change to your application, as needed:

1. Change the structure name hostent to addrinfo .

See also Section 8.4.2 for related changes.

8.4 Function Changes

The names and parameters have changed for the following functions:

• gethostbyaddr()
• gethostbyname()
• inet_ntoa()
• inet_addr()

The following sections discuss these changes.

8.4.1 gethostbyaddr() Function

Applications that use the IPv4 gethostbyaddr() function must be changed to use the IPv6 getnameinfo() function, as follows:

Make the following change to your application, as needed:

1. Change the function name from gethostbyaddr() to getnameinfo() and provide a pointer to the socket address structure, a character string for the returned node name, an integer for the length of the returned node name, a character string to receive the returned service name, an integer for the length of the returned service name, and an integer that specifies the type of address processing to be performed.

Applications that use the gethostbynam()e function must be changed to use the getaddrinfo() function, as folllows:

Make the following changes to your application, as needed:

1. Change the function name from gethostbyname() to getaddrinfo() and provide a character string that contains the node name, a character string that contains the service name to use, a pointer to a hints structure that contains processing options, and a pointer to an addrinfo structure or structures for the returned address information.
2. Add a call to the freeaddrinfo() routine to free the addrinfo structure or structures when your application is finished using them.

Applications that use the inet_ntoa() function must be changed to use the getnameinfo() function, as follows:

Make the following change to your application, as needed:

1. Change the function name from inet_ntoa() to getnameinfo() and provide a pointer to the socket address structure, a character string for the returned node name, an integer for the length of the returned node name, a character string to receive the returned service name, an integer for the length of the returned service name, and the NI_NUMERICHOST flag.