ARES_SEARCH(3)						     Library Functions Manual						    ARES_SEARCH(3)

NAME

       ares_search - Initiate a DNS query with domain search

SYNOPSIS

       #include <ares.h>

       typedef void (*ares_callback)(void *arg, int status,
       int timeouts, unsigned char *abuf, int alen)

       void ares_search(ares_channel channel, const char *name,
	    int dnsclass, int type, ares_callback callback,
       void *arg)

DESCRIPTION

       The  ares_search  function  initiates  a series of single-question DNS queries on the name service channel identified by channel, using the
       channel's search domains as well as a host alias file given by the HOSTALIAS environment variable.  The parameter name gives the alias name
       or  the	base  of  the  query  name as a NUL-terminated C string of period-separated labels; if it ends with a period, the channel's search
       domains will not be used.  Periods and backslashes within a label must be escaped with a backslash.  The parameters dnsclass and type  give
       the  class and type of the query using the values defined in <arpa/nameser.h>.  When the query sequence is complete or has failed, the ares
       library will invoke callback.  Completion or failure of the query sequence 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_search argument arg.  The callback argument status indicates whether the query sequence
       ended with a successful query and, if not, how the query sequence failed.  It may have any of the following values:

       ARES_SUCCESS	  A query completed successfully.

       ARES_ENODATA	  No query completed successfully; when the query was tried without a search domain appended, a response was returned with
			  no answers.

       ARES_EFORMERR	  A query completed but the server claimed that the query was malformatted.

       ARES_ESERVFAIL	  No  query  completed successfully; when the query was tried without a search domain appended, the server claimed to have
			  experienced a failure.  (This code can only occur if the ARES_FLAG_NOCHECKRESP flag was specified at channel initializa-
			  tion time; otherwise, such responses are ignored at the ares_send(3) level.)

       ARES_ENOTFOUND	  No query completed successfully; when the query was tried without a search domain appended, the server reported that the
			  queried-for domain name was not found.

       ARES_ENOTIMP	  A query completed but the server does not implement the operation requested by the query.  (This code can only occur	if
			  the  ARES_FLAG_NOCHECKRESP  flag  was specified at channel initialization time; otherwise, such responses are ignored at
			  the ares_send(3) level.)

       ARES_EREFUSED	  A query completed but the server refused the query.  (This code can only occur  returned  if	the  ARES_FLAG_NOCHECKRESP
			  flag was specified at channel initialization time; otherwise, such responses are ignored at the ares_send(3) level.)

       ARES_TIMEOUT	  No name servers responded to a query within the timeout period.

       ARES_ECONNREFUSED  No name servers could be contacted.

       ARES_ENOMEM	  Memory was exhausted.

       ARES_EDESTRUCTION  The name service channel channel is being destroyed; the query will not be completed.

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

       If a query completed successfully, the callback argument abuf points to a result buffer of length alen.	If the query did not complete suc-
       cessfully, abuf will usually be NULL and alen will usually be 0, but in some cases an unsuccessful query result may be placed in abuf.

SEE ALSO

       ares_process(3)

AUTHOR

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

								   24 July 1998 						    ARES_SEARCH(3)