Print this page
Ensured various XPG7 stuff are declared properly in sys/stat.h (and cleanup)
New documentation for wcslen, wcsnlen, wcscasecmp (and friends), wcsdup.
Various other tweaks and markup improvements.
Finished obsoleting interfaces for XPG7.
   1 '\" te
   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 .TH GETHOSTBYNAME 3NSL "Sep 10, 2013"
  13 .SH NAME
  14 gethostbyname, gethostbyname_r, gethostbyaddr, gethostbyaddr_r, gethostent,
  15 gethostent_r, sethostent, endhostent \- get network host entry
  16 .SH SYNOPSIS
  17 .LP
  18 .nf
  19 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lnsl\fR [ \fIlibrary\fR... ]
  20 #include <netdb.h>
  21 
  22 \fBstruct hostent *\fR\fBgethostbyname\fR(\fBconst char *\fR\fIname\fR);
  23 .fi
  24 
  25 .LP
  26 .nf
  27 \fBstruct hostent *\fR\fBgethostbyname_r\fR(\fBconst char *\fR\fIname\fR,
  28      \fBstruct hostent *\fR\fIresult\fR, \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbuflen\fR,
  29      \fBint *\fR\fIh_errnop\fR);
  30 .fi
  31 
  32 .LP
  33 .nf
  34 \fBstruct hostent *\fR\fBgethostbyaddr\fR(\fBconst char *\fR\fIaddr\fR, \fBint\fR \fIlen\fR,
  35      \fBint\fR \fItype\fR);
  36 .fi
  37 
  38 .LP
  39 .nf
  40 \fBstruct hostent *\fR\fBgethostbyaddr_r\fR(\fBconst char *\fR\fIaddr\fR, \fBint\fR \fIlength\fR,
  41      \fBint\fR \fItype\fR, \fBstruct hostent *\fR\fIresult\fR, \fBchar *\fR\fIbuffer\fR,
  42      \fBint\fR \fIbuflen\fR, \fBint *\fR\fIh_errnop\fR);
  43 .fi
  44 
  45 .LP
  46 .nf
  47 \fBstruct hostent *\fR\fBgethostent\fR(\fBvoid\fR);
  48 .fi
  49 
  50 .LP
  51 .nf
  52 \fBstruct hostent *\fR\fBgethostent_r\fR(\fBstruct hostent *\fR\fIresult\fR,
  53      \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbuflen\fR, \fBint *\fR\fIh_errnop\fR);
  54 .fi
  55 
  56 .LP
  57 .nf
  58 \fBint\fR \fBsethostent\fR(\fBint\fR \fIstayopen\fR);
  59 .fi
  60 
  61 .LP
  62 .nf
  63 \fBint\fR \fBendhostent\fR(\fBvoid\fR);
  64 .fi
  65 
  66 .SH DESCRIPTION
  67 .sp
  68 .LP
  69 These functions are used to obtain entries describing hosts. An entry can come
  70 from any of the sources for \fBhosts\fR specified in the
  71 \fB/etc/nsswitch.conf\fR file. See \fBnsswitch.conf\fR(4). These functions have
  72 been superseded by \fBgetipnodebyname\fR(3SOCKET),
  73 \fBgetipnodebyaddr\fR(3SOCKET), and \fBgetaddrinfo\fR(3SOCKET), which provide








  74 greater portability to applications when multithreading is performed or
  75 technologies such as IPv6 are used. For example, the functions described in the
  76 following cannot be used with applications targeted to work with IPv6.
  77 .sp
  78 .LP
  79 The \fBgethostbyname()\fR function searches for information for a host with the
  80 hostname specified by the character-string parameter \fIname\fR.
  81 .sp
  82 .LP
  83 The \fBgethostbyaddr()\fR function searches for information for a host with a
  84 given host address. The parameter \fBtype\fR specifies the family of the





  85 address. This should be one of the address families defined in
  86 \fB<sys/socket.h>\fR\&. See the \fBNOTES\fR section for more information. Also
  87 see the \fBEXAMPLES\fR section for information on how to convert an Internet
  88 \fBIP\fR address notation that is separated by periods (.) into an \fIaddr\fR
  89 parameter. The parameter \fIlen\fR specifies the length of the buffer indicated
  90 by \fIaddr\fR.
  91 .sp
  92 .LP








  93 All addresses are returned in network order. In order to interpret the
  94 addresses, \fBbyteorder\fR(3SOCKET) must be used for byte order conversion.
  95 .sp
  96 .LP
  97 The \fBsethostent()\fR, \fBgethostent()\fR, and \fBendhostent()\fR functions
  98 are used to enumerate host entries from the database.
  99 .sp
 100 .LP
 101 The \fBsethostent()\fR function sets or resets the enumeration to the beginning
 102 of the set of host entries. This function should be called before the first
 103 call to \fBgethostent()\fR. Calls to \fBgethostbyname()\fR and
 104 \fBgethostbyaddr()\fR leave the enumeration position in an indeterminate state.
 105 If the \fIstayopen\fR flag is non-zero, the system can keep allocated resources
 106 such as open file descriptors until a subsequent call to \fBendhostent()\fR.
 107 .sp
 108 .LP
 109 Successive calls to the \fBgethostent()\fR function return either successive
 110 entries or \fINULL,\fR indicating the end of the enumeration.
 111 .sp
 112 .LP
 113 The \fBendhostent()\fR function can be called to indicate that the caller
 114 expects to do no further host entry retrieval operations; the system can then
 115 deallocate resources it was using. It is still allowed, but possibly less
 116 efficient, for the process to call more host retrieval functions after calling
 117 \fBendhostent()\fR.
 118 .SS "Reentrant Interfaces"
 119 .sp
 120 .LP
 121 The \fBgethostbyname()\fR, \fBgethostbyaddr()\fR, and \fBgethostent()\fR
 122 functions use static storage that is reused in each call, making these
 123 functions unsafe for use in multithreaded applications.
 124 .sp
 125 .LP
 126 The \fBgethostbyname_r()\fR, \fBgethostbyaddr_r()\fR, and \fBgethostent_r()\fR


 127 functions provide reentrant interfaces for these operations.
 128 .sp
 129 .LP
 130 Each reentrant interface performs the same operation as its non-reentrant
 131 counterpart, named by removing the \fB_r\fR suffix. The reentrant interfaces,


 132 however, use buffers supplied by the caller to store returned results and the
 133 interfaces are safe for use in both single-threaded and multithreaded
 134 applications.
 135 .sp
 136 .LP
 137 Each reentrant interface takes the same parameters as its non-reentrant
 138 counterpart, as well as the following additional parameters. The parameter
 139 \fIresult\fR must be a pointer to a \fBstruct hostent\fR structure allocated by



 140 the caller. On successful completion, the function returns the host entry in
 141 this structure. The parameter \fIbuffer\fR must be a pointer to a buffer


 142 supplied by the caller. This buffer is used as storage space for the host data.
 143 All of the pointers within the returned \fBstruct hostent\fR \fIresult\fR point
 144 to data stored within this buffer. See the \fBRETURN VALUES\fR section for more



 145 information. The buffer must be large enough to hold all of the data associated
 146 with the host entry. The parameter \fIbuflen\fR should give the size in bytes
 147 of the buffer indicated by \fIbuffer\fR. The parameter \fIh_errnop\fR should be






 148 a pointer to an integer. An integer error status value is stored there on
 149 certain error conditions. See the \fBERRORS\fR section for more information.
 150 .sp
 151 .LP
 152 For enumeration in multithreaded applications, the position within the
 153 enumeration is a process-wide property shared by all threads. The
 154 \fBsethostent()\fR function can be used in a multithreaded application but
 155 resets the enumeration position for all threads. If multiple threads interleave
 156 calls to \fBgethostent_r()\fR, the threads will enumerate disjoint subsets of
 157 the host database.
 158 .sp
 159 .LP
 160 Like their non-reentrant counterparts, \fBgethostbyname_r()\fR and
 161 \fBgethostbyaddr_r()\fR leave the enumeration position in an indeterminate
 162 state.
 163 .SH RETURN VALUES
 164 .sp
 165 .LP
 166 Host entries are represented by the \fBstruct hostent\fR structure defined in
 167 \fB<netdb.h>\fR:
 168 .sp
 169 .in +2
 170 .nf
 171 struct hostent {
 172     char    *h_name;         /* canonical name of host */
 173     char    **h_aliases;     /* alias list */
 174     int     h_addrtype;      /* host address type */
 175     int     h_length;        /* length of address */
 176     char    **h_addr_list;   /* list of addresses */
 177 };
 178 .fi
 179 .in -2
 180 
 181 .sp
 182 .LP
 183 See the \fBEXAMPLES\fR section for information about how to retrieve a ``.''
 184 separated Internet \fBIP\fR address string from the \fIh_addr_list\fR field of
 185 \fBstruct hostent\fR.
 186 .sp
 187 .LP
 188 The \fBgethostbyname()\fR, \fBgethostbyname_r()\fR, \fBgethostbyaddr()\fR, and
 189 \fBgethostbyaddr_r()\fR functions each return a pointer to a \fBstruct
 190 hostent\fR if they successfully locate the requested entry; otherwise they
 191 return \fINULL\fR.
 192 .sp
 193 .LP
 194 The \fBgethostent()\fR and \fBgethostent_r()\fR functions each return a pointer
 195 to a \fBstruct hostent\fR if they successfully enumerate an entry; otherwise
 196 they return \fINULL\fR, indicating the end of the enumeration.
 197 .sp
 198 .LP
 199 The \fBgethostbyname()\fR, \fBgethostbyaddr()\fR, and \fBgethostent()\fR





 200 functions use static storage, so returned data must be copied before a
 201 subsequent call to any of these functions if the data is to be saved.
 202 .sp
 203 .LP
 204 When the pointer returned by the reentrant functions \fBgethostbyname_r()\fR,
 205 \fBgethostbyaddr_r()\fR, and \fBgethostent_r()\fR is not \fINULL\fR, it is
 206 always equal to the \fIresult\fR pointer that was supplied by the caller.
 207 .sp
 208 .LP
 209 The \fBsethostent()\fR and \fBendhostent()\fR functions return \fB0\fR on
 210 success.
 211 .SH ERRORS
 212 .sp
 213 .LP
 214 The reentrant functions \fBgethostbyname_r()\fR, \fBgethostbyaddr_r()\fR, and
 215 \fBgethostent_r()\fR will return \fINULL\fR and set \fIerrno\fR to \fBERANGE\fR
 216 if the length of the buffer supplied by caller is not large enough to store the
 217 result. See \fBIntro\fR(2) for the proper usage and interpretation of
 218 \fBerrno\fR in multithreaded applications.
 219 .sp
 220 .LP
 221 The reentrant functions \fBgethostbyname_r()\fR and \fBgethostbyaddr_r()\fR set
 222 the integer pointed to by \fIh_errnop\fR to one of these values in case of
 223 error.
 224 .sp
 225 .LP
 226 On failures, the non-reentrant functions \fBgethostbyname()\fR and
 227 \fBgethostbyaddr()\fR set a global integer \fIh_errno\fR to indicate one of
 228 these error codes (defined in \fB<netdb.h>\fR): \fBHOST_NOT_FOUND\fR,
 229 \fBTRY_AGAIN\fR, \fBNO_RECOVERY\fR, \fBNO_DATA\fR, and \fBNO_ADDRESS\fR.
 230 .sp
 231 .LP
 232 If a resolver is provided with a malformed address, or if any other error
 233 occurs before \fBgethostbyname()\fR is resolved, then \fBgethostbyname()\fR
 234 returns an internal error with a value of \(mi1.
 235 .sp
 236 .LP
 237 The \fBgethostbyname()\fR function will set \fIh_errno\fR to
 238 \fBNETDB_INTERNAL\fR when it returns a \fINULL\fR value.
 239 .SH EXAMPLES
 240 .LP
 241 \fBExample 1 \fRUsing \fBgethostbyaddr()\fR
 242 .sp
 243 .LP
 244 Here is a sample program that gets the canonical name, aliases, and ``.''
 245 separated Internet \fBIP\fR addresses for a given ``.'' separated \fBIP\fR
 246 address:
 247 
 248 .sp
 249 .in +2
 250 .nf
 251 #include <stdio.h>
 252 #include <stdlib.h
 253 #include <string.h>
 254 #include <sys/types.h>
 255 #include <sys/socket.h>
 256 #include <netinet/in.h>
 257 #include <arpa/inet.h>
 258 #include <netdb.h>
 259 int main(int argc, const char **argv)
 260 {
 261         in_addr_t addr;
 262         struct hostent *hp;
 263         char **p;
 264         if (argc != 2) {
 265             (void) printf("usage: %s IP-address\en", argv[0]);
 266             exit (1);
 267         }
 268         if ((int)(addr = inet_addr(argv[1])) == -1) {
 269             (void) printf("IP-address must be of the form a.b.c.d\en");
 270             exit (2);
 271         }
 272         hp = gethostbyaddr((char *)&addr, 4, AF_INET);
 273         if (hp == NULL) {
 274             (void) printf("host information for %s not found\en", argv[1]);
 275             exit (3);
 276         }
 277         for (p = hp->h_addr_list; *p != 0; p++) {
 278             struct in_addr in;
 279             char **q;
 280             (void) memcpy(&in.s_addr, *p, sizeof (in.s_addr));
 281          (void) printf("%s\t%s", inet_ntoa(in), hp\(mi>h_name);
 282             for (q = hp->h_aliases; *q != 0; q++)
 283                 (void) printf(" %s", *q);
 284             (void) putchar('\en');
 285         }
 286         exit (0);
 287 }
 288 .fi
 289 .in -2
 290 
 291 .sp
 292 .LP
 293 Note that the preceding sample program is unsafe for use in multithreaded
 294 applications.
 295 
 296 .SH FILES
 297 .sp
 298 .ne 2
 299 .na
 300 \fB\fB/etc/hosts\fR\fR
 301 .ad
 302 .RS 22n
 303 hosts file that associates the names of hosts with their Internet Protocol (IP)
 304 addresses
 305 .RE
 306 
 307 .sp
 308 .ne 2
 309 .na
 310 \fB\fB/etc/netconfig\fR\fR
 311 .ad
 312 .RS 22n
 313 network configuration database
 314 .RE
 315 
 316 .sp
 317 .ne 2
 318 .na
 319 \fB\fB/etc/nsswitch.conf\fR\fR
 320 .ad
 321 .RS 22n
 322 configuration file for the name service switch
 323 .RE
 324 
 325 .SH ATTRIBUTES
 326 .sp
 327 .LP
 328 See \fBattributes\fR(5) for descriptions of the following attributes:
 329 .sp
 330 
 331 .sp
 332 .TS
 333 box;
 334 c | c
 335 l | l .
 336 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 337 _
 338 MT-Level        T{
 339 See \fBReentrant Interfaces\fR in the \fBDESCRIPTION\fR section.
 340 T}
 341 .TE
 342 
 343 .SH SEE ALSO
 344 .sp
 345 .LP
 346 \fBIntro\fR(2), \fBIntro\fR(3), \fBbyteorder\fR(3SOCKET), \fBinet\fR(3SOCKET),
 347 \fBnetdb.h\fR(3HEAD), \fBnetdir\fR(3NSL), \fBhosts\fR(4), \fBnetconfig\fR(4),
 348 \fBnss\fR(4), \fBnsswitch.conf\fR(4), \fBattributes\fR(5)
 349 .SH WARNINGS
 350 .sp
 351 .LP
 352 The reentrant interfaces \fBgethostbyname_r()\fR, \fBgethostbyaddr_r()\fR, and
 353 \fBgethostent_r()\fR are included in this release on an uncommitted basis only














































 354 and are subject to change or removal in future minor releases.
 355 .SH NOTES
 356 .sp
 357 .LP
 358 To ensure that they all return consistent results, \fBgethostbyname()\fR,
 359 \fBgethostbyname_r()\fR, and \fBnetdir_getbyname()\fR are implemented in terms


 360 of the same internal library function. This function obtains the system-wide
 361 source lookup policy based on the \fBinet\fR family entries in
 362 \fBnetconfig\fR(4) and the \fBhosts:\fR entry in \fBnsswitch.conf\fR(4).
 363 Similarly, \fBgethostbyaddr()\fR, \fBgethostbyaddr_r()\fR, and
 364 \fBnetdir_getbyaddr()\fR are implemented in terms of the same internal library
 365 function. If the \fBinet\fR family entries in \fBnetconfig\fR(4) have a ``-''
 366 in the last column for \fBnametoaddr\fR libraries, then the entry for
 367 \fBhosts\fR in \fBnsswitch.conf\fR will be used; \fBnametoaddr\fR libraries in
 368 that column will be used, and \fBnsswitch.conf\fR will not be consulted.
 369 .sp
 370 .LP
 371 There is no analogue of \fBgethostent()\fR and \fBgethostent_r()\fR in the
 372 netdir functions, so these enumeration functions go straight to the \fBhosts\fR
 373 entry in \fBnsswitch.conf\fR. Thus enumeration can return results from a
 374 different source than that used by \fBgethostbyname()\fR,
 375 \fBgethostbyname_r()\fR, \fBgethostbyaddr()\fR, and \fBgethostbyaddr_r()\fR.
 376 .sp
 377 .LP
 378 All the functions that return a \fBstruct hostent\fR must always return the
 379 \fIcanonical name\fR in the \fIh_name\fR field. This name, by definition, is

 380 the well-known and official hostname shared between all aliases and all
 381 addresses. The underlying source that satisfies the request determines the
 382 mapping of the input name or address into the set of names and addresses in
 383 \fBhostent\fR. Different sources might do that in different ways. If there is
 384 more than one alias and more than one address in \fBhostent\fR, no pairing is



 385 implied between them.
 386 .sp
 387 .LP
 388 The system attempts to put those addresses that are on the same subnet as the
 389 caller before addresses that are on different subnets. However, if address
 390 sorting is disabled by setting \fBSORT_ADDRS\fR to FALSE in the
 391 \fB/etc/default/nss\fR file, the system does not put the local subnet addresses
 392 first. See \fBnss\fR(4) for more information.
 393 .sp
 394 .LP
 395 When compiling multithreaded applications, see \fBIntro\fR(3), \fBMULTITHREADED
 396 APPLICATIONS\fR, for information about the use of the \fB_REENTRANT\fR flag.
 397 .sp
 398 .LP
 399 Use of the enumeration interfaces \fBgethostent()\fR and \fBgethostent_r()\fR
 400 is discouraged; enumeration might not be supported for all database sources.
 401 The semantics of enumeration are discussed further in \fBnsswitch.conf\fR(4).
 402 .sp
 403 .LP
 404 The current implementations of these functions only return or accept addresses
 405 for the Internet address family (type \fBAF_INET\fR).
 406 .sp
 407 .LP
 408 The form for an address of type \fBAF_INET\fR is a \fBstruct in_addr\fR defined
 409 in <\fBnetinet/in.h\fR>. The functions described in \fBinet\fR(3SOCKET), and
 410 illustrated in the \fBEXAMPLES\fR section, are helpful in constructing and








 411 manipulating addresses in this form.













   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 .