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 gethostent, gethostent_r, sethostent, endhostent 17 .Nd enumerate network host entries 18 .Sh SYNOPSIS 19 .Ic cc 20 .Op Ar flag No Ns ... 21 .Ar file No Ns ... 22 .Fl lnsl 23 .Op Ar library No Ns ... 24 .Lp 25 .In netdb.h 26 .Ft "struct hostent *" 27 .Fn gethostent "void" 28 .Ft "struct hostent *" 29 .Fo gethostent_r 30 .Fa "struct hostent *result" 31 .Fa "char *buffer" 32 .Fa "int buflen" 33 .Fa "int *h_errnop" 34 .Fc 35 .Ft int 36 .Fn sethostent "int stayopen" 37 .Ft int 38 .Fn endhostent void 39 .Sh DESCRIPTION 40 These functions are used to enumerate entries in the network hosts database. 41 An entries can come 42 from any of the sources for 43 .Sy hosts 44 specified in the 45 .Pa /etc/nsswitch.conf 46 file. See 47 .Xr nsswitch.conf 4 . 48 .Lp 49 All addresses are returned in network order. In order to interpret the 50 addresses, 51 .Xr byteorder 3SOCKET 52 must be used for byte order conversion. 53 .Lp 54 The 55 .Fn sethostent 56 function sets or resets the enumeration to the beginning 57 of the set of host entries. This function should be called before the first 58 call to 59 .Fn gethostent . 60 If the 61 .Fa stayopen 62 flag is non-zero, the system can keep allocated resources 63 such as open file descriptors until a subsequent call to 64 .Fn endhostent . 65 .Lp 66 Successive calls to the 67 .Fn gethostent 68 function return either successive 69 entries or 70 .Dv NULL , 71 indicating the end of the enumeration. 72 .Lp 73 The 74 .Fn endhostent() 75 function can be called to indicate that the caller 76 expects to do no further host entry retrieval operations; the system can then 77 deallocate resources it was using. It is still allowed, but possibly less 78 efficient, for the process to call more host retrieval functions after calling 79 .Fn endhostent . 80 .Lp 81 The 82 .Fn gethostent 83 function uses static storage that is reused in each call, making this 84 function unsafe for use in multithreaded applications. 85 .Lp 86 The 87 .Fn gethostent_r 88 function performs the same function as 89 .Fn gethostent, but provides a reentrant interface. 90 It uses a buffer supplied by the caller to store returned results and 91 is safe for use in both single-threaded and multithreaded applications. 92 .Lp 93 The 94 .Fn gethostent_r 95 function takes the same parameters as 96 .Fn gethostent , 97 as well as the following additional parameters. The parameter 98 .Fa result 99 must be a pointer to a 100 .Vt "struct hostent" 101 structure allocated by the caller. On successful completion, the function 102 returns the host entry in 103 this structure. The parameter 104 .Fa buffer 105 must be a pointer to a buffer 106 supplied by the caller. This buffer is used as storage space for the host data. 107 All of the pointers within the returned 108 .Vt "struct hostent" 109 point to data stored within this buffer. See the 110 .Sx RETURN VALUES 111 section for more 112 information. The buffer must be large enough to hold all of the data associated 113 with the host entry. The parameter 114 .Fa buflen 115 should give the size in bytes 116 of the buffer indicated by 117 .Fa buffer . The parameter 118 .Fa h_errnop 119 should be 120 a pointer to an integer. An integer error status value is stored there on 121 certain error conditions. See the 122 .Sx ERRORS 123 section for more information. 124 .Sh RETURN VALUES 125 The 126 .Fn gethostent 127 and 128 .Fn gethostent_r 129 functions each return a pointer 130 to a 131 .Vt "struct hostent" 132 if they successfully enumerate an entry; otherwise they return 133 .Dv NULL , 134 indicating the end of the enumeration. See 135 .Xr gethostbyname 3NSL 136 for a descriptin of the 137 .Vt "struct hostent" 138 structure. 139 .Lp 140 The 141 .Fn gethostent 142 function uses static storage, so results from from one call may be overwritten 143 by subsequent calls it. 144 .Lp 145 When the pointer returned by 146 .Fn gethostent_r 147 is not 148 .Dv NULL , it is 149 always equal to the 150 .Fa result 151 pointer that was supplied by the caller. 152 .Lp 153 The 154 .Fn sethostent 155 and 156 .Fn endhostent 157 functions return 0 on success. 158 .Sh FILES 159 .Bl -tag -width "/etc/nsswitch.conf" 160 .It Pa /etc/hosts 161 hosts file that associates the names of hosts with their Internet Protocol (IP) 162 addresses 163 .It Pa /etc/nsswitch.conf 164 configuration file for the name service switch 165 .El 166 .Sh ERRORS 167 The 168 .Fn gethostent_r 169 function will return 170 .Dv NULL 171 and set 172 .Va errno 173 to 174 .Er ERANGE 175 if the length of the buffer supplied by caller is not large enough to store the 176 result. It may also store one of the following 177 .Va h_errno 178 values into the location pointed by 179 .Fa h_errnop . On error, the 180 .Fn gethostent 181 function will set the global 182 .Va h_errno 183 value to one of these values: 184 .Dv HOST_NOT_FOUND , 185 .Dv TRY_AGAIN , 186 .Dv NO_RECOVERY , 187 .Dv NO_DATA , 188 .Dv NO_ADDRESS , 189 or 190 .Dv NETDB_INTERNAL . 191 .Sh INTERFACE STABILITY 192 The 193 .Fn gethostent , 194 .Fn sethostent , 195 and 196 .Fn endhostent 197 functions are 198 .Sy Standard . 199 The 200 .Fn gethostent_r 201 function is 202 .Sy Obsolete Uncommitted . 203 .Sh MT-LEVEL 204 The 205 .Fn gethostent 206 function is 207 .Sy Unsafe . 208 .Lp 209 The 210 .Fn gethostent_r , 211 .Fn sethostent , 212 and 213 .Fn endhostent 214 functions are 215 .Sy Safe with Exceptions . 216 For enumeration in multithreaded applications, the position within the 217 enumeration is a process-wide property shared by all threads. 218 If multiple threads interleave 219 calls to these functions, 220 the threads will enumerate disjoint subsets of the host database. 221 .Sh SEE ALSO 222 .Xr byteorder 3SOCKET , 223 .Xr gethostbyname 3NSL , 224 .Xr netdb.h 3HEAD , 225 .Xr hosts 4 , 226 .Xr nss 4 , 227 .Xr nsswitch.conf 4 , 228 .Xr standards 5 229 .Sh NOTES 230 The 231 .Fn gethostent_r 232 function is provided as an 233 .Sy Uncommitted 234 interface, and is subject to removal or change in a subsequent release. 235 .Lp 236 The 237 .Fn gethostent 238 and 239 .Fn gethostent_r 240 functions must always return the 241 .Em canonical name 242 in the 243 .Fa h_name 244 field. This name, by definition, is 245 the well-known and official hostname shared between all aliases and all 246 addresses. The underlying source that satisfies the request determines the 247 mapping of the input name or address into the set of names and addresses in 248 .Fa hostent . 249 Different sources might do that in different ways. If there is 250 more than one alias and more than one address in 251 .Fa hostent , 252 no pairing is implied between them. 253 .Lp 254 The system attempts to put those addresses that are on the same subnet as the 255 caller before addresses that are on different subnets. However, if address 256 sorting is disabled by setting 257 .Sy SORT_ADDRS 258 to 259 .Sy FALSE 260 in the 261 .Pa /etc/default/nss 262 file, the system does not put the local subnet addresses 263 first. See 264 .Xr nss 4 265 for more information. 266 .Lp 267 Use of these enumeration functions 268 is discouraged; enumeration might not be supported for all database sources. 269 The semantics of enumeration are discussed further in 270 .Xr nsswitch.conf 4 . 271 .Lp 272 The current implementations of these functions only return addresses 273 for the Internet address family 274 .Po type Dv AF_INET Pc . 275 See 276 .Xr inet 4 277 for more information. 278 .Sh STANDARDS 279 The 280 .Fn gethostent , 281 .Fn sethostent , 282 and 283 .Fn endhostent 284 functions were introduced in 285 .Bx 4.2 286 and standardized in 287 .St -xns5.2 and 288 .St -p1003.1-2001 .