|
|
getipnodebyname(3)
Contents
|
getipnodebyname - Get a network host entry by name for a
specific address family
#include <netdb.h>
struct hostent *getipnodebyname(
const char *name,
int addr_family,
int flags,
int *error_num );
Standard C Library (libc)
Specifies the official network node name, alias, or
numeric node address (for example, a IPv4 dotted-decimal
address or an IPv6 hexadecimal address). Specifies the
address family. This can be AF_INET for IPv4 addresses or
AF_INET6 for IPv6 addresses. Specifies the type of
addresses for which to search and the types of addresses
that are returned. See the "Nodename-to-Address Processing"
section. Specifies an error return code value if the
function is not successful. See the ERRORS section for a
description of the values.
The use of this routine is deprecated. Use the getaddrinfo(3) routine instead; it is also protocol-independent.
The getipnodebyname() routine is an evolution of the gethostbyname()
routine that enables name lookups in address
families other than AF_INET.
The getipnodebyname() routine returns a pointer to a
structure of type hostent. Its members specify data
obtained from the local /etc/ipnodes file, /etc/hosts
file, or one of the files distributed by DNS/BIND or NIS.
If multiple addresses are found, the h_addr_list field in
the hostent structure contains the addresses. To determine
which file or files to search, and in which order,
the system uses the switches in the /etc/svc.conf file.
The netdb.h header file defines the hostent structure.
If using DNS/BIND, the information is obtained from a name
server specified in the /etc/resolv.conf file. When the
name server is not running, the getipnodebyname() routine
searches the local ipnodes name file for IPv6 and IPv4
addresses and the hosts name file for IPv4 addresses, if
none are found in the ipnodes file.
If the name parameter does not contain a dot "." and you
are using DNS/BIND, the getipnodebyname() routine checks
whether the environment variable HOSTALIASES is set. If
set, it first searches the file named by HOSTALIASES for
an alias matching the name parameter. If HOSTALIASES is
not set, the routine uses the default domain. The alias
file has the following format:
name1 name2
The alias name. This name cannot include dots. The host
name used by DNS/BIND to look up the node information.
The hosts database must be distributed by DNS/BIND.
The getipnodebyname() routine dynamically allocates the
hostent structure. Use the freehostent() routine to free
the allocated memory.
Nodename-to-Address Processing [Toc] [Back]
A following is a list of the flags parameters and how the
processing is affected by the value of the af parameters:
If the af value is AF_INET, the routine searches for A
records. If found, returns IPv4 addresses (h_length=4). If
no A records are found, returns a NULL pointer.
Provides backward compatibility for existing IPv4
applications.
If the af value is AF_INET6, searches for AAAA
records. If found, returns IPv6 records
(h_length=16). If no AAAA records are found,
returns a NULL pointer. If the af value is
AF_INET, this is ignored.
If the af value is AF_INET6, searches for AAAA
records. If found, returns IPv6 records
(h_length=16). If no AAAA records are found,
searches for A records. If found, returns
IPv4-mapped IPv6 addresses (h_length=16). If no
records are found, returns a NULL pointer. If the
af value is AF_INET, this is ignored.
If the af value is AF_INET6, searches for AAAA
records. If found, returns IPv6 addresses
(h_length=16). Then, searches for A records. If
found, returns IPv4-mapped IPv6 addresses
(h_length=16). If no records are found, returns a
NULL pointer.
You can use the flagss 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 list describes how
the AI_ADDRCONFIG flag works by itself. 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 list describes
how AI_DEFAULT directs the search. If the af value is
AF_INET, searches for A records only if an IPv4 source
address is configured on the system. If found, returns
IPv4 addresses (h_length=4). If no A records are found,
returns a NULL pointer.
If the af value is AF_INET6, searches for AAAA
records only if an IPv6 source address is configured
on the system. If found, returns IPv6
addresses (h_length=16). If no AAAA records are
found and if an IPv4 address is configured on the
system, searches for A records. If found, returns
IPv4-mapped IPv6 addresses. If no records are
found, returns a NULL pointer.
Upon successful completion, the getipnodebyname() routine
returns a pointer to a hostent structure. If it reaches
the end of the network hostname database, it returns a
null pointer.
If the getipnodebyname() routine call fails, error_num is
set to one of the following the values: The name you have
used is not an official node name or alias; another type
of name server request may be successful. 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. An unexpected server failure occurred.
This is a nonrecoverable error. A transient error
occurred, for example, the server did not respond. A
retry at some later time may be successful.
For IPv4 applications (backward compatibility), use the
following syntax:
getipnodebyname(address, AF_INET, 0, &error_num);
The Internet network node name database. Each record in
the file occupies a single line and has three fields consisting
of the node address (IPv6 or IPv4), official node
name, and aliases. The Internet network hostname
database. Each record in the file occupies a single line
and has three fields consisting of the host IPv4 address,
official hostname, and aliases. The resolver configuration
file. The database service selection configuration
file.
Functions: endhostent(3), freehostent(3), getaddrinfo(3),
getipnodebyaddr(3), sethostent(3).
Files: hostname(5), resolv.conf(4), svc.conf(4).
Networks: bind_intro(7), nis_intro(7).
getipnodebyname(3)
[ Back ] |
