home *** CD-ROM | disk | FTP | other *** search
/ rtsi.com / 2014.01.www.rtsi.com.tar / www.rtsi.com / OS9 / OSK / NETWORK / ISP / bind.4.8.3.lzh / BIND483 / MAN / gethostbyname.3 next >
Text File  |  1993-08-24  |  6KB  |  204 lines
  1. .\" Copyright (c) 1983, 1987 The Regents of the University of California.
  2. .\" All rights reserved.
  3. .\"
  4. .\" Redistribution and use in source and binary forms are permitted provided
  5. .\" that: (1) source distributions retain this entire copyright notice and
  6. .\" comment, and (2) distributions including binaries display the following
  7. .\" acknowledgement:  ``This product includes software developed by the
  8. .\" University of California, Berkeley and its contributors'' in the
  9. .\" documentation or other materials provided with the distribution and in
  10. .\" all advertising materials mentioning features or use of this software.
  11. .\" Neither the name of the University nor the names of its contributors may
  12. .\" be used to endorse or promote products derived from this software without
  13. .\" specific prior written permission.
  14. .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
  15. .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
  16. .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  17. .\"
  18. .\"    @(#)gethostbyname.3    6.12 (Berkeley) 6/23/90
  19. .\"
  20. .TH GETHOSTBYNAME 3 "June 23, 1990"
  21. .UC 5
  22. .SH NAME
  23. gethostbyname, gethostbyaddr, gethostent, sethostent, endhostent, herror \- get network host entry
  24. .SH SYNOPSIS
  25. .B "#include <netdb.h>
  26. .PP
  27. .B "extern int h_errno;
  28. .PP
  29. .B "struct hostent *gethostbyname(name)
  30. .br
  31. .B "char *name;
  32. .PP
  33. .B "struct hostent *gethostbyaddr(addr, len, type)
  34. .br
  35. .B "char *addr; int len, type;
  36. .PP
  37. .B "struct hostent *gethostent()
  38. .PP
  39. .B "sethostent(stayopen)
  40. .br
  41. .B "int stayopen;
  42. .PP
  43. .B "endhostent()
  44. .PP
  45. .B "herror(string)
  46. .br
  47. .B "char *string;
  48. .PP
  49. .SH DESCRIPTION
  50. .I Gethostbyname
  51. and
  52. .I gethostbyaddr
  53. each return a pointer to an object with the
  54. following structure describing an internet host
  55. referenced by name or by address, respectively.
  56. This structure contains either the information obtained from the name server,
  57. .IR named (8),
  58. or broken-out fields from a line in 
  59. .IR /etc/hosts .
  60. If the local name server is not running these routines do a lookup in
  61. .IR /etc/hosts .
  62. .RS
  63. .PP
  64. .nf
  65. struct    hostent {
  66.     char    *h_name;    /* official name of host */
  67.     char    **h_aliases;    /* alias list */
  68.     int    h_addrtype;    /* host address type */
  69.     int    h_length;    /* length of address */
  70.     char    **h_addr_list;    /* list of addresses from name server */
  71. };
  72. #define    h_addr  h_addr_list[0]    /* address, for backward compatibility */
  73. .ft R
  74. .ad
  75. .fi
  76. .RE
  77. .PP
  78. The members of this structure are:
  79. .TP \w'h_addr_list'u+2n
  80. h_name
  81. Official name of the host.
  82. .TP \w'h_addr_list'u+2n
  83. h_aliases
  84. A zero terminated array of alternate names for the host.
  85. .TP \w'h_addr_list'u+2n
  86. h_addrtype
  87. The type of address being returned; currently always AF_INET.
  88. .TP \w'h_addr_list'u+2n
  89. h_length
  90. The length, in bytes, of the address.
  91. .TP \w'h_addr_list'u+2n
  92. h_addr_list
  93. A zero terminated array of network addresses for the host.
  94. Host addresses are returned in network byte order.
  95. .TP \w'h_addr_list'u+2n
  96. h_addr
  97. The first address in h_addr_list; this is for backward compatiblity.
  98. .PP
  99. When using the nameserver,
  100. .I gethostbyname
  101. will search for the named host in the current domain and its parents
  102. unless the name ends in a dot.
  103. If the name contains no dot, and if the environment variable ``HOSTALAIASES''
  104. contains the name of an alias file, the alias file will first be searched
  105. for an alias matching the input name.
  106. See
  107. .IR hostname (7)
  108. for the domain search procedure and the alias file format.
  109. .PP
  110. .I Sethostent
  111. may be used to request the use of a connected TCP socket for queries.
  112. If the
  113. .I stayopen
  114. flag is non-zero,
  115. this sets the option to send all queries to the name server using TCP
  116. and to retain the connection after each call to 
  117. .I gethostbyname
  118. or
  119. .IR gethostbyaddr .
  120. Otherwise, queries are performed using UDP datagrams.
  121. .PP
  122. .I Endhostent
  123. closes the TCP connection.
  124. .SH DIAGNOSTICS
  125. .PP
  126. Error return status from 
  127. .I gethostbyname
  128. and
  129. .I gethostbyaddr
  130. is indicated by return of a null pointer.
  131. The external integer
  132. .IR h_errno
  133. may then be checked to see whether this is a temporary failure
  134. or an invalid or unknown host.
  135. The routine
  136. .I herror
  137. can be used to print an error message describing the failure.
  138. If its argument
  139. .I string
  140. is non-NULL, it is printed, followed by a colon and a space.
  141. The error message is printed with a trailing newline.
  142. .PP
  143. .IR h_errno
  144. can have the following values:
  145. .RS
  146. .IP HOST_NOT_FOUND \w'HOST_NOT_FOUND'u+2n
  147. No such host is known.
  148. .IP TRY_AGAIN \w'HOST_NOT_FOUND'u+2n
  149. This is usually a temporary error
  150. and means that the local server did not receive
  151. a response from an authoritative server.
  152. A retry at some later time may succeed.
  153. .IP NO_RECOVERY \w'HOST_NOT_FOUND'u+2n
  154. Some unexpected server failure was encountered.
  155. This is a non-recoverable error.
  156. .IP NO_DATA \w'HOST_NOT_FOUND'u+2n
  157. The requested name is valid but does not have an IP address; 
  158. this is not a temporary error.  
  159. This means that the name is known to the name server but there is no address
  160. associated with this name.
  161. Another type of request to the name server using this domain name
  162. will result in an answer;
  163. for example, a mail-forwarder may be registered for this domain.
  164. .RE
  165. .SH FILES
  166. /etc/hosts
  167. .SH "SEE ALSO"
  168. resolver(3), hosts(5), hostname(7), named(8)
  169. .SH CAVEAT
  170. .PP
  171. .I Gethostent
  172. is defined, and
  173. .I sethostent
  174. and
  175. .I endhostent
  176. are redefined,
  177. when
  178. .IR libc
  179. is built to use only the routines to lookup in
  180. .IR /etc/hosts 
  181. and not the name server.
  182. .PP
  183. .I Gethostent
  184. reads the next line of
  185. .IR /etc/hosts ,
  186. opening the file if necessary.
  187. .PP
  188. .I Sethostent 
  189. is redefined to open and rewind the file.  If the
  190. .I stayopen
  191. argument is non-zero,
  192. the hosts data base will not be closed after each call to
  193. .I gethostbyname
  194. or
  195. .IR gethostbyaddr .
  196. .I Endhostent
  197. is redefined to close the file.
  198. .SH BUGS
  199. All information
  200. is contained in a static area
  201. so it must be copied if it is
  202. to be saved.  Only the Internet
  203. address format is currently understood.
  204.