]>
Commit | Line | Data |
---|---|---|
997358a6 MW |
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_GETIPNODE" "3" "Jun 30, 2000" "BIND9" "" | |
18 | .SH NAME | |
19 | lwres_getipnodebyname, lwres_getipnodebyaddr, lwres_freehostent \- lightweight resolver nodename / address translation API | |
20 | .SH SYNOPSIS | |
21 | \fB#include <lwres/netdb.h> | |
22 | .sp | |
23 | .na | |
24 | struct hostent * | |
25 | lwres_getipnodebyname(const char *name, int af, int flags, int *error_num); | |
26 | .ad | |
27 | .sp | |
28 | .na | |
29 | struct hostent * | |
30 | lwres_getipnodebyaddr(const void *src, size_t len, int af, int *error_num); | |
31 | .ad | |
32 | .sp | |
33 | .na | |
34 | void | |
35 | lwres_freehostent(struct hostent *he); | |
36 | .ad | |
37 | \fR.SH "DESCRIPTION" | |
38 | .PP | |
39 | These functions perform thread safe, protocol independent | |
40 | nodename-to-address and address-to-nodename | |
41 | translation as defined in RFC2553. | |
42 | .PP | |
43 | They use a | |
44 | \fBstruct hostent\fR | |
45 | which is defined in | |
46 | \fInamedb.h\fR: | |
47 | .sp | |
48 | .nf | |
49 | struct hostent { | |
50 | char *h_name; /* official name of host */ | |
51 | char **h_aliases; /* alias list */ | |
52 | int h_addrtype; /* host address type */ | |
53 | int h_length; /* length of address */ | |
54 | char **h_addr_list; /* list of addresses from name server */ | |
55 | }; | |
56 | #define h_addr h_addr_list[0] /* address, for backward compatibility */ | |
57 | .sp | |
58 | .fi | |
59 | .PP | |
60 | The members of this structure are: | |
61 | .TP | |
62 | \fBh_name\fR | |
63 | The official (canonical) name of the host. | |
64 | .TP | |
65 | \fBh_aliases\fR | |
66 | A NULL-terminated array of alternate names (nicknames) for the host. | |
67 | .TP | |
68 | \fBh_addrtype\fR | |
69 | The type of address being returned - usually | |
70 | \fBPF_INET\fR | |
71 | or | |
72 | \fBPF_INET6\fR. | |
73 | .TP | |
74 | \fBh_length\fR | |
75 | The length of the address in bytes. | |
76 | .TP | |
77 | \fBh_addr_list\fR | |
78 | A | |
79 | \fBNULL\fR | |
80 | terminated array of network addresses for the host. | |
81 | Host addresses are returned in network byte order. | |
82 | .PP | |
83 | \fBlwres_getipnodebyname()\fR | |
84 | looks up addresses of protocol family | |
85 | \fIaf\fR | |
86 | for the hostname | |
87 | \fIname\fR. | |
88 | The | |
89 | \fIflags\fR | |
90 | parameter contains ORed flag bits to | |
91 | specify the types of addresses that are searched | |
92 | for, and the types of addresses that are returned. | |
93 | The flag bits are: | |
94 | .TP | |
95 | \fBAI_V4MAPPED\fR | |
96 | This is used with an | |
97 | \fIaf\fR | |
98 | of AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped | |
99 | IPv6 addresses. | |
100 | .TP | |
101 | \fBAI_ALL\fR | |
102 | This is used with an | |
103 | \fIaf\fR | |
104 | of AF_INET6, and causes all known addresses (IPv6 and IPv4) to be returned. | |
105 | If AI_V4MAPPED is also set, the IPv4 addresses are return as mapped | |
106 | IPv6 addresses. | |
107 | .TP | |
108 | \fBAI_ADDRCONFIG\fR | |
109 | Only return an IPv6 or IPv4 address if here is an active network | |
110 | interface of that type. This is not currently implemented | |
111 | in the BIND 9 lightweight resolver, and the flag is ignored. | |
112 | .TP | |
113 | \fBAI_DEFAULT\fR | |
114 | This default sets the | |
115 | AI_V4MAPPED | |
116 | and | |
117 | AI_ADDRCONFIG | |
118 | flag bits. | |
119 | .PP | |
120 | \fBlwres_getipnodebyaddr()\fR | |
121 | performs a reverse lookup | |
122 | of address | |
123 | \fIsrc\fR | |
124 | which is | |
125 | \fIlen\fR | |
126 | bytes long. | |
127 | \fIaf\fR | |
128 | denotes the protocol family, typically | |
129 | \fBPF_INET\fR | |
130 | or | |
131 | \fBPF_INET6\fR. | |
132 | .PP | |
133 | \fBlwres_freehostent()\fR | |
134 | releases all the memory associated with | |
135 | the | |
136 | \fBstruct hostent\fR | |
137 | pointer | |
138 | \fIhe\fR. | |
139 | Any memory allocated for the | |
140 | h_name, | |
141 | h_addr_list | |
142 | and | |
143 | h_aliases | |
144 | is freed, as is the memory for the | |
145 | \fBhostent\fR | |
146 | structure itself. | |
147 | .SH "RETURN VALUES" | |
148 | .PP | |
149 | If an error occurs, | |
150 | \fBlwres_getipnodebyname()\fR | |
151 | and | |
152 | \fBlwres_getipnodebyaddr()\fR | |
153 | set | |
154 | \fI*error_num\fR | |
155 | to an approriate error code and the function returns a | |
156 | \fBNULL\fR | |
157 | pointer. | |
158 | The error codes and their meanings are defined in | |
159 | \fI<lwres/netdb.h>\fR: | |
160 | .TP | |
161 | \fBHOST_NOT_FOUND\fR | |
162 | No such host is known. | |
163 | .TP | |
164 | \fBNO_ADDRESS\fR | |
165 | The server recognised the request and the name but no address is | |
166 | available. Another type of request to the name server for the | |
167 | domain might return an answer. | |
168 | .TP | |
169 | \fBTRY_AGAIN\fR | |
170 | A temporary and possibly transient error occurred, such as a | |
171 | failure of a server to respond. The request may succeed if | |
172 | retried. | |
173 | .TP | |
174 | \fBNO_RECOVERY\fR | |
175 | An unexpected failure occurred, and retrying the request | |
176 | is pointless. | |
177 | .PP | |
178 | \fBlwres_hstrerror\fR(3) | |
179 | translates these error codes to suitable error messages. | |
180 | .SH "SEE ALSO" | |
181 | .PP | |
182 | \fBRFC2553\fR, | |
183 | \fBlwres\fR(3), | |
184 | \fBlwres_gethostent\fR(3), | |
185 | \fBlwres_getaddrinfo\fR(3), | |
186 | \fBlwres_getnameinfo\fR(3), | |
187 | \fBlwres_hstrerror\fR(3). |