1netdir(3NSL) Networking Services Library Functions netdir(3NSL)
2
6 netdir, netdir_getbyname, netdir_getbyaddr, netdir_free, net‐
7 dir_options, taddr2uaddr, uaddr2taddr, netdir_perror, netdir_sperror,
8 netdir_mergeaddr - generic transport name-to-address translation
9
11 cc [ flag... ] file... -lnsl [ library...]
12 #include <netdir.h>
13 int netdir_getbyname(struct netconfig *config,
15 struct nd_hostserv *service, struct nd_addrlist **addrs);
16 int netdir_getbyaddr(struct netconfig *config,
19 struct nd_hostservlist **service, struct netbuf *netaddr);
20 void netdir_free(void *ptr, int struct_type);
23 int netdir_options(struct netconfig *config, int option, int fildes,
26 char *point_to_args);
27 char *taddr2uaddr(struct netconfig *config, struct netbuf *addr);
30 struct netbuf *uaddr2taddr(struct netconfig *config, char *uaddr);
33 void netdir_perror(char *s);
36 char *netdir_sperror(void);
39
42 The netdir functions provide a generic interface for name-to-address
43 mapping that will work with all transport protocols. This interface
44 provides a generic way for programs to convert transport specific
45 addresses into common structures and back again. The netconfig struc‐
46 ture, described on the netconfig(4) manual page, identifies the trans‐
47 port.
48 The netdir_getbyname() function maps the machine name and service name
51 in the nd_hostserv structure to a collection of addresses of the type
52 understood by the transport identified in the netconfig structure. This
53 function returns all addresses that are valid for that transport in the
54 nd_addrlist structure. The nd_hostserv structure contains the following
55 members:
56 char *h_host; /* host name */
58 char *h_serv; /* service name */
59 The nd_addrlist structure contains the following members:
63 int n_cnt; /* number of addresses */
65 struct netbuf *n_addrs;
66 The netdir_getbyname() function accepts some special-case host names.
70 The host names are defined in <netdir.h>. The currently defined host
71 names are:
72 HOST_SELF Represents the address to which local programs
74 will bind their endpoints. HOST_SELF differs from
75 the host name provided by gethostname(3C), which
76 represents the address to which remote programs
77 will bind their endpoints.
78 HOST_ANY Represents any host accessible by this transport
81 provider. HOST_ANY allows applications to specify
82 a required service without specifying a particular
83 host name.
84 HOST_SELF_CONNECT Represents the host address that can be used to
87 connect to the local host.
88 HOST_BROADCAST Represents the address for all hosts accessible by
91 this transport provider. Network requests to this
92 address are received by all machines.
93 All fields of the nd_hostserv structure must be initialized.
97 To find the address of a given host and service on all available trans‐
100 ports, call the netdir_getbyname() function with each struct netconfig
101 structure returned by getnetconfig(3NSL).
102 The netdir_getbyaddr() function maps addresses to service names. The
105 function returns service, a list of host and service pairs that yield
106 these addresses. If more than one tuple of host and service name is
107 returned, the first tuple contains the preferred host and service
108 names:
109 struct nd_hostservlist {
111 int *h_cnt; /* number of hostservs found */
112 struct hostserv *h_hostservs;
113 }
114 The netdir_free() structure is used to free the structures allocated by
118 the name to address translation functions. The ptr parameter points to
119 the structure that has to be freed. The parameter struct_type identi‐
120 fies the structure:
121 struct netbuf ND_ADDR
123 struct nd_addrlist ND_ADDRLIST
124 struct hostserv ND_HOSTSERV
125 struct nd_hostservlist ND_HOSTSERVLIST
126 The free() function is used to free the universal address returned by
130 the taddr2uaddr() function.
131 The netdir_options() function is used to do all transport-specific set‐
134 ups and option management. fildes is the associated file descriptor.
135 option, fildes, and pointer_to_args are passed to the netdir_options()
136 function for the transport specified in config. Currently four values
137 are defined for option:
138 ND_SET_BROADCAST
139 ND_SET_RESERVEDPORT
140 ND_CHECK_RESERVEDPORT
141 ND_MERGEADDR
142 The taddr2uaddr() and uaddr2taddr() functions support translation
145 between universal addresses and TLI type netbufs. The taddr2uaddr()
146 function takes a struct netbuf data structure and returns a pointer to
147 a string that contains the universal address. It returns NULL if the
148 conversion is not possible. This is not a fatal condition as some
149 transports do not support a universal address form.
150 The uaddr2taddr() function is the reverse of the taddr2uaddr() func‐
153 tion. It returns the struct netbuf data structure for the given univer‐
154 sal address.
155 If a transport provider does not support an option, netdir_options
158 returns -1 and the error message can be printed through netdir_perror()
159 or netdir_sperror().
160 The specific actions of each option follow.
163 ND_SET_BROADCAST Sets the transport provider up to allow broad‐
165 cast if the transport supports broadcast.
166 fildes is a file descriptor into the trans‐
167 port, that is, the result of a t_open of
168 /dev/udp. pointer_to_args is not used. If this
169 completes, broadcast operations can be per‐
170 formed on file descriptor fildes.
171 ND_SET_RESERVEDPORT Allows the application to bind to a reserved
174 port if that concept exists for the transport
175 provider. fildes is an unbound file descriptor
176 into the transport. If pointer_to_args is
177 NULL, fildes is bound to a reserved port. If
178 pointer_to_args is a pointer to a netbuf
179 structure, an attempt is made to bind to any
180 reserved port on the specified address.
181 ND_CHECK_RESERVEDPORT Used to verify that the address corresponds to
184 a reserved port if that concept exists for the
185 transport provider. fildes is not used.
186 pointer_to_args is a pointer to a netbuf
187 structure that contains the address. This
188 option returns 0 only if the address specified
189 in pointer_to_args is reserved.
190 ND_MERGEADDR Used to take a ``local address'' such as a
193 0.0.0.0 TCP address and return a ``real
194 address'' to which client machines can con‐
195 nect. fildes is not used. pointer_to_args is a
196 pointer to a struct nd_mergearg which has the
197 following members:
198 char s_uaddr; /* server's universal address */
200 char c_uaddr; /* client's universal address */
201 char m_uaddr; /* the result */
202 If s_uaddr is an address such as 0.0.0.0.1.12,
204 and the call is successful m_uaddr is set to
205 an address such as 192.11.109.89.1.12. For
206 most transports, m_uaddr is identical to
207 s_uaddr.
208
211 The netdir_perror() function prints an error message in standard output
212 that states the cause of a name-to-address mapping failure. The error
213 message is preceded by the string given as an argument.
214 The netdir_sperror() function returns a string with an error message
217 that states the cause of a name-to-address mapping failure.
218 The netdir_sperror() function returns a pointer to a buffer which con‐
221 tains the error message string. The buffer is overwritten on each call.
222 In multithreaded applications, thise buffer is implemented as thread-
223 specific data.
224 The netdir_getbyaddr() function returns 0 on success and a non-zero
227 value on failure.
228
230 See attributes(5) for descriptions of the following attributes:
231 ┌─────────────────────────────┬─────────────────────────────┐
236 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
237 ├─────────────────────────────┼─────────────────────────────┤
238 │MT-Level │Safe │
239 └─────────────────────────────┴─────────────────────────────┘
240
242 gethostname(3C), getnetconfig(3NSL), getnetpath(3NSL), netconfig(4),
243 attributes(5)
244SunOS 5.11 28 Jan 2005 netdir(3NSL)