ares_gethostbyname(3)

ARES_GETHOSTBYNAME(3)  C LIBRARY FUNCTIONS  ARES_GETHOSTBYNAME(3)

NAME

     ares_gethostbyname - Initiate a host query by name

SYNOPSIS

     #include <ares.h>

     typedef void (*ares_host_callback)(void *arg, int status,
          int timeouts, 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  hap-
     pen  during a later call to ares_process(3), ares_destroy(3)
     or ares_cancel(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_ECANCELLED    The query was cancelled.

     ARES_EDESTRUCTION  The name service channel channel is being
                        destroyed;  the  query  will  not be com-
                        pleted.

     The callback argument timeouts  reports  how  many  times  a
     query timed out during the execution of the given request.

     On successful completion of the query, the callback argument
     hostent  points  to  a struct hostent containing the name of

                    Last change: 25 July 1998                   1

ARES_GETHOSTBYNAME(3)  C LIBRARY FUNCTIONS  ARES_GETHOSTBYNAME(3)

     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), ares_gethostbyaddr(3)

AUTHOR

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

                    Last change: 25 July 1998                   2