HP OpenVMS Systems Documentation

To compile an IPv6 application that contains #includes of the following form

#include <path/file.h>

that is, an include file specification preceded by "path/" , you need to set up the following environment:

$ DEFINE DECC$SYSTEM_INCLUDE TCPIP$EXAMPLES:
$ DEFINE ARPA TCPIP$EXAMPLES:
$ DEFINE NET TCPIP$EXAMPLES:
$ DEFINE NETINET TCPIP$EXAMPLES:
$ DEFINE SYS TCPIP$EXAMPLES:

If your IPv6 application does not contain any include statements of that format, the DEFINE statements are not necessary.

To use certain features of the basic and advanced APIs, you must take special measures when compiling and linking.

Under either of these conditions:

• Using getaddrinfo() with OpenVMS 7.3-1 or earlier
• Using any of the advanced APIs with any version of OpenVMS

You should do both of the following:

• Add /INCLUDE_DIRECTORY=TCPIP$EXAMPLES: to the compile command line. This allows the compiler to use the updated header files that exist in the TCPIP$EXAMPLES directory which are provided by TCP/IP Services for OpenVMS. Otherwise, the compiler will use the header files from the C Run-Time Library, which may not contain the information needed or which may contain out-of-date information.
• Add TCPIP$LIBRARY:TCPIP$LIB/LIBRARY to the link command line. This allows the linker to resolve references to routines from TCPIP$LIB.OLB provided by TCP/IP Services for OpenVMS. This is necessary because routines have not yet been implemented in the C Run-Time library.

See Section 8.6 for examples of the compile and link command lines.

7.7 IPv6 Library Functions API

This section describes functions that comprise the Sockets API that support IPv6 and that are supported by TCP/IP Services.

This function frees system resources used by an address information structure.

Format

#include <netdb.h>

void freeaddrinfo ( struct addrinfo *ai );

Arguments

ai

Points to the addrinfo structure to be freed.

Description

This function frees an addrinfo structure and any dynamic storage pointed to by the structure. The process continues until the function encounters a NULL ai_next pointer.

Provides a descriptive text string that corresponds to an EAI_xxx error value.

Format

#include <netdb.h>

const char *gai_strerror ( int ecode );

Arguments

ecode

The ecode argument is one of the EAI_xx values defined for the getaddrinfo and getnameinfo functions.

Description

The gai_strerror () function returns a descriptive text string that corresponds to an EAI_xxx error value. The return value points to a string that describes the error. If the argument is not one of the EAI_xx values, the function still returns a pointer to a string whose contents indicates an unknown error.

Return Values

X	text string
-1	Failure

Errors

EAI_AGAIN	The name could not be resolved at this time. Future attempts may succeed.
EAI_BADFLAGS	The flags parameter had an invalid value.
EAI_FAIL	A nonrecoverable error occurred when attempting to resolve the name.
EAI_FAMILY	The address family was not recognized.
EAI_MEMORY	There was a memory allocation failure when trying to allocate storage for the return value.
EAI_NONAME	The name does not resolve for the supplied parameters. Neither nodename nor servname were supplied. At least one of these must be supplied.
EAI_SERVICE	The service passed was not recognized for the specified socket type.
EAI_SOCKTYPE	The intended socket type was not recognized.
EAI_SYSTEM	A system error occurred; the error code can be found in errno .

Takes a service location (nodename) or a service name (servname), or both, and returns a pointer to a linked list of one or more structures of type addrinfo .

Format

#include <socket.h>

#include <netdb.h>

int getaddrinfo ( const char *nodename, const char *servname, const struct addrinfo *hints, struct addrinfo **res );

Arguments

nodename

Points to a network node name, alias, or numeric host address (for example, an IPv4 dotted-decimal address or an IPv6 hexadecimal address). An IPv6 nonglobal address with an intended scope zone may also be specified. See Section 1.2.4 for more information. This is a null-terminated string or NULL. NULL means the service location is local to the caller. The nodename and servname arguments cannot both be NULL.

servname

Points to a network service name or port number. This is a null-terminated string or NULL; NULL returns network-level addresses for the specified nodename. The nodename and servname arguments cannot both be NULL.

hints

Points to an addrinfo structure that contains information about the type of socket, address family, or protocol the caller supports. The <netdb.h> header file defines the addrinfo structure. If hints is a null pointer, the behavior is the same as if addrinfo contained the value 0 for the ai_flags , ai_socktype and ai_protocol members and AF_UNSPEC for the ai_family member.

res

Points to a linked list of one or more addrinfo structures.

Description

The getaddrinfo() routine takes a service location (nodename) or a service name (servname), or both, and returns a pointer to a linked list of one or more structures of type addrinfo . Its members specify data obtained from either the local hosts database TCPIP$ETC:IPNODES.DAT file, local TCPIP$HOSTS.DAT file, or one of the files distributed by DNS/BIND.

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

If the hints argument is non-NULL, all addrinfo structure members other than the following members must be zero or a NULL pointer:

• ai_flags
  Controls the processing behavior of getaddrinfo() . See Table 7-8 for a complete description of the flags.
• ai_family
  Specifies to return addresses for use with a specific protocol family.
  • If you specify a value of AF_UNSPEC, the routine returns addresses for any protocol family that can be used with nodename or servname.
  • If the value is not AF_UNSPEC and ai_protocol is not zero, the routine returns addresses for use only with the specified protocol family and protocol.
  • If the application handles only IPv4, set this member of the hints structure to PF_INET.
  • If ai_family is set to PF_INET6, the function looks only in the TCPIP$ETC:IPNODES.DAT file and the lookup fails in the BIND database.
• ai_socktype
  Specifies a socket type for the given service. If you specify a value of 0, you will accept any socket type. This resolves the service name for all socket types and returns all successful results.
• ai_protocol
  Specifies a network protocol. If you specify a value of 0, you will accept any protocol. If the application handles only TCP, set this member to IPPROTO_TCP.

Table 7-8 describes the ai_flags member values.

Table 7-8 ai_flags Member Values

Flag Value	Description
AI_V4MAPPED	If af value is AF_INET:	If af value is AF_INET6:
	Ignored.	Searches for AAAA records. The lookup sequence is LOCAL host database, TCPIP$ETC:IPNODES.DAT, BIND database. The lookup for a particular type of record, for example an AAAA record, will be performed in each database before moving on to perform a lookup for the next type of record. If AAAA records found, returns IPv6 addresses; no search for A records is performed. If no AAAA records found, searches for A records. If A records found, returns IPv4-mapped IPv6 addresses. If no A records found, returns a NULL pointer.
AI_ALL | AI_V4MAPPED	If af value is AF_INET:	If af value is AF_INET6:
	Ignored.	Searches for AAAA records. The lookup sequence is LOCAL host database, TCPIP$ETC:IPNODES.DAT, BIND database. The lookup for a particular type of record, for example an AAAA record, will be performed in each database before moving on to perform a lookup for the next type of record. If AAAA records found, IPv6 addresses will be included with the returned addresses. Searches for A records. If A records found, returns IPv4-mapped IPv6 addresses and also any IPv6 addresses that were found with the AAAA record search. If no A records found, returns a NULL pointer.
AI_CANONNAME	If the nodename argument is not NULL, the function searches f or the specified node's canonical name. Upon successful completion, the ai_canonname member of the first addrinfo structure in the linked list points to a null-terminated string containing the canonical name of the specified node name. If the nodename argument is an address literal, the ai_cannonname member will refer to the nodename argument that has been converted to its numeric binary form, in network byte order. If the canonical name is not available, the ai_canonname member refers to the nodename argument or to a string with the same contents. The ai_flags field contents are undefined.
AI_NUMERICHOST	A non-NULL node name string must be a numeric host address string. Resolution of the service name is not performed.
AI_NUMERICSERV	A non-NULL service name string must be a numeric port string. Resolution of the service name is not performed.
AI_PASSIVE	Returns a socket address structure that your application can use in a call to bind() . If the nodename parameter is a NULL pointer, the IP address portion of the socket address structure is set to INADDR_ANY (for an IPv4 address) or IN6ADDR_ANY_INIT (for an IPv6 address). If not set, returns a socket address structure that your application can use to call connect() (for a connection-oriented protocol) or either connect() , sendto() , or sendmsg() (for a connectionless protocol). If the nodename argument is a NULL pointer, the IP address portion of the socket address structure is set to the loopback address.

You can use the flags 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. The following table describes how the AI_ADDRCONFIG flags works by itself.

Flag Value	If af Value is AF_INET	If af Value is AF_INET6
AI_ADDRCONFIG	If an IPv4 source address is configured, searches for A records.	If an IPv6 source address is configured, searches for AAAA records.

Most applications will want to use the 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. The following table describes how AI_DEFAULT directs the search.

Flag Value	If af Value is AF_INET	If af Value is AF_INET6
AI_DEFAULT	Searches for A records only if an IPv4 source address is configured on the system. If found, returns IPv4 addresses. If not, returns a NULL pointer.	Searches for AAAA records only if an IPv6 source address is configured on the system. If found, returns IPv6 addresses. If not and if an IPv4 address is configured on the system, searches for A records. If found, returns IPv4-mapped IPv6 addresses. If not, returns a NULL pointer.

These flags are defined in <netdb.h> .

addrinfo Structure Processing

Upon successful return, getaddrinfo() returns a pointer to a linked list of one or more addrinfo structures. The application can process each addrinfo structure in the list by following the ai_next pointer until a NULL pointer is encountered. In each returned addrinfo structure, the ai_family , ai_socktype , and ai_protocol members are the corresponding arguments for a call to the socket() function. The ai_addr member points to a filled-in socket address structure whose length is specified by the ai_addrlen member.

Return Values

0 (zero)	Success
nonzero value	Failure

Maps addresses to names in a protocol-independent way.

Format

#include <socket.h>

#include <netdb.h>

int getnameinfo ( const struct sockaddr *sa, size_t salen, char *node, size_t nodelen, char *service, size_t servicelen, int flags );

Arguments

sa

Points either to a sockaddr_in structure (for IPv4) or to a sockaddr_in6 structure (for IPv6) that holds the IP address and port number.

salen

Specifies the length of either the sockaddr_in structure or the sockaddr_in6 structure.

node

Points to a buffer in which to receive the null-terminated network node name or alias corresponding to the address contained in the sa. The node name may be suffixed with an intended scope zone as described in Section 1.2.4. A NULL pointer instructs the routine not to return a node name. The node parameter and service parameter cannot both be zero.

nodelen

Specifies the length of the node buffer. A value of zero instructs the routine not to return a node name.

service

Points to a buffer in which to receive the null-terminated network service name associated with the port number contained in sa. A NULL pointer instructs the routine not to return a service name. The node parameter and service parameter cannot both be 0.

servicelen

Specifies the length of the service buffer. A value of zero instructs the routine not to return a service name.

flags

Specifies changes to the routine's default actions. By default, the routine searches for the fully qualified domain name of the node in the host's database and returns it. See Table 7-9 for a list of flag bits and their meanings.

Description

The getnameinfo() routine looks up an IP address and port number in a sockaddr structure specified by sa and returns node name and service name text strings in the buffers pointed to by the node and service parameters, respectively.

If the node name is not found, the routine returns the numeric form of the node address, regardless of the value of the flags parameter. If the service's name is not found, the routine returns the numeric form of the service's address (port number) regardless of the value of the flags parameter.

The application must provide buffers large enough to hold the fully qualified domain name and the service name, including the terminating null characters.

Flag bits

Table 7-9 describes the flag bits and, if set, their meanings.

Table 7-9 Flag Bits

Flag Value	Description
NI_DGRAM	Specifies that the service is a datagram service (SOCK_DGRAM). The default assumes a stream service (SOCK_STREAM). This is required for the few ports (512-514) that have different services for UDP and TCP.
NI_NAMEREQD	Returns an error if the host name cannot be located in the host's database.
NI_NOFQDN	Searches the host's database and returns the node name portion of the fully qualified domain name for local hosts.
NI_NUMERICHOST	Returns the numeric form of the host's address instead of its name. Resolution of the host name is not performed.
NI_NUMERICSERV	Returns the numeric form (port number) of the service address instead of its name. Resolution of the host name is not performed.

The two NI_NUMERIC* flags are required to support the -n flag that many commands provide. All flags are defined in <netdb.h> header file.

Return Values

0 (zero)	Success
nonzero value	Failure

Frees dynamic memory allocated by if_nameindex() to the array of interface names and indexes.

Format

#include <if.h>

void if_freenameindex ( struct if_nameindex *ptr );

Arguments

ptr

Pointer that was returned by the if_nameindex() function.

Description

The if_freenameindex() function frees dynamic memory that was allocated by the if_nameindex() function.

Maps an interface index to its corresponding name.

Format

#include <if.h>

char *if_indextoname ( unsigned int ifindex, char *ifname );

Arguments

ifindex

The interface index.

ifname

The ifname argument points to a buffer that is IFNAMSIZ bytes in length (IFNAMSIZ is defined in <if.h> ). If an interface name is found, it is returned in the buffer.

Description

The if_indextoname() function maps an interface index to its corresponding name.

Return Values

Interface name	If interface name is found, it is returned to the buffer.
NULL	If no interface name corresponds to the specified index, the function returns NULL and sets errno to ENXIO.

Errors

ENXIO	No interface name corresponds to the specified index.
System error	A system error.