Sockets Library Functions getipnodebyname(3SOCKET)
NAME
getipnodebyname, getipnodebyaddr, freehostent - get IP node
entry
SYNOPSIS
cc [ flag... ] file... -lsocket -lnsl [ library... ]
#include
#include
struct hostent *getipnodebyname(const char *name, int af,
int flags, int *errornum);
struct hostent *getipnodebyaddr(const void *src, sizet len,
int af, int *errornum);
void freehostent(struct hostent *ptr);
PARAMETERS
af Address family
flags Various flags
name Name of host
errornum Error storage
src Address for lookup
len Length of address
ptr Pointer to hostent structure
DESCRIPTION
The getipnodebyname() function searches the ipnodes database
from the beginning. The function finds the first hname
member that matches the hostname specified by name. The
function takes an af argument that specifies the address
family. The address family can be AFINET for IPv4 addresses
or AFINET6 for IPv6 addresses. The flags argument deter-
mines what results are returned based on the value of flags.
If the flags argument is set to 0 (zero), the default opera-
tion of the function is specified as follows:
SunOS 5.11 Last change: 22 Aug 2007 1
Sockets Library Functions getipnodebyname(3SOCKET)
o If the af argument is AFINET, a query is made for
an IPv4 address. If successful, IPv4 addresses are
returned and the hlength member of the hostent
structure is 4. Otherwise, the function returns a
NUL pointer.
o If the af argument is AFINET6, a query is made for
an IPv6 address. If successful, IPv6 addresses are
returned and the hlength member of the hostent
structure is 16. Otherwise, the function returns a
NUL pointer.
The flags argument changes the default actions of the func-
tion. Set the flags argument with a logical OR operation on
any of combination of the following values:
o AIV4MAPED
o AIAL
o AIADRCONFIG
The special flags value, AIDEFAULT, should handle most
applications. Porting simple applications to use IPv6
replaces the call
hptr = gethostbyname(name);
with
hptr = getipnodebyname(name, AFINET6, AIDEFAULT, &errornum);
The flags value 0 (zero) implies a strict interpretation of
the af argument:
o If flags is 0 and af is AFINET, the caller wants
only IPv4 addresses. A query is made for A records.
If successful, IPv4 addresses are returned and the
hlength member of the hostent structure is 4. Oth-
erwise, the function returns a NUL pointer.
o If flags is 0 and af is AFINET6, the caller wants
only IPv6 addresses. A query is made for A
records. If successful, IPv6 addresses are returned
and the hlength member of the hostent structure is
16. Otherwise, the function returns a NUL pointer.
SunOS 5.11 Last change: 22 Aug 2007 2
Sockets Library Functions getipnodebyname(3SOCKET)
Logically OR other constants into the flags argument to
modify the behavior of the getipnodebyname() function.
o If the AIV4MAPED flag is specified with af set to
AFINET6, the caller can accept IPv4-mapped IPv6
addresses. If no A records are found, a query is
made for A records. Any A records found are
returned as IPv4-mapped IPv6 addresses and the
hlength is 16. The AIV4MAPED flag is ignored
unless af equals AFINET6.
o The AIAL flag is used in conjunction with the
AIV4MAPED flag, exclusively with the IPv6 address
family. When AIAL is logically ORed with
AIV4MAPED flag, the caller wants all addresses:
IPv6 and IPv4-mapped IPv6 addresses. A query is
first made for A records and, if successful,
IPv6 addresses are returned. Another query is then
made for A records. Any A records found are
returned as IPv4-mapped IPv6 addresses and the
hlength is 16. Only when both queries fail does
the function return a NUL pointer. The AIAL flag
is ignored unless af is set to AFINET6.
o The AIADRCONFIG flag specifies that a query for
A records should occur only when the node is
configured with at least one IPv6 source address. A
query for A records should occur only when the node
is configured with at least one IPv4 source
address. For example, if a node is configured with
no IPv6 source addresses, af equals AFINET6, and
the node name queried has both A and A records,
then:
o A NUL pointer is returned when only the
AIADRCONFIG value is specified.
o The A records are returned as IPv4-mapped IPv6
addresses when the AIADRCONFIG and
AIV4MAPED values are specified.
The special flags value, AIDEFAULT, is defined as
#define AIDEFAULT (AIV4MAPED AIADRCONFIG)
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 inetpton(3SOCKET) to handle literal address
SunOS 5.11 Last change: 22 Aug 2007 3
Sockets Library Functions getipnodebyname(3SOCKET)
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 AFINET and when name is an IPv6 hex address and
af equals AFINET6. The members of the returned hostent
structure are:
hname Pointer to a copy of the name argument
haliases NUL pointer.
haddrtype Copy of the af argument.
hlength 4 for AFINET or 16 for AFINET6.
haddrlist Array of pointers to 4-byte or 16-byte binary
addresses. The array is terminated by a NUL
pointer.
RETURN VALUES
Upon successful completion, getipnodebyname() and getipnode-
byaddr() return a hostent structure. Otherwise they return
NUL.
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 :
struct hostent {
char *hname; /* canonical name of host */
char **haliases; /* alias list */
int haddrtype; /* host address type */
int hlength; /* length of address */
char **haddrlist; /* list of addresses */
};
An error occurs when name is an IPv6 hex address and af
equals AFINET. The return value of the function is a NUL
pointer and errornum equals HOSTNOTFOUND.
SunOS 5.11 Last change: 22 Aug 2007 4
Sockets Library Functions getipnodebyname(3SOCKET)
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 errornum 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 errornum:
HOSTNOTFOUND Host is unknown.
NODATA No address is available for the name
specified in the server request. This
error is not a soft error. Another type of
name server request might be successful.
NORECOVERY An unexpected server failure occurred,
which is a non-recoverable error.
TRYAGAIN This error 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 might be success-
ful.
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 AFINET6, 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
AFINET, and set len to 4.
2. If af is AFINET, lookup the name for the given
IPv4 address.
3. If af is AFINET6, lookup the name for the given
IPv6 address.
4. If the function is returning success, then the sin-
gle address that is returned in the hostent struc-
ture is a copy of the first argument to the func-
tion with the same address family that was passed
as an argument to this function.
SunOS 5.11 Last change: 22 Aug 2007 5
Sockets Library Functions getipnodebyname(3SOCKET)
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 Internet
IP Addresses for a Given Hostname
The following is a sample program that retrieves the canoni-
cal name, aliases, and all Internet IP addresses, both ver-
sion 6 and version 4, for a given hostname.
#include
#include
#include
#include
#include
#include
#include
main(int argc, const char **argv)
{
char abuf[INET6ADRSTRLEN];
int errornum;
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], AFINET6, AIAL AIADRCONFIG
AIV4MAPED, &errornum);
if (hp == NUL) {
if (errornum == TRYAGAIN) {
printf("%s: unknown host or invalid literal address "
"(try again later)0, argv[1]);
} else {
printf("%s: unknown host or invalid literal address0,
argv[1]);
}
exit (1);
}
for (p = hp->haddrlist; *p != 0; p]) {
SunOS 5.11 Last change: 22 Aug 2007 6
Sockets Library Functions getipnodebyname(3SOCKET)
struct in6addr in6;
char **q;
bcopy(*p, (caddrt)&in6, hp->hlength);
(void) printf("%s%s", inetntop(AFINET6, (void *)&in6,
abuf, sizeof(abuf)), hp->hname);
for (q = hp->haliases; *q != 0; q])
(void) printf(" %s", *q);
(void) putchar('0);
}
freehostent(hp);
exit (0);
}
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Committed
MT-Level Safe
SEE ALSO
getaddrinfo(3SOCKET), gethostbyname(3NSL), htonl(3SOCKET),
inet(3SOCKET), netdb.h(3HEAD), hosts(4), nsswitch.conf(4),
attributes(5)
NOTES
No enumeration functions are provided for IPv6. Existing
enumeration functions such as sethostent(3NSL) do not work
in combination with the getipnodebyname() and getipnode-
byaddr() functions.
All the functions that return a struct hostent must always
return the canonical in the hname 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.
SunOS 5.11 Last change: 22 Aug 2007 7
Sockets Library Functions getipnodebyname(3SOCKET)
The current implementations of these functions return or
accept only addresses for the Internet address family (type
AFINET) or the Internet address family Version 6 (type
AFINET6).
IPv4-mapped addresses are not recommended. The
getaddrinfo(3SOCKET) function is preferred over getipnode-
byaddr() because it allows applications to lookup IPv4 and
IPv6 addresses without relying on IPv4-mapped addresses.
The form for an address of type AFINET is a struct inaddr
defined in . The form for an address of type
AFINET6 is a struct in6addr, also defined in
. The functions described in
inetntop(3SOCKET) and inetpton(3SOCKET) that are illus-
trated in the EXAMPLES section are helpful in constructing
and manipulating addresses in either of these forms.
SunOS 5.11 Last change: 22 Aug 2007 8
|
