Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/man/man3/ares_getaddrinfo.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 1998 by the Massachusetts Institute of Technology.
jpayne@68 3 .\" SPDX-License-Identifier: MIT
jpayne@68 4 .\"
jpayne@68 5 .TH ARES_GETADDRINFO 3 "4 November 2018"
jpayne@68 6 .SH NAME
jpayne@68 7 ares_getaddrinfo \- Initiate a host query by name and service
jpayne@68 8 .SH SYNOPSIS
jpayne@68 9 .nf
jpayne@68 10 #include <ares.h>
jpayne@68 11
jpayne@68 12 typedef void (*ares_addrinfo_callback)(void *\fIarg\fP, int \fIstatus\fP,
jpayne@68 13 int \fItimeouts\fP,
jpayne@68 14 struct ares_addrinfo *\fIresult\fP)
jpayne@68 15
jpayne@68 16 void ares_getaddrinfo(ares_channel_t *\fIchannel\fP, const char *\fIname\fP,
jpayne@68 17 const char* \fIservice\fP,
jpayne@68 18 const struct ares_addrinfo_hints *\fIhints\fP,
jpayne@68 19 ares_addrinfo_callback \fIcallback\fP, void *\fIarg\fP)
jpayne@68 20 .fi
jpayne@68 21 .SH DESCRIPTION
jpayne@68 22 The \fBares_getaddrinfo(3)\fP function initiates a host query by name on the
jpayne@68 23 name service channel identified by
jpayne@68 24 .IR channel .
jpayne@68 25 The
jpayne@68 26 .I name
jpayne@68 27 and
jpayne@68 28 .I service
jpayne@68 29 parameters give the hostname and service as NULL-terminated C strings.
jpayne@68 30 The
jpayne@68 31 .I hints
jpayne@68 32 parameter is an
jpayne@68 33 .BR ares_addrinfo_hints
jpayne@68 34 structure:
jpayne@68 35 .PP
jpayne@68 36 .RS
jpayne@68 37 .EX
jpayne@68 38 struct ares_addrinfo_hints {
jpayne@68 39 int ai_flags;
jpayne@68 40 int ai_family;
jpayne@68 41 int ai_socktype;
jpayne@68 42 int ai_protocol;
jpayne@68 43 };
jpayne@68 44 .EE
jpayne@68 45 .RE
jpayne@68 46 .TP
jpayne@68 47 .I ai_family
jpayne@68 48 Specifies desired address family. AF_UNSPEC means return both AF_INET and AF_INET6.
jpayne@68 49 .TP
jpayne@68 50 .I ai_socktype
jpayne@68 51 Specifies desired socket type, for example SOCK_STREAM or SOCK_DGRAM.
jpayne@68 52 Setting this to 0 means any type.
jpayne@68 53 .TP
jpayne@68 54 .I ai_protocol
jpayne@68 55 Setting this to 0 means any protocol.
jpayne@68 56 .TP
jpayne@68 57 .I ai_flags
jpayne@68 58 Specifies additional options, see below.
jpayne@68 59 .PP
jpayne@68 60 .TP 19
jpayne@68 61 .B ARES_AI_NUMERICSERV
jpayne@68 62 If this option is set
jpayne@68 63 .I service
jpayne@68 64 field will be treated as a numeric value.
jpayne@68 65 .TP 19
jpayne@68 66 .B ARES_AI_CANONNAME
jpayne@68 67 The ares_addrinfo structure will return a canonical names list.
jpayne@68 68 .TP 19
jpayne@68 69 .B ARES_AI_NOSORT
jpayne@68 70 Result addresses will not be sorted and no connections to resolved addresses will be attempted.
jpayne@68 71 .TP 19
jpayne@68 72 .B ARES_AI_ENVHOSTS
jpayne@68 73 Read hosts file path from the environment variable
jpayne@68 74 .I CARES_HOSTS .
jpayne@68 75 .PP
jpayne@68 76 When the query is complete or has failed, the ares library will invoke \fIcallback\fP.
jpayne@68 77 Completion or failure of the query may happen immediately, or may happen
jpayne@68 78 during a later call to \fIares_process(3)\fP, \fIares_destroy(3)\fP or
jpayne@68 79 \fIares_cancel(3)\fP.
jpayne@68 80 .PP
jpayne@68 81 When the associated callback is called, it is called with a channel lock so care
jpayne@68 82 must be taken to ensure any processing is minimal to prevent DNS channel stalls.
jpayne@68 83
jpayne@68 84 The callback may be triggered from a different thread than the one which
jpayne@68 85 called \fIares_getaddrinfo(3)\fP.
jpayne@68 86
jpayne@68 87 For integrators running their own event loops and not using \fBARES_OPT_EVENT_THREAD\fP,
jpayne@68 88 care needs to be taken to ensure any file descriptor lists are updated immediately
jpayne@68 89 within the eventloop when notified.
jpayne@68 90 .PP
jpayne@68 91 The callback argument
jpayne@68 92 .I arg
jpayne@68 93 is copied from the \fBares_getaddrinfo(3)\fP argument
jpayne@68 94 .IR arg .
jpayne@68 95 The callback argument
jpayne@68 96 .I status
jpayne@68 97 indicates whether the query succeeded and, if not, how it failed. It
jpayne@68 98 may have any of the following values:
jpayne@68 99 .TP 19
jpayne@68 100 .B ARES_SUCCESS
jpayne@68 101 The host lookup completed successfully.
jpayne@68 102 .TP 19
jpayne@68 103 .B ARES_ENOTIMP
jpayne@68 104 The ares library does not know how to find addresses of type
jpayne@68 105 .IR family .
jpayne@68 106 .TP 19
jpayne@68 107 .B ARES_ENOTFOUND
jpayne@68 108 The
jpayne@68 109 .I name
jpayne@68 110 was not found.
jpayne@68 111 .TP 19
jpayne@68 112 .B ARES_ENOMEM
jpayne@68 113 Memory was exhausted.
jpayne@68 114 .TP 19
jpayne@68 115 .B ARES_ESERVICE
jpayne@68 116 The textual service name provided could not be dereferenced into a port.
jpayne@68 117 .TP 19
jpayne@68 118 .B ARES_ECANCELLED
jpayne@68 119 The query was cancelled.
jpayne@68 120 .TP 19
jpayne@68 121 .B ARES_EDESTRUCTION
jpayne@68 122 The name service channel
jpayne@68 123 .I channel
jpayne@68 124 is being destroyed; the query will not be completed.
jpayne@68 125 .PP
jpayne@68 126 On successful completion of the query, the callback argument
jpayne@68 127 .I result
jpayne@68 128 points to a
jpayne@68 129 .B struct ares_addrinfo
jpayne@68 130 which contains two linked lists, one with resolved addresses and another with canonical names.
jpayne@68 131 Also included is the official name of the host (analogous to gethostbyname() h_name).
jpayne@68 132 .PP
jpayne@68 133 .RS
jpayne@68 134 .EX
jpayne@68 135 struct ares_addrinfo {
jpayne@68 136 struct ares_addrinfo_cname *cnames;
jpayne@68 137 struct ares_addrinfo_node *nodes;
jpayne@68 138 char *name;
jpayne@68 139 };
jpayne@68 140 .EE
jpayne@68 141 .RE
jpayne@68 142 .PP
jpayne@68 143 .I ares_addrinfo_node
jpayne@68 144 structure is similar to RFC3493 addrinfo, but without canonname and with extra ttl field.
jpayne@68 145 .RS
jpayne@68 146 .PP
jpayne@68 147 .EX
jpayne@68 148 struct ares_addrinfo_node {
jpayne@68 149 int ai_ttl;
jpayne@68 150 int ai_flags;
jpayne@68 151 int ai_family;
jpayne@68 152 int ai_socktype;
jpayne@68 153 int ai_protocol;
jpayne@68 154 ares_socklen_t ai_addrlen;
jpayne@68 155 struct sockaddr *ai_addr;
jpayne@68 156 struct ares_addrinfo_node *ai_next;
jpayne@68 157 };
jpayne@68 158 .EE
jpayne@68 159 .RE
jpayne@68 160 .PP
jpayne@68 161 .I ares_addrinfo_cname
jpayne@68 162 structure is a linked list of CNAME records where
jpayne@68 163 .I ttl
jpayne@68 164 is a time to live
jpayne@68 165 .I alias
jpayne@68 166 is a label of the resource record and
jpayne@68 167 .I name
jpayne@68 168 is a value (canonical name) of the resource record.
jpayne@68 169 See RFC2181 10.1.1. CNAME terminology.
jpayne@68 170 .RS
jpayne@68 171 .PP
jpayne@68 172 .EX
jpayne@68 173 struct ares_addrinfo_cname {
jpayne@68 174 int ttl;
jpayne@68 175 char *alias;
jpayne@68 176 char *name;
jpayne@68 177 struct ares_addrinfo_cname *next;
jpayne@68 178 };
jpayne@68 179 .EE
jpayne@68 180 .RE
jpayne@68 181 .PP
jpayne@68 182 The reserved memory has to be deleted by \fBares_freeaddrinfo(3)\fP.
jpayne@68 183
jpayne@68 184 The result is sorted according to RFC6724 except:
jpayne@68 185 - Rule 3 (Avoid deprecated addresses)
jpayne@68 186 - Rule 4 (Prefer home addresses)
jpayne@68 187 - Rule 7 (Prefer native transport)
jpayne@68 188
jpayne@68 189 Please note that the function will attempt a connection
jpayne@68 190 on each of the resolved addresses as per RFC6724.
jpayne@68 191 .SH AVAILABILITY
jpayne@68 192 This function was added in c-ares 1.16.0, released in March 2020.
jpayne@68 193 .SH SEE ALSO
jpayne@68 194 .BR ares_freeaddrinfo (3)