Annotation of src/lib/libc/net/gethostbyname.3, Revision 1.28
1.28 ! apb 1: .\" $NetBSD: gethostbyname.3,v 1.27 2004/08/17 13:45:14 wiz Exp $
1.6 cgd 2: .\"
3: .\" Copyright (c) 1983, 1987, 1991, 1993
4: .\" The Regents of the University of California. All rights reserved.
1.1 cgd 5: .\"
6: .\" Redistribution and use in source and binary forms, with or without
7: .\" modification, are permitted provided that the following conditions
8: .\" are met:
9: .\" 1. Redistributions of source code must retain the above copyright
10: .\" notice, this list of conditions and the following disclaimer.
11: .\" 2. Redistributions in binary form must reproduce the above copyright
12: .\" notice, this list of conditions and the following disclaimer in the
13: .\" documentation and/or other materials provided with the distribution.
1.24 agc 14: .\" 3. Neither the name of the University nor the names of its contributors
1.1 cgd 15: .\" may be used to endorse or promote products derived from this software
16: .\" without specific prior written permission.
17: .\"
18: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28: .\" SUCH DAMAGE.
29: .\"
1.10 mrg 30: .\" @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95
1.1 cgd 31: .\"
1.28 ! apb 32: .Dd October 7, 2006
1.1 cgd 33: .Dt GETHOSTBYNAME 3
1.15 garbled 34: .Os
1.1 cgd 35: .Sh NAME
36: .Nm gethostbyname ,
1.16 itojun 37: .Nm gethostbyname2 ,
1.1 cgd 38: .Nm gethostbyaddr ,
1.26 ginsbach 39: .Nm gethostent ,
1.1 cgd 40: .Nm sethostent ,
41: .Nm endhostent ,
1.7 jtc 42: .Nm herror ,
43: .Nm hstrerror
1.1 cgd 44: .Nd get network host entry
1.11 perry 45: .Sh LIBRARY
46: .Lb libc
1.1 cgd 47: .Sh SYNOPSIS
1.23 wiz 48: .In netdb.h
1.4 davidb 49: .Fd extern int h_errno;
1.1 cgd 50: .Ft struct hostent *
1.5 deraadt 51: .Fn gethostbyname "const char *name"
1.1 cgd 52: .Ft struct hostent *
1.16 itojun 53: .Fn gethostbyname2 "const char *name" "int af"
54: .Ft struct hostent *
1.19 kleink 55: .Fn gethostbyaddr "const char *addr" "socklen_t len" "int type"
1.26 ginsbach 56: .Ft struct hostent *
57: .Fn gethostent void
1.7 jtc 58: .Ft void
1.1 cgd 59: .Fn sethostent "int stayopen"
1.7 jtc 60: .Ft void
1.1 cgd 61: .Fn endhostent void
1.7 jtc 62: .Ft void
1.8 lukem 63: .Fn herror "const char *string"
64: .Ft const char *
1.7 jtc 65: .Fn hstrerror "int err"
1.1 cgd 66: .Sh DESCRIPTION
67: The
1.16 itojun 68: .Fn gethostbyname ,
69: .Fn gethostbyname2
1.1 cgd 70: and
71: .Fn gethostbyaddr
72: functions
73: each return a pointer to an object with the
1.28 ! apb 74: following structure describing an internet host.
1.1 cgd 75: .Bd -literal
76: struct hostent {
77: char *h_name; /* official name of host */
78: char **h_aliases; /* alias list */
79: int h_addrtype; /* host address type */
80: int h_length; /* length of address */
81: char **h_addr_list; /* list of addresses from name server */
82: };
83: #define h_addr h_addr_list[0] /* address, for backward compatibility */
84: .Ed
85: .Pp
86: The members of this structure are:
87: .Bl -tag -width h_addr_list
88: .It Fa h_name
89: Official name of the host.
90: .It Fa h_aliases
1.10 mrg 91: A NULL-terminated array of alternative names for the host.
1.1 cgd 92: .It Fa h_addrtype
93: The type of address being returned; currently always
94: .Dv AF_INET .
95: .It Fa h_length
96: The length, in bytes, of the address.
97: .It Fa h_addr_list
1.10 mrg 98: A NULL-terminated array of network addresses for the host.
1.1 cgd 99: Host addresses are returned in network byte order.
100: .It Fa h_addr
101: The first address in
102: .Fa h_addr_list ;
1.3 jtc 103: this is for backward compatibility.
1.10 mrg 104: .El
1.1 cgd 105: .Pp
1.28 ! apb 106: In the case of
! 107: .Fn gethostbyname
! 108: and
! 109: .Fn gethostbyname2 ,
! 110: the host is specified by name,
! 111: or using a string representation of a numeric address.
! 112: In the case of
! 113: .Fn gethostbyaddr ,
! 114: the host is specified using a binary representation of an address.
! 115: .Pp
! 116: The returned
! 117: .Ft "struct hostent"
! 118: structure may contain
! 119: the result of a simple string to binary conversion,
! 120: information obtained from the domain name resolver (see
! 121: .Xr resolver 3 ) ,
! 122: broken-out fields from a line in
! 123: .Pa /etc/hosts ,
! 124: or database entries supplied by the
! 125: .Xr yp 8
! 126: system.
! 127: The order of the lookups is controlled by the
! 128: .Sq hosts
! 129: entry in
! 130: .Xr nsswitch.conf 5 .
! 131: .Pp
! 132: When using the domain name resolver,
1.1 cgd 133: .Fn gethostbyname
1.16 itojun 134: and
135: .Fn gethostbyname2
1.1 cgd 136: will search for the named host in the current domain and its parents
137: unless the name ends in a dot.
138: If the name contains no dot, and if the environment variable
139: .Dq Ev HOSTALIASES
140: contains the name of an alias file, the alias file will first be searched
141: for an alias matching the input name.
142: See
143: .Xr hostname 7
144: for the domain search procedure and the alias file format.
145: .Pp
146: The
1.16 itojun 147: .Fn gethostbyname2
148: function is an evolution of
149: .Fn gethostbyname
150: which is intended to allow lookups in address families other than
151: .Dv AF_INET ,
152: for example
153: .Dv AF_INET6 .
154: Currently the
155: .Fa af
156: argument must be specified as
157: .Dv AF_INET
158: or
159: .Dv AF_INET6 ,
1.22 wiz 160: else the function will return
1.16 itojun 161: .Dv NULL
162: after having set
163: .Va h_errno
164: to
1.17 itojun 165: .Dv NETDB_INTERNAL .
1.16 itojun 166: .Pp
167: The
1.26 ginsbach 168: .Fn gethostent
169: function
170: reads the next line of the
171: .Pa /etc/hosts
172: file, opening the file if necessary.
173: .Pp
174: The
1.1 cgd 175: .Fn sethostent
176: function
177: may be used to request the use of a connected
178: .Tn TCP
179: socket for queries.
180: If the
181: .Fa stayopen
182: flag is non-zero,
183: this sets the option to send all queries to the name server using
184: .Tn TCP
1.12 fair 185: and to retain the connection after each call to
1.16 itojun 186: .Fn gethostbyname ,
1.27 wiz 187: .Fn gethostbyname2 ,
1.1 cgd 188: or
189: .Fn gethostbyaddr .
190: Otherwise, queries are performed using
191: .Tn UDP
192: datagrams.
193: .Pp
194: The
195: .Fn endhostent
196: function
197: closes the
198: .Tn TCP
199: connection.
1.16 itojun 200: .Pp
201: The
202: .Fn herror
203: function writes a message to the diagnostic output consisting of the
204: string parameter
205: .Fa s ,
206: the constant string ": ", and a message corresponding to the value of
207: .Va h_errno .
208: .Pp
209: The
210: .Fn hstrerror
211: function returns a string which is the message text corresponding to the
212: value of the
213: .Fa err
214: parameter.
1.1 cgd 215: .Sh FILES
216: .Bl -tag -width /etc/hosts -compact
217: .It Pa /etc/hosts
218: .El
219: .Sh DIAGNOSTICS
1.12 fair 220: Error return status from
1.26 ginsbach 221: .Fn gethostbyent ,
1.16 itojun 222: .Fn gethostbyname ,
1.27 wiz 223: .Fn gethostbyname2 ,
1.1 cgd 224: and
225: .Fn gethostbyaddr
226: is indicated by return of a null pointer.
227: The external integer
228: .Va h_errno
229: may then be checked to see whether this is a temporary failure
230: or an invalid or unknown host.
231: The routine
232: .Fn herror
233: can be used to print an error message describing the failure.
234: If its argument
235: .Fa string
236: is
237: .Pf non Dv -NULL ,
238: it is printed, followed by a colon and a space.
239: The error message is printed with a trailing newline.
240: .Pp
241: The variable
242: .Va h_errno
243: can have the following values:
244: .Bl -tag -width HOST_NOT_FOUND
245: .It Dv HOST_NOT_FOUND
246: No such host is known.
247: .It Dv TRY_AGAIN
248: This is usually a temporary error
249: and means that the local server did not receive
250: a response from an authoritative server.
251: A retry at some later time may succeed.
252: .It Dv NO_RECOVERY
253: Some unexpected server failure was encountered.
254: This is a non-recoverable error.
255: .It Dv NO_DATA
1.12 fair 256: The requested name is valid but does not have an IP address;
257: this is not a temporary error.
1.1 cgd 258: This means that the name is known to the name server but there is no address
259: associated with this name.
260: Another type of request to the name server using this domain name
261: will result in an answer;
262: for example, a mail-forwarder may be registered for this domain.
263: .El
264: .Sh SEE ALSO
265: .Xr resolver 3 ,
266: .Xr hosts 5 ,
1.13 lukem 267: .Xr nsswitch.conf 5 ,
1.1 cgd 268: .Xr hostname 7 ,
269: .Xr named 8
1.25 wiz 270: .Sh HISTORY
271: The
272: .Fn herror
273: function appeared in
274: .Bx 4.3 .
275: The
276: .Fn endhostent ,
277: .Fn gethostbyaddr ,
278: .Fn gethostbyname ,
1.26 ginsbach 279: .Fn gethostent ,
1.25 wiz 280: and
281: .Fn sethostent
282: functions appeared in
283: .Bx 4.2 .
284: The
285: .Fn gethostbyname2
286: function first appeared in bind-4.9.4.
287: IPv6 support was implemented in WIDE Hydrangea IPv6 protocol stack kit.
1.20 wiz 288: .Sh CAVEATS
1.18 itojun 289: If the search routines specified in
290: .Xr nsswitch.conf 5
291: decide to read the
1.1 cgd 292: .Pa /etc/hosts
1.18 itojun 293: file,
1.26 ginsbach 294: .Fn gethostbyname ,
1.27 wiz 295: .Fn gethostbyname2 ,
296: and
1.26 ginsbach 297: .Fn gethostbyaddr
298: will
1.18 itojun 299: read the next line of the file,
300: re-opening the file if necessary.
1.1 cgd 301: .Pp
302: The
303: .Fn sethostent
304: function
1.6 cgd 305: opens and/or rewinds the file
306: .Pa /etc/hosts .
307: If the
1.1 cgd 308: .Fa stayopen
309: argument is non-zero,
1.6 cgd 310: the file will not be closed after each call to
1.16 itojun 311: .Fn gethostbyname ,
1.27 wiz 312: .Fn gethostbyname2 ,
1.26 ginsbach 313: .Fn gethostbyaddr ,
1.1 cgd 314: or
1.26 ginsbach 315: .Fn gethostent .
1.6 cgd 316: .Pp
1.1 cgd 317: The
318: .Fn endhostent
1.18 itojun 319: function closes the file.
1.1 cgd 320: .Sh BUGS
321: These functions use static data storage;
322: if the data is needed for future use, it should be
323: copied before any subsequent calls overwrite it.
324: Only the Internet
325: address format is currently understood.
1.26 ginsbach 326: .Pp
327: The
328: .Fn gethostent
1.27 wiz 329: does not currently follow the search order specified in
1.26 ginsbach 330: .Xr nsswitch.conf 5
331: and only reads the
332: .Pa /etc/hosts
333: file.
CVSweb <webmaster@jp.NetBSD.org>