ares_search.3

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