GETHOSTBYNAME(3) | Library Functions Manual | GETHOSTBYNAME(3) |
gethostbyname
,
gethostbyname2
,
gethostbyaddr
, gethostent
,
sethostent
, endhostent
,
herror
, hstrerror
—
get network host entry
Standard C Library (libc, -lc)
#include
<netdb.h>
int h_errno;
struct hostent *
gethostbyname
(const
char *name);
struct hostent *
gethostbyname2
(const
char *name, int
af);
struct hostent *
gethostbyaddr
(const
void *addr, socklen_t
len, int type);
struct hostent *
gethostent
(void);
void
sethostent
(int
stayopen);
void
endhostent
(void);
void
herror
(const
char *string);
const char *
hstrerror
(int
err);
gethostbyname
(),
gethostbyname2
(), and
gethostbyaddr
()
functions.The
gethostbyname
(),
gethostbyname2
() and
gethostbyaddr
()
functions each return a pointer to an object with the following structure
describing an internet host referenced by name or by address,
respectively.
The name argument
passed to
gethostbyname
()
or gethostbyname2
() should point to a
NUL
-terminated hostname. The
addr argument passed to
gethostbyaddr
()
should point to an address which is len bytes long, in
binary form (i.e., not an IP address in human readable ASCII form). The
type argument specifies the address family (e.g.
AF_INET
, AF_INET6
, etc.) of
this address.
The structure returned contains information obtained from mDNSResponder(8), including records in /etc/hosts.
struct hostent { char *h_name; /* official name of host */ char **h_aliases; /* alias list */ int h_addrtype; /* host address type */ int h_length; /* length of address */ char **h_addr_list; /* list of addresses from name server */ }; #define h_addr h_addr_list[0] /* address, for backward compatibility */
The members of this structure are:
NULL
-terminated array of alternate names for the
host.AF_INET
.NULL
-terminated array of network addresses for
the host. Host addresses are returned in network byte order.When using the nameserver,
gethostbyname
()
and gethostbyname2
() will search for the named host
in the current domain and its parents unless the name ends in a dot.
The
gethostbyname2
()
function is an evolution of gethostbyname
() which is
intended to allow lookups in address families other than
AF_INET
, for example
AF_INET6
.
The
herror
()
function writes a message to the diagnostic output consisting of the string
argument string, the constant string
":
", and a message corresponding
to the value of h_errno.
The
hstrerror
()
function returns a string which is the message text corresponding to the
value of the err argument.
Historically, passing a host's own hostname
to
gethostbyname
()
or gethostbyname2
() has been a popular technique for
determining that host's IP address(es), but this is fragile, and doesn't
work reliably in all cases. The appropriate way for software to discover the
IP address(es) of the host it is running on is to use
getifaddrs(3).
Print out the hostname associated with a specific IP address:
const char *ipstr = "127.0.0.1"; struct in_addr ip; struct hostent *hp; if (!inet_aton(ipstr, &ip)) errx(1, "can't parse IP address %s", ipstr); if ((hp = gethostbyaddr((const void *)&ip, sizeof ip, AF_INET)) == NULL) errx(1, "no name associated with %s", ipstr); printf("name associated with %s is %s\n", ipstr, hp->h_name);
Error return status from gethostbyname
(),
gethostbyname2
() and
gethostbyaddr
() is indicated by return of a
NULL
pointer. The integer
h_errno may then be checked to see whether this is a
temporary failure or an invalid or unknown host. The routine
herror
() can be used to print an error message
describing the failure. If its argument string is
non-NULL
, it is printed, followed by a colon and a
space. The error message is printed with a trailing newline.
The variable h_errno can have the following values:
HOST_NOT_FOUND
TRY_AGAIN
NO_RECOVERY
NO_DATA
getaddrinfo(3), getnameinfo(3), inet_aton(3), resolver(3), hosts(5), hostname(7), mDNSResponder(8)
The
gethostent
()
function is defined, and sethostent
() and
endhostent
() are redefined, when
Standard C Library (libc, -lc) is built to
use only the routines to lookup in /etc/hosts and
not the name server.
The
gethostent
()
function reads the next line of /etc/hosts, opening
the file if necessary.
The
sethostent
()
function opens and/or rewinds the file /etc/hosts.
If the stayopen argument is non-zero, the file will
not be closed after each call to gethostbyname
(),
gethostbyname2
() or
gethostbyaddr
().
The
endhostent
()
function closes the file.
The herror
() function appeared in
4.3BSD. The endhostent
(),
gethostbyaddr
(),
gethostbyname
(),
gethostent
(), and
sethostent
() functions appeared in
4.2BSD. The gethostbyname2
()
function first appeared in BIND version 4.9.4.
These functions use a thread-specific data storage; if the data is needed for future use, it should be copied before any subsequent calls overwrite it.
Though these functions are thread-safe, still it is recommended to use the getaddrinfo(3) family of functions, instead.
Only the Internet address format is currently understood.
May 12, 2006 | macOS 14.6 |