Index for Section 3

Alphabetical listing for G

Bottom of page

getipnodebyname(3)
NAME
  getipnodebyname - 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
  name
      Specifies the official network node name, alias, or numeric node
      address (for example, a IPv4 dotted-decimal address or an IPv6
      hexadecimal address).

  addr_family
      Specifies the address family.  This can be AF_INET for IPv4 addresses
      or AF_INET6 for IPv6 addresses.

  flags
      Specifies the type of addresses for which to search and the types of
      addresses that are returned.  See the "Nodename-to-Address Processing"
      section.

  error_num
      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 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

  name1
      The alias name.  This name cannot include dots.

  name2
      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:

  0   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.

  AI_V4MAPPED
      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.

  AI_ALL | AI_V4MAPPED
      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.

  AI_ADDRCONFIG
      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.

  AI_DEFAULT
      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.

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:

  [HOST_NOT_FOUND]
      The name you have used is not an official node name or alias; another
      type of name server request may be successful.

  [NO_ADDRESS]
      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.

  [NO_RECOVERY]
      An unexpected server failure occurred.  This is a nonrecoverable error.

  [TRY_AGAIN]
      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 syntax:

       getipnodebyname(address, AF_INET, 0, &error_num);

FILES
  /etc/ipnodes
      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.

  /etc/hosts
      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.

  /etc/resolv.conf
      The resolver configuration file.

  /etc/svc.conf
      The database service selection configuration file.

SEE ALSO
  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).

Index for Section 3

Alphabetical listing for G

Top of page