Print this page
11622 clean up rarer mandoc lint warnings
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man3nsl/netdir.3nsl
+++ new/usr/src/man/man3nsl/netdir.3nsl
1 1 '\" te
2 2 .\" Copyright 2015 Nexenta Systems, Inc. All rights reserved.
3 3 .\" Copyright 1989 AT&T
|
↓ open down ↓ |
3 lines elided |
↑ open up ↑ |
4 4 .\" Copyright (C) 2005, Sun Microsystems, Inc. All Rights Reserved
5 5 .\" 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.
6 6 .\" 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.
7 7 .\" 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]
8 8 .TH NETDIR 3NSL "Feb 14, 2015"
9 9 .SH NAME
10 10 netdir, netdir_getbyname, netdir_getbyaddr, netdir_free, netdir_options,
11 11 taddr2uaddr, uaddr2taddr, netdir_perror, netdir_sperror, netdir_mergeaddr \-
12 12 generic transport name-to-address translation
13 13 .SH SYNOPSIS
14 -.LP
15 14 .nf
16 15 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lnsl\fR [ \fIlibrary\fR...]
17 16 #include <netdir.h>
18 17
19 18 \fBint\fR \fBnetdir_getbyname\fR(\fBstruct netconfig *\fR\fIconfig\fR,
20 19 \fBstruct nd_hostserv *\fR\fIservice\fR, \fBstruct nd_addrlist **\fR\fIaddrs\fR);
21 20 .fi
22 21
23 22 .LP
24 23 .nf
25 24 \fBint\fR \fBnetdir_getbyaddr\fR(\fBstruct netconfig *\fR\fIconfig\fR,
26 25 \fBstruct nd_hostservlist **\fR\fIservice\fR, \fBstruct netbuf *\fR\fInetaddr\fR);
27 26 .fi
28 27
29 28 .LP
30 29 .nf
31 30 \fBvoid\fR \fBnetdir_free\fR(\fBvoid *\fR\fIptr\fR, \fBint\fR \fIstruct_type\fR);
32 31 .fi
33 32
34 33 .LP
35 34 .nf
36 35 \fBint\fR \fBnetdir_options\fR(\fBstruct netconfig *\fR\fIconfig\fR, \fBint\fR \fIoption\fR, \fBint\fR \fIfildes\fR,
37 36 \fBchar *\fR\fIpointer_to_args\fR);
38 37 .fi
39 38
40 39 .LP
41 40 .nf
42 41 \fBchar *\fR\fBtaddr2uaddr\fR(\fBstruct netconfig *\fR\fIconfig\fR, \fBstruct netbuf *\fR\fIaddr\fR);
43 42 .fi
44 43
45 44 .LP
46 45 .nf
47 46 \fBstruct netbuf *\fR\fBuaddr2taddr\fR(\fBstruct netconfig *\fR\fIconfig\fR, \fBchar *\fR\fIuaddr\fR);
48 47 .fi
49 48
50 49 .LP
|
↓ open down ↓ |
26 lines elided |
↑ open up ↑ |
51 50 .nf
52 51 \fBvoid\fR \fBnetdir_perror\fR(\fBchar *\fR\fIs\fR);
53 52 .fi
54 53
55 54 .LP
56 55 .nf
57 56 \fBchar *\fR\fBnetdir_sperror\fR(\fBvoid\fR);
58 57 .fi
59 58
60 59 .SH DESCRIPTION
61 -.LP
62 60 The \fBnetdir\fR functions provide a generic interface for name-to-address
63 61 mapping that will work with all transport protocols. This interface provides a
64 62 generic way for programs to convert transport specific addresses into common
65 63 structures and back again. The \fBnetconfig\fR structure, described on the
66 64 \fBnetconfig\fR(4) manual page, identifies the transport.
67 65 .sp
68 66 .LP
69 67 The \fBnetdir_getbyname()\fR function maps the machine name and service name in
70 68 the \fBnd_hostserv\fR structure to a collection of addresses of the type
71 69 understood by the transport identified in the \fBnetconfig\fR structure. This
72 70 function returns all addresses that are valid for that transport in the
73 71 \fBnd_addrlist\fR structure. The \fBnd_hostserv\fR structure contains the
74 72 following members:
75 73 .sp
76 74 .in +2
77 75 .nf
78 76 char *h_host; /* host name */
79 77 char *h_serv; /* service name */
80 78 .fi
81 79 .in -2
82 80
83 81 .sp
84 82 .LP
85 83 The \fBnd_addrlist\fR structure contains the following members:
86 84 .sp
87 85 .in +2
88 86 .nf
89 87 int n_cnt; /* number of addresses */
90 88 struct netbuf *n_addrs;
91 89 .fi
92 90 .in -2
93 91
94 92 .sp
95 93 .LP
96 94 The \fBnetdir_getbyname()\fR function accepts some special-case host names. The
97 95 host names are defined in <\fBnetdir.h\fR>. The currently defined host names
98 96 are:
99 97 .sp
100 98 .ne 2
101 99 .na
102 100 \fB\fBHOST_SELF\fR\fR
103 101 .ad
104 102 .RS 21n
105 103 Represents the address to which local programs will bind their endpoints.
106 104 \fBHOST_SELF\fR differs from the host name provided by \fBgethostname\fR(3C),
107 105 which represents the address to which \fIremote\fR programs will bind their
108 106 endpoints.
109 107 .RE
110 108
111 109 .sp
112 110 .ne 2
113 111 .na
114 112 \fB\fBHOST_ANY\fR\fR
115 113 .ad
116 114 .RS 21n
117 115 Represents any host accessible by this transport provider. \fBHOST_ANY\fR
118 116 allows applications to specify a required service without specifying a
119 117 particular host name.
120 118 .RE
121 119
122 120 .sp
123 121 .ne 2
124 122 .na
125 123 \fB\fBHOST_SELF_CONNECT\fR\fR
126 124 .ad
127 125 .RS 21n
128 126 Represents the host address that can be used to connect to the local host.
129 127 .RE
130 128
131 129 .sp
132 130 .ne 2
133 131 .na
134 132 \fB\fBHOST_BROADCAST\fR\fR
135 133 .ad
136 134 .RS 21n
137 135 Represents the address for all hosts accessible by this transport provider.
138 136 Network requests to this address are received by all machines.
139 137 .RE
140 138
141 139 .sp
142 140 .LP
143 141 All fields of the \fBnd_hostserv\fR structure must be initialized.
144 142 .sp
145 143 .LP
146 144 To find the address of a given host and service on all available transports,
147 145 call the \fBnetdir_getbyname()\fR function with each \fBstruct netconfig\fR
148 146 structure returned by \fBgetnetconfig\fR(3NSL).
149 147 .sp
150 148 .LP
151 149 The \fBnetdir_getbyaddr()\fR function maps addresses to service names. The
152 150 function returns \fIservice\fR, a list of host and service pairs that yield
153 151 these addresses. If more than one tuple of host and service name is returned,
154 152 the first tuple contains the preferred host and service names:
155 153 .sp
156 154 .in +2
157 155 .nf
158 156 struct nd_hostservlist {
159 157 int *h_cnt; /* number of hostservs found */
160 158 struct hostserv *h_hostservs;
161 159 }
162 160 .fi
163 161 .in -2
164 162
165 163 .sp
166 164 .LP
167 165 The \fBnetdir_free()\fR structure is used to free the structures allocated by
168 166 the name to address translation functions. The \fIptr\fR parameter points to
169 167 the structure that has to be freed. The parameter \fBstruct_type\fR identifies
170 168 the structure:
171 169 .sp
172 170 .in +2
173 171 .nf
174 172 struct netbuf ND_ADDR
175 173 struct nd_addrlist ND_ADDRLIST
176 174 struct hostserv ND_HOSTSERV
177 175 struct nd_hostservlist ND_HOSTSERVLIST
|
↓ open down ↓ |
106 lines elided |
↑ open up ↑ |
178 176 .fi
179 177 .in -2
180 178
181 179 .sp
182 180 .LP
183 181 The \fBnetdir_options()\fR function is used to do all transport-specific setups
184 182 and option management. \fIfildes\fR is the associated file descriptor.
185 183 \fIoption\fR, \fIfildes\fR, and \fIpointer_to_args\fR are passed to the
186 184 \fBnetdir_options()\fR function for the transport specified in \fIconfig\fR.
187 185 Currently four values are defined for \fIoption\fR:
188 -.br
189 186
190 187 .in +2
191 188 \fBND_SET_BROADCAST\fR
192 189 .in -2
193 190 .br
194 191 .in +2
195 192 \fBND_SET_RESERVEDPORT\fR
196 193 .in -2
197 194 .br
198 195 .in +2
199 196 \fBND_CHECK_RESERVEDPORT\fR
200 197 .in -2
201 198 .br
202 199 .in +2
203 200 \fBND_MERGEADDR\fR
204 201 .sp
205 202 .LP
206 203 The specific actions of each option follow.
207 204 .sp
208 205 .ne 2
209 206 .na
210 207 \fB\fBND_SET_BROADCAST\fR\fR
211 208 .ad
212 209 .RS 25n
213 210 Sets the transport provider up to allow broadcast if the transport supports
214 211 broadcast. \fIfildes\fR is a file descriptor into the transport, that is, the
215 212 result of a \fBt_open\fR of \fB/dev/udp\fR. \fIpointer_to_args\fR is not used.
216 213 If this completes, broadcast operations can be performed on file descriptor
217 214 \fIfildes\fR.
218 215 .RE
219 216
220 217 .sp
221 218 .ne 2
222 219 .na
223 220 \fB\fBND_SET_RESERVEDPORT\fR\fR
224 221 .ad
225 222 .RS 25n
226 223 Allows the application to bind to a reserved port if that concept exists for
227 224 the transport provider. \fIfildes\fR is an unbound file descriptor into the
228 225 transport. If \fIpointer_to_args\fR is \fINULL,\fR \fIfildes\fR is bound to a
229 226 reserved port. If \fIpointer_to_args\fR is a pointer to a \fBnetbuf\fR
230 227 structure, an attempt is made to bind to any reserved port on the specified
231 228 address.
232 229 .RE
233 230
234 231 .sp
235 232 .ne 2
236 233 .na
237 234 \fB\fBND_CHECK_RESERVEDPORT\fR\fR
238 235 .ad
239 236 .RS 25n
240 237 Used to verify that the address corresponds to a reserved port if that concept
241 238 exists for the transport provider. \fIfildes\fR is not used.
242 239 \fIpointer_to_args\fR is a pointer to a \fBnetbuf\fR structure that contains
243 240 the address. This option returns \fB0\fR only if the address specified in
244 241 \fIpointer_to_args\fR is reserved.
245 242 .RE
246 243
247 244 .sp
248 245 .ne 2
249 246 .na
250 247 \fB\fBND_MERGEADDR\fR\fR
251 248 .ad
252 249 .RS 25n
253 250 Used to take a ``local address'' such as a \fB0.0.0.0\fR TCP address and return
254 251 a ``real address'' to which client machines can connect. \fIfildes\fR is not
255 252 used. \fIpointer_to_args\fR is a pointer to a \fBstruct nd_mergearg\fR which
256 253 has the following members:
257 254 .sp
258 255 .in +2
259 256 .nf
260 257 \fBchar\fR \fIs_uaddr;\fR /* server's universal address */
261 258 \fBchar\fR \fIc_uaddr;\fR /* client's universal address */
262 259 \fBchar\fR \fIm_uaddr;\fR /* the result */
263 260 .fi
264 261 .in -2
265 262
266 263 If \fBs_uaddr\fR is an address such as \fB0.0.0.0.1.12\fR, and the call is
267 264 successful \fBm_uaddr\fR is set to an address such as \fB192.11.109.89.1.12\fR.
268 265 For most transports, \fBm_uaddr\fR is identical to \fBs_uaddr\fR.
269 266 .RE
270 267 .sp
271 268 .LP
272 269 If a transport provider does not support an option, \fBnetdir_options\fR
273 270 returns \fB-1\fR and the error message can be printed through
274 271 \fBnetdir_perror()\fR or \fBnetdir_sperror()\fR.
275 272
276 273 .in -2
277 274 .sp
278 275 .LP
279 276 The \fBtaddr2uaddr()\fR and \fBuaddr2taddr()\fR functions support translation
280 277 between universal addresses and \fBTLI\fR type \fBnetbufs\fR. The
281 278 \fBtaddr2uaddr()\fR function takes a \fBstruct\fR \fBnetbuf\fR data structure
282 279 and returns a pointer to a string that contains the universal address. It
283 280 returns \fINULL\fR if the conversion is not possible. This is not a fatal
284 281 condition as some transports do not support a universal address form.
285 282 .sp
286 283 .LP
287 284 The \fBfree()\fR function is used to free the universal address returned by the
288 285 \fBtaddr2uaddr()\fR function.
289 286 .sp
290 287 .LP
291 288 The \fBuaddr2taddr()\fR function is the reverse of the \fBtaddr2uaddr()\fR
292 289 function. It returns the \fBstruct netbuf\fR data structure for the given
293 290 universal address and \fINULL\fR on failure.
294 291
295 292 .sp
|
↓ open down ↓ |
97 lines elided |
↑ open up ↑ |
296 293 .LP
297 294 The \fBnetdir_perror()\fR function prints an error message in standard output
298 295 that states the cause of a name-to-address mapping failure. The error message
299 296 is preceded by the string given as an argument.
300 297 .sp
301 298 .LP
302 299 The \fBnetdir_sperror()\fR function returns a string with an error message that
303 300 states the cause of a name-to-address mapping failure.
304 301
305 302 .SH RETURN VALUES
306 -.LP
307 303 The \fBnetdir_sperror()\fR function returns a pointer to a buffer which
308 304 contains the error message string. The buffer is overwritten on each call. In
309 305 multithreaded applications, this buffer is implemented as thread-specific
310 306 data.
311 307 .sp
312 308 .LP
313 309 The \fBnetdir_getbyname()\fR, \fBnetdir_getbyaddr()\fR, and \fBnetdir_options()\fR
314 310 functions return \fB0\fR on success and a non-zero value on failure.
315 311 .SH ATTRIBUTES
316 -.LP
317 312 See \fBattributes\fR(5) for descriptions of the following attributes:
318 313 .sp
319 314
320 315 .sp
321 316 .TS
322 317 box;
323 318 c | c
324 319 l | l .
325 320 ATTRIBUTE TYPE ATTRIBUTE VALUE
326 321 _
327 322 MT-Level Safe
328 323 .TE
329 324
330 325 .SH SEE ALSO
331 -.LP
332 326 \fBgethostname\fR(3C), \fBgetnetconfig\fR(3NSL), \fBgetnetpath\fR(3NSL),
333 327 \fBnetconfig\fR(4), \fBattributes\fR(5)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX