Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/man/man3/ares_getnameinfo.3 @ 68:5028fdace37b

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