man3/gethostbyname.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\"
   3 .\" Permission is granted to make and distribute verbatim copies of this
   4 .\" manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\" Permission is granted to copy and distribute modified versions of this
   8 .\" manual under the conditions for verbatim copying, provided that the
   9 .\" entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\" Since the Linux kernel and libraries are constantly changing, this
  13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  14 .\" responsibility for errors or omissions, or for damages resulting from
  15 .\" the use of the information contained herein.  The author(s) may not
  16 .\" have taken the same level of care in the production of this manual,
  17 .\" which is licensed free of charge, as they might when working
  18 .\" professionally.
  19 .\"
  20 .\" Formatted or processed versions of this manual, if unaccompanied by
  21 .\" the source, must acknowledge the copyright and authors of this work.
  22 .\"
  23 .\" References consulted:
  24 .\"     Linux libc source code
  25 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
  26 .\"     386BSD man pages
  27 .\" Modified 1993-05-22, David Metcalfe
  28 .\" Modified 1993-07-25, Rik Faith (faith@cs.unc.edu)
  29 .\" Modified 1997-02-16, Andries Brouwer (aeb@cwi.nl)
  30 .\" Modified 1998-12-21, Andries Brouwer (aeb@cwi.nl)
  31 .\" Modified 2000-08-12, Andries Brouwer (aeb@cwi.nl)
  32 .\" Modified 2001-05-19, Andries Brouwer (aeb@cwi.nl)
  33 .\" Modified 2002-08-05, Michael Kerrisk
  34 .\" Modified 2004-10-31, Andries Brouwer
  35 .\"
  36 .TH GETHOSTBYNAME 3 2004-10-31 "" "Linux Programmer's Manual"
  37 .SH NAME
  38 gethostbyname, gethostbyaddr, sethostent, gethostent, endhostent,
  39 herror, hstrerror \- get network host entry
  40 .SH SYNOPSIS
  41 .nf
  42 .B #include <netdb.h>
  43 .B extern int h_errno;
  44 .sp
  45 .BI "struct hostent *gethostbyname(const char *" name );
  46 .sp
  47 .BR "#include <sys/socket.h>" "       /* for AF_INET */"
  48 .BI "struct hostent *gethostbyaddr(const void *" addr \
  49 ", socklen_t " len ", int " type );
  50 .sp
  51 .BI "void sethostent(int " stayopen );
  52 .sp
  53 .B void endhostent(void);
  54 .sp
  55 .BI "void herror(const char *" s );
  56 .sp
  57 .BI "const char *hstrerror(int " err );
  58 .sp
  59 /* System V/POSIX extension */
  60 .br
  61 .B struct hostent *gethostent(void);
  62 .sp
  63 /* GNU extensions */
  64 .br
  65 .BI "struct hostent *gethostbyname2(const char *" name ", int " af );
  66 .sp
  67 .BI "int gethostent_r("
  68 .BI "        struct hostent *" ret ", char *" buf ", size_t " buflen ,
  69 .BI "        struct hostent **" result ", int *" h_errnop );
  70 .sp
  71 .BI "int gethostbyname_r(const char *" name ,
  72 .BI "        struct hostent *" ret ", char *" buf ", size_t " buflen ,
  73 .BI "        struct hostent **" result ", int *" h_errnop );
  74 .sp
  75 .BI "int gethostbyname2_r(const char *" name ", int " af,
  76 .BI "        struct hostent *" ret ", char *" buf ", size_t " buflen ,
  77 .BI "        struct hostent **" result ", int *" h_errnop );
  78 .fi
  79 .SH DESCRIPTION
  80 The
  81 .BR gethostbyname ()
  82 function returns a structure of type
  83 .I hostent
  84 for the given host
  85 .IR name .
  86 Here
  87 .I name
  88 is either a host name, or an IPv4 address in standard dot notation,
  89 or an IPv6 address in colon (and possibly dot) notation.
  90 (See RFC\ 1884 for the description of IPv6 addresses.)
  91 If
  92 .I name
  93 is an IPv4 or IPv6 address, no lookup is performed and
  94 .BR gethostbyname ()
  95 simply copies
  96 .I name
  97 into the
  98 .I h_name
  99 field and its
 100 .I struct in_addr
 101 equivalent into the
 102 .I h_addr_list[0]
 103 field of the returned
 104 .I hostent
 105 structure.
 106 If
 107 .I name
 108 doesn't end in a dot and the environment variable
 109 .B HOSTALIASES
 110 is set, the alias file pointed to by
 111 .B HOSTALIASES
 112 will first be searched for
 113 .I name
 114 (see
 115 .BR hostname (7)
 116 for the file format).
 117 The current domain and its parents are searched unless \fIname\fP
 118 ends in a dot.
 119 .PP
 120 The
 121 .BR gethostbyaddr ()
 122 function returns a structure of type \fIhostent\fP
 123 for the given host address \fIaddr\fP of length \fIlen\fP and address type
 124 \fItype\fP.
 125 Valid address types are
 126 .B AF_INET
 127 and
 128 .BR AF_INET6 .
 129 The host address argument is a pointer to a struct of a type depending
 130 on the address type, for example a \fBstruct in_addr *\fP (probably
 131 obtained via a call to
 132 .BR inet_addr (3))
 133 for address type AF_INET.
 134 .PP
 135 The
 136 .BR sethostent ()
 137 function specifies, if \fIstayopen\fP is true (1),
 138 that a connected TCP socket should be used for the name server queries and
 139 that the connection should remain open during successive queries.
 140 Otherwise, name server queries will use UDP datagrams.
 141 .PP
 142 The
 143 .BR endhostent ()
 144 function ends the use of a TCP connection for name
 145 server queries.
 146 .PP
 147 The (obsolete)
 148 .BR herror ()
 149 function prints the error message associated
 150 with the current value of \fIh_errno\fP on \fIstderr\fp.
 151 .PP
 152 The (obsolete)
 153 .BR hstrerror ()
 154 function takes an error number
 155 (typically \fIh_errno\fP) and returns the corresponding message string.
 156 .PP
 157 The domain name queries carried out by
 158 .BR gethostbyname ()
 159 and
 160 .BR gethostbyaddr ()
 161 use a combination of any or all of the name server
 162 .BR named (8),
 163 a broken out line from \fI/etc/hosts\fP, and the Network
 164 Information Service (NIS or YP), depending upon the contents of the
 165 \fIorder\fP line in
 166 .IR /etc/host.conf .
 167 .\" (See
 168 .\" .BR resolv+ (8)).
 169 The default action is to query
 170 .BR named (8),
 171 followed by
 172 .IR /etc/hosts .
 173 .PP
 174 The \fIhostent\fP structure is defined in \fI<netdb.h>\fP as follows:
 175 .sp
 176 .in +0.5i
 177 .nf
 178 .ne 7
 179 struct hostent {
 180     char  *h_name;            /* official name of host */
 181     char **h_aliases;         /* alias list */
 182     int    h_addrtype;        /* host address type */
 183     int    h_length;          /* length of address */
 184     char **h_addr_list;       /* list of addresses */
 185 }
 186 #define h_addr h_addr_list[0] /* for backward compatibility */
 187 .fi
 188 .in -0.5i
 189 .PP
 190 The members of the \fIhostent\fP structure are:
 191 .TP
 192 .I h_name
 193 The official name of the host.
 194 .TP
 195 .I h_aliases
 196 An array of alternative names for the host, terminated by a NULL pointer.
 197 .TP
 198 .I h_addrtype
 199 The type of address; always
 200 .B AF_INET
 201 or
 202 .B AF_INET6
 203 at present.
 204 .TP
 205 .I h_length
 206 The length of the address in bytes.
 207 .TP
 208 .I h_addr_list
 209 An array of pointers to network addresses for the host (in network byte
 210 order), terminated by a NULL pointer.
 211 .TP
 212 .I h_addr
 213 The first address in \fIh_addr_list\fP for backward compatibility.
 214 .SH "RETURN VALUE"
 215 The
 216 .BR gethostbyname ()
 217 and
 218 .BR gethostbyaddr ()
 219 functions return the
 220 .I hostent
 221 structure or a NULL pointer if an error occurs.
 222 On error, the
 223 .I h_errno
 224 variable holds an error number.
 225 When non-NULL, the return value may point at static data, see the notes below.
 226 .SH ERRORS
 227 The variable \fIh_errno\fP can have the following values:
 228 .TP
 229 .B HOST_NOT_FOUND
 230 The specified host is unknown.
 231 .TP
 232 .BR NO_ADDRESS " or " NO_DATA
 233 The requested name is valid but does not have an IP address.
 234 .TP
 235 .B NO_RECOVERY
 236 A non-recoverable name server error occurred.
 237 .TP
 238 .B TRY_AGAIN
 239 A temporary error occurred on an authoritative name server.
 240 Try again later.
 241 .SH FILES
 242 .TP
 243 .I /etc/host.conf
 244 resolver configuration file
 245 .TP
 246 .I /etc/hosts
 247 host database file
 248 .TP
 249 .I /etc/nsswitch.conf
 250 name service switch configuration
 251 .SH "CONFORMING TO"
 252 4.3BSD, POSIX.1-2001.
 253 .SH NOTES
 254 The functions
 255 .BR gethostbyname ()
 256 and
 257 .BR gethostbyaddr ()
 258 may return pointers to static data, which may be overwritten by
 259 later calls.
 260 Copying the
 261 .I struct hostent
 262 does not suffice, since it contains pointers; a deep copy is required.
 263 .LP
 264 In the original BSD implementation the
 265 .I len
 266 argument
 267 of
 268 .BR gethostbyname ()
 269 was an
 270 .IR int .
 271 The SUSv2 standard is buggy and declares the
 272 .I len
 273 parameter of
 274 .BR gethostbyaddr ()
 275 to be of type
 276 .IR size_t .
 277 (That is wrong, because it has to be
 278 .IR int ,
 279 and
 280 .I size_t
 281 is not.
 282 POSIX.1-2001 makes it
 283 .IR socklen_t ,
 284 which is OK.)
 285 See also
 286 .BR accept (2).
 287 .LP
 288 The BSD prototype for
 289 .BR gethostbyaddr ()
 290 uses
 291 .I const char *
 292 for the first argument.
 293 .LP
 294 POSIX.1-2001 marks
 295 .BR gethostbyaddr ()
 296 and
 297 .BR gethostbyname ()
 298 obsolescent.
 299 See
 300 .BR getaddrinfo (3),
 301 .BR getnameinfo (3),
 302 .BR gai_strerror (3).
 303 .SS "System V/POSIX Extension"
 304 POSIX requires the
 305 .BR gethostent ()
 306 call, that should return the next entry in the host data base.
 307 When using DNS/BIND this does not make much sense, but it may
 308 be reasonable if the host data base is a file that can be read
 309 line by line.
 310 On many systems a routine of this name reads
 311 from the file
 312 .IR /etc/hosts .
 313 .\" e.g., Linux, FreeBSD, Unixware, HP-UX
 314 It may be available only when the library was built without DNS support.
 315 .\" e.g., FreeBSD, AIX
 316 The glibc version will ignore ipv6 entries.
 317 This function is not reentrant,
 318 and glibc adds a reentrant version
 319 .BR gethostent_r ().
 320 .SS "GNU Extensions"
 321 Glibc2 also has a
 322 .BR gethostbyname2 ()
 323 that works like
 324 .BR gethostbyname (),
 325 but permits to specify the address family to which the address must belong.
 326 .LP
 327 Glibc2 also has reentrant versions
 328 .BR gethostbyname_r ()
 329 and
 330 .BR gethostbyname2_r ().
 331 These return 0 on success and non-zero on error.
 332 The result of the call
 333 is now stored in the struct with address
 334 .IR ret .
 335 After the call,
 336 .RI * result
 337 will be NULL on error or point to the result on success.
 338 Auxiliary data is stored in the buffer
 339 .I buf
 340 of length
 341 .IR buflen .
 342 (If the buffer is too small, these functions will return
 343 .BR ERANGE .)
 344 No global variable
 345 .I h_errno
 346 is modified, but the address of a variable in which to store error numbers
 347 is passed in
 348 .IR h_errnop .
 349 .SH "SEE ALSO"
 350 .BR getaddrinfo (3),
 351 .BR getipnodebyaddr (3),
 352 .BR getipnodebyname (3),
 353 .BR getnameinfo (3),
 354 .BR inet_ntop (3),
 355 .BR inet_pton (3),
 356 .BR resolver (3),
 357 .BR hosts (5),
 358 .BR nsswitch.conf (5),
 359 .BR hostname (7),
 360 .BR named (8)
 361 .\" .BR resolv+ (8)