getipnodebyname(3)					     Library Functions Manual						getipnodebyname(3)

NAME

       getipnodebyname - Get a network host entry by name for a specific address family

LIBRARY

       Standard C Library (libc.so, libc.a)

SYNOPSIS

       #include <netdb.h>

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

PARAMETERS

       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.

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/ipn-
       odes 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 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 structure.  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 flags 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 flags 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 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 AAA 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.

EXAMPLES

       For IPv4 applications (backward compatibility), use the following syntax: getipnodebyname(address, AF_INET, 0, &error_num);

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 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 non-
       recoverable error.  A transient error occurred, for example, the server did not respond.  A retry at some later time may be successful.

FILES

       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 sin-
       gle 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.

RELATED INFORMATION

       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).  delim off

																getipnodebyname(3)