| blob | 6b1129b79884aac0f565e79473de0c997eb2a304 |
1 .\" $NetBSD: lwres_resutil.3,v 1.5 2014/12/10 04:38:02 christos Exp $
2 .\"
3 .\" Copyright (C) 2004, 2005, 2007, 2014 Internet Systems Consortium, Inc. ("ISC")
4 .\" Copyright (C) 2000, 2001 Internet Software Consortium.
5 .\"
6 .\" Permission to use, copy, modify, and/or distribute this software for any
7 .\" purpose with or without fee is hereby granted, provided that the above
8 .\" copyright notice and this permission notice appear in all copies.
9 .\"
10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
11 .\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
12 .\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
13 .\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
14 .\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
15 .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
16 .\" PERFORMANCE OF THIS SOFTWARE.
17 .\"
18 .\" Id
19 .\"
20 .hy 0
21 .ad l
22 .\" Title: lwres_resutil
23 .\" Author:
24 .\" Generator: DocBook XSL Stylesheets v1.71.1 <http://docbook.sf.net/>
25 .\" Date: June 18, 2007
26 .\" Manual: BIND9
27 .\" Source: BIND9
28 .\"
29 .TH "LWRES_RESUTIL" "3" "June 18, 2007" "BIND9" "BIND9"
30 .\" disable hyphenation
31 .nh
32 .\" disable justification (adjust text to left margin only)
33 .ad l
34 .SH "NAME"
35 lwres_string_parse, lwres_addr_parse, lwres_getaddrsbyname, lwres_getnamebyaddr \- lightweight resolver utility functions
36 .SH "SYNOPSIS"
37 .nf
38 #include <lwres/lwres.h>
39 .fi
40 .HP 34
41 .BI "lwres_result_t lwres_string_parse(lwres_buffer_t\ *" "b" ", char\ **" "c" ", lwres_uint16_t\ *" "len" ");"
42 .HP 32
43 .BI "lwres_result_t lwres_addr_parse(lwres_buffer_t\ *" "b" ", lwres_addr_t\ *" "addr" ");"
44 .HP 36
45 .BI "lwres_result_t lwres_getaddrsbyname(lwres_context_t\ *" "ctx" ", const\ char\ *" "name" ", lwres_uint32_t\ " "addrtypes" ", lwres_gabnresponse_t\ **" "structp" ");"
46 .HP 35
47 .BI "lwres_result_t lwres_getnamebyaddr(lwres_context_t\ *" "ctx" ", lwres_uint32_t\ " "addrtype" ", lwres_uint16_t\ " "addrlen" ", const\ unsigned\ char\ *" "addr" ", lwres_gnbaresponse_t\ **" "structp" ");"
48 .SH "DESCRIPTION"
49 .PP
50 \fBlwres_string_parse()\fR
51 retrieves a DNS\-encoded string starting the current pointer of lightweight resolver buffer
52 \fIb\fR: i.e.
53 \fBb\->current\fR. When the function returns, the address of the first byte of the encoded string is returned via
54 \fI*c\fR
55 and the length of that string is given by
56 \fI*len\fR. The buffer's current pointer is advanced to point at the character following the string length, the encoded string, and the trailing
57 \fBNULL\fR
58 character.
59 .PP
60 \fBlwres_addr_parse()\fR
61 extracts an address from the buffer
62 \fIb\fR. The buffer's current pointer
63 \fBb\->current\fR
64 is presumed to point at an encoded address: the address preceded by a 32\-bit protocol family identifier and a 16\-bit length field. The encoded address is copied to
65 \fBaddr\->address\fR
66 and
67 \fBaddr\->length\fR
68 indicates the size in bytes of the address that was copied.
69 \fBb\->current\fR
70 is advanced to point at the next byte of available data in the buffer following the encoded address.
71 .PP
72 \fBlwres_getaddrsbyname()\fR
73 and
74 \fBlwres_getnamebyaddr()\fR
75 use the
76 \fBlwres_gnbaresponse_t\fR
77 structure defined below:
78 .PP
79 .RS 4
80 .nf
81 typedef struct {
82 lwres_uint32_t flags;
83 lwres_uint16_t naliases;
84 lwres_uint16_t naddrs;
85 char *realname;
86 char **aliases;
87 lwres_uint16_t realnamelen;
88 lwres_uint16_t *aliaslen;
89 lwres_addrlist_t addrs;
90 void *base;
91 size_t baselen;
92 } lwres_gabnresponse_t;
93 .fi
94 .RE
95 .PP
96 The contents of this structure are not manipulated directly but they are controlled through the
97 \fBlwres_gabn\fR(3)
98 functions.
99 .PP
100 The lightweight resolver uses
101 \fBlwres_getaddrsbyname()\fR
102 to perform forward lookups. Hostname
103 \fIname\fR
104 is looked up using the resolver context
105 \fIctx\fR
106 for memory allocation.
107 \fIaddrtypes\fR
108 is a bitmask indicating which type of addresses are to be looked up. Current values for this bitmask are
109 \fBLWRES_ADDRTYPE_V4\fR
110 for IPv4 addresses and
111 \fBLWRES_ADDRTYPE_V6\fR
112 for IPv6 addresses. Results of the lookup are returned in
113 \fI*structp\fR.
114 .PP
115 \fBlwres_getnamebyaddr()\fR
116 performs reverse lookups. Resolver context
117 \fIctx\fR
118 is used for memory allocation. The address type is indicated by
119 \fIaddrtype\fR:
120 \fBLWRES_ADDRTYPE_V4\fR
121 or
122 \fBLWRES_ADDRTYPE_V6\fR. The address to be looked up is given by
123 \fIaddr\fR
124 and its length is
125 \fIaddrlen\fR
126 bytes. The result of the function call is made available through
127 \fI*structp\fR.
128 .SH "RETURN VALUES"
129 .PP
130 Successful calls to
131 \fBlwres_string_parse()\fR
132 and
133 \fBlwres_addr_parse()\fR
134 return
135 \fBLWRES_R_SUCCESS.\fR
136 Both functions return
137 \fBLWRES_R_FAILURE\fR
138 if the buffer is corrupt or
139 \fBLWRES_R_UNEXPECTEDEND\fR
140 if the buffer has less space than expected for the components of the encoded string or address.
141 .PP
142 \fBlwres_getaddrsbyname()\fR
143 returns
144 \fBLWRES_R_SUCCESS\fR
145 on success and it returns
146 \fBLWRES_R_NOTFOUND\fR
147 if the hostname
148 \fIname\fR
149 could not be found.
150 .PP
151 \fBLWRES_R_SUCCESS\fR
152 is returned by a successful call to
153 \fBlwres_getnamebyaddr()\fR.
154 .PP
155 Both
156 \fBlwres_getaddrsbyname()\fR
157 and
158 \fBlwres_getnamebyaddr()\fR
159 return
160 \fBLWRES_R_NOMEMORY\fR
161 when memory allocation requests fail and
162 \fBLWRES_R_UNEXPECTEDEND\fR
163 if the buffers used for sending queries and receiving replies are too small.
164 .SH "SEE ALSO"
165 .PP
166 \fBlwres_buffer\fR(3),
167 \fBlwres_gabn\fR(3).
168 .SH "COPYRIGHT"
169 Copyright \(co 2004, 2005, 2007, 2014 Internet Systems Consortium, Inc. ("ISC")
170 .br
171 Copyright \(co 2000, 2001 Internet Software Consortium.
172 .br