source: trunk/athena/lib/ares/ares_search.3 @ 11855

Revision 11855, 4.4 KB checked in by ghudson, 27 years ago (diff)
Documentation for libares, an asynchronous resolver library
Line 
1.\" $Id: ares_search.3,v 1.1 1998-08-13 18:07:35 ghudson Exp $
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
19ares_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 \fIclass\fP, int \fItype\fP, ares_callback \fIcallback\fP,
29.B      void *\fIarg\fP)
30.fi
31.SH DESCRIPTION
32The
33.B ares_search
34function initiates a series of single-question DNS queries on the name
35service channel identified by
36.IR channel ,
37using the channel's search domains as well as a host alias file given
38by the HOSTALIAS environment variable.  The parameter
39.I name
40gives the alias name or the base of the query name as a NUL-terminated
41C string of period-separated labels; if it ends with a period, the
42channel's search domains will not be used.  Periods and backslashes
43within a label must be escaped with a backslash.  The parameters
44.I class
45and
46.I type
47give the class and type of the query using the values defined in
48.BR <arpa/nameser.h> .
49When the query sequence is complete or has failed, the ares library
50will invoke
51.IR callback .
52Completion or failure of the query sequence may happen immediately, or
53may happen during a later call to
54.BR ares_process (3)
55or
56.BR ares_destroy (3).
57.PP
58The callback argument
59.I arg
60is copied from the
61.B ares_search
62argument
63.IR arg .
64The callback argument
65.I status
66indicates whether the query sequence ended with a successful query
67and, if not, how the query sequence failed.  It may have any of the
68following values:
69.TP 19
70.B ARES_SUCCESS
71A query completed successfully.
72.TP 19
73.B ARES_ENODATA
74No query completed successfully; when the query was tried without a
75search domain appended, a response was returned with no answers.
76.TP 19
77.B ARES_EFORMERR
78A query completed but the server claimed that the query was
79malformatted.
80.TP 19
81.B ARES_ESERVFAIL
82No query completed successfully; when the query was tried without a
83search domain appended, the server claimed to have experienced a
84failure.  (This code can only occur if the
85.B ARES_FLAG_NOCHECKRESP
86flag was specified at channel initialization time; otherwise, such
87responses are ignored at the
88.BR ares_send (3)
89level.)
90.TP 19
91.B ARES_ENOTFOUND
92No query completed successfully; when the query was tried without a
93search domain appended, the server reported that the queried-for
94domain name was not found.
95.TP 19
96.B ARES_ENOTIMP
97A query completed but the server does not implement the operation
98requested by the query.  (This code can only occur if the
99.B ARES_FLAG_NOCHECKRESP
100flag was specified at channel initialization time; otherwise, such
101responses are ignored at the
102.BR ares_send (3)
103level.)
104.TP 19
105.B ARES_EREFUSED
106A query completed but the server refused the query.  (This code can
107only occur returned if the
108.B ARES_FLAG_NOCHECKRESP
109flag was specified at channel initialization time; otherwise, such
110responses are ignored at the
111.BR ares_send (3)
112level.)
113.TP 19
114.B ARES_TIMEOUT
115No name servers responded to a query within the timeout period.
116.TP 19
117.B ARES_ECONNREFUSED
118No name servers could be contacted.
119.TP 19
120.B ARES_ENOMEM
121Memory was exhausted.
122.TP 19
123.B ARES_EDESTRUCTION
124The name service channel
125.I channel
126is being destroyed; the query will not be completed.
127.PP
128If a query completed successfully, the callback argument
129.I abuf
130points to a result buffer of length
131.IR alen .
132If the query did not complete successfully,
133.I abuf
134will usually be NULL and
135.I alen
136will usually be 0, but in some cases an unsuccessful query result may
137be placed in
138.IR abuf .
139.SH SEE ALSO
140.BR ares_process (3)
141.SH AUTHOR
142Greg Hudson, MIT Information Systems
143.br
144Copyright 1998 by the Massachusetts Institute of Technology.
Note: See TracBrowser for help on using the repository browser.