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