lib/liblwres/man/lwres_getaddrinfo.3

   1 .\"
   2 .\" Copyright (C) 2000, 2001  Internet Software Consortium.
   3 .\"
   4 .\" Permission to use, copy, modify, and distribute this software for any
   5 .\" purpose with or without fee is hereby granted, provided that the above
   6 .\" copyright notice and this permission notice appear in all copies.
   7 .\"
   8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
   9 .\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
  10 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
  11 .\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
  12 .\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
  13 .\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
  14 .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
  15 .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16 .\"
  17 .TH "LWRES_GETADDRINFO" "3" "Jun 30, 2000" "BIND9" ""
  18 .SH NAME
  19 lwres_getaddrinfo, lwres_freeaddrinfo \- socket address structure to host and service name
  20 .SH SYNOPSIS
  21 \fB#include <lwres/netdb.h>
  22 .sp
  23 .na
  24 int
  25 lwres_getaddrinfo(const char *hostname, const char *servname, const struct addrinfo *hints, struct addrinfo **res);
  26 .ad
  27 .sp
  28 .na
  29 void
  30 lwres_freeaddrinfo(struct addrinfo *ai);
  31 .ad
  32 \fR.PP
  33 If the operating system does not provide a
  34 \fBstruct addrinfo\fR,
  35 the following structure is used:
  36 .sp
  37 .nf
  38 struct  addrinfo {
  39         int             ai_flags;       /* AI_PASSIVE, AI_CANONNAME */
  40         int             ai_family;      /* PF_xxx */
  41         int             ai_socktype;    /* SOCK_xxx */
  42         int             ai_protocol;    /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
  43         size_t          ai_addrlen;     /* length of ai_addr */
  44         char            *ai_canonname;  /* canonical name for hostname */
  45         struct sockaddr *ai_addr;       /* binary address */
  46         struct addrinfo *ai_next;       /* next structure in linked list */
  47 };
  48 .sp
  49 .fi
  50 .SH "DESCRIPTION"
  51 .PP
  52 \fBlwres_getaddrinfo()\fR
  53 is used to get a list of IP addresses and port numbers for host
  54 \fIhostname\fR
  55 and service
  56 \fIservname\fR.
  57 The function is the lightweight resolver's implementation of
  58 \fBgetaddrinfo()\fR
  59 as defined in RFC2133.
  60 \fIhostname\fR
  61 and
  62 \fIservname\fR
  63 are pointers to null-terminated
  64 strings or
  65 \fBNULL\fR.
  66 \fIhostname\fR
  67 is either a host name or a numeric host address string: a dotted decimal
  68 IPv4 address or an IPv6 address.
  69 \fIservname\fR
  70 is either a decimal port number or a service name as listed in
  71 \fI/etc/services\fR.
  72 .PP
  73 \fIhints\fR
  74 is an optional pointer to a
  75 \fBstruct addrinfo\fR.
  76 This structure can be used to provide hints concerning the type of socket
  77 that the caller supports or wishes to use.
  78 The caller can supply the following structure elements in
  79 \fI*hints\fR:
  80 .TP
  81 \fBai_family\fR
  82 The protocol family that should be used.
  83 When
  84 ai_family
  85 is set to
  86 \fBPF_UNSPEC\fR,
  87 it means the caller will accept any protocol family supported by the
  88 operating system.
  89 .TP
  90 \fBai_socktype\fR
  91 denotes the type of socket \(em
  92 \fBSOCK_STREAM\fR,
  93 \fBSOCK_DGRAM\fR
  94 or
  95 \fBSOCK_RAW\fR
  96 \(em that is wanted.
  97 When
  98 ai_socktype
  99 is zero the caller will accept any socket type.
 100 .TP
 101 \fBai_protocol\fR
 102 indicates which transport protocol is wanted: IPPROTO_UDP or
 103 IPPROTO_TCP.
 104 If
 105 ai_protocol
 106 is zero the caller will accept any protocol.
 107 .TP
 108 \fBai_flags\fR
 109 Flag bits.
 110 If the
 111 \fBAI_CANONNAME\fR
 112 bit is set, a successful call to
 113 \fBlwres_getaddrinfo()\fR
 114 will return a a null-terminated string containing the canonical name
 115 of the specified hostname in
 116 ai_canonname
 117 of the first
 118 \fBaddrinfo\fR
 119 structure returned.
 120 Setting the
 121 \fBAI_PASSIVE\fR
 122 bit indicates that the returned socket address structure is intended
 123 for used in a call to
 124 \fBbind\fR(2).
 125 In this case, if the hostname argument is a
 126 \fBNULL\fR
 127 pointer, then the IP address portion of the socket
 128 address structure will be set to
 129 \fBINADDR_ANY\fR
 130 for an IPv4 address or
 131 \fBIN6ADDR_ANY_INIT\fR
 132 for an IPv6 address.
 133
 134 When
 135 ai_flags
 136 does not set the
 137 \fBAI_PASSIVE\fR
 138 bit, the returned socket address structure will be ready
 139 for use in a call to
 140 \fBconnect\fR(2)
 141 for a connection-oriented protocol or
 142 \fBconnect\fR(2),
 143 \fBsendto\fR(2),
 144 or
 145 \fBsendmsg\fR(2)
 146 if a connectionless protocol was chosen.
 147 The IP address portion of the socket address structure will be
 148 set to the loopback address if
 149 \fIhostname\fR
 150 is a
 151 \fBNULL\fR
 152 pointer and
 153 \fBAI_PASSIVE\fR
 154 is not set in
 155 ai_flags.
 156
 157 If
 158 ai_flags
 159 is set to
 160 \fBAI_NUMERICHOST\fR
 161 it indicates that
 162 \fIhostname\fR
 163 should be treated as a numeric string defining an IPv4 or IPv6 address
 164 and no name resolution should be attempted.
 165 .PP
 166 All other elements of the \fBstruct addrinfo\fR passed
 167 via \fIhints\fR must be zero.
 168 .PP
 169 A \fIhints\fR of \fBNULL\fR is treated as if
 170 the caller provided a \fBstruct addrinfo\fR initialized to zero
 171 with ai_familyset to
 172 PF_UNSPEC.
 173 .PP
 174 After a successful call to
 175 \fBlwres_getaddrinfo()\fR,
 176 \fI*res\fR
 177 is a pointer to a linked list of one or more
 178 \fBaddrinfo\fR
 179 structures.
 180 Each
 181 \fBstruct addrinfo\fR
 182 in this list cn be processed by following
 183 the
 184 ai_next
 185 pointer, until a
 186 \fBNULL\fR
 187 pointer is encountered.
 188 The three members
 189 ai_family,
 190 ai_socktype,
 191 and
 192 ai_protocol
 193 in each
 194 returned
 195 \fBaddrinfo\fR
 196 structure contain the corresponding arguments for a call to
 197 \fBsocket\fR(2).
 198 For each
 199 \fBaddrinfo\fR
 200 structure in the list, the
 201 ai_addr
 202 member points to a filled-in socket address structure of length
 203 ai_addrlen.
 204 .PP
 205 All of the information returned by
 206 \fBlwres_getaddrinfo()\fR
 207 is dynamically allocated: the addrinfo structures, and the socket
 208 address structures and canonical host name strings pointed to by the
 209 addrinfostructures.
 210 Memory allocated for the dynamically allocated structures created by
 211 a successful call to
 212 \fBlwres_getaddrinfo()\fR
 213 is released by
 214 \fBlwres_freeaddrinfo()\fR.
 215 \fIai\fR
 216 is a pointer to a
 217 \fBstruct addrinfo\fR
 218 created by a call to
 219 \fBlwres_getaddrinfo()\fR.
 220 .SH "RETURN VALUES"
 221 .PP
 222 \fBlwres_getaddrinfo()\fR
 223 returns zero on success or one of the error codes listed in
 224 \fBgai_strerror\fR(3)
 225 if an error occurs.
 226 If both
 227 \fIhostname\fR
 228 and
 229 \fIservname\fR
 230 are
 231 \fBNULL\fR
 232 \fBlwres_getaddrinfo()\fR
 233 returns
 234 EAI_NONAME.
 235 .SH "SEE ALSO"
 236 .PP
 237 \fBlwres\fR(3),
 238 \fBlwres_getaddrinfo\fR(3),
 239 \fBlwres_freeaddrinfo\fR(3),
 240 \fBlwres_gai_strerror\fR(3),
 241 \fBRFC2133\fR,
 242 \fBgetservbyname\fR(3),
 243 \fBbind\fR(2),
 244 \fBconnect\fR(2),
 245 \fBsendto\fR(2),
 246 \fBsendmsg\fR(2),
 247 \fBsocket\fR(2).