1 cfa37a7b 2004-04-10 devnull .TH DIAL 3
3 058b0118 2005-01-03 devnull dial, hangup, 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 058b0118 2005-01-03 devnull int dialparse(char *addr, char **net, char **unix, u32int *host, int *port)
38 cfa37a7b 2004-04-10 devnull .SH DESCRIPTION
39 cfa37a7b 2004-04-10 devnull For these routines,
41 cfa37a7b 2004-04-10 devnull is a network address of the form
42 cfa37a7b 2004-04-10 devnull .IB network ! netaddr ! service\f1,
43 cfa37a7b 2004-04-10 devnull .IB network ! netaddr\f1,
44 cfa37a7b 2004-04-10 devnull or simply
45 cfa37a7b 2004-04-10 devnull .IR netaddr .
46 cfa37a7b 2004-04-10 devnull .I Network
48 058b0118 2005-01-03 devnull .BR tcp ,
49 058b0118 2005-01-03 devnull .BR udp ,
50 058b0118 2005-01-03 devnull .BR unix ,
51 cfa37a7b 2004-04-10 devnull or the special token,
52 cfa37a7b 2004-04-10 devnull .BR net .
54 cfa37a7b 2004-04-10 devnull is a free variable that stands for any network in common
55 cfa37a7b 2004-04-10 devnull between the source and the host
56 cfa37a7b 2004-04-10 devnull .IR netaddr .
57 cfa37a7b 2004-04-10 devnull .I Netaddr
58 058b0118 2005-01-03 devnull can be a host name, a domain name, or a network address.
59 058b0118 2005-01-03 devnull .\" or a meta-name of the form
60 058b0118 2005-01-03 devnull .\" .BI $ attribute\f1,
61 058b0118 2005-01-03 devnull .\" which
62 058b0118 2005-01-03 devnull .\" is replaced by
63 058b0118 2005-01-03 devnull .\" .I value
64 058b0118 2005-01-03 devnull .\" from the value-attribute pair
65 058b0118 2005-01-03 devnull .\" .IB attribute = value
66 058b0118 2005-01-03 devnull .\" most closely associated with the source host in the
67 058b0118 2005-01-03 devnull .\" network data base (see
68 058b0118 2005-01-03 devnull .\" .IR ndb (6)).
70 058b0118 2005-01-03 devnull On Plan 9, the
72 058b0118 2005-01-03 devnull argument is a path name to a
73 cfa37a7b 2004-04-10 devnull .I line directory
74 058b0118 2005-01-03 devnull that has files for accessing the connection.
75 058b0118 2005-01-03 devnull To keep the same function signatures,
76 058b0118 2005-01-03 devnull the Unix port of these routines uses strings of the form
77 058b0118 2005-01-03 devnull .BI /dev/fd/ n
78 058b0118 2005-01-03 devnull instead of line directory paths.
79 058b0118 2005-01-03 devnull These strings should be treated as opaque data and ignored.
82 cfa37a7b 2004-04-10 devnull makes a call to destination
84 cfa37a7b 2004-04-10 devnull on a multiplexed network.
85 cfa37a7b 2004-04-10 devnull If the network in
88 cfa37a7b 2004-04-10 devnull .BR net ,
90 cfa37a7b 2004-04-10 devnull will try in succession all
91 cfa37a7b 2004-04-10 devnull networks in common between source and destination
92 cfa37a7b 2004-04-10 devnull until a call succeeds.
93 cfa37a7b 2004-04-10 devnull It returns a file descriptor open for reading and writing the
95 cfa37a7b 2004-04-10 devnull file in the line directory.
98 cfa37a7b 2004-04-10 devnull file in the line directory contains the address called.
99 058b0118 2005-01-03 devnull .\" If the network allows the local address to be set,
100 058b0118 2005-01-03 devnull .\" as is the case with UDP and TCP port numbers, and
101 058b0118 2005-01-03 devnull .\" .IR local
102 058b0118 2005-01-03 devnull .\" is non-zero, the local address will be set to
103 058b0118 2005-01-03 devnull .\" .IR local .
104 058b0118 2005-01-03 devnull .IR Dial 's
105 058b0118 2005-01-03 devnull .IR local ,
106 058b0118 2005-01-03 devnull .IR dir ,
109 058b0118 2005-01-03 devnull arguments
110 058b0118 2005-01-03 devnull are not supported and must be zero.
112 cfa37a7b 2004-04-10 devnull .I Announce
114 cfa37a7b 2004-04-10 devnull .I listen
115 cfa37a7b 2004-04-10 devnull are the complements of
116 cfa37a7b 2004-04-10 devnull .IR dial .
117 cfa37a7b 2004-04-10 devnull .I Announce
118 cfa37a7b 2004-04-10 devnull establishes a network
119 cfa37a7b 2004-04-10 devnull name to which calls can be made.
121 cfa37a7b 2004-04-10 devnull .IR dial ,
122 cfa37a7b 2004-04-10 devnull .I announce
123 cfa37a7b 2004-04-10 devnull returns an open
127 cfa37a7b 2004-04-10 devnull .I netaddr
128 cfa37a7b 2004-04-10 devnull used in announce may be a local address or an asterisk,
129 cfa37a7b 2004-04-10 devnull to indicate all local addresses, e.g.
130 cfa37a7b 2004-04-10 devnull .BR tcp!*!echo .
132 cfa37a7b 2004-04-10 devnull .I listen
133 cfa37a7b 2004-04-10 devnull routine takes as its first argument the
135 cfa37a7b 2004-04-10 devnull of a previous
136 cfa37a7b 2004-04-10 devnull .IR announce .
137 cfa37a7b 2004-04-10 devnull When a call is received,
138 cfa37a7b 2004-04-10 devnull .I listen
139 cfa37a7b 2004-04-10 devnull returns an open
141 cfa37a7b 2004-04-10 devnull file for the line the call was received on.
143 cfa37a7b 2004-04-10 devnull .I newdir
144 cfa37a7b 2004-04-10 devnull to the path name of the new line directory.
145 cfa37a7b 2004-04-10 devnull .I Accept
146 cfa37a7b 2004-04-10 devnull accepts a call received by
147 cfa37a7b 2004-04-10 devnull .IR listen ,
149 cfa37a7b 2004-04-10 devnull .I reject
150 cfa37a7b 2004-04-10 devnull refuses the call because of
151 cfa37a7b 2004-04-10 devnull .IR cause .
152 cfa37a7b 2004-04-10 devnull .I Accept
153 cfa37a7b 2004-04-10 devnull returns a file descriptor for the data file opened
154 cfa37a7b 2004-04-10 devnull .BR ORDWR .
156 cfa37a7b 2004-04-10 devnull .I Netmkaddr
157 cfa37a7b 2004-04-10 devnull makes an address suitable for dialing or announcing.
158 cfa37a7b 2004-04-10 devnull It takes an address along with a default network and service to use
159 cfa37a7b 2004-04-10 devnull if they are not specified in the address.
160 cfa37a7b 2004-04-10 devnull It returns a pointer to static data holding the actual address to use.
162 058b0118 2005-01-03 devnull .I Dialparse
163 058b0118 2005-01-03 devnull parses a network address as described above
164 058b0118 2005-01-03 devnull into a network name, a Unix domain socket address,
165 058b0118 2005-01-03 devnull an IPv4 host address, and an IPv4 port number.
167 058b0118 2005-01-03 devnull .\" .I Getnetconninfo
168 058b0118 2005-01-03 devnull .\" returns a structure containing information about a
169 058b0118 2005-01-03 devnull .\" network connection. The structure is:
171 058b0118 2005-01-03 devnull .\" typedef struct NetConnInfo NetConnInfo;
172 058b0118 2005-01-03 devnull .\" struct NetConnInfo
174 058b0118 2005-01-03 devnull .\" char *dir; /* connection directory */
175 058b0118 2005-01-03 devnull .\" char *root; /* network root */
176 058b0118 2005-01-03 devnull .\" char *spec; /* binding spec */
177 058b0118 2005-01-03 devnull .\" char *lsys; /* local system */
178 058b0118 2005-01-03 devnull .\" char *lserv; /* local service */
179 058b0118 2005-01-03 devnull .\" char *rsys; /* remote system */
180 058b0118 2005-01-03 devnull .\" char *rserv; /* remote service */
184 058b0118 2005-01-03 devnull .\" The information is obtained from the connection directory,
185 058b0118 2005-01-03 devnull .\" .IR conndir .
187 058b0118 2005-01-03 devnull .\" .I conndir
188 058b0118 2005-01-03 devnull .\" is nil, the directory is obtained by performing
189 058b0118 2005-01-03 devnull .\" .IR fd2path (3)
191 058b0118 2005-01-03 devnull .\" .IR fd .
192 058b0118 2005-01-03 devnull .\" .I Getnetconninfo
193 058b0118 2005-01-03 devnull .\" returns either a completely specified structure, or
194 058b0118 2005-01-03 devnull .\" nil if either the structure can't be allocated or the
195 058b0118 2005-01-03 devnull .\" network directory can't be determined.
196 058b0118 2005-01-03 devnull .\" The structure
197 058b0118 2005-01-03 devnull .\" is freed using
198 058b0118 2005-01-03 devnull .\" .IR freenetconninfo .
200 058b0118 2005-01-03 devnull .\" .I Setnetmtpt
201 058b0118 2005-01-03 devnull .\" copies the name of the network mount point into
202 058b0118 2005-01-03 devnull .\" the buffer
203 058b0118 2005-01-03 devnull .\" .IR to ,
204 058b0118 2005-01-03 devnull .\" whose length is
205 058b0118 2005-01-03 devnull .\" .IR tolen .
206 058b0118 2005-01-03 devnull .\" It exists to merge two pre-existing conventions for specifying
207 058b0118 2005-01-03 devnull .\" the mount point.
208 058b0118 2005-01-03 devnull .\" Commands that take a network mount point as a parameter
209 058b0118 2005-01-03 devnull .\" (such as
210 058b0118 2005-01-03 devnull .\" .BR dns ,
211 058b0118 2005-01-03 devnull .\" .BR cs
212 058b0118 2005-01-03 devnull .\" (see
213 058b0118 2005-01-03 devnull .\" .IR ndb (8)),
215 058b0118 2005-01-03 devnull .\" .IR ipconfig (8))
216 058b0118 2005-01-03 devnull .\" should now call
217 058b0118 2005-01-03 devnull .\" .IR setnetmtpt .
219 058b0118 2005-01-03 devnull .\" .I from
221 058b0118 2005-01-03 devnull .\" .BR nil ,
222 058b0118 2005-01-03 devnull .\" the mount point is set to the default,
223 058b0118 2005-01-03 devnull .\" .BR /net .
225 058b0118 2005-01-03 devnull .\" .I from
226 058b0118 2005-01-03 devnull .\" points to a string starting with a slash,
227 058b0118 2005-01-03 devnull .\" the mount point is that path.
228 058b0118 2005-01-03 devnull .\" Otherwise, the mount point is the string pointed to by
229 058b0118 2005-01-03 devnull .\" .I from
230 058b0118 2005-01-03 devnull .\" appended to the string
231 058b0118 2005-01-03 devnull .\" .BR /net .
232 058b0118 2005-01-03 devnull .\" The last form is obsolete and is should be avoided.
233 058b0118 2005-01-03 devnull .\" It exists only to aid in conversion.
234 cfa37a7b 2004-04-10 devnull .SH EXAMPLES
235 cfa37a7b 2004-04-10 devnull Make a call and return an open file descriptor to
236 cfa37a7b 2004-04-10 devnull use for communications:
239 cfa37a7b 2004-04-10 devnull int callkremvax(void)
241 cfa37a7b 2004-04-10 devnull return dial("kremvax", 0, 0, 0);
245 058b0118 2005-01-03 devnull Connect to a Unix socket served by
246 058b0118 2005-01-03 devnull .IR acme (4):
249 058b0118 2005-01-03 devnull int dialacme(void)
251 058b0118 2005-01-03 devnull return dial("unix!/tmp/ns.ken.:0/acme", 0, 0, 0);
255 cfa37a7b 2004-04-10 devnull Announce as
256 cfa37a7b 2004-04-10 devnull .B kremvax
257 cfa37a7b 2004-04-10 devnull on TCP/IP and
258 cfa37a7b 2004-04-10 devnull loop forever receiving calls and echoing back
259 cfa37a7b 2004-04-10 devnull to the caller anything sent:
263 cfa37a7b 2004-04-10 devnull bekremvax(void)
265 cfa37a7b 2004-04-10 devnull int dfd, acfd, lcfd;
266 cfa37a7b 2004-04-10 devnull char adir[40], ldir[40];
268 cfa37a7b 2004-04-10 devnull char buf[256];
270 cfa37a7b 2004-04-10 devnull acfd = announce("tcp!*!7", adir);
271 cfa37a7b 2004-04-10 devnull if(acfd < 0)
272 cfa37a7b 2004-04-10 devnull return -1;
273 cfa37a7b 2004-04-10 devnull for(;;){
274 cfa37a7b 2004-04-10 devnull /* listen for a call */
275 cfa37a7b 2004-04-10 devnull lcfd = listen(adir, ldir);
276 cfa37a7b 2004-04-10 devnull if(lcfd < 0)
277 cfa37a7b 2004-04-10 devnull return -1;
278 cfa37a7b 2004-04-10 devnull /* fork a process to echo */
279 cfa37a7b 2004-04-10 devnull switch(fork()){
280 cfa37a7b 2004-04-10 devnull case -1:
281 cfa37a7b 2004-04-10 devnull perror("forking");
282 cfa37a7b 2004-04-10 devnull close(lcfd);
285 cfa37a7b 2004-04-10 devnull /* accept the call and open the data file */
286 cfa37a7b 2004-04-10 devnull dfd = accept(lcfd, ldir);
287 cfa37a7b 2004-04-10 devnull if(dfd < 0)
288 cfa37a7b 2004-04-10 devnull return -1;
290 cfa37a7b 2004-04-10 devnull /* echo until EOF */
291 cfa37a7b 2004-04-10 devnull while((n = read(dfd, buf, sizeof(buf))) > 0)
292 cfa37a7b 2004-04-10 devnull write(dfd, buf, n);
293 cfa37a7b 2004-04-10 devnull exits(0);
294 cfa37a7b 2004-04-10 devnull default:
295 cfa37a7b 2004-04-10 devnull close(lcfd);
301 cfa37a7b 2004-04-10 devnull .SH SOURCE
302 c3674de4 2005-01-11 devnull .B \*9/src/lib9/dial.c
304 c3674de4 2005-01-11 devnull .B \*9/src/lib9/announce.c
306 c3674de4 2005-01-11 devnull .B \*9/src/lib9/_p9dialparse.c
307 cfa37a7b 2004-04-10 devnull .SH DIAGNOSTICS
308 cfa37a7b 2004-04-10 devnull .IR Dial ,
309 cfa37a7b 2004-04-10 devnull .IR announce ,
311 cfa37a7b 2004-04-10 devnull .I listen
312 cfa37a7b 2004-04-10 devnull return \-1 if they fail.
