1.\" $OpenBSD: gethostbyname.3,v 1.16 2000/12/24 00:30:56 aaron Exp $ 2.\" 3.\" Copyright (c) 1983, 1987, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 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. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.Dd March 13, 1997 35.Dt GETHOSTBYNAME 3 36.Os 37.Sh NAME 38.Nm gethostbyname , 39.Nm gethostbyname2 , 40.Nm gethostbyaddr , 41.Nm gethostent , 42.Nm sethostent , 43.Nm endhostent , 44.Nm hstrerror , 45.Nm herror 46.Nd get network host entry 47.Sh SYNOPSIS 48.Fd #include <netdb.h> 49.Fd extern int h_errno; 50.Ft struct hostent * 51.Fn gethostbyname "const char *name" 52.Ft struct hostent * 53.Fn gethostbyname2 "const char *name" "int af" 54.Ft struct hostent * 55.Fn gethostbyaddr "const char *addr" "int len" "int af" 56.Ft struct hostent * 57.Fn gethostent void 58.Ft void 59.Fn sethostent "int stayopen" 60.Ft void 61.Fn endhostent void 62.Ft void 63.Fn herror "const char *string" 64.Ft const char * 65.Fn hstrerror "int err" 66.Sh DESCRIPTION 67The 68.Fn gethostbyname 69and 70.Fn gethostbyaddr 71functions each return a pointer to an object with the following structure 72describing an internet host referenced by name or by address, respectively. 73This structure contains either information obtained from the name server (i.e., 74.Xr resolver 3 75and 76.Xr named 8 ) , 77broken-out fields from a line in 78.Pa /etc/hosts , 79or database entries supplied by the 80.Xr yp 8 81system. 82.Xr resolv.conf 5 83describes how the particular database is chosen. 84.Bd -literal 85struct hostent { 86 char *h_name; /* official name of host */ 87 char **h_aliases; /* alias list */ 88 int h_addrtype; /* host address type */ 89 int h_length; /* length of address */ 90 char **h_addr_list; /* list of addresses from name server */ 91}; 92#define h_addr h_addr_list[0] /* address, for backward compatibility */ 93.Ed 94.Pp 95The members of this structure are: 96.Bl -tag -width h_addr_list 97.It Fa h_name 98Official name of the host. 99.It Fa h_aliases 100A zero-terminated array of alternate names for the host. 101.It Fa h_addrtype 102The type of address being returned. 103.It Fa h_length 104The length, in bytes, of the address. 105.It Fa h_addr_list 106A zero-terminated array of network addresses for the host. 107Host addresses are returned in network byte order. 108.It Fa h_addr 109The first address in 110.Fa h_addr_list ; 111this is for backward compatibility. 112.El 113.Pp 114The function 115.Fn gethostbyname 116will search for the named host in the current domain and its parents 117using the search lookup semantics detailed in 118.Xr resolv.conf 5 119and 120.Xr hostname 7 . 121.Pp 122.Fn gethostbyname2 123is an advanced form of 124.Fn gethostbyname 125which allows lookups in address families other than 126.Dv AF_INET , 127for example 128.Dv AF_INET6 . 129.Pp 130The 131.Fn gethostbyaddr 132function will search for the specified address of length 133.Fa len 134in the address family 135.Fa af . 136The only address family currently supported is 137.Dv AF_INET . 138.Pp 139The 140.Fn sethostent 141function may be used to request the use of a connected 142.Tn TCP 143socket for queries. 144If the 145.Fa stayopen 146flag is non-zero, 147this sets the option to send all queries to the name server using 148.Tn TCP 149and to retain the connection after each call to 150.Fn gethostbyname 151or 152.Fn gethostbyaddr . 153Otherwise, queries are performed using 154.Tn UDP 155datagrams. 156.Pp 157The 158.Fn endhostent 159function closes the 160.Tn TCP 161connection. 162.Pp 163The 164.Fn herror 165function prints an error message describing the failure. 166If its argument 167.Fa string 168is non-null, 169it is prepended to the message string and separated from it by a colon 170.Pq Ql \&: 171and a space. 172The error message is printed with a trailing newline. 173The contents of the error message is the same as that returned by 174.Fn hstrerror 175with argument 176.Fa h_errno . 177.Sh FILES 178.Bl -tag -width /etc/resolv.conf -compact 179.It Pa /etc/hosts 180.It Pa /etc/resolv.conf 181.El 182.Sh DIAGNOSTICS 183Error return status from 184.Fn gethostbyname , 185.Fn gethostbyname2 , 186and 187.Fn gethostbyaddr 188is indicated by return of a null pointer. 189The external integer 190.Va h_errno 191may then be checked to see whether this is a temporary failure 192or an invalid or unknown host. 193.Pp 194The variable 195.Va h_errno 196can have the following values: 197.Bl -tag -width HOST_NOT_FOUND 198.It Dv HOST_NOT_FOUND 199No such host is known. 200.It Dv TRY_AGAIN 201This is usually a temporary error 202and means that the local server did not receive 203a response from an authoritative server. 204A retry at some later time may succeed. 205.It Dv NO_RECOVERY 206Some unexpected server failure was encountered. 207This is a non-recoverable error. 208.It Dv NO_DATA 209The requested name is valid but does not have an IP address; 210this is not a temporary error. 211This means that the name is known to the name server but there is no address 212associated with this name. 213Another type of request to the name server using this domain name 214will result in an answer; 215for example, a mail-forwarder may be registered for this domain. 216.El 217.Sh SEE ALSO 218.Xr resolver 3 , 219.Xr getaddrinfo 3 , 220.Xr getnameinfo 3 , 221.Xr hosts 5 , 222.Xr resolv.conf 5 , 223.Xr hostname 7 , 224.Xr named 8 225.Sh CAVEAT 226If the search routines in 227.Xr resolv.conf 5 228decide to read the 229.Pa /etc/hosts 230file, 231.Fn gethostent 232and other functions will 233read the next line of the file, 234re-opening the file if necessary. 235.Pp 236The 237.Fn sethostent 238function opens and/or rewinds the file 239.Pa /etc/hosts . 240If the 241.Fa stayopen 242argument is non-zero, the file will not be closed after each call to 243.Fn gethostbyname , 244.Fn gethostbyname2 , 245or 246.Fn gethostbyaddr . 247.Pp 248The 249.Fn endhostent 250function closes the file. 251.Sh HISTORY 252The 253.Fn herror 254function appeared in 255.Bx 4.3 . 256The 257.Fn endhostent , 258.Fn gethostbyaddr , 259.Fn gethostbyname , 260.Fn gethostent , 261and 262.Fn sethostent 263functions appeared in 264.Bx 4.2 . 265.Sh BUGS 266These functions use static data storage; 267if the data is needed for future use, it should be 268copied before any subsequent calls overwrite it. 269Only the Internet 270address formats are currently understood. 271.Pp 272YP does not support any address families other than 273.Dv AF_INET 274and uses 275the traditional database format. 276