ares_getnameinfo.3 (4231B)
1 .\" 2 .\" Copyright 2005 by Dominick Meglio. 3 .\" SPDX-License-Identifier: MIT 4 .\" 5 .TH ARES_GETNAMEINFO 3 "1 May 2009" 6 .SH NAME 7 ares_getnameinfo \- Address-to-nodename translation in protocol-independent manner 8 .SH SYNOPSIS 9 .nf 10 #include <ares.h> 11 12 typedef void (*ares_nameinfo_callback)(void *\fIarg\fP, int \fIstatus\fP, 13 int \fItimeouts\fP, char *\fInode\fP, 14 char *\fIservice\fP) 15 16 void ares_getnameinfo(ares_channel_t *\fIchannel\fP, const struct sockaddr *\fIsa\fP, 17 ares_socklen_t \fIsalen\fP, int \fIflags\fP, 18 ares_nameinfo_callback \fIcallback\fP, void *\fIarg\fP) 19 .fi 20 .SH DESCRIPTION 21 The 22 .B ares_getnameinfo 23 function is defined for protocol-independent address translation. The function 24 is a combination of \fIares_gethostbyaddr(3)\fP and \fIgetservbyport(3)\fP. The function will 25 translate the address either by executing a host query on the name service channel 26 identified by 27 .IR channel 28 or it will attempt to resolve it locally if possible. 29 The parameters 30 .I sa 31 and 32 .I len 33 give the address as a sockaddr structure, and 34 .I flags 35 gives the options that the function will use. Valid flags are listed below: 36 .TP 19 37 .B ARES_NI_NOFQDN 38 Only the nodename portion of the FQDN is returned for local hosts. 39 .TP 19 40 .B ARES_NI_NUMERICHOST 41 The numeric form of the hostname is returned rather than the name. 42 .TP 19 43 .B ARES_NI_NAMEREQD 44 An error is returned if the hostname cannot be found in the DNS. 45 .TP 19 46 .B ARES_NI_NUMERICSERV 47 The numeric form of the service is returned rather than the name. 48 .TP 19 49 .B ARES_NI_TCP 50 The service name is to be looked up for the TCP protocol. 51 .TP 19 52 .B ARES_NI_UDP 53 The service name is to be looked up for the UDP protocol. 54 .TP 19 55 .B ARES_NI_SCTP 56 The service name is to be looked up for the SCTP protocol. 57 .TP 19 58 .B ARES_NI_DCCP 59 The service name is to be looked up for the DCCP protocol. 60 .TP 19 61 .B ARES_NI_NUMERICSCOPE 62 The numeric form of the scope ID is returned rather than the name. 63 .TP 19 64 .B ARES_NI_LOOKUPHOST 65 A hostname lookup is being requested. 66 .TP 19 67 .B ARES_NI_LOOKUPSERVICE 68 A service name lookup is being requested. 69 .PP 70 When the query 71 is complete or has 72 failed, the ares library will invoke \fIcallback\fP. Completion or failure of 73 the query may happen immediately, or may happen during a later call to 74 \fIares_process(3)\fP, \fIares_destroy(3)\fP or \fIares_cancel(3)\fP. 75 .PP 76 When the associated callback is called, it is called with a channel lock so care 77 must be taken to ensure any processing is minimal to prevent DNS channel stalls. 78 79 The callback may be triggered from a different thread than the one which 80 called \fIares_getnameinfo(3)\fP. 81 82 For integrators running their own event loops and not using \fBARES_OPT_EVENT_THREAD\fP, 83 care needs to be taken to ensure any file descriptor lists are updated immediately 84 within the eventloop when notified. 85 .PP 86 The callback argument 87 .I arg 88 is copied from the 89 .B ares_getnameinfo 90 argument 91 .IR arg . 92 The callback argument 93 .I status 94 indicates whether the query succeeded and, if not, how it failed. It 95 may have any of the following values: 96 .TP 19 97 .B ARES_SUCCESS 98 The host lookup completed successfully. 99 .TP 19 100 .B ARES_ENOTIMP 101 The ares library does not know how to look up addresses of type 102 .IR family . 103 .TP 19 104 .B ARES_ENOTFOUND 105 The address 106 .I addr 107 was not found. 108 .TP 19 109 .B ARES_ENOMEM 110 Memory was exhausted. 111 .TP 19 112 .B ARES_ECANCELLED 113 The query was cancelled. 114 .TP 19 115 .B ARES_EDESTRUCTION 116 The name service channel 117 .I channel 118 is being destroyed; the query will not be completed. 119 .TP 19 120 .B ARES_EBADFLAGS 121 The 122 .I flags 123 parameter contains an illegal value. 124 .PP 125 The callback argument 126 .I timeouts 127 reports how many times a query timed out during the execution of the 128 given request. 129 .PP 130 On successful completion of the query, the callback argument 131 .I node 132 contains a string representing the hostname (assuming 133 .B ARES_NI_LOOKUPHOST 134 was specified). Additionally, 135 .I service 136 contains a string representing the service name (assuming 137 .B ARES_NI_LOOKUPSERVICE 138 was specified). 139 If the query did not complete successfully, or one of the values 140 was not requested, 141 .I node 142 or 143 .I service 144 will be 145 .BR NULL . 146 .SH SEE ALSO 147 .BR ares_process (3),