HP OpenVMS Systems Documentation

HP TCP/IP Services for OpenVMS
Sockets API and System Services Programming

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_xxx values defined for the getaddrinfo() and getnameinfo() functions.

The values for ecode are:

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 .

Description

This 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_xxx values, the function returns a pointer to a string whose contents indicate an unknown error.

For a complete list of error codes, see Appendix D.

Return Values

x	text string
-1	Failure

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. This is a null-terminated string or NULL. NULL means the service location is local to the caller. The nodename and servname arguments must not 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 must not 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

This function 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 the local hosts database TCPIP$ETC:IPNODES.DAT file, the 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 4-2 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, getaddrinfo() 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, getaddrinfo() 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.
• 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 4-2 describes the values for ai_flags members.

Table 4-2 ai_flags Member Values

Flag Value	Description
AI_V4MAPPED	If ai_family is AF_INET, the flag is ignored. If ai_family is AF_INET6, getaddrinfo() searches for AAAA records. The lookup sequence is: Local hosts 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 are found, returns IPv6 addresses; no search for A records is performed. If no AAAA records are 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 ai_family is AF_INET, the flag is ignored. If the ai_family is AF_INET6, getaddrinfo() searches for AAAA records. The lookup sequence is: Local hosts 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 are found, IPv6 addresses will be included with the returned addresses. If A records are 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 for 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.
AI_ADDRCONFIG	Used in combination with other flags, modifies the search based on the source address or addresses configured on the system.

You can use the flags in any combination to achieve finer control of the translation process. Many applications use the combination of the AI_ADDRCONFIG and AI_V4MAPPED flags to control their search.

• If the value of ai_family is AF_INET, and an IPv4 source address is configured on the system, getaddrinfo() searches for A records only. If found, getaddrinfo() returns IPv4 addresses. If not, getaddrinfo() returns a NULL pointer.
• If the value of ai_family is AF_INET6 and an IPv6 source address is configured on the system, getaddrinfo() searches for AAAA records. If found, getaddrinfo() returns IPv6 addresses. If not, and if an IPv4 address is configured on the system, getaddrinfo() searches for A records. If found, getaddrinfo() returns IPv4-mapped IPv6 addresses. If not, getaddrinfo() returns a NULL pointer.

These flags are defined in the NETDB.H header file.

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	Indicates success
-1	Indicates an error

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 .

Returns the standard host address for the processor.

Format

#include <socket.h>

int gethostaddr (char *addr);

Argument

addr

A pointer to the buffer in which the standard host address for the current processor is returned.

Description

This function returns the standard host address for the current processor. The returned address is null-terminated. The addr parameter must point to at least 16 bytes of free space.

Host addresses are limited to 16 characters.

Return Values

0	Indicates success.
- 1	Indicates that an error has occurred and is further specified in the global errno .

Searches the hosts database that is referenced by the TCPIP$HOST logical name for a host record with a given IPv4 address. If the host record is not found there, the function may also invoke the BIND resolver to query the appropriate name server.

The $QIO equivalent is the IO$_ACPCONTROL function with the INETACP_FUNC$C_GETHOSTBYADDR subfunction code.

Format

#include <netdb.h>

struct hostent *gethostbyaddr ( const void *addr, size_t len, int type );

Arguments

addr

A pointer to a series of bytes in network order specifying the address of the host sought.

len

The number of bytes in the address pointed to by the addr argument.

type

The type of address format being sought (AF_INET).

Description

This function finds the first host record with the specified address in the hosts database or using DNS/BIND.

The gethostbyaddr() function uses a common static area for its return values. This means that subsequent calls to this function overwrite previously returned host entries. You must make a copy of the host entry if you want to save it.

Return Values

x	A pointer to an object having the hostent structure. See Section 3.2.3 for a description of the hostent structure.
NULL	Indicates an error; errno is set to one of the following values.

Errors

ENETDOWN	TCP/IP Services was not started.
HOST_NOT_FOUND	Host is unknown.
NO_DATA	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 may be successful.

Searches the hosts database that is referenced by the TCPIP$HOST logical name for a host record with the specified name or alias.

If the host record is not found, this function may also invoke the BIND resolver to query the appropriate name server for the information.

The $QIO equivalent is the IO$_ACPCONTROL function with the INETACP_FUNC$C_GETHOSTBYNAME subfunction code.

Format

#include <netdb.h>

struct hostent *gethostbyname ( char *name );

Argument

name

A pointer to a null-terminated character string containing the name or an alias of the host being sought.

Description

This function finds the first host with the specified name or alias in the hosts database, or using DNS/BIND.

The gethostbyname() function uses a common static area for its return values. This means that subsequent calls to this function overwrite previously returned host entries. You must make a copy of the host entry if you want to save it.

Return Values

x	A pointer to an object having the hostent structure. See Section 3.2.3 for a description of the hostent structure.
NULL	Indicates an error. errno is set to one of the following values.

Errors

ENETDOWN	TCP/IP Services was not started.
HOST_NOT_FOUND	Host is unknown.
NO_DATA	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 may be successful.

Retrieves an entry from the hosts database file.

Format

#include <netdb.h>

struct hostent *gethostent (void);

Description

The gethostent() function reads the next entry of the hosts database file (TCPIP$ETC:IPNODES.DAT).

See the NETDB.H header file for a description of the hostent structure.

The gethostent() function uses a common static area for its return values. Therefore, subsequent calls to gethostent() overwrite any existing host entry. You must make a copy of the host entry, if you wish to save it.

Return Values

x	A pointer to an object having the hostent structure. See Section 3.2.3 for a description of the hostent structure.
NULL	Indicates an error; errno is set to one of the following values.

Errors

ENETDOWN	TCP/IP Services was not started.
HOST_NOT_FOUND	Host is unknown.
NO_DATA	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 may be successful.