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