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.

Split Close
Expand all
Collapse all
          --- old/usr/src/man/man3nsl/gethostbyname.3nsl
          +++ new/usr/src/man/man3nsl/gethostbyname.3nsl
   1      -'\" te
        1 +.\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
   2    2  .\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved.
   3    3  .\" Copyright 1989 AT&T.
   4    4  .\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved
   5    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    6  .\" http://www.opengroup.org/bookstore/.
   7    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    8  .\"  This notice shall appear on any product containing this material.
   9    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   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   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
       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
  69   56  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
       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
  74   69  greater portability to applications when multithreading is performed or
  75   70  technologies such as IPv6 are used. For example, the functions described in the
  76   71  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
       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   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
       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
  93  101  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
      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
 122  110  functions use static storage that is reused in each call, making these
 123  111  functions unsafe for use in multithreaded applications.
 124      -.sp
 125      -.LP
 126      -The \fBgethostbyname_r()\fR, \fBgethostbyaddr_r()\fR, and \fBgethostent_r()\fR
      112 +.Lp
      113 +The
      114 +.Fn gethostbyname_r
      115 +and
      116 +.Fn gethostbyaddr_r
 127  117  functions provide reentrant interfaces for these operations.
 128      -.sp
 129      -.LP
      118 +.Lp
 130  119  Each reentrant interface performs the same operation as its non-reentrant
 131      -counterpart, named by removing the \fB_r\fR suffix. The reentrant interfaces,
      120 +counterpart, named by removing the
      121 +.Sy _r
      122 +suffix. The reentrant interfaces,
 132  123  however, use buffers supplied by the caller to store returned results and the
 133  124  interfaces are safe for use in both single-threaded and multithreaded
 134  125  applications.
 135      -.sp
 136      -.LP
      126 +.Lp
 137  127  Each reentrant interface takes the same parameters as its non-reentrant
 138  128  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
      129 +.Fa result
      130 +must be a pointer to a
      131 +.Vt "struct hostent"
      132 +structure allocated by
 140  133  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
      134 +this structure. The parameter
      135 +.Fa buffer
      136 +must be a pointer to a buffer
 142  137  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
      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
 145  143  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
      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
 148  152  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
      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
 171  162  struct hostent {
 172  163      char    *h_name;         /* canonical name of host */
 173  164      char    **h_aliases;     /* alias list */
 174  165      int     h_addrtype;      /* host address type */
 175  166      int     h_length;        /* length of address */
 176  167      char    **h_addr_list;   /* list of addresses */
 177  168  };
 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
      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
 200  196  functions use static storage, so returned data must be copied before a
 201  197  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
      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()
 244  218  Here is a sample program that gets the canonical name, aliases, and ``.''
 245      -separated Internet \fBIP\fR addresses for a given ``.'' separated \fBIP\fR
      219 +separated Internet Protocol addresses for a given ``.'' separated IP
 246  220  address:
 247      -
 248      -.sp
 249      -.in +2
 250      -.nf
      221 +.Bd -literal -offset indent
 251  222  #include <stdio.h>
 252  223  #include <stdlib.h
 253  224  #include <string.h>
 254  225  #include <sys/types.h>
 255  226  #include <sys/socket.h>
 256  227  #include <netinet/in.h>
 257  228  #include <arpa/inet.h>
 258  229  #include <netdb.h>
 259  230  int main(int argc, const char **argv)
 260  231  {
 261  232          in_addr_t addr;
 262  233          struct hostent *hp;
 263  234          char **p;
 264  235          if (argc != 2) {
 265  236              (void) printf("usage: %s IP-address\en", argv[0]);
 266  237              exit (1);
 267  238          }
 268  239          if ((int)(addr = inet_addr(argv[1])) == -1) {
 269      -            (void) printf("IP-address must be of the form a.b.c.d\en");
      240 +            (void) printf("IP-address must be of form a.b.c.d\en");
 270  241              exit (2);
 271  242          }
 272  243          hp = gethostbyaddr((char *)&addr, 4, AF_INET);
 273  244          if (hp == NULL) {
 274      -            (void) printf("host information for %s not found\en", argv[1]);
      245 +            (void) printf("host %s not found\en", argv[1]);
 275  246              exit (3);
 276  247          }
 277  248          for (p = hp->h_addr_list; *p != 0; p++) {
 278  249              struct in_addr in;
 279  250              char **q;
 280  251              (void) memcpy(&in.s_addr, *p, sizeof (in.s_addr));
 281  252           (void) printf("%s\t%s", inet_ntoa(in), hp\(mi>h_name);
 282  253              for (q = hp->h_aliases; *q != 0; q++)
 283  254                  (void) printf(" %s", *q);
 284  255              (void) putchar('\en');
 285  256          }
 286  257          exit (0);
 287  258  }
 288      -.fi
 289      -.in -2
 290      -
 291      -.sp
 292      -.LP
      259 +.Ed
      260 +.Lp
 293  261  Note that the preceding sample program is unsafe for use in multithreaded
 294  262  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
      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
 354  368  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
      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
 360  376  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
      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
 380  397  the well-known and official hostname shared between all aliases and all
 381  398  addresses. The underlying source that satisfies the request determines the
 382  399  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
      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
 385  405  implied between them.
 386      -.sp
 387      -.LP
      406 +.Lp
 388  407  The system attempts to put those addresses that are on the same subnet as the
 389  408  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
      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
 404  420  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
      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
 411  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 .
    
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX