tdial.3 - plan9port - [fork] Plan 9 from user space
HTML git clone git://src.adamsgaard.dk/plan9port
DIR Log
DIR Files
DIR Refs
DIR README
DIR LICENSE
---
tdial.3 (7071B)
---
1 .TH DIAL 3
2 .SH NAME
3 dial, announce, listen, accept, reject, netmkaddr, getnetconninfo, freenetconninfo, dialparse \- make and break network connections
4 .SH SYNOPSIS
5 .B #include <u.h>
6 .br
7 .B #include <libc.h>
8 .PP
9 .B
10 int dial(char *addr, char *local, char *dir, int *cfdp)
11 .PP
12 .B
13 int announce(char *addr, char *dir)
14 .PP
15 .B
16 int listen(char *dir, char *newdir)
17 .PP
18 .B
19 int accept(int ctl, char *dir)
20 .PP
21 .B
22 int reject(int ctl, char *dir, char *cause)
23 .PP
24 .B
25 char* netmkaddr(char *addr, char *defnet, char *defservice)
26 .\" .PP
27 .\" .B
28 .\" void setnetmtpt(char *to, int tolen, char *from)
29 .PP
30 .B
31 NetConnInfo* getnetconninfo(char *dir, int fd)
32 .PP
33 .B
34 void freenetconninfo(NetConnINfo*)
35 .PP
36 .B
37 int dialparse(char *addr, char **net, char **unix,
38 .br
39 .B
40 void *host, int *port)
41 .SH DESCRIPTION
42 For these routines,
43 .I addr
44 is a network address of the form
45 .IB network ! netaddr ! service\f1,
46 .IB network ! netaddr\f1,
47 or simply
48 .IR netaddr .
49 .I Network
50 is
51 .BR tcp ,
52 .BR udp ,
53 .BR unix ,
54 or the special token,
55 .BR net .
56 .B Net
57 is a free variable that stands for any network in common
58 between the source and the host
59 .IR netaddr .
60 .I Netaddr
61 can be a host name, a domain name, or a network address.
62 .\" or a meta-name of the form
63 .\" .BI $ attribute\f1,
64 .\" which
65 .\" is replaced by
66 .\" .I value
67 .\" from the value-attribute pair
68 .\" .IB attribute = value
69 .\" most closely associated with the source host in the
70 .\" network data base (see
71 .\" .IR ndb (6)).
72 .PP
73 On Plan 9, the
74 .I dir
75 argument is a path name to a
76 .I line directory
77 that has files for accessing the connection.
78 To keep the same function signatures,
79 the Unix port of these routines uses strings of the form
80 .BI /dev/fd/ n
81 instead of line directory paths.
82 These strings should be treated as opaque data and ignored.
83 .PP
84 .I Dial
85 makes a call to destination
86 .I addr
87 on a multiplexed network.
88 If the network in
89 .I addr
90 is
91 .BR net ,
92 .I dial
93 will try in succession all
94 networks in common between source and destination
95 until a call succeeds.
96 It returns a file descriptor open for reading and writing the
97 call.
98 .\" .B data
99 .\" file in the line directory.
100 .\" The
101 .\" .B addr
102 .\" file in the line directory contains the address called.
103 If the network allows the local address to be set,
104 as is the case with UDP and TCP port numbers, and
105 .IR local
106 is non-zero, the local address will be set to
107 .IR local .
108 .IR Dial 's
109 .IR dir
110 and
111 .I cfdp
112 arguments
113 are not supported and must be zero.
114 .PP
115 .I Announce
116 and
117 .I listen
118 are the complements of
119 .IR dial .
120 .I Announce
121 establishes a network
122 name to which calls can be made.
123 Like
124 .IR dial ,
125 .I announce
126 returns an open
127 .B ctl
128 file.
129 The
130 .I netaddr
131 used in announce may be a local address or an asterisk,
132 to indicate all local addresses, e.g.
133 .BR tcp!*!echo .
134 The
135 .I listen
136 routine takes as its first argument the
137 .I dir
138 of a previous
139 .IR announce .
140 When a call is received,
141 .I listen
142 returns an open
143 .B ctl
144 file for the line the call was received on.
145 It sets
146 .I newdir
147 to the path name of the new line directory.
148 .I Accept
149 accepts a call received by
150 .IR listen ,
151 while
152 .I reject
153 refuses the call because of
154 .IR cause .
155 .I Accept
156 returns a file descriptor for the data file opened
157 .BR ORDWR .
158 .PP
159 .I Netmkaddr
160 makes an address suitable for dialing or announcing.
161 It takes an address along with a default network and service to use
162 if they are not specified in the address.
163 It returns a pointer to static data holding the actual address to use.
164 .PP
165 .I Netmkaddr
166 also translates Unix conventions into Plan 9 syntax.
167 If
168 .I addr
169 is the name of a local file or Unix domain socket,
170 .I netmkaddr
171 will return
172 .IB unix ! addr \fR.
173 If
174 .I addr
175 is of the form
176 .IB host : port \fR,
177 .I netmkaddr
178 will return
179 .IB net ! host ! port \fR.
180 .PP
181 .I Dialparse
182 parses a network address as described above
183 into a network name, a Unix domain socket address,
184 an IP host address, and an IP port number.
185 .PP
186 .I Getnetconninfo
187 returns a structure containing information about a
188 network connection. The structure is:
189 .PP
190 .EX
191 typedef struct NetConnInfo NetConnInfo;
192 struct NetConnInfo
193 {
194 char *dir; /* connection directory */
195 char *root; /* network root */
196 char *spec; /* binding spec */
197 char *lsys; /* local system */
198 char *lserv; /* local service */
199 char *rsys; /* remote system */
200 char *rserv; /* remote service */
201 char *laddr; /* local address */
202 char *raddr; /* remote address */
203 };
204 .EE
205 .PP
206 The information is obtained from the
207 `line directory'
208 .IR dir ,
209 or if
210 .I dir
211 is nil, from the connection file descriptor
212 .IR fd .
213 .I Getnetconninfo
214 returns either a completely specified structure, or
215 nil if either the structure can't be allocated or the
216 network directory can't be determined.
217 The structure
218 is freed using
219 .IR freenetconninfo .
220 .\" .PP
221 .\" .I Setnetmtpt
222 .\" copies the name of the network mount point into
223 .\" the buffer
224 .\" .IR to ,
225 .\" whose length is
226 .\" .IR tolen .
227 .\" It exists to merge two pre-existing conventions for specifying
228 .\" the mount point.
229 .\" Commands that take a network mount point as a parameter
230 .\" (such as
231 .\" .BR dns ,
232 .\" .BR cs
233 .\" (see
234 .\" .IR ndb (8)),
235 .\" and
236 .\" .IR ipconfig (8))
237 .\" should now call
238 .\" .IR setnetmtpt .
239 .\" If
240 .\" .I from
241 .\" is
242 .\" .BR nil ,
243 .\" the mount point is set to the default,
244 .\" .BR /net .
245 .\" If
246 .\" .I from
247 .\" points to a string starting with a slash,
248 .\" the mount point is that path.
249 .\" Otherwise, the mount point is the string pointed to by
250 .\" .I from
251 .\" appended to the string
252 .\" .BR /net .
253 .\" The last form is obsolete and is should be avoided.
254 .\" It exists only to aid in conversion.
255 .SH EXAMPLES
256 Make a call and return an open file descriptor to
257 use for communications:
258 .IP
259 .EX
260 int callkremvax(void)
261 {
262 return dial("kremvax", 0, 0, 0);
263 }
264 .EE
265 .PP
266 Connect to a Unix socket served by
267 .MR acme (4) :
268 .IP
269 .EX
270 int dialacme(void)
271 {
272 return dial("unix!/tmp/ns.ken.:0/acme", 0, 0, 0);
273 }
274 .EE
275 .PP
276 Announce as
277 .B kremvax
278 on TCP/IP and
279 loop forever receiving calls and echoing back
280 to the caller anything sent:
281 .IP
282 .EX
283 int
284 bekremvax(void)
285 {
286 int dfd, acfd, lcfd;
287 char adir[40], ldir[40];
288 int n;
289 char buf[256];
290
291 acfd = announce("tcp!*!7", adir);
292 if(acfd < 0)
293 return -1;
294 for(;;){
295 /* listen for a call */
296 lcfd = listen(adir, ldir);
297 if(lcfd < 0)
298 return -1;
299 /* fork a process to echo */
300 switch(fork()){
301 case -1:
302 perror("forking");
303 close(lcfd);
304 break;
305 case 0:
306 /* accept the call and open the data file */
307 dfd = accept(lcfd, ldir);
308 if(dfd < 0)
309 return -1;
310
311 /* echo until EOF */
312 while((n = read(dfd, buf, sizeof(buf))) > 0)
313 write(dfd, buf, n);
314 exits(0);
315 default:
316 close(lcfd);
317 break;
318 }
319 }
320 }
321 .EE
322 .SH SOURCE
323 .B \*9/src/lib9/dial.c
324 .br
325 .B \*9/src/lib9/announce.c
326 .br
327 .B \*9/src/lib9/_p9dialparse.c
328 .br
329 .B \*9/src/lib9/getnetconn.c
330 .SH DIAGNOSTICS
331 .IR Dial ,
332 .IR announce ,
333 and
334 .I listen
335 return \-1 if they fail.
336 .SH BUGS
337 To avoid name conflicts with the underlying system,
338 .IR dial ,
339 .IR announce ,
340 .IR listen ,
341 .IR netmkaddr ,
342 and
343 .I reject
344 are preprocessor macros defined as
345 .IR p9dial ,
346 .IR p9announce ,
347 and so on;
348 see
349 .MR intro (3) .