1 cfa37a7b 2004-04-10 devnull .TH DIAL 3
3 c8b6342d 2005-01-13 devnull dial, announce, listen, accept, reject, netmkaddr, 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 058b0118 2005-01-03 devnull .\" NetConnInfo* getnetconninfo(char *conndir, int fd)
34 058b0118 2005-01-03 devnull .\" void freenetconninfo(NetConnINfo*)
37 c8b6342d 2005-01-13 devnull int dialparse(char *addr, char **net, char **unix,
40 c8b6342d 2005-01-13 devnull u32int *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 cfa37a7b 2004-04-10 devnull file in the line directory.
101 cfa37a7b 2004-04-10 devnull file in the line directory contains the address called.
102 058b0118 2005-01-03 devnull .\" If the network allows the local address to be set,
103 058b0118 2005-01-03 devnull .\" as is the case with UDP and TCP port numbers, and
104 058b0118 2005-01-03 devnull .\" .IR local
105 058b0118 2005-01-03 devnull .\" is non-zero, the local address will be set to
106 058b0118 2005-01-03 devnull .\" .IR local .
107 058b0118 2005-01-03 devnull .IR Dial 's
108 058b0118 2005-01-03 devnull .IR local ,
109 058b0118 2005-01-03 devnull .IR dir ,
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 058b0118 2005-01-03 devnull .I Dialparse
166 058b0118 2005-01-03 devnull parses a network address as described above
167 058b0118 2005-01-03 devnull into a network name, a Unix domain socket address,
168 058b0118 2005-01-03 devnull an IPv4 host address, and an IPv4 port number.
170 058b0118 2005-01-03 devnull .\" .I Getnetconninfo
171 058b0118 2005-01-03 devnull .\" returns a structure containing information about a
172 058b0118 2005-01-03 devnull .\" network connection. The structure is:
174 058b0118 2005-01-03 devnull .\" typedef struct NetConnInfo NetConnInfo;
175 058b0118 2005-01-03 devnull .\" struct NetConnInfo
177 058b0118 2005-01-03 devnull .\" char *dir; /* connection directory */
178 058b0118 2005-01-03 devnull .\" char *root; /* network root */
179 058b0118 2005-01-03 devnull .\" char *spec; /* binding spec */
180 058b0118 2005-01-03 devnull .\" char *lsys; /* local system */
181 058b0118 2005-01-03 devnull .\" char *lserv; /* local service */
182 058b0118 2005-01-03 devnull .\" char *rsys; /* remote system */
183 058b0118 2005-01-03 devnull .\" char *rserv; /* remote service */
187 058b0118 2005-01-03 devnull .\" The information is obtained from the connection directory,
188 058b0118 2005-01-03 devnull .\" .IR conndir .
190 058b0118 2005-01-03 devnull .\" .I conndir
191 058b0118 2005-01-03 devnull .\" is nil, the directory is obtained by performing
192 058b0118 2005-01-03 devnull .\" .IR fd2path (3)
194 058b0118 2005-01-03 devnull .\" .IR fd .
195 058b0118 2005-01-03 devnull .\" .I Getnetconninfo
196 058b0118 2005-01-03 devnull .\" returns either a completely specified structure, or
197 058b0118 2005-01-03 devnull .\" nil if either the structure can't be allocated or the
198 058b0118 2005-01-03 devnull .\" network directory can't be determined.
199 058b0118 2005-01-03 devnull .\" The structure
200 058b0118 2005-01-03 devnull .\" is freed using
201 058b0118 2005-01-03 devnull .\" .IR freenetconninfo .
203 058b0118 2005-01-03 devnull .\" .I Setnetmtpt
204 058b0118 2005-01-03 devnull .\" copies the name of the network mount point into
205 058b0118 2005-01-03 devnull .\" the buffer
206 058b0118 2005-01-03 devnull .\" .IR to ,
207 058b0118 2005-01-03 devnull .\" whose length is
208 058b0118 2005-01-03 devnull .\" .IR tolen .
209 058b0118 2005-01-03 devnull .\" It exists to merge two pre-existing conventions for specifying
210 058b0118 2005-01-03 devnull .\" the mount point.
211 058b0118 2005-01-03 devnull .\" Commands that take a network mount point as a parameter
212 058b0118 2005-01-03 devnull .\" (such as
213 058b0118 2005-01-03 devnull .\" .BR dns ,
214 058b0118 2005-01-03 devnull .\" .BR cs
215 058b0118 2005-01-03 devnull .\" (see
216 058b0118 2005-01-03 devnull .\" .IR ndb (8)),
218 058b0118 2005-01-03 devnull .\" .IR ipconfig (8))
219 058b0118 2005-01-03 devnull .\" should now call
220 058b0118 2005-01-03 devnull .\" .IR setnetmtpt .
222 058b0118 2005-01-03 devnull .\" .I from
224 058b0118 2005-01-03 devnull .\" .BR nil ,
225 058b0118 2005-01-03 devnull .\" the mount point is set to the default,
226 058b0118 2005-01-03 devnull .\" .BR /net .
228 058b0118 2005-01-03 devnull .\" .I from
229 058b0118 2005-01-03 devnull .\" points to a string starting with a slash,
230 058b0118 2005-01-03 devnull .\" the mount point is that path.
231 058b0118 2005-01-03 devnull .\" Otherwise, the mount point is the string pointed to by
232 058b0118 2005-01-03 devnull .\" .I from
233 058b0118 2005-01-03 devnull .\" appended to the string
234 058b0118 2005-01-03 devnull .\" .BR /net .
235 058b0118 2005-01-03 devnull .\" The last form is obsolete and is should be avoided.
236 058b0118 2005-01-03 devnull .\" It exists only to aid in conversion.
237 cfa37a7b 2004-04-10 devnull .SH EXAMPLES
238 cfa37a7b 2004-04-10 devnull Make a call and return an open file descriptor to
239 cfa37a7b 2004-04-10 devnull use for communications:
242 cfa37a7b 2004-04-10 devnull int callkremvax(void)
244 cfa37a7b 2004-04-10 devnull return dial("kremvax", 0, 0, 0);
248 058b0118 2005-01-03 devnull Connect to a Unix socket served by
249 058b0118 2005-01-03 devnull .IR acme (4):
252 058b0118 2005-01-03 devnull int dialacme(void)
254 058b0118 2005-01-03 devnull return dial("unix!/tmp/ns.ken.:0/acme", 0, 0, 0);
258 cfa37a7b 2004-04-10 devnull Announce as
259 cfa37a7b 2004-04-10 devnull .B kremvax
260 cfa37a7b 2004-04-10 devnull on TCP/IP and
261 cfa37a7b 2004-04-10 devnull loop forever receiving calls and echoing back
262 cfa37a7b 2004-04-10 devnull to the caller anything sent:
266 cfa37a7b 2004-04-10 devnull bekremvax(void)
268 cfa37a7b 2004-04-10 devnull int dfd, acfd, lcfd;
269 cfa37a7b 2004-04-10 devnull char adir[40], ldir[40];
271 cfa37a7b 2004-04-10 devnull char buf[256];
273 cfa37a7b 2004-04-10 devnull acfd = announce("tcp!*!7", adir);
274 cfa37a7b 2004-04-10 devnull if(acfd < 0)
275 cfa37a7b 2004-04-10 devnull return -1;
276 cfa37a7b 2004-04-10 devnull for(;;){
277 cfa37a7b 2004-04-10 devnull /* listen for a call */
278 cfa37a7b 2004-04-10 devnull lcfd = listen(adir, ldir);
279 cfa37a7b 2004-04-10 devnull if(lcfd < 0)
280 cfa37a7b 2004-04-10 devnull return -1;
281 cfa37a7b 2004-04-10 devnull /* fork a process to echo */
282 cfa37a7b 2004-04-10 devnull switch(fork()){
283 cfa37a7b 2004-04-10 devnull case -1:
284 cfa37a7b 2004-04-10 devnull perror("forking");
285 cfa37a7b 2004-04-10 devnull close(lcfd);
288 cfa37a7b 2004-04-10 devnull /* accept the call and open the data file */
289 cfa37a7b 2004-04-10 devnull dfd = accept(lcfd, ldir);
290 cfa37a7b 2004-04-10 devnull if(dfd < 0)
291 cfa37a7b 2004-04-10 devnull return -1;
293 cfa37a7b 2004-04-10 devnull /* echo until EOF */
294 cfa37a7b 2004-04-10 devnull while((n = read(dfd, buf, sizeof(buf))) > 0)
295 cfa37a7b 2004-04-10 devnull write(dfd, buf, n);
296 cfa37a7b 2004-04-10 devnull exits(0);
297 cfa37a7b 2004-04-10 devnull default:
298 cfa37a7b 2004-04-10 devnull close(lcfd);
304 cfa37a7b 2004-04-10 devnull .SH SOURCE
305 c3674de4 2005-01-11 devnull .B \*9/src/lib9/dial.c
307 c3674de4 2005-01-11 devnull .B \*9/src/lib9/announce.c
309 c3674de4 2005-01-11 devnull .B \*9/src/lib9/_p9dialparse.c
310 cfa37a7b 2004-04-10 devnull .SH DIAGNOSTICS
311 cfa37a7b 2004-04-10 devnull .IR Dial ,
312 cfa37a7b 2004-04-10 devnull .IR announce ,
314 cfa37a7b 2004-04-10 devnull .I listen
315 cfa37a7b 2004-04-10 devnull return \-1 if they fail.
316 c8b6342d 2005-01-13 devnull .SH BUGS
317 c8b6342d 2005-01-13 devnull To avoid name conflicts with the underlying system,
318 c8b6342d 2005-01-13 devnull .IR dial ,
319 c8b6342d 2005-01-13 devnull .IR announce ,
320 c8b6342d 2005-01-13 devnull .IR listen ,
321 c8b6342d 2005-01-13 devnull .IR netmkaddr ,
323 c8b6342d 2005-01-13 devnull .I reject
324 c8b6342d 2005-01-13 devnull are preprocessor macros defined as
325 c8b6342d 2005-01-13 devnull .IR p9dial ,
326 c8b6342d 2005-01-13 devnull .IR p9announce ,
327 c8b6342d 2005-01-13 devnull and so on;
329 c8b6342d 2005-01-13 devnull .IR intro (3).
