getipnodebyname(3N)

NAME

getipnodebyname(), getipnodebyaddr() — translation between node name and address

SYNOPSIS

#include <sys/socket.h> 
#include <netdb.h> 

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

struct hostent *getipnodebyaddr( 
                   const void *src, 
                   size_t len, 
                   int af, 
                   int *error_num 
                   ); 

DESCRIPTION

getipnodebyname() - nodename to address translation (forward lookup).

getipnodebyaddr() - address to nodename translation (reverse lookup).

The getipnodebyname(), and getipnodebyaddr() functions both return a pointer to a structure of type hostent, defined as follows in <netdb.h>:

struct hostent { 
    char    *h_name; 
    char    **h_aliases; 
    int     h_addrtype; 
    int     h_length; 
    char    **h_addr_list; 
}; 

#define h_addr  h_addr_list[0] 

The members of this structure are:

h_name: The official name of the host.
h_aliases: A null-terminated array of alternate names for the host.
h_addrtype: The type of address: AF_INET or AF_INET6.
h_length: The length, in bytes, of the address.
h_addr_list: A null-terminated array of network addresses for the host.
h_addr: The first address in h_addr_list; this is for compatibility with previous HP-UX implementations where a struct hostent contains only one network address per host.

Name Service Switch-Based Operation

These host entry library routines internally call the name service switch to access the ipnodes database lookup policy configured in the /etc/nsswitch.conf file (see nsswitch.conf(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve host names and Internet addresses. If addresses are not gathered after contacting all the ipnodes directives, and if the caller has set the address family parameter af to AF_INET or set the parameter flags to AI_V4MAPPED with an address family parameter af of AF_INET6, getipnodebyname()/getipnodebyaddr() uses the hosts directive in the /etc/nsswitch.conf file to resolve the hostname/address. In this case, when the hostname/address resolution fails, the error number returned is that of the error number returned by the hosts directive lookup. The operations of these name services: Domain Name Server and nonserver mode (e.g., files) are listed below.

Domain Name Server Operation

If the local system is configured to use the named name server (see named(1M) and resolver(4)) for name or address resolution, then the functions:

getipnodebyname()
getipnodebyaddr(): Both retrieve host information from the name server. Names are matched without respect to uppercase or lowercase. For example, berkeley.edu, Berkeley.EDU, and BERKELEY.EDU all match the entry for berkeley.edu. When hosts directive is used for hostname/address resolution, a delay may be observed due to an additional lookup using the sources specified for hosts directive.

Nonserver Operation

If the /etc/hosts file is used for name or address resolution, then the function:

getipnodebyaddr(): Sequentially searches from the beginning of the file for Internet addresses matching its src parameter till EOF is encountered.
getipnodebyname(): Sequentially searches from the beginning of the file for host names (among either the official names or the aliases) matching its name parameter till EOF is encountered. Names are matched without respect to uppercase or lowercase, as described above in the name server case.

The return value, struct hostent, must be saved before a subsequent call to the functions gethost*(), getipnodeby*(), getaddrinfo() and getnameinfo().

In a multithreaded application, getipnodebyname() and getipnodebyaddr() use thread-specific storage that is re-used in each call. The return value, struct hostent, should be unique for each thread and should be saved, if desired, before the thread makes the next getipnode*(), gethost*(), getaddrinfo() or getnameinfo() call. The return value must be saved before a subsequent call to the function getipnodebyname() or getipnodebyaddr(), is made because these functions may internally call the gethost*() function which may overwrite the return value, struct hostent.

For enumeration in multithreaded applications, the position within the enumeration is a process-wide property shared by all threads.

NOTES: Currently, only the Internet address format is understood. Hence AF_INET and AF_INET6 alone are valid address families.

Arguments

name

The name argument to the function, getipnodebyname() can be either a node name or a literal address string (i.e., a dotted-decimal IPv4 address or an IPv6 hexadecimal address). This saves applications from having to call inet_pton() to handle literal address strings.

af

The af argument specifies the address family. Currently address families AF_INET and AF_INET6, alone, are supported.

flags

The flags argument specifies the types of addresses that are to be searched for, and the types of addresses that are returned. The flags argument can be a bitwise OR of the following values :

AI_V4MAPPED: Return IPv4-Mapped IPv6 addresses only.
AI_ADDRCONFIG: Return addresses only if the node has at least one of the interfaces configured for that particular address family.
AI_ALL: Return both IPv6 and IPv4 addresses.
AI_DEFAULT: This is defined as AI_V4MAPPED | AI_ADDRCONFIG.

error_num

getipnodebyname() and getipnodebyaddr() return errors to the caller via the error_num pointer passed to these functions. The error value is returned to the caller with appropriate error code, to support thread safe error code returns. The value of error_num can be one of those explained under the heading ERRORS below.

In calls to getipnodebyaddr(), the parameter src must be a pointer to an in_addr or in6_addr structure, an Internet address in network order (see byteorder(3N)) and the header file <netinet/in.h>). The parameter len must be the number of bytes in an Internet address; that is, sizeof (struct in_addr) or sizeof (struct in6_addr).

RETURN VALUE

If successful, getipnodebyname() and getipnodebyaddr() return a pointer to the requested hostent structure.

getipnodebyname() and getipnodebyaddr() return NULL if their host or src parameters, respectively, cannot be found in the database. If /etc/hosts is being used, they return NULL if they are unable to open /etc/hosts.

getipnodebyaddr() returns NULL if either its src or len parameter is invalid. The table below shows the values returned by getipnodebyname() for a few combinations of flags and af arguments.

getipnodebyname() and getipnodebyddr() Usage
flags	Address	Returns
Values	Family
		IPv4 addresses alone are returned.
0	AF_INET	Length of the address returned is 4;
		ie. 'A' records alone are returned.
		NULL is returned if no A records are found.
		IPv6 addresses alone are returned.
0	AF_INET6	Length of the address returned is 16;
		ie. AAAA records alone are returned. NULL
		is returned if no AAAA records are found.
		IPv4-mapped IPv6 address is returned.
AI_V4MAPPED	AF_INET6	If no AAAA records are found then
		'A' records, if found, are returned, as
		IPv4-mapped IPv6 records. Length of the
		address returned is 16. NULL is returned
		if both AAAA and A records are not found.
logical OR		IPv6 and IPv4-mapped IPv6 addresses are
		returned. Length of the addresses returned
AI_ALL		is 16;
\|	AF_INET6	ie AAAA and A (IPv4-mapped IPv6) records
AI_V4MAPPED		are returned.
		IPv4 addresses are returned only if
AI_ADDRCONFIG	AF_INET	at least one IPv4 address is
		configured.
logical OR		If at least one IPv6 address source is
		configured :
AI_ADDRCONFIG	AF_INET6	IPv6 addresses are returned only if
\|		if no IPv6 source addresses are configured,
AI_V4MAPPED		but at least one IPv4 address sources is
		configured :
		IPv4-Mapped IPv6 addresses are returned.

ERRORS

If the name server is being used and getipnodebyname() or getipnodebyaddr() returns a NULL pointer, the pointer error_num contains one of the following values:

HOST_NOT_FOUND: No such host is known.
TRY_AGAIN: This is usually a temporary error. The local server did not receive a response from an authoritative server. A retry at some later time may succeed.
NO_RECOVERY: This is a non-recoverable error.
NO_ADDRESS: The requested name is valid but does not have an IP address; this is not a temporary error. This means another type of request to the name server will result in an answer.

WARNINGS

Programs that use the interfaces described in this manpage cannot be linked statically because the implementations of these functions employ dynamic loading and linking of shared objects at run time.

AUTHOR

gethostent(3N) was developed by Sun Microsystems Inc. getipnodebyname(3N) was developed by Hewlett-Packard.

FILES

/etc/hosts