GETHOSTBYNAME(3) | Library Functions Manual | GETHOSTBYNAME(3) |
gethostbyname
, gethostbyname2
,
gethostbyaddr
, gethostent
,
sethostent
, endhostent
,
herror
, hstrerror
—
#include <netdb.h>
extern 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 each return a pointer to an
object with the following structure describing an internet host.
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:
AF_INET
.In the case of gethostbyname
() and
gethostbyname2
(), the host is specified by name, or
using a string representation of a numeric address. In the case of
gethostbyaddr
(), the host is specified using a
binary representation of an address.
The returned struct hostent structure may contain the result of a simple string to binary conversion, information obtained from the domain name resolver (see resolver(3)), broken-out fields from a line in /etc/hosts, or database entries supplied by the yp(8) system. The order of the lookups is controlled by the ‘hosts’ entry in nsswitch.conf(5).
When using the domain name resolver,
gethostbyname
() and
gethostbyname2
() will search for the named host in
the current domain and its parents unless the name ends in a dot. If the
name contains no dot, and if the environment variable
“HOSTALIASES
” contains the name of an
alias file, the alias file will first be searched for an alias matching the
input name. See hostname(7)
for the domain search procedure and the alias file format.
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
. Currently the af
argument must be specified as AF_INET
or
AF_INET6
, else the function will return
NULL
after having set h_errno
to NETDB_INTERNAL
.
The gethostent
() function reads the next
line of the /etc/hosts file, opening the file if
necessary.
The sethostent
() function may be used to
request the use of a connected TCP socket for queries. If the
stayopen flag is non-zero, this sets the option to
send all queries to the name server using TCP and to retain the connection
after each call to gethostbyname
(),
gethostbyname2
(), or
gethostbyaddr
(). Otherwise, queries are performed
using UDP datagrams.
The endhostent
() function closes the TCP
connection.
The herror
() function writes a message to
the diagnostic output consisting of the string parameter
s, 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 parameter.
gethostbyent
(),
gethostbyname
(),
gethostbyname2
(), and
gethostbyaddr
() is indicated by return of a null
pointer. The external 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
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-4.9.4. IPv6 support was implemented in WIDE
Hydrangea IPv6 protocol stack kit.
gethostbyname
(),
gethostbyname2
(), and
gethostbyaddr
() will read the next line of the file,
re-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
(),
gethostbyaddr
(), or
gethostent
().
The endhostent
() function closes the
file.
The gethostent
() does not currently follow
the search order specified in
nsswitch.conf(5) and
only reads the /etc/hosts file.
August 19, 2013 | NetBSD 9.0 |