getipnodebyname(3)getipnodebyname(3)NAMEgetipnodebyname - Get a network host entry by name for a specific
address family
SYNOPSIS
#include <netdb.h>
struct hostent *getipnodebyname(
const char *name,
int addr_family,
int flags,
int *error_num );
LIBRARY
Standard C Library (libc)
PARAMETERS
Specifies the official network node name, alias, or numeric node
address (for example, a IPv4 dotted-decimal address or an IPv6 hexadec‐
imal 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.
DESCRIPTION
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 spec‐
ified in the /etc/resolv.conf file. When the name server is not run‐
ning, 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 HOSTAL‐
IASES 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 struc‐
ture. Use the freehostent() routine to free the allocated memory.
Nodename-to-Address Processing
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_ADDRCON‐
FIG 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 sys‐
tem. 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.
RETURN VALUES
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.
ERRORS
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 success‐
ful. 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 nonre‐
coverable error. A transient error occurred, for example, the server
did not respond. A retry at some later time may be successful.
EXAMPLES
For IPv4 applications (backward compatibility), use the following syn‐
tax:
getipnodebyname(address, AF_INET, 0, &error_num);
FILES
The Internet network node name database. Each record in the file occu‐
pies 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 host‐
name, and aliases. The resolver configuration file. The database ser‐
vice selection configuration file.
SEE ALSO
Functions: endhostent(3), freehostent(3), getaddrinfo(3), getipnode‐
byaddr(3), sethostent(3).
Files: hostname(5), resolv.conf(4), svc.conf(4).
Networks: bind_intro(7), nis_intro(7).
getipnodebyname(3)