NAME
ares_gethostbyname - Initiate a host query by name
SYNOPSIS
typedef void (*ares_host_callback)(void *arg, int status,
struct hostent *hostent)
void ares_gethostbyname(ares_channel channel, const char *name,
int family, ares_host_callback callback, void *arg)
DESCRIPTION
The
ares_gethostbyname
function initiates a host query by name on the name service channel
identified by
R channel .
The parameter
name
gives the hostname as a NUL-terminated C string, and
family
gives the desired type of address for the resulting host entry. When
the query is complete or has failed, the ares library will invoke
R callback .
Completion or failure of the query may happen immediately, or may
happen during a later call to
ares_process(3)
or
ares_destroy(3).
The callback argument
arg
is copied from the
ares_gethostbyname
argument
R arg .
The callback argument
status
indicates whether the query succeeded and, if not, how it failed. It
may have any of the following values:
ARES_SUCCESS
The host lookup completed successfully.
ARES_ENOTIMP
The ares library does not know how to find addresses of type
R family .
ARES_EBADNAME
The hostname
name
is composed entirely of numbers and periods, but is not a valid
representation of an Internet address.
ARES_ENOTFOUND
The address
addr
was not found.
ARES_ENOMEM
Memory was exhausted.
ARES_EDESTRUCTION
The name service channel
channel
is being destroyed; the query will not be completed.
On successful completion of the query, the callback argument
hostent
points to a
struct hostent
containing the name of the host returned by the query. The callback
need not and should not attempt to free the memory pointed to by
R hostent ;
the ares library will free it when the callback returns. If the query
did not complete successfully,
hostent
will be
R NULL .
SEE ALSO
AUTHOR
Greg Hudson, MIT Information Systems
Copyright 1998 by the Massachusetts Institute of Technology.
