1.\" $NetBSD: gethostbyname.3,v 1.1.1.2 2012/09/09 16:07:45 christos Exp $ 2.\" 3.\" Copyright (C) 2009 Internet Systems Consortium, Inc. ("ISC") 4.\" 5.\" Permission to use, copy, modify, and/or distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15.\" PERFORMANCE OF THIS SOFTWARE. 16.\" 17.\" Id: gethostbyname.3,v 1.3 2009/01/22 23:49:23 tbox Exp 18.\" 19.Dd June 23, 1990 20.Dt GETHOSTBYNAME @LIB_NETWORK_EXT_U@ 21.Os BSD 4 22.Sh NAME 23.Nm gethostbyname , 24.Nm gethostbyaddr , 25.Nm gethostent , 26.Nm sethostent , 27.Nm endhostent , 28.Nm herror 29.Nd get network host entry 30.Sh SYNOPSIS 31.Fd #include <netdb.h> 32.Ft extern int 33.Fa h_errno ; 34.Pp 35.Ft struct hostent * 36.Fn gethostbyname "char *name" 37.Ft struct hostent * 38.Fn gethostbyname2 "char *name" "int af" 39.Ft struct hostent * 40.Fn gethostbyaddr "char *addr" "int len, type" 41.Ft struct hostent * 42.Fn gethostent 43.Fn sethostent "int stayopen" 44.Fn endhostent 45.Fn herror "char *string" 46.Sh DESCRIPTION 47.Fn Gethostbyname , 48.Fn gethostbyname2 , 49and 50.Fn gethostbyaddr 51each return a pointer to a 52.Ft hostent 53structure (see below) describing an internet host 54referenced by name or by address, as the function names indicate. 55This structure contains either the information obtained from the name server, 56or broken-out fields from a line in 57.Pa /etc/hosts . 58If the local name server is not running, these routines do a lookup in 59.Pa /etc/hosts . 60.Bd -literal -offset indent 61struct hostent { 62 char *h_name; /* official name of host */ 63 char **h_aliases; /* alias list */ 64 int h_addrtype; /* host address type */ 65 int h_length; /* length of address */ 66 char **h_addr_list; /* list of addresses from name server */ 67}; 68 69#define h_addr h_addr_list[0] /* address, for backward compatibility */ 70.Ed 71.Pp 72The members of this structure are: 73.Bl -tag -width "h_addr_list" 74.It h_name 75Official name of the host. 76.It h_aliases 77A zero-terminated array of alternate names for the host. 78.It h_addrtype 79The type of address being returned; usually 80.Dv AF_INET . 81.It h_length 82The length, in bytes, of the address. 83.It h_addr_list 84A zero-terminated array of network addresses for the host. 85Host addresses are returned in network byte order. 86.It h_addr 87The first address in 88.Li h_addr_list ; 89this is for backward compatibility. 90.El 91.Pp 92When using the nameserver, 93.Fn gethostbyname 94will search for the named host in each parent domain given in the 95.Dq Li search 96directive of 97.Xr resolv.conf @FORMAT_EXT@ 98unless the name contains a dot 99.Pq Dq \&. . 100If the name contains no dot, and if the environment variable 101.Ev HOSTALIASES 102contains the name of an alias file, the alias file will first be searched 103for an alias matching the input name. 104See 105.Xr hostname @DESC_EXT@ 106for the domain search procedure and the alias file format. 107.Pp 108.Fn Gethostbyname2 109is an evolution of 110.Fn gethostbyname 111intended to allow lookups in address families other than 112.Dv AF_INET , 113for example, 114.Dv AF_INET6 . 115Currently, the 116.Fa af 117argument must be specified as 118.Dv AF_INET 119else the function will return 120.Dv NULL 121after having set 122.Ft h_errno 123to 124.Dv NETDB_INTERNAL . 125.Pp 126.Fn Sethostent 127may be used to request the use of a connected TCP socket for queries. 128If the 129.Fa stayopen 130flag is non-zero, 131this sets the option to send all queries to the name server using TCP 132and to retain the connection after each call to 133.Fn gethostbyname 134or 135.Fn gethostbyaddr . 136Otherwise, queries are performed using UDP datagrams. 137.Pp 138.Fn Endhostent 139closes the TCP connection. 140.Sh ENVIRONMENT 141.Bl -tag -width "HOSTALIASES " -compact 142.It Ev HOSTALIASES 143Name of file containing 144.Pq Ar host alias , full hostname 145pairs. 146.El 147.Sh FILES 148.Bl -tag -width "HOSTALIASES " -compact 149.It Pa /etc/hosts 150See 151.Xr hosts @FORMAT_EXT@ . 152.El 153.Sh DIAGNOSTICS 154.Pp 155Error return status from 156.Fn gethostbyname 157and 158.Fn gethostbyaddr 159is indicated by return of a null pointer. 160The external integer 161.Ft h_errno 162may then be checked to see whether this is a temporary failure 163or an invalid or unknown host. 164The routine 165.Fn herror 166can be used to print an error message describing the failure. 167If its argument 168.Fa string 169is non-NULL, it is printed, followed by a colon and a space. 170The error message is printed with a trailing newline. 171.Pp 172.Ft h_errno 173can have the following values: 174.Bl -tag -width "HOST_NOT_FOUND " -offset indent 175.It Dv NETDB_INTERNAL 176This indicates an internal error in the library, unrelated to the network 177or name service. 178.Ft errno 179will be valid in this case; see 180.Xr perror @SYSCALL_EXT@ . 181.It Dv HOST_NOT_FOUND 182No such host is known. 183.It Dv TRY_AGAIN 184This is usually a temporary error 185and means that the local server did not receive 186a response from an authoritative server. 187A retry at some later time may succeed. 188.It Dv NO_RECOVERY 189Some unexpected server failure was encountered. 190This is a non-recoverable error, as one might expect. 191.It Dv NO_DATA 192The requested name is valid but does not have an IP address; 193this is not a temporary error. 194This means that the name is known to the name server but there is no address 195associated with this name. 196Another type of request to the name server using this domain name 197will result in an answer; 198for example, a mail-forwarder may be registered for this domain. 199.El 200.Sh SEE ALSO 201.Xr hosts @FORMAT_EXT@ , 202.Xr hostname @DESC_EXT@ , 203.Xr resolver @LIB_NETWORK_EXT@ , 204.Xr resolver @FORMAT_EXT@ . 205.Sh CAVEAT 206.Pp 207.Fn Gethostent 208is defined, and 209.Fn sethostent 210and 211.Fn endhostent 212are redefined, 213when 214.Pa libc 215is built to use only the routines to lookup in 216.Pa /etc/hosts 217and not the name server: 218.Bd -ragged -offset indent 219.Pp 220.Fn Gethostent 221reads the next line of 222.Pa /etc/hosts , 223opening the file if necessary. 224.Pp 225.Fn Sethostent 226is redefined to open and rewind the file. If the 227.Fa stayopen 228argument is non-zero, 229the hosts data base will not be closed after each call to 230.Fn gethostbyname 231or 232.Fn gethostbyaddr . 233.Pp 234.Fn Endhostent 235is redefined to close the file. 236.Ed 237.Sh BUGS 238All information is contained in a static area so it must be copied if it is 239to be saved. Only the Internet address format is currently understood. 240