/[resiprocate]/main/contrib/ares/ares_search.3
ViewVC logotype

Contents of /main/contrib/ares/ares_search.3

Parent Directory Parent Directory | Revision Log Revision Log


Revision 5295 - (show annotations) (download)
Mon Aug 22 00:30:05 2005 UTC (14 years, 2 months ago) by jason
File size: 4482 byte(s)
merged 5270:HEAD from b-directory-reorg
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 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_EDESTRUCTION
123 The name service channel
124 .I channel
125 is being destroyed; the query will not be completed.
126 .PP
127 If a query completed successfully, the callback argument
128 .I abuf
129 points to a result buffer of length
130 .IR alen .
131 If the query did not complete successfully,
132 .I abuf
133 will usually be NULL and
134 .I alen
135 will usually be 0, but in some cases an unsuccessful query result may
136 be placed in
137 .IR abuf .
138 .SH SEE ALSO
139 .BR ares_process (3)
140 .SH AUTHOR
141 Greg Hudson, MIT Information Systems
142 .br
143 Copyright 1998 by the Massachusetts Institute of Technology.

webmaster AT resiprocate DOT org
ViewVC Help
Powered by ViewVC 1.1.27