ares_search.3

   1 .\"
   2 .\" Copyright 1998 by the Massachusetts Institute of Technology.
   3 .\"
   4 .\" Permission to use, copy, modify, and distribute this
   5 .\" software and its documentation for any purpose and without
   6 .\" fee is hereby granted, provided that the above copyright
   7 .\" notice appear in all copies and that both that copyright
   8 .\" notice and this permission notice appear in supporting
   9 .\" documentation, and that the name of M.I.T. not be used in
  10 .\" advertising or publicity pertaining to distribution of the
  11 .\" software without specific, written prior permission.
  12 .\" M.I.T. makes no representations about the suitability of
  13 .\" this software for any purpose.  It is provided "as is"
  14 .\" without express or implied warranty.
  15 .\"
  16 .TH ARES_SEARCH 3 "24 July 1998"
  17 .SH NAME
  18 ares_search \- Initiate a DNS query with domain search
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <ares.h>
  22 .PP
  23 .B typedef void (*ares_callback)(void *\fIarg\fP, int \fIstatus\fP,
  24 .B      int \fItimeouts\fP, unsigned char *\fIabuf\fP, int \fIalen\fP)
  25 .PP
  26 .B void ares_search(ares_channel \fIchannel\fP, const char *\fIname\fP,
  27 .B      int \fIdnsclass\fP, int \fItype\fP, ares_callback \fIcallback\fP,
  28 .B      void *\fIarg\fP)
  29 .fi
  30 .SH DESCRIPTION
  31 The
  32 .B ares_search
  33 function initiates a series of single-question DNS queries on the name
  34 service channel identified by
  35 .IR channel ,
  36 using the channel's search domains as well as a host alias file given
  37 by the HOSTALIAS environment variable.  The parameter
  38 .I name
  39 gives the alias name or the base of the query name as a NUL-terminated
  40 C string of period-separated labels; if it ends with a period, the
  41 channel's search domains will not be used.  Periods and backslashes
  42 within a label must be escaped with a backslash.  The parameters
  43 .I dnsclass
  44 and
  45 .I type
  46 give the class and type of the query using the values defined in
  47 .BR <arpa/nameser.h> .
  48 When the query sequence is complete or has failed, the ares library
  49 will invoke
  50 .IR callback .
  51 Completion or failure of the query sequence may happen immediately, or
  52 may happen during a later call to
  53 .BR ares_process (3)
  54 or
  55 .BR ares_destroy (3).
  56 .PP
  57 The callback argument
  58 .I arg
  59 is copied from the
  60 .B ares_search
  61 argument
  62 .IR arg .
  63 The callback argument
  64 .I status
  65 indicates whether the query sequence ended with a successful query
  66 and, if not, how the query sequence failed.  It may have any of the
  67 following values:
  68 .TP 19
  69 .B ARES_SUCCESS
  70 A query completed successfully.
  71 .TP 19
  72 .B ARES_ENODATA
  73 No query completed successfully; when the query was tried without a
  74 search domain appended, a response was returned with no answers.
  75 .TP 19
  76 .B ARES_EFORMERR
  77 A query completed but the server claimed that the query was
  78 malformatted.
  79 .TP 19
  80 .B ARES_ESERVFAIL
  81 No query completed successfully; when the query was tried without a
  82 search domain appended, the server claimed to have experienced a
  83 failure.  (This code can only occur if the
  84 .B ARES_FLAG_NOCHECKRESP
  85 flag was specified at channel initialization time; otherwise, such
  86 responses are ignored at the
  87 .BR ares_send (3)
  88 level.)
  89 .TP 19
  90 .B ARES_ENOTFOUND
  91 No query completed successfully; when the query was tried without a
  92 search domain appended, the server reported that the queried-for
  93 domain name was not found.
  94 .TP 19
  95 .B ARES_ENOTIMP
  96 A query completed but the server does not implement the operation
  97 requested by the query.  (This code can only occur if the
  98 .B ARES_FLAG_NOCHECKRESP
  99 flag was specified at channel initialization time; otherwise, such
 100 responses are ignored at the
 101 .BR ares_send (3)
 102 level.)
 103 .TP 19
 104 .B ARES_EREFUSED
 105 A query completed but the server refused the query.  (This code can
 106 only occur returned if the
 107 .B ARES_FLAG_NOCHECKRESP
 108 flag was specified at channel initialization time; otherwise, such
 109 responses are ignored at the
 110 .BR ares_send (3)
 111 level.)
 112 .TP 19
 113 .B ARES_TIMEOUT
 114 No name servers responded to a query within the timeout period.
 115 .TP 19
 116 .B ARES_ECONNREFUSED
 117 No name servers could be contacted.
 118 .TP 19
 119 .B ARES_ENOMEM
 120 Memory was exhausted.
 121 .TP 19
 122 .B ARES_ECANCELLED
 123 The query was cancelled.
 124 .TP 19
 125 .B ARES_EDESTRUCTION
 126 The name service channel
 127 .I channel
 128 is being destroyed; the query will not be completed.
 129 .PP
 130 The callback argument
 131 .I timeouts
 132 reports how many times a query timed out during the execution of the
 133 given request.
 134 .PP
 135 If a query completed successfully, the callback argument
 136 .I abuf
 137 points to a result buffer of length
 138 .IR alen .
 139 If the query did not complete successfully,
 140 .I abuf
 141 will usually be NULL and
 142 .I alen
 143 will usually be 0, but in some cases an unsuccessful query result may
 144 be placed in
 145 .IR abuf .
 146 .SH SEE ALSO
 147 .BR ares_process (3)
 148 .SH AUTHOR
 149 Greg Hudson, MIT Information Systems
 150 .br
 151 Copyright 1998 by the Massachusetts Institute of Technology.