1 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org> 2 .\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. 3 .\" Copyright 1989 AT&T. 4 .\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved 5 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at 6 .\" http://www.opengroup.org/bookstore/. 7 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. 8 .\" This notice shall appear on any product containing this material. 9 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. 10 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. 11 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] 12 .Dd Jul 22, 2014 13 .Dt GETHOSTBYNAME 3NSL 14 .Os 15 .Sh NAME 16 .Nm gethostbyname , 17 .Nm gethostbyname_r , 18 .Nm gethostbyaddr , 19 .Nm gethostbyaddr_r 20 .Nd lookup network host entry 21 .Sh SYNOPSIS 22 .Ic cc 23 .Op Ar flag No Ns ... 24 .Ar file No Ns ... 25 .Fl lnsl 26 .Op Ar library No Ns ... 27 .Lp 28 .In netdb.h 29 .Ft "struct hostent *" 30 .Fn gethostbyname "const char *name" 31 .Ft "struct hostent *" 32 .Fo gethostbyname_r 33 .Fa "const char *name" 34 .Fa "struct hostent *result" 35 .Fa "char *buffer" 36 .Fa "int buflen" 37 .Fa "int *h_errnop" 38 .Fc 39 .Ft "struct hostent *" 40 .Fo gethostbyaddr 41 .Fa "const char *addr" 42 .Fa "socklen_t len" 43 .Fa "int type" 44 .Fc 45 .Ft "struct hostent *" 46 .Fo gethostbyaddr_r 47 .Fa "const char *addr" 48 .Fa "int length" 49 .Fa "int type" 50 .Fa "struct hostent *result" 51 .Fa "char *buffer" 52 .Fa "int buflen" 53 .Fa "int *h_errnop" 54 .Fc 55 .Sh DESCRIPTION 56 These functions are used to obtain entries describing hosts. An entry can come 57 from any of the sources for 58 .Sy hosts 59 specified in the 60 .Pa /etc/nsswitch.conf 61 file. See 62 .Xr nsswitch.conf 4 . 63 These functions have been superseded by 64 .Xr getipnodebyname 3SOCKET , 65 .Xr getipnodebyaddr 3SOCKET , 66 and 67 .Xr getaddrinfo 3SOCKET , 68 which provide 69 greater portability to applications when multithreading is performed or 70 technologies such as IPv6 are used. For example, the functions described in the 71 following cannot be used with applications targeted to work with IPv6. 72 .Lp 73 The 74 .Fn gethostbyname 75 function searches for information for a host with the 76 hostname specified by the character-string parameter 77 .Fa name . 78 .Lp 79 The 80 .Fn gethostbyaddr 81 function searches for information for a host with a 82 given host address. The parameter 83 .Fa type 84 specifies the family of the 85 address. This should be one of the address families defined in 86 .In sys/socket.h . 87 See the 88 .Sx NOTES 89 section for more information. Also 90 see the 91 .Sx EXAMPLES 92 section for information on how to convert an Internet 93 Protocol address notation that is separated by periods (.) into an 94 .Fa addr 95 parameter. The parameter 96 .Fa len 97 specifies the length of the buffer indicated 98 by 99 .Fa addr . 100 .Lp 101 All addresses are returned in network order. In order to interpret the 102 addresses, 103 .Xr byteorder 3SOCKET 104 must be used for byte order conversion. 105 .Ss "Reentrant Interfaces" 106 The 107 .Fn gethostbyname 108 and 109 .Fn gethostbyaddr 110 functions use static storage that is reused in each call, making these 111 functions unsafe for use in multithreaded applications. 112 .Lp 113 The 114 .Fn gethostbyname_r 115 and 116 .Fn gethostbyaddr_r 117 functions provide reentrant interfaces for these operations. 118 .Lp 119 Each reentrant interface performs the same operation as its non-reentrant 120 counterpart, named by removing the 121 .Sy _r 122 suffix. The reentrant interfaces, 123 however, use buffers supplied by the caller to store returned results and the 124 interfaces are safe for use in both single-threaded and multithreaded 125 applications. 126 .Lp 127 Each reentrant interface takes the same parameters as its non-reentrant 128 counterpart, as well as the following additional parameters. The parameter 129 .Fa result 130 must be a pointer to a 131 .Vt "struct hostent" 132 structure allocated by 133 the caller. On successful completion, the function returns the host entry in 134 this structure. The parameter 135 .Fa buffer 136 must be a pointer to a buffer 137 supplied by the caller. This buffer is used as storage space for the host data. 138 All of the pointers within the returned 139 .Vt "struct hostent" 140 point to data stored within this buffer. See the 141 .Sx RETURN VALUES 142 section for more 143 information. The buffer must be large enough to hold all of the data associated 144 with the host entry. The parameter 145 .Fa buflen 146 should give the size in bytes 147 of the buffer indicated by 148 .Fa buffer . 149 The parameter 150 .Fa h_errnop 151 should be 152 a pointer to an integer. An integer error status value is stored there on 153 certain error conditions. See the 154 .Sx ERRORS 155 section for more information. 156 .Sh RETURN VALUES 157 Host entries are represented by the 158 .Vt "struct hostent" 159 structure defined in 160 .In netdb.h : 161 .Bd -literal -offset indent 162 struct hostent { 163 char *h_name; /* canonical name of host */ 164 char **h_aliases; /* alias list */ 165 int h_addrtype; /* host address type */ 166 int h_length; /* length of address */ 167 char **h_addr_list; /* list of addresses */ 168 }; 169 .Ed 170 .Lp 171 See the 172 .Sx EXAMPLES 173 section for information about how to retrieve a 174 .Sq \&. 175 separated Internet Protocol address string from the 176 .Fa h_addr_list 177 field of 178 .Vt "struct hostent" . 179 .Lp 180 The 181 .Fn gethostbyname , 182 .Fn gethostbyname_r , 183 .Fn gethostbyaddr , 184 and 185 .Fn gethostbyaddr_r 186 functions each return a pointer to a 187 .Vt "struct hostent" 188 if they successfully locate the requested entry; otherwise they 189 return 190 .Dv NULL . 191 .Lp 192 The 193 .Fn gethostbyname 194 and 195 .Fn gethostbyaddr 196 functions use static storage, so returned data must be copied before a 197 subsequent call to any of these functions if the data is to be saved. 198 .Lp 199 When the pointer returned by the reentrant functions 200 .Fn gethostbyname_r 201 and 202 .Fn gethostbyaddr_r 203 is not 204 .Dv NULL , 205 it is always equal to the 206 .Fa result 207 pointer that was supplied by the caller. 208 .Sh FILES 209 .Bl -tag -width Pa 210 .It Pa /etc/hosts 211 hosts file that associates the names of hosts with their Internet Protocol (IP) 212 addresses 213 .It Pa /etc/nsswitch.conf 214 configuration file for the name service switch 215 .El 216 .Sh EXAMPLES 217 .Ss Example 1 Using gethostbyaddr() 218 Here is a sample program that gets the canonical name, aliases, and ``.'' 219 separated Internet Protocol addresses for a given ``.'' separated IP 220 address: 221 .Bd -literal -offset indent 222 #include <stdio.h> 223 #include <stdlib.h 224 #include <string.h> 225 #include <sys/types.h> 226 #include <sys/socket.h> 227 #include <netinet/in.h> 228 #include <arpa/inet.h> 229 #include <netdb.h> 230 int main(int argc, const char **argv) 231 { 232 in_addr_t addr; 233 struct hostent *hp; 234 char **p; 235 if (argc != 2) { 236 (void) printf("usage: %s IP-address\en", argv[0]); 237 exit (1); 238 } 239 if ((int)(addr = inet_addr(argv[1])) == -1) { 240 (void) printf("IP-address must be of form a.b.c.d\en"); 241 exit (2); 242 } 243 hp = gethostbyaddr((char *)&addr, 4, AF_INET); 244 if (hp == NULL) { 245 (void) printf("host %s not found\en", argv[1]); 246 exit (3); 247 } 248 for (p = hp->h_addr_list; *p != 0; p++) { 249 struct in_addr in; 250 char **q; 251 (void) memcpy(&in.s_addr, *p, sizeof (in.s_addr)); 252 (void) printf("%s\t%s", inet_ntoa(in), hp\(mi>h_name); 253 for (q = hp->h_aliases; *q != 0; q++) 254 (void) printf(" %s", *q); 255 (void) putchar('\en'); 256 } 257 exit (0); 258 } 259 .Ed 260 .Lp 261 Note that the preceding sample program is unsafe for use in multithreaded 262 applications. 263 .Sh ERRORS 264 The reentrant functions 265 .Fn gethostbyname_r 266 and 267 .Fn gethostbyaddr_r 268 will return 269 .Dv NULL 270 and set 271 .Va errno 272 to 273 .Er ERANGE 274 if the length of the buffer supplied by caller is not large enough to store the 275 result. See 276 .Xr Intro 2 277 for the proper usage and interpretation of 278 .Va errno 279 in multithreaded applications. 280 .Lp 281 The reentrant functions 282 .Fn gethostbyname_r 283 and 284 .Fn gethostbyaddr_r 285 set the integer pointed to by 286 .Fa h_errnop 287 to one of these values in case of error. 288 .Lp 289 On failures, the non-reentrant functions 290 .Fn gethostbyname 291 and 292 .Fn gethostbyaddr 293 set a global integer 294 .Va h_errno 295 to indicate one of 296 these error codes 297 .Po defined in 298 .In netdb.h Pc : 299 .Dv HOST_NOT_FOUND , 300 .Dv TRY_AGAIN , 301 .Dv NO_RECOVERY , 302 .Dv NO_DATA , 303 and 304 .Dv NO_ADDRESS . 305 .Lp 306 If a resolver is provided with a malformed address, or if any other error 307 occurs before 308 .Fn gethostbyname 309 is resolved, then 310 .Fn gethostbyname 311 returns an internal error with a value of \(mi1. 312 .Lp 313 The 314 .Fn gethostbyname 315 function will set 316 .Va h_errno 317 to 318 .Dv NETDB_INTERNAL 319 when it returns a 320 .Dv NULL 321 value. 322 .Sh INTERFACE STABILITY 323 The 324 .Fn gethostbyname 325 and 326 .Fn gethostbyaddr 327 functions are 328 .Sy Obsolete Standard . 329 .Lp 330 The 331 .Fn gethostbyname_r 332 and 333 .Fn gethostbyaddr_r 334 functions are 335 .Sy Obsolete Uncommitted . 336 .Sh MT-LEVEL 337 The 338 .Fn gethostbyname 339 and 340 .Fn gethostbyaddr 341 functions are 342 .Sy Unsafe . 343 .Lp 344 The 345 .Fn gethostbyname_r 346 and 347 .Fn gethostbyaddr_r 348 functions are 349 .Sy Safe . 350 .Sh SEE ALSO 351 .Xr Intro 2 , 352 .Xr netdb.h 3HEAD , 353 .Xr netdir 3NSL , 354 .Xr byteorder 3SOCKET, 355 .Xr getaddrinfo 3SOCKET 356 .Xr getnameinfo 3SOCKET 357 .Xr inet 3SOCKET , 358 .Xr hosts 4 , 359 .Xr nss 4 , 360 .Xr nsswitch.conf 4 , 361 .Xr standards 5 362 .Sh NOTES 363 The reentrant interfaces 364 .Fn gethostbyname_r 365 and 366 .Fn gethostbyaddr_r 367 are included in this release on an uncommitted basis only 368 and are subject to change or removal in future minor releases. 369 .Lp 370 To ensure that they all return consistent results, 371 .Fn gethostbyname , 372 .Fn gethostbyname_r , 373 and 374 .Xr netdir_getbyname 3NSL 375 are implemented in terms 376 of the same internal library function. This function obtains the system-wide 377 source lookup policy based on the 378 .Sy hosts: 379 entry in 380 .Xr nsswitch.conf 4 . 381 Similarly, 382 .Fn gethostbyaddr , 383 .Fn gethostbyaddr_r , 384 and 385 .Xr netdir_getbyaddr 3NSL 386 are implemented in terms of the same internal library 387 function, which also is driven by the 388 .Sy hosts: 389 entry in 390 .Xr nsswitch.conf 4 . 391 .Lp 392 These functions must always return the 393 .Em canonical name 394 in the 395 .Fa h_name 396 field. This name, by definition, is 397 the well-known and official hostname shared between all aliases and all 398 addresses. The underlying source that satisfies the request determines the 399 mapping of the input name or address into the set of names and addresses in 400 .Fa hostent . 401 Different sources might do that in different ways. If there is 402 more than one alias and more than one address in 403 .Fa hostent , 404 no pairing is 405 implied between them. 406 .Lp 407 The system attempts to put those addresses that are on the same subnet as the 408 caller before addresses that are on different subnets. However, if address 409 sorting is disabled by setting 410 .Sy SORT_ADDRS 411 to 412 .Sy FALSE 413 in the 414 .Pa /etc/default/nss 415 file, the system does not put the local subnet addresses 416 first. See 417 .Xr nss 4 418 for more information. 419 .Lp 420 The current implementations of these functions only return or accept addresses 421 for the Internet address family 422 .Po type Dv AF_INET Pc . 423 .Lp 424 The form for an address of type 425 .Dv AF_INET 426 is a 427 .Vt "struct in_addr" 428 defined 429 .In netinet/in.h . 430 The functions described in 431 .Xr inet 3SOCKET , 432 and illustrated in the 433 .Sx EXAMPLES 434 section, are helpful in constructing and 435 manipulating addresses in this form. 436 .Sh STANDARDS 437 The 438 .Fn gethostbyaddr 439 and 440 .Fn gethostbyname 441 functions were introduced in 442 .Bx 4.2 , 443 and standardized in 444 .St -xns5.2 445 and 446 .St -p1003.1-2001 . 447 They were subsequently removed from 448 .St -p1003.1-2008 .