/contrib/bind9/lib/lwres/man/lwres_gethostent.3

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 315 lines · 315 code · 0 blank · 0 comment · 0 complexity · e97d2b592b94b8d37f40bf85021c9189 MD5 · raw file

  1. .\" Copyright (C) 2004, 2005, 2007, 2012 Internet Systems Consortium, Inc. ("ISC")
  2. .\" Copyright (C) 2001 Internet Software Consortium.
  3. .\"
  4. .\" Permission to use, copy, modify, and/or 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 ISC DISCLAIMS ALL WARRANTIES WITH
  9. .\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  10. .\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  11. .\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  12. .\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  13. .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  14. .\" PERFORMANCE OF THIS SOFTWARE.
  15. .\"
  16. .\" $Id$
  17. .\"
  18. .hy 0
  19. .ad l
  20. .\" Title: lwres_gethostent
  21. .\" Author:
  22. .\" Generator: DocBook XSL Stylesheets v1.71.1 <http://docbook.sf.net/>
  23. .\" Date: Jun 30, 2000
  24. .\" Manual: BIND9
  25. .\" Source: BIND9
  26. .\"
  27. .TH "LWRES_GETHOSTENT" "3" "Jun 30, 2000" "BIND9" "BIND9"
  28. .\" disable hyphenation
  29. .nh
  30. .\" disable justification (adjust text to left margin only)
  31. .ad l
  32. .SH "NAME"
  33. lwres_gethostbyname, lwres_gethostbyname2, lwres_gethostbyaddr, lwres_gethostent, lwres_sethostent, lwres_endhostent, lwres_gethostbyname_r, lwres_gethostbyaddr_r, lwres_gethostent_r, lwres_sethostent_r, lwres_endhostent_r \- lightweight resolver get network host entry
  34. .SH "SYNOPSIS"
  35. .nf
  36. #include <lwres/netdb.h>
  37. .fi
  38. .HP 37
  39. .BI "struct hostent * lwres_gethostbyname(const\ char\ *" "name" ");"
  40. .HP 38
  41. .BI "struct hostent * lwres_gethostbyname2(const\ char\ *" "name" ", int\ " "af" ");"
  42. .HP 37
  43. .BI "struct hostent * lwres_gethostbyaddr(const\ char\ *" "addr" ", int\ " "len" ", int\ " "type" ");"
  44. .HP 34
  45. .BI "struct hostent * lwres_gethostent(void);"
  46. .HP 22
  47. .BI "void lwres_sethostent(int\ " "stayopen" ");"
  48. .HP 22
  49. .BI "void lwres_endhostent(void);"
  50. .HP 39
  51. .BI "struct hostent * lwres_gethostbyname_r(const\ char\ *" "name" ", struct\ hostent\ *" "resbuf" ", char\ *" "buf" ", int\ " "buflen" ", int\ *" "error" ");"
  52. .HP 39
  53. .BI "struct hostent * lwres_gethostbyaddr_r(const\ char\ *" "addr" ", int\ " "len" ", int\ " "type" ", struct\ hostent\ *" "resbuf" ", char\ *" "buf" ", int\ " "buflen" ", int\ *" "error" ");"
  54. .HP 36
  55. .BI "struct hostent * lwres_gethostent_r(struct\ hostent\ *" "resbuf" ", char\ *" "buf" ", int\ " "buflen" ", int\ *" "error" ");"
  56. .HP 24
  57. .BI "void lwres_sethostent_r(int\ " "stayopen" ");"
  58. .HP 24
  59. .BI "void lwres_endhostent_r(void);"
  60. .SH "DESCRIPTION"
  61. .PP
  62. These functions provide hostname\-to\-address and address\-to\-hostname lookups by means of the lightweight resolver. They are similar to the standard
  63. \fBgethostent\fR(3)
  64. functions provided by most operating systems. They use a
  65. \fBstruct hostent\fR
  66. which is usually defined in
  67. \fI<namedb.h>\fR.
  68. .PP
  69. .RS 4
  70. .nf
  71. struct hostent {
  72. char *h_name; /* official name of host */
  73. char **h_aliases; /* alias list */
  74. int h_addrtype; /* host address type */
  75. int h_length; /* length of address */
  76. char **h_addr_list; /* list of addresses from name server */
  77. };
  78. #define h_addr h_addr_list[0] /* address, for backward compatibility */
  79. .fi
  80. .RE
  81. .sp
  82. .PP
  83. The members of this structure are:
  84. .PP
  85. \fBh_name\fR
  86. .RS 4
  87. The official (canonical) name of the host.
  88. .RE
  89. .PP
  90. \fBh_aliases\fR
  91. .RS 4
  92. A NULL\-terminated array of alternate names (nicknames) for the host.
  93. .RE
  94. .PP
  95. \fBh_addrtype\fR
  96. .RS 4
  97. The type of address being returned \(em
  98. \fBPF_INET\fR
  99. or
  100. \fBPF_INET6\fR.
  101. .RE
  102. .PP
  103. \fBh_length\fR
  104. .RS 4
  105. The length of the address in bytes.
  106. .RE
  107. .PP
  108. \fBh_addr_list\fR
  109. .RS 4
  110. A
  111. \fBNULL\fR
  112. terminated array of network addresses for the host. Host addresses are returned in network byte order.
  113. .RE
  114. .PP
  115. For backward compatibility with very old software,
  116. \fBh_addr\fR
  117. is the first address in
  118. \fBh_addr_list.\fR
  119. .PP
  120. \fBlwres_gethostent()\fR,
  121. \fBlwres_sethostent()\fR,
  122. \fBlwres_endhostent()\fR,
  123. \fBlwres_gethostent_r()\fR,
  124. \fBlwres_sethostent_r()\fR
  125. and
  126. \fBlwres_endhostent_r()\fR
  127. provide iteration over the known host entries on systems that provide such functionality through facilities like
  128. \fI/etc/hosts\fR
  129. or NIS. The lightweight resolver does not currently implement these functions; it only provides them as stub functions that always return failure.
  130. .PP
  131. \fBlwres_gethostbyname()\fR
  132. and
  133. \fBlwres_gethostbyname2()\fR
  134. look up the hostname
  135. \fIname\fR.
  136. \fBlwres_gethostbyname()\fR
  137. always looks for an IPv4 address while
  138. \fBlwres_gethostbyname2()\fR
  139. looks for an address of protocol family
  140. \fIaf\fR: either
  141. \fBPF_INET\fR
  142. or
  143. \fBPF_INET6\fR
  144. \(em IPv4 or IPV6 addresses respectively. Successful calls of the functions return a
  145. \fBstruct hostent\fRfor the name that was looked up.
  146. \fBNULL\fR
  147. is returned if the lookups by
  148. \fBlwres_gethostbyname()\fR
  149. or
  150. \fBlwres_gethostbyname2()\fR
  151. fail.
  152. .PP
  153. Reverse lookups of addresses are performed by
  154. \fBlwres_gethostbyaddr()\fR.
  155. \fIaddr\fR
  156. is an address of length
  157. \fIlen\fR
  158. bytes and protocol family
  159. \fItype\fR
  160. \(em
  161. \fBPF_INET\fR
  162. or
  163. \fBPF_INET6\fR.
  164. \fBlwres_gethostbyname_r()\fR
  165. is a thread\-safe function for forward lookups. If an error occurs, an error code is returned in
  166. \fI*error\fR.
  167. \fIresbuf\fR
  168. is a pointer to a
  169. \fBstruct hostent\fR
  170. which is initialised by a successful call to
  171. \fBlwres_gethostbyname_r()\fR.
  172. \fIbuf\fR
  173. is a buffer of length
  174. \fIlen\fR
  175. bytes which is used to store the
  176. \fBh_name\fR,
  177. \fBh_aliases\fR, and
  178. \fBh_addr_list\fR
  179. elements of the
  180. \fBstruct hostent\fR
  181. returned in
  182. \fIresbuf\fR. Successful calls to
  183. \fBlwres_gethostbyname_r()\fR
  184. return
  185. \fIresbuf\fR, which is a pointer to the
  186. \fBstruct hostent\fR
  187. it created.
  188. .PP
  189. \fBlwres_gethostbyaddr_r()\fR
  190. is a thread\-safe function that performs a reverse lookup of address
  191. \fIaddr\fR
  192. which is
  193. \fIlen\fR
  194. bytes long and is of protocol family
  195. \fItype\fR
  196. \(em
  197. \fBPF_INET\fR
  198. or
  199. \fBPF_INET6\fR. If an error occurs, the error code is returned in
  200. \fI*error\fR. The other function parameters are identical to those in
  201. \fBlwres_gethostbyname_r()\fR.
  202. \fIresbuf\fR
  203. is a pointer to a
  204. \fBstruct hostent\fR
  205. which is initialised by a successful call to
  206. \fBlwres_gethostbyaddr_r()\fR.
  207. \fIbuf\fR
  208. is a buffer of length
  209. \fIlen\fR
  210. bytes which is used to store the
  211. \fBh_name\fR,
  212. \fBh_aliases\fR, and
  213. \fBh_addr_list\fR
  214. elements of the
  215. \fBstruct hostent\fR
  216. returned in
  217. \fIresbuf\fR. Successful calls to
  218. \fBlwres_gethostbyaddr_r()\fR
  219. return
  220. \fIresbuf\fR, which is a pointer to the
  221. \fBstruct hostent()\fR
  222. it created.
  223. .SH "RETURN VALUES"
  224. .PP
  225. The functions
  226. \fBlwres_gethostbyname()\fR,
  227. \fBlwres_gethostbyname2()\fR,
  228. \fBlwres_gethostbyaddr()\fR, and
  229. \fBlwres_gethostent()\fR
  230. return NULL to indicate an error. In this case the global variable
  231. \fBlwres_h_errno\fR
  232. will contain one of the following error codes defined in
  233. \fI<lwres/netdb.h>\fR:
  234. .PP
  235. \fBHOST_NOT_FOUND\fR
  236. .RS 4
  237. The host or address was not found.
  238. .RE
  239. .PP
  240. \fBTRY_AGAIN\fR
  241. .RS 4
  242. A recoverable error occurred, e.g., a timeout. Retrying the lookup may succeed.
  243. .RE
  244. .PP
  245. \fBNO_RECOVERY\fR
  246. .RS 4
  247. A non\-recoverable error occurred.
  248. .RE
  249. .PP
  250. \fBNO_DATA\fR
  251. .RS 4
  252. The name exists, but has no address information associated with it (or vice versa in the case of a reverse lookup). The code NO_ADDRESS is accepted as a synonym for NO_DATA for backwards compatibility.
  253. .RE
  254. .PP
  255. \fBlwres_hstrerror\fR(3)
  256. translates these error codes to suitable error messages.
  257. .PP
  258. \fBlwres_gethostent()\fR
  259. and
  260. \fBlwres_gethostent_r()\fR
  261. always return
  262. \fBNULL\fR.
  263. .PP
  264. Successful calls to
  265. \fBlwres_gethostbyname_r()\fR
  266. and
  267. \fBlwres_gethostbyaddr_r()\fR
  268. return
  269. \fIresbuf\fR, a pointer to the
  270. \fBstruct hostent\fR
  271. that was initialised by these functions. They return
  272. \fBNULL\fR
  273. if the lookups fail or if
  274. \fIbuf\fR
  275. was too small to hold the list of addresses and names referenced by the
  276. \fBh_name\fR,
  277. \fBh_aliases\fR, and
  278. \fBh_addr_list\fR
  279. elements of the
  280. \fBstruct hostent\fR. If
  281. \fIbuf\fR
  282. was too small, both
  283. \fBlwres_gethostbyname_r()\fR
  284. and
  285. \fBlwres_gethostbyaddr_r()\fR
  286. set the global variable
  287. \fBerrno\fR
  288. to
  289. \fBERANGE\fR.
  290. .SH "SEE ALSO"
  291. .PP
  292. \fBgethostent\fR(3),
  293. \fBlwres_getipnode\fR(3),
  294. \fBlwres_hstrerror\fR(3)
  295. .SH "BUGS"
  296. .PP
  297. \fBlwres_gethostbyname()\fR,
  298. \fBlwres_gethostbyname2()\fR,
  299. \fBlwres_gethostbyaddr()\fR
  300. and
  301. \fBlwres_endhostent()\fR
  302. are not thread safe; they return pointers to static data and provide error codes through a global variable. Thread\-safe versions for name and address lookup are provided by
  303. \fBlwres_gethostbyname_r()\fR, and
  304. \fBlwres_gethostbyaddr_r()\fR
  305. respectively.
  306. .PP
  307. The resolver daemon does not currently support any non\-DNS name services such as
  308. \fI/etc/hosts\fR
  309. or
  310. \fBNIS\fR, consequently the above functions don't, either.
  311. .SH "COPYRIGHT"
  312. Copyright \(co 2004, 2005, 2007, 2012 Internet Systems Consortium, Inc. ("ISC")
  313. .br
  314. Copyright \(co 2001 Internet Software Consortium.
  315. .br