te
Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
getipnodebyname, getipnodebyaddr, freehostent - get IP node entry

cc [ flag... ] file... -lsocket  -lnsl  [ library... ]
#include <sys/socket.h>
#include <netdb.h>

struct hostent *getipnodebyname(const char *name, int af,
 int flags, int *error_num);

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

void freehostent(struct hostent *ptr);

af flags name error_num src len ptr

The getipnodebyname() function searches the ipnodes database from the beginning. The function finds the first h_name member that matches the hostname specified by name. The function takes an af argument that specifies the address family. The address family can be AF_INET for IPv4 addresses or AF_INET6 for IPv6 addresses. The flags argument determines what results are returned based on the value of flags. If the flags argument is set to 0 (zero), the default operation of the function is specified as follows:

The flags argument changes the default actions of the function. Set the flags argument with a logical OR operation on any of combination of the following values:

The special flags value, AI_DEFAULT, should handle most applications. Porting simple applications to use IPv6 replaces the call

hptr = gethostbyname(name);

with

hptr = getipnodebyname(name, AF_INET6, AI_DEFAULT, &error_num);

The flags value 0 (zero) implies a strict interpretation of the af argument:

Logically OR other constants into the flags argument to modify the behavior of the getipnodebyname() function.

The special flags value, AI_DEFAULT, is defined as

#define AI_DEFAULT (AI_V4MAPPED | AI_ADDRCONFIG)

The getipnodebyname() function allows the name argument to be a node name or a literal address string: a dotted-decimal IPv4 address or an IPv6 hex address. Applications do not have to call inet_pton(3C) to handle literal address strings.

Four scenarios arise based on the type of literal address string and the value of the af argument. The two simple cases occur when name is a dotted-decimal IPv4 address and af equals AF_INET and when name is an IPv6 hex address and af equals AF_INET6. The members of the returned hostent structure are: h_name

h_aliases h_addrtype h_length h_addr_list

Upon successful completion, getipnodebyname() and getipnodebyaddr() return a hostent structure. Otherwise they return NULL.

The hostent structure does not change from the existing definition when used with gethostbyname(3NSL). For example, host entries are represented by the struct hostent structure defined in <netdb.h>:

struct hostent {
 char *h_name; /* canonical name of host */
 char **h_aliases; /* alias list */
 int h_addrtype; /* host address type */
 int h_length; /* length of address */
 char **h_addr_list; /* list of addresses */
};

An error occurs when name is an IPv6 hex address and af equals AF_INET. The return value of the function is a NULL pointer and error_num equals HOST_NOT_FOUND.

The getipnodebyaddr() function has the same arguments as the existing gethostbyaddr(3NSL) function, but adds an error number. As with getipnodebyname(), getipnodebyaddr() is thread-safe. The error_num value is returned to the caller with the appropriate error code to support thread-safe error code returns. The following error conditions can be returned for error_num: HOST_NOT_FOUND

NO_DATA NO_RECOVERY TRY_AGAIN

One possible source of confusion is the handling of IPv4-mapped IPv6 addresses and IPv4-compatible IPv6 addresses, but the following logic should apply:

All four steps listed are performed in order.

This structure, and the information pointed to by this structure, are dynamically allocated by getipnodebyname() and getipnodebyaddr(). The freehostent() function frees this memory.

Example 1 Getting the Canonical Name, Aliases, and Internet IP Addresses for a Given Hostname

The following is a sample program that retrieves the canonical name, aliases, and all Internet IP addresses, both version 6 and version 4, for a given hostname.

 #include <stdio.h>
 #include <string.h>
 #include <sys/types.h>
 #include <sys/socket.h>
 #include <netinet/in.h>
 #include <arpa/inet.h>
 #include <netdb.h>

 main(int argc, const char **argv)
 {
 char abuf[INET6_ADDRSTRLEN];
 int error_num;
 struct hostent *hp;
 char **p;

 if (argc != 2) {
 (void) printf("usage: %s hostname\en", argv[0]);
 exit (1);
 }

 /* argv[1] can be a pointer to a hostname or literal IP address */
 hp = getipnodebyname(argv[1], AF_INET6, AI_ALL | AI_ADDRCONFIG |
 AI_V4MAPPED, &error_num);
 if (hp == NULL) {
 if (error_num == TRY_AGAIN) {
 printf("%s: unknown host or invalid literal address "
 "(try again later)\en", argv[1]);
 } else {
 printf("%s: unknown host or invalid literal address\en",
 argv[1]);
 }
 exit (1);
 }
 for (p = hp->h_addr_list; *p != 0; p++) {
 struct in6_addr in6;
 char **q;

 bcopy(*p, (caddr_t)&in6, hp->h_length);
 (void) printf("%s\et%s", inet_ntop(AF_INET6, (void *)&in6,
 abuf, sizeof(abuf)), hp->h_name);
 for (q = hp->h_aliases; *q != 0; q++)
 (void) printf(" %s", *q);
 (void) putchar('\en');
 }
 freehostent(hp);
 exit (0);
 }

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Interface Stability Committed

MT-Level Safe

getaddrinfo(3SOCKET), gethostbyname(3NSL), htonl(3C), inet(3SOCKET), netdb.h(3HEAD), hosts(4), nsswitch.conf(4), attributes(5)

No enumeration functions are provided for IPv6. Existing enumeration functions such as sethostent(3NSL) do not work in combination with the getipnodebyname() and getipnodebyaddr() functions.

All the functions that return a struct hostent must always return the canonical in the h_name field. This name, by definition, is the well-known and official hostname shared between all aliases and all addresses. The underlying source that satisfies the request determines the mapping of the input name or address into the set of names and addresses in hostent. Different sources might make such as determination in different ways. If more than one alias and more than one address in hostent exist, no pairing is implied between the alias and address.

The current implementations of these functions return or accept only addresses for the Internet address family (type AF_INET) or the Internet address family Version 6 (type AF_INET6).

IPv4-mapped addresses are not recommended. The getaddrinfo(3SOCKET) function is preferred over getipnodebyaddr() because it allows applications to lookup IPv4 and IPv6 addresses without relying on IPv4-mapped addresses.

The form for an address of type AF_INET is a struct in_addr defined in <netinet/in.h>. The form for an address of type AF_INET6 is a struct in6_addr, also defined in <netinet/in.h>. The functions described in inet_ntop(3C) and inet_pton(3C) that are illustrated in the EXAMPLES section are helpful in constructing and manipulating addresses in either of these forms.