|
jpayne@68
|
1 .\"
|
|
jpayne@68
|
2 .\" Copyright 1998 by the Massachusetts Institute of Technology.
|
|
jpayne@68
|
3 .\" SPDX-License-Identifier: MIT
|
|
jpayne@68
|
4 .\"
|
|
jpayne@68
|
5 .TH ARES_GETHOSTBYADDR 3 "24 July 1998"
|
|
jpayne@68
|
6 .SH NAME
|
|
jpayne@68
|
7 ares_gethostbyaddr \- Initiate a host query by address
|
|
jpayne@68
|
8 .SH SYNOPSIS
|
|
jpayne@68
|
9 .nf
|
|
jpayne@68
|
10 #include <ares.h>
|
|
jpayne@68
|
11
|
|
jpayne@68
|
12 typedef void (*ares_host_callback)(void *\fIarg\fP, int \fIstatus\fP,
|
|
jpayne@68
|
13 int \fItimeouts\fP,
|
|
jpayne@68
|
14 struct hostent *\fIhostent\fP)
|
|
jpayne@68
|
15
|
|
jpayne@68
|
16 void ares_gethostbyaddr(ares_channel_t *\fIchannel\fP, const void *\fIaddr\fP,
|
|
jpayne@68
|
17 int \fIaddrlen\fP, int \fIfamily\fP,
|
|
jpayne@68
|
18 ares_host_callback \fIcallback\fP, void *\fIarg\fP)
|
|
jpayne@68
|
19 .fi
|
|
jpayne@68
|
20 .SH DESCRIPTION
|
|
jpayne@68
|
21 The
|
|
jpayne@68
|
22 .B ares_gethostbyaddr
|
|
jpayne@68
|
23 function initiates a host query by address on the name service channel
|
|
jpayne@68
|
24 identified by
|
|
jpayne@68
|
25 .IR channel .
|
|
jpayne@68
|
26 The parameters
|
|
jpayne@68
|
27 .I addr
|
|
jpayne@68
|
28 and
|
|
jpayne@68
|
29 .I addrlen
|
|
jpayne@68
|
30 give the address as a series of bytes, and
|
|
jpayne@68
|
31 .I family
|
|
jpayne@68
|
32 gives the type of address. When the query is complete or has failed, the ares
|
|
jpayne@68
|
33 library will invoke \fIcallback\fP. Completion or failure of the query may
|
|
jpayne@68
|
34 happen immediately, or may happen during a later call to
|
|
jpayne@68
|
35 \fIares_process(3)\fP, \fIares_destroy(3)\fP or \fIares_cancel(3)\fP.
|
|
jpayne@68
|
36 .PP
|
|
jpayne@68
|
37 The callback argument
|
|
jpayne@68
|
38 .I arg
|
|
jpayne@68
|
39 is copied from the
|
|
jpayne@68
|
40 .B ares_gethostbyaddr
|
|
jpayne@68
|
41 argument
|
|
jpayne@68
|
42 .IR arg .
|
|
jpayne@68
|
43 The callback argument
|
|
jpayne@68
|
44 .I status
|
|
jpayne@68
|
45 indicates whether the query succeeded and, if not, how it failed. It
|
|
jpayne@68
|
46 may have any of the following values:
|
|
jpayne@68
|
47 .TP 19
|
|
jpayne@68
|
48 .B ARES_SUCCESS
|
|
jpayne@68
|
49 The host lookup completed successfully.
|
|
jpayne@68
|
50 .TP 19
|
|
jpayne@68
|
51 .B ARES_ENOTIMP
|
|
jpayne@68
|
52 The ares library does not know how to look up addresses of type
|
|
jpayne@68
|
53 .IR family .
|
|
jpayne@68
|
54 .TP 19
|
|
jpayne@68
|
55 .B ARES_ENOTFOUND
|
|
jpayne@68
|
56 The address
|
|
jpayne@68
|
57 .I addr
|
|
jpayne@68
|
58 was not found.
|
|
jpayne@68
|
59 .TP 19
|
|
jpayne@68
|
60 .B ARES_ENOMEM
|
|
jpayne@68
|
61 Memory was exhausted.
|
|
jpayne@68
|
62 .TP 19
|
|
jpayne@68
|
63 .B ARES_ECANCELLED
|
|
jpayne@68
|
64 The query was cancelled.
|
|
jpayne@68
|
65 .TP 19
|
|
jpayne@68
|
66 .B ARES_EDESTRUCTION
|
|
jpayne@68
|
67 The name service channel
|
|
jpayne@68
|
68 .I channel
|
|
jpayne@68
|
69 is being destroyed; the query will not be completed.
|
|
jpayne@68
|
70 .PP
|
|
jpayne@68
|
71 The callback argument
|
|
jpayne@68
|
72 .I timeouts
|
|
jpayne@68
|
73 reports how many times a query timed out during the execution of the
|
|
jpayne@68
|
74 given request.
|
|
jpayne@68
|
75 .PP
|
|
jpayne@68
|
76 On successful completion of the query, the callback argument
|
|
jpayne@68
|
77 .I hostent
|
|
jpayne@68
|
78 points to a
|
|
jpayne@68
|
79 .B struct hostent
|
|
jpayne@68
|
80 containing the name of the host returned by the query. The callback
|
|
jpayne@68
|
81 need not and should not attempt to free the memory pointed to by
|
|
jpayne@68
|
82 .IR hostent ;
|
|
jpayne@68
|
83 the ares library will free it when the callback returns. If the query
|
|
jpayne@68
|
84 did not complete successfully,
|
|
jpayne@68
|
85 .I hostent
|
|
jpayne@68
|
86 will be
|
|
jpayne@68
|
87 .BR NULL .
|
|
jpayne@68
|
88 .PP
|
|
jpayne@68
|
89 When the associated callback is called, it is called with a channel lock so care
|
|
jpayne@68
|
90 must be taken to ensure any processing is minimal to prevent DNS channel stalls.
|
|
jpayne@68
|
91
|
|
jpayne@68
|
92 The callback may be triggered from a different thread than the one which
|
|
jpayne@68
|
93 called \fIares_gethostbyaddr(3)\fP.
|
|
jpayne@68
|
94
|
|
jpayne@68
|
95 For integrators running their own event loops and not using \fBARES_OPT_EVENT_THREAD\fP,
|
|
jpayne@68
|
96 care needs to be taken to ensure any file descriptor lists are updated immediately
|
|
jpayne@68
|
97 within the eventloop when notified.
|
|
jpayne@68
|
98 .SH SEE ALSO
|
|
jpayne@68
|
99 .BR ares_process (3),
|
|
jpayne@68
|
100 .BR ares_gethostbyname (3)
|
