SunOS man pages : getipnodebyname (3)
Network Functions getipnodebyname(3SOCKET)
NAME
getipnodebyname, getipnodebyaddr, freehostent - get IP node
entry
SYNOPSIS
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);
DESCRIPTION
The getipnodebyname() function searches the ipnodes database
from the beginning and finds the first entry for which the
hostname specified by name matches the h_name member. It
takes an af argument which specifies the address family,
which can be either AF_INET for IPv4 addresses or AF_INET6
for IPv6 addresses. The flags argument determines what
results will be returned based on the value of flags. If
the flags argument is set to 0 (zero), then the default
operation of this function is specified as follows:
o If the af argument is AF_INET, then a query is made
for an IPv4 address. If successful, IPv4 addresses
are returned and the h_length member of the hostent
structure will be 4. Otherwise, the function returns a
null pointer.
o If the af argument is AF_INET6, then a query is made
for an IPv6 address.
If successful, IPv6 addresses are returned and the
h_length member of the hostent structure will be 16.
Otherwise, the function returns a null pointer.
The flags argument will change the default actions of the
function. The flags argument can be set by logically ORing
any of the following values together:
o AI_V4MAPPED
o AI_ALL
o AI_ADDRCONFIG
SunOS 5.8 Last change: 17 Nov 1999 1
Network Functions getipnodebyname(3SOCKET)
Note that a special flags value of AI_DEFAULT as defined
below should handle most applications. That is, porting
simple applications to use IPv6 replaces the call
hptr = gethostbyname(name);
with
hptr = getipnodebyname(name, AF_INET6, AI_DEFAULT);
A flags of 0 implies a strict interpretation of the af argu-
ment:
o If flags is 0 and af is AF_INET, then the caller wants
only IPv4 addresses. A query is made for A records.
If successful, the IPv4 addresses are returned and the
h_length member of the hostent structure will be 4;
otherwise, the function returns a null pointer.
o If flags is 0, and if af is AF_INET6, then the caller
wants only IPv6 addresses. A query is made for AAAA
records. If successful, the IPv6 addresses are
returned and the h_length member of the hostent struc-
ture will be 16; otherwise, the function returns a
null pointer.
Other constants can be logically-ORed into the flags argu-
ment, to modify the behavior of the function.
o If the AI_V4MAPPED flag is specified along with an af
of AF_INET6, then the caller will accept IPv4-mapped
IPv6 addresses. That is, if no AAAA records are
found, then a query is made for A records, and any
found are returned as IPv4-mapped IPv6 addresses
(h_length will be 16). The AI_V4MAPPED flag is
ignored unless af equals AF_INET6.
o The AI_ALL flag is used in conjunction with the
AI_V4MAPPED flag, and is only used with the IPv6
address family. When AI_ALL is logically OR'd with
AI_V4MAPPED flag then the caller wants all addresses:
IPv6 and IPv4-mapped IPv6. A query is first made for
AAAA records and if successful, the IPv6 addresses are
returned.
Another query is then made for A records, and any
found are returned as IPv4-mapped IPv6 addresses.
h_length will be 16. Only if both queries fail does
the function return a null pointer.
This flag is ignored unless af equals AF_INET6.
o The AI_ADDRCONFIG flag specifies that a query for AAAA
records should occur only if the node has at least one
SunOS 5.8 Last change: 17 Nov 1999 2
Network Functions getipnodebyname(3SOCKET)
IPv6 source address configured and a query for A
records should occur only if the node has at least one
IPv4 source address configured. For example, if the
node has no IPv6 source addresses configured, and af
equals AF_INET6, and the node name being looked up has
both AAAA and A records, then
1. If only AI_ADDRCONFIG is specified, the function
returns a null pointer;
2. If AI_ADDRCONFIG or AI_V4MAPPED is specified, the A
records are returned as IPv4-mapped IPv6 addresses;
The special flags value of AI_DEFAULT is defined as
#define AI_DEFAULT (AI_V4MAPPED | AI_ADDRCONFIG)
The getipnodebyname() function must allow the name argument
to be either a node name or a literal address string, that
is, a dotted-decimal IPv4 address or an IPv6 hex address.
This saves applications from having to call
inet_pton(3SOCKET) to handle literal address strings.
There are four scenarios based on the type of literal
address string and the value of the af argument. The two
simple cases are when name is a dotted-decimal IPv4 address
and af equals AF_INET, or when name is an IPv6 hex address
and af equals AF_INET6. The members of the returned hostent
structure are:
h_name
points to a copy of the name argument
h_aliases
is a null pointer.
h_addrtype
is a copy of the af argument.
h_length
is either 4 (for AF_INET) or 16 (for AF_INET6).
h_addr_list[0]
is a pointer to the 4-byte or 16-byte binary address.
h_addr_list[1]
is a null pointer
PARAMETERS
af address family
flags various flags
SunOS 5.8 Last change: 17 Nov 1999 3
Network Functions getipnodebyname(3SOCKET)
name name of host
error_num
error storage
src address for lookup
len length of address
ptr pointer to hostent structure
RETURN VALUES
Upon successful completion, getipnodebyname() and getipnode-
byaddr() return a hostent structure. Otherwise they return
NULL.
The hostent structure does not change from its existing
definition when used with gethostbyname(3NSL). For example,
host entries are represented by the struct hostent struc-
ture 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 */
};
It is an error when name is an IPv6 hex address and af
equals AF_INET. The function's return value 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
may be returned for error_num:
HOST_NOT_FOUND
Host is unknown.
NO_DATA
No address is available for the name specified in
the server request. This is not a soft error.
Another type of name server request may be suc-
cessful.
SunOS 5.8 Last change: 17 Nov 1999 4
Network Functions getipnodebyname(3SOCKET)
NO_RECOVERY
An unexpected server failure occurred. This is a
nonrecoverable error.
TRY_AGAIN
This is a soft error that indicates that the
local server did not
receive a response from an authoritative
server. A retry at some later time may be suc-
cessful.
One possible source of confusion is the handling of IPv4-
mapped IPv6 addresses and IPv4-compatible IPv6 addresses,
but the following logic should apply.
1. If af is AF_INET6, and if len equals 16, and if the IPv6
address
is an IPv4-mapped IPv6 address or an IPv4-compatible
IPv6 address, then skip over the first 12 bytes of the
IPv6 address, set af to AF_INET, and set len to 4.
2. If af is AF_INET, lookup the name for the given IPv4
address.
3. If af is AF_INET6, lookup the name for the given IPv6
address.
4. If the function is returning success, then the single
address that is returned in the hostent structure is a
copy of the first argument to the function with the same
address family that was passed as an argument to this
function.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.
EXAMPLES
Example 1: Getting the canonical name, aliases, and all
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>
SunOS 5.8 Last change: 17 Nov 1999 5
Network Functions getipnodebyname(3SOCKET)
#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 hostname0, 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)\n", argv[1]);
} else {
printf("%s: unknown host or invalid literal address\n",
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\t%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('\n');
}
freehostent(hp);
exit (0);
}
FILES
/etc/inet/hosts
/etc/inet/ipnodes
/etc/netconfig
/etc/nsswitch.conf
SunOS 5.8 Last change: 17 Nov 1999 6
Network Functions getipnodebyname(3SOCKET)
SEE ALSO
getaddrinfo(3SOCKET), gethostbyname(3NSL), htonl(3SOCKET),
inet(3SOCKET), netdb(3HEAD), hosts(4), ipnodes(4),
nsswitch.conf(4)
NOTES
Programs that use the interfaces described in this manual
page
cannot be linked statically since the implementations of
these functions employ dynamic loading and linking of
shared objects at run time.
There is no enumeration functions provided for IPv6. Exist-
ing enumeration functions, for example, sethostent(3NSL),
will not work in combination with getipnodebyname() and
getipnodebyaddr().
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 do that in
different ways. If there is more than one alias and more
than one address in hostent, no pairing is implied between
them.
The current implementations of these functions only return
or accept addresses for the Internet address family (type
AF_INET) or the Internet address family Version 6 (type
AF_INET6).
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 defined also in
<netinet/in.h>. The functions described in
inet_ntop(3SOCKET) and inet_pton(3SOCKET)
that are illustrated in the EXAMPLES section are helpful in
constructing and manipulating addresses in either of these
forms.
SunOS 5.8 Last change: 17 Nov 1999 7
|
 |
|
|
