contrib/bind/doc/man/gethostbyname.3

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