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 ", int " 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 \fIinet_addr\fP()) for address type AF_INET.
 132 .PP
 133 The
 134 .BR sethostent ()
 135 function specifies, if \fIstayopen\fP is true (1),
 136 that a connected TCP socket should be used for the name server queries and
 137 that the connection should remain open during successive queries.
 138 Otherwise, name server queries will use UDP datagrams.
 139 .PP
 140 The
 141 .BR endhostent ()
 142 function ends the use of a TCP connection for name
 143 server queries.
 144 .PP
 145 The (obsolete)
 146 .BR herror ()
 147 function prints the error message associated
 148 with the current value of \fIh_errno\fP on stderr.
 149 .PP
 150 The (obsolete)
 151 .BR hstrerror ()
 152 function takes an error number
 153 (typically \fIh_errno\fP) and returns the corresponding message string.
 154 .PP
 155 The domain name queries carried out by
 156 .BR gethostbyname ()
 157 and
 158 .BR gethostbyaddr ()
 159 use a combination of any or all of the name server
 160 .BR named (8),
 161 a broken out line from \fI/etc/hosts\fP, and the Network
 162 Information Service (NIS or YP), depending upon the contents of the
 163 \fIorder\fP line in
 164 .IR /etc/host.conf .
 165 .\" (See
 166 .\" .BR resolv+ (8)).
 167 The default action is to query
 168 .BR named (8),
 169 followed by
 170 .IR /etc/hosts .
 171 .PP
 172 The \fIhostent\fP structure is defined in \fI<netdb.h>\fP as follows:
 173 .sp
 174 .in +0.5i
 175 .nf
 176 .ne 7
 177 struct hostent {
 178     char  *h_name;            /* official name of host */
 179     char **h_aliases;         /* alias list */
 180     int    h_addrtype;        /* host address type */
 181     int    h_length;          /* length of address */
 182     char **h_addr_list;       /* list of addresses */
 183 }
 184 #define h_addr h_addr_list[0] /* for backward compatibility */
 185 .fi
 186 .in -0.5i
 187 .PP
 188 The members of the \fIhostent\fP structure are:
 189 .TP
 190 .I h_name
 191 The official name of the host.
 192 .TP
 193 .I h_aliases
 194 An array of alternative names for the host, terminated by a NULL pointer.
 195 .TP
 196 .I h_addrtype
 197 The type of address; always
 198 .B AF_INET
 199 or
 200 .B AF_INET6
 201 at present.
 202 .TP
 203 .I h_length
 204 The length of the address in bytes.
 205 .TP
 206 .I h_addr_list
 207 An array of pointers to network addresses for the host (in network byte
 208 order), terminated by a NULL pointer.
 209 .TP
 210 .I h_addr
 211 The first address in \fIh_addr_list\fP for backward compatibility.
 212 .SH "RETURN VALUE"
 213 The
 214 .BR gethostbyname ()
 215 and
 216 .BR gethostbyaddr ()
 217 functions return the
 218 .I hostent
 219 structure or a NULL pointer if an error occurs.
 220 On error, the
 221 .I h_errno
 222 variable holds an error number.
 223 When non-NULL, the return value may point at static data, see the notes below.
 224 .SH ERRORS
 225 The variable \fIh_errno\fP can have the following values:
 226 .TP
 227 .B HOST_NOT_FOUND
 228 The specified host is unknown.
 229 .TP
 230 .BR NO_ADDRESS " or " NO_DATA
 231 The requested name is valid but does not have an IP address.
 232 .TP
 233 .B NO_RECOVERY
 234 A non-recoverable name server error occurred.
 235 .TP
 236 .B TRY_AGAIN
 237 A temporary error occurred on an authoritative name server.
 238 Try again later.
 239 .SH FILES
 240 .TP
 241 .I /etc/host.conf
 242 resolver configuration file
 243 .TP
 244 .I /etc/hosts
 245 host database file
 246 .TP
 247 .I /etc/nsswitch.conf
 248 name service switch configuration
 249 .SH "CONFORMING TO"
 250 4.3BSD, POSIX.1-2001.
 251 .SH "SYSTEM V/POSIX EXTENSION"
 252 POSIX requires the
 253 .BR gethostent ()
 254 call, that should return the next entry in the host data base.
 255 When using DNS/BIND this does not make much sense, but it may
 256 be reasonable if the host data base is a file that can be read
 257 line by line.
 258 On many systems a routine of this name reads
 259 from the file
 260 .IR /etc/hosts .
 261 .\" e.g. Linux, FreeBSD, Unixware, HP-UX
 262 It may be available only when the library was built without DNS support.
 263 .\" e.g. FreeBSD, AIX
 264 The glibc version will ignore ipv6 entries.
 265 This function is not reentrant,
 266 and glibc adds a reentrant version
 267 .BR gethostent_r ().
 268 .SH "GNU EXTENSIONS"
 269 Glibc2 also has a
 270 .BR gethostbyname2 ()
 271 that works like
 272 .BR gethostbyname (),
 273 but permits to specify the address family to which the address must belong.
 274 .LP
 275 Glibc2 also has reentrant versions
 276 .BR gethostbyname_r ()
 277 and
 278 .BR gethostbyname2_r ().
 279 These return 0 on success and non-zero on error.
 280 The result of the call
 281 is now stored in the struct with address
 282 .IR ret .
 283 After the call,
 284 .RI * result
 285 will be NULL on error or point to the result on success.
 286 Auxiliary data is stored in the buffer
 287 .I buf
 288 of length
 289 .IR buflen .
 290 (If the buffer is too small, these functions will return
 291 .BR ERANGE .)
 292 No global variable
 293 .I h_errno
 294 is modified, but the address of a variable in which to store error numbers
 295 is passed in
 296 .IR h_errnop .
 297 .SH NOTES
 298 The functions
 299 .BR gethostbyname ()
 300 and
 301 .BR gethostbyaddr ()
 302 may return pointers to static data, which may be overwritten by
 303 later calls.
 304 Copying the
 305 .I struct hostent
 306 does not suffice, since it contains pointers; a deep copy is required.
 307 .LP
 308 The SUS-v2 standard is buggy and declares the
 309 .I len
 310 parameter of
 311 .BR gethostbyaddr ()
 312 to be of type
 313 .IR size_t .
 314 (That is wrong, because it has to be
 315 .IR int ,
 316 and
 317 .I size_t
 318 is not.
 319 POSIX.1-2001 makes it
 320 .IR socklen_t ,
 321 which is OK.)
 322 .LP
 323 The BSD prototype for
 324 .BR gethostbyaddr ()
 325 uses
 326 .I const char *
 327 for the first argument.
 328 .LP
 329 POSIX.1-2001 marks
 330 .BR gethostbyaddr ()
 331 and
 332 .BR gethostbyname ()
 333 obsolescent.
 334 See
 335 .BR getaddrinfo (3),
 336 .BR getnameinfo (3),
 337 .BR gai_strerror (3).
 338 .SH "SEE ALSO"
 339 .BR getaddrinfo (3),
 340 .BR getipnodebyaddr (3),
 341 .BR getipnodebyname (3),
 342 .BR getnameinfo (3),
 343 .BR inet_ntop (3),
 344 .BR inet_pton (3),
 345 .BR resolver (3),
 346 .BR hosts (5),
 347 .BR nsswitch.conf (5),
 348 .BR hostname (7),
 349 .BR named (8)
 350 .\" .BR resolv+ (8)