Print this page
11622 clean up rarer mandoc lint warnings
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man3nsl/netdir.3nsl.man.txt
+++ new/usr/src/man/man3nsl/netdir.3nsl.man.txt
1 1 NETDIR(3NSL) Networking Services Library Functions NETDIR(3NSL)
2 2
3 3
4 4
5 5 NAME
6 6 netdir, netdir_getbyname, netdir_getbyaddr, netdir_free,
7 7 netdir_options, taddr2uaddr, uaddr2taddr, netdir_perror,
8 8 netdir_sperror, netdir_mergeaddr - generic transport name-to-address
9 9 translation
10 10
11 11 SYNOPSIS
12 12 cc [ flag... ] file... -lnsl [ library...]
13 13 #include <netdir.h>
14 14
15 15 int netdir_getbyname(struct netconfig *config,
16 16 struct nd_hostserv *service, struct nd_addrlist **addrs);
17 17
18 18
19 19 int netdir_getbyaddr(struct netconfig *config,
20 20 struct nd_hostservlist **service, struct netbuf *netaddr);
21 21
22 22
23 23 void netdir_free(void *ptr, int struct_type);
24 24
25 25
26 26 int netdir_options(struct netconfig *config, int option, int fildes,
27 27 char *pointer_to_args);
28 28
29 29
30 30 char *taddr2uaddr(struct netconfig *config, struct netbuf *addr);
31 31
32 32
33 33 struct netbuf *uaddr2taddr(struct netconfig *config, char *uaddr);
34 34
35 35
36 36 void netdir_perror(char *s);
37 37
38 38
39 39 char *netdir_sperror(void);
40 40
41 41
42 42 DESCRIPTION
43 43 The netdir functions provide a generic interface for name-to-address
44 44 mapping that will work with all transport protocols. This interface
45 45 provides a generic way for programs to convert transport specific
46 46 addresses into common structures and back again. The netconfig
47 47 structure, described on the netconfig(4) manual page, identifies the
48 48 transport.
49 49
50 50
51 51 The netdir_getbyname() function maps the machine name and service name
52 52 in the nd_hostserv structure to a collection of addresses of the type
53 53 understood by the transport identified in the netconfig structure. This
54 54 function returns all addresses that are valid for that transport in the
55 55 nd_addrlist structure. The nd_hostserv structure contains the following
56 56 members:
57 57
58 58 char *h_host; /* host name */
59 59 char *h_serv; /* service name */
60 60
61 61
62 62
63 63 The nd_addrlist structure contains the following members:
64 64
65 65 int n_cnt; /* number of addresses */
66 66 struct netbuf *n_addrs;
67 67
68 68
69 69
70 70 The netdir_getbyname() function accepts some special-case host names.
71 71 The host names are defined in <netdir.h>. The currently defined host
72 72 names are:
73 73
74 74 HOST_SELF
75 75 Represents the address to which local programs
76 76 will bind their endpoints. HOST_SELF differs from
77 77 the host name provided by gethostname(3C), which
78 78 represents the address to which remote programs
79 79 will bind their endpoints.
80 80
81 81
82 82 HOST_ANY
83 83 Represents any host accessible by this transport
84 84 provider. HOST_ANY allows applications to specify
85 85 a required service without specifying a particular
86 86 host name.
87 87
88 88
89 89 HOST_SELF_CONNECT
90 90 Represents the host address that can be used to
91 91 connect to the local host.
92 92
93 93
94 94 HOST_BROADCAST
95 95 Represents the address for all hosts accessible by
96 96 this transport provider. Network requests to this
97 97 address are received by all machines.
98 98
99 99
100 100
101 101 All fields of the nd_hostserv structure must be initialized.
102 102
103 103
104 104 To find the address of a given host and service on all available
105 105 transports, call the netdir_getbyname() function with each struct
106 106 netconfig structure returned by getnetconfig(3NSL).
107 107
108 108
109 109 The netdir_getbyaddr() function maps addresses to service names. The
110 110 function returns service, a list of host and service pairs that yield
111 111 these addresses. If more than one tuple of host and service name is
112 112 returned, the first tuple contains the preferred host and service
113 113 names:
114 114
115 115 struct nd_hostservlist {
116 116 int *h_cnt; /* number of hostservs found */
117 117 struct hostserv *h_hostservs;
118 118 }
119 119
120 120
121 121
122 122 The netdir_free() structure is used to free the structures allocated by
123 123 the name to address translation functions. The ptr parameter points to
124 124 the structure that has to be freed. The parameter struct_type
125 125 identifies the structure:
126 126
127 127 struct netbuf ND_ADDR
128 128 struct nd_addrlist ND_ADDRLIST
129 129 struct hostserv ND_HOSTSERV
130 130 struct nd_hostservlist ND_HOSTSERVLIST
131 131
132 132
133 133
134 134 The netdir_options() function is used to do all transport-specific
135 135 setups and option management. fildes is the associated file descriptor.
136 136 option, fildes, and pointer_to_args are passed to the netdir_options()
137 137 function for the transport specified in config. Currently four values
138 138 are defined for option:
139 139
140 140 ND_SET_BROADCAST
141 141 ND_SET_RESERVEDPORT
142 142 ND_CHECK_RESERVEDPORT
143 143 ND_MERGEADDR
144 144
145 145
146 146 The specific actions of each option follow.
147 147
148 148 ND_SET_BROADCAST
149 149 Sets the transport provider up to allow
150 150 broadcast if the transport supports broadcast.
151 151 fildes is a file descriptor into the
152 152 transport, that is, the result of a t_open of
153 153 /dev/udp. pointer_to_args is not used. If
154 154 this completes, broadcast operations can be
155 155 performed on file descriptor fildes.
156 156
157 157
158 158 ND_SET_RESERVEDPORT
159 159 Allows the application to bind to a reserved
160 160 port if that concept exists for the transport
161 161 provider. fildes is an unbound file descriptor
162 162 into the transport. If pointer_to_args is
163 163 NULL, fildes is bound to a reserved port. If
164 164 pointer_to_args is a pointer to a netbuf
165 165 structure, an attempt is made to bind to any
166 166 reserved port on the specified address.
167 167
168 168
169 169 ND_CHECK_RESERVEDPORT
170 170 Used to verify that the address corresponds to
171 171 a reserved port if that concept exists for the
172 172 transport provider. fildes is not used.
173 173 pointer_to_args is a pointer to a netbuf
174 174 structure that contains the address. This
175 175 option returns 0 only if the address specified
176 176 in pointer_to_args is reserved.
177 177
178 178
179 179 ND_MERGEADDR
180 180 Used to take a ``local address'' such as a
181 181 0.0.0.0 TCP address and return a ``real
182 182 address'' to which client machines can
183 183 connect. fildes is not used. pointer_to_args
184 184 is a pointer to a struct nd_mergearg which has
185 185 the following members:
186 186
187 187 char s_uaddr; /* server's universal address */
188 188 char c_uaddr; /* client's universal address */
189 189 char m_uaddr; /* the result */
190 190
191 191 If s_uaddr is an address such as 0.0.0.0.1.12,
192 192 and the call is successful m_uaddr is set to
193 193 an address such as 192.11.109.89.1.12. For
194 194 most transports, m_uaddr is identical to
195 195 s_uaddr.
196 196
197 197
198 198 If a transport provider does not support an option, netdir_options
199 199 returns -1 and the error message can be printed through netdir_perror()
200 200 or netdir_sperror().
201 201
202 202
203 203
204 204 The taddr2uaddr() and uaddr2taddr() functions support translation
205 205 between universal addresses and TLI type netbufs. The taddr2uaddr()
206 206 function takes a struct netbuf data structure and returns a pointer to
207 207 a string that contains the universal address. It returns NULL if the
208 208 conversion is not possible. This is not a fatal condition as some
209 209 transports do not support a universal address form.
210 210
211 211
212 212 The free() function is used to free the universal address returned by
213 213 the taddr2uaddr() function.
214 214
215 215
216 216 The uaddr2taddr() function is the reverse of the taddr2uaddr()
217 217 function. It returns the struct netbuf data structure for the given
218 218 universal address and NULL on failure.
219 219
220 220
221 221
222 222 The netdir_perror() function prints an error message in standard output
223 223 that states the cause of a name-to-address mapping failure. The error
224 224 message is preceded by the string given as an argument.
225 225
226 226
227 227 The netdir_sperror() function returns a string with an error message
228 228 that states the cause of a name-to-address mapping failure.
229 229
230 230
231 231 RETURN VALUES
232 232 The netdir_sperror() function returns a pointer to a buffer which
233 233 contains the error message string. The buffer is overwritten on each
234 234 call. In multithreaded applications, this buffer is implemented as
235 235 thread-specific data.
236 236
237 237
238 238 The netdir_getbyname(), netdir_getbyaddr(), and netdir_options()
239 239 functions return 0 on success and a non-zero value on failure.
240 240
241 241 ATTRIBUTES
242 242 See attributes(5) for descriptions of the following attributes:
243 243
244 244
245 245
246 246
247 247 +---------------+-----------------+
248 248 |ATTRIBUTE TYPE | ATTRIBUTE VALUE |
249 249 +---------------+-----------------+
250 250 |MT-Level | Safe |
251 251 +---------------+-----------------+
252 252
253 253 SEE ALSO
254 254 gethostname(3C), getnetconfig(3NSL), getnetpath(3NSL), netconfig(4),
255 255 attributes(5)
256 256
257 257
258 258
259 259 February 14, 2015 NETDIR(3NSL)
|
↓ open down ↓ |
259 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX