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