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