1.\" $OpenBSD: gethostbyname.3,v 1.32 2016/08/05 16:16:06 schwarze 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. Neither the name of the University nor the names of its contributors 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.\" 30.Dd $Mdocdate: August 5 2016 $ 31.Dt GETHOSTBYNAME 3 32.Os 33.Sh NAME 34.Nm gethostbyname , 35.Nm gethostbyname2 , 36.Nm gethostbyaddr , 37.Nm gethostent , 38.Nm sethostent , 39.Nm endhostent , 40.Nm hstrerror , 41.Nm herror 42.Nd get network host entry 43.Sh SYNOPSIS 44.In netdb.h 45.Vt extern int h_errno ; 46.Ft struct hostent * 47.Fn gethostbyname "const char *name" 48.Ft struct hostent * 49.Fn gethostent void 50.Ft void 51.Fn sethostent "int stayopen" 52.Ft void 53.Fn endhostent void 54.Ft void 55.Fn herror "const char *string" 56.Ft const char * 57.Fn hstrerror "int err" 58.In sys/socket.h 59.In netdb.h 60.Ft struct hostent * 61.Fn gethostbyname2 "const char *name" "int af" 62.Ft struct hostent * 63.Fn gethostbyaddr "const void *addr" "socklen_t len" "int af" 64.Sh DESCRIPTION 65The 66.Fn gethostbyname , 67.Fn gethostbyname2 , 68and 69.Fn gethostbyaddr 70functions each return a pointer to an object with the following structure 71describing an Internet host referenced by 72.Fa name 73or 74.Fa addr , 75respectively. 76This structure contains either information obtained from a name server, 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 -offset indent 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 returned addresses */ 91}; 92#define h_addr h_addr_list[0] /* address, for backward compat */ 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 101.Dv NULL Ns -terminated 102array of alternate names for the host. 103.It Fa h_addrtype 104The type of address being returned. 105.It Fa h_length 106The length, in bytes, of the address. 107.It Fa h_addr_list 108A 109.Dv NULL Ns -terminated 110array of network addresses for the host. 111Host addresses are returned in network byte order. 112.It Fa h_addr 113The first address in 114.Fa h_addr_list ; 115this is for backward compatibility. 116.El 117.Pp 118The function 119.Fn gethostbyname 120will search for the named host in the current domain and its parents 121using the search lookup semantics detailed in 122.Xr resolv.conf 5 123and 124.Xr hostname 7 . 125.Pp 126.Fn gethostbyname2 127is an advanced form of 128.Fn gethostbyname 129which allows lookups in address families other than 130.Dv AF_INET . 131Currently, the only supported address family besides 132.Dv AF_INET 133is 134.Dv AF_INET6 . 135.Pp 136The 137.Fn gethostbyaddr 138function will search for the specified address of length 139.Fa len 140in the address family 141.Fa af . 142The only address family currently supported is 143.Dv AF_INET . 144.Pp 145The 146.Fn sethostent 147function may be used to request the use of a connected 148TCP socket for queries. 149If the 150.Fa stayopen 151flag is non-zero, 152this sets the option to send all queries to the name server using TCP 153and to retain the connection after each call to 154.Fn gethostbyname 155or 156.Fn gethostbyaddr . 157Otherwise, queries are performed using UDP datagrams. 158.Pp 159The 160.Fn endhostent 161function closes the TCP connection. 162.Pp 163The 164.Fn herror 165function prints an error message describing the failure. 166If its argument 167.Fa string 168is not 169.Dv NULL , 170it is prepended to the message string and separated from it by a colon 171.Pq Ql \&: 172and a space. 173The error message is printed with a trailing newline. 174The contents of the error message is the same as that returned by 175.Fn hstrerror 176with argument 177.Va h_errno . 178.Sh ENVIRONMENT 179.Bl -tag -width RES_OPTIONS 180.It Ev RES_OPTIONS 181A list of options to override the resolver's internal defaults. 182See 183.Xr resolv.conf 5 184for more information. 185.El 186.Sh FILES 187.Bl -tag -width /etc/resolv.conf -compact 188.It Pa /etc/hosts 189.It Pa /etc/resolv.conf 190.El 191.Sh DIAGNOSTICS 192Error return status from 193.Fn gethostbyname , 194.Fn gethostbyname2 , 195and 196.Fn gethostbyaddr 197is indicated by return of a 198.Dv NULL 199pointer. 200The external integer 201.Va h_errno 202may then be checked to see whether this is a temporary failure 203or an invalid or unknown host. 204.Pp 205The variable 206.Va h_errno 207can have the following values: 208.Bl -tag -width HOST_NOT_FOUND 209.It Dv HOST_NOT_FOUND 210No such host is known. 211.It Dv TRY_AGAIN 212This is usually a temporary error 213and means that the local server did not receive 214a response from an authoritative server. 215A retry at some later time may succeed. 216.It Dv NO_RECOVERY 217Some unexpected server failure was encountered. 218This is a non-recoverable error. 219.It Dv NO_DATA 220The requested name is valid but does not have an IP address; 221this is not a temporary error. 222This means that the name is known to the name server but there is no address 223associated with this name. 224Another type of request to the name server using this domain name 225will result in an answer; 226for example, a mail-forwarder may be registered for this domain. 227.It Dv NETDB_INTERNAL 228An internal error occurred. 229This may occur when an address family other than 230.Dv AF_INET 231or 232.Dv AF_INET6 233is specified or when a resource is unable to be allocated. 234.It Dv NETDB_SUCCESS 235The function completed successfully. 236.El 237.Sh SEE ALSO 238.Xr getaddrinfo 3 , 239.Xr getnameinfo 3 , 240.Xr resolver 3 , 241.Xr hosts 5 , 242.Xr resolv.conf 5 , 243.Xr hostname 7 244.Sh HISTORY 245The 246.Fn endhostent , 247.Fn gethostbyaddr , 248.Fn gethostbyname , 249.Fn gethostent , 250and 251.Fn sethostent 252functions appeared in 253.Bx 4.1c . 254The function 255.Fn herror 256was added in 257.Bx 4.3 Tahoe , 258.Fn hstrerror 259in 260.Bx 4.4 , 261and 262.Fn gethostbyname2 263in 264.Ox 2.1 . 265.Sh CAVEATS 266If the search routines in 267.Xr resolv.conf 5 268decide to read the 269.Pa /etc/hosts 270file, 271.Fn gethostent 272and other functions will 273read the next line of the file, 274re-opening the file if necessary. 275.Pp 276The 277.Fn sethostent 278function opens and/or rewinds the file 279.Pa /etc/hosts . 280If the 281.Fa stayopen 282argument is non-zero, the file will not be closed after each call to 283.Fn gethostbyname , 284.Fn gethostbyname2 , 285or 286.Fn gethostbyaddr . 287.Pp 288The 289.Fn endhostent 290function closes the file. 291.Sh BUGS 292These functions use static data storage; 293if the data is needed for future use, it should be 294copied before any subsequent calls overwrite it. 295.Pp 296Only the Internet 297address formats are currently understood. 298.Pp 299YP does not support any address families other than 300.Dv AF_INET 301and uses 302the traditional database format. 303