Man Linux: Main Page and Category List

NAME

       ares_gethostbyname - Initiate a host query by name

SYNOPSIS

       #include <ares.h>

       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 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  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 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 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 hostent; the ares library will free it when the
       callback returns.  If the query did not complete successfully,  hostent
       will be NULL.

SEE ALSO

       ares_process(3)

AUTHOR

       Greg Hudson, MIT Information Systems
       Copyright 1998 by the Massachusetts Institute of Technology.

                                 25 July 1998