1 cfa37a7b 2004-04-10 devnull .TH DIAL 3
3 cfa37a7b 2004-04-10 devnull dial, hangup, announce, listen, accept, reject, netmkaddr, setnetmtpt, getnetconninfo, freenetconninfo \- 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 hangup(int ctl)
16 cfa37a7b 2004-04-10 devnull int announce(char *addr, char *dir)
19 cfa37a7b 2004-04-10 devnull int listen(char *dir, char *newdir)
22 cfa37a7b 2004-04-10 devnull int accept(int ctl, char *dir)
25 cfa37a7b 2004-04-10 devnull int reject(int ctl, char *dir, char *cause)
28 cfa37a7b 2004-04-10 devnull char* netmkaddr(char *addr, char *defnet, char *defservice)
31 cfa37a7b 2004-04-10 devnull void setnetmtpt(char *to, int tolen, char *from)
34 cfa37a7b 2004-04-10 devnull NetConnInfo* getnetconninfo(char *conndir, int fd)
37 cfa37a7b 2004-04-10 devnull void freenetconninfo(NetConnINfo*)
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
47 cfa37a7b 2004-04-10 devnull is any directory listed in
49 cfa37a7b 2004-04-10 devnull or the special token,
50 cfa37a7b 2004-04-10 devnull .BR net .
52 cfa37a7b 2004-04-10 devnull is a free variable that stands for any network in common
53 cfa37a7b 2004-04-10 devnull between the source and the host
54 cfa37a7b 2004-04-10 devnull .IR netaddr .
55 cfa37a7b 2004-04-10 devnull .I Netaddr
56 cfa37a7b 2004-04-10 devnull can be a host name, a domain name, a network address,
57 cfa37a7b 2004-04-10 devnull or a meta-name of the form
58 cfa37a7b 2004-04-10 devnull .BI $ attribute\f1,
60 cfa37a7b 2004-04-10 devnull is replaced by
62 cfa37a7b 2004-04-10 devnull from the value-attribute pair
63 cfa37a7b 2004-04-10 devnull .IB attribute = value
64 cfa37a7b 2004-04-10 devnull most closely associated with the source host in the
65 cfa37a7b 2004-04-10 devnull network data base (see
66 cfa37a7b 2004-04-10 devnull .IR ndb (6)).
68 cfa37a7b 2004-04-10 devnull If a connection attempt is successful and
70 cfa37a7b 2004-04-10 devnull is non-zero,
71 cfa37a7b 2004-04-10 devnull the path name of a
72 cfa37a7b 2004-04-10 devnull .I line directory
73 cfa37a7b 2004-04-10 devnull that has files for accessing the connection
74 cfa37a7b 2004-04-10 devnull is copied into
75 cfa37a7b 2004-04-10 devnull .IR dir .
76 cfa37a7b 2004-04-10 devnull The path name is guaranteed to be less than 40
77 cfa37a7b 2004-04-10 devnull bytes long.
78 cfa37a7b 2004-04-10 devnull One line directory exists for each possible connection.
81 cfa37a7b 2004-04-10 devnull file in the line directory should be used to communicate with the destination.
84 cfa37a7b 2004-04-10 devnull file in the line directory can be used to send commands to the line.
86 cfa37a7b 2004-04-10 devnull .IR ip (3)
87 cfa37a7b 2004-04-10 devnull for messages that can be written to the
90 cfa37a7b 2004-04-10 devnull The last close of the
94 cfa37a7b 2004-04-10 devnull file will close the connection.
97 cfa37a7b 2004-04-10 devnull makes a call to destination
99 cfa37a7b 2004-04-10 devnull on a multiplexed network.
100 cfa37a7b 2004-04-10 devnull If the network in
103 cfa37a7b 2004-04-10 devnull .BR net ,
105 cfa37a7b 2004-04-10 devnull will try in succession all
106 cfa37a7b 2004-04-10 devnull networks in common between source and destination
107 cfa37a7b 2004-04-10 devnull until a call succeeds.
108 cfa37a7b 2004-04-10 devnull It returns a file descriptor open for reading and writing the
110 cfa37a7b 2004-04-10 devnull file in the line directory.
113 cfa37a7b 2004-04-10 devnull file in the line directory contains the address called.
114 cfa37a7b 2004-04-10 devnull If the network allows the local address to be set,
115 cfa37a7b 2004-04-10 devnull as is the case with UDP and TCP port numbers, and
116 cfa37a7b 2004-04-10 devnull .IR local
117 cfa37a7b 2004-04-10 devnull is non-zero, the local address will be set to
118 cfa37a7b 2004-04-10 devnull .IR local .
121 cfa37a7b 2004-04-10 devnull is non-zero,
122 cfa37a7b 2004-04-10 devnull .BI * cfdp
123 cfa37a7b 2004-04-10 devnull is set to a file descriptor open for reading and
124 cfa37a7b 2004-04-10 devnull writing the control file.
126 cfa37a7b 2004-04-10 devnull .I Hangup
127 cfa37a7b 2004-04-10 devnull is a means of forcing a connection to hang up without
128 cfa37a7b 2004-04-10 devnull closing the
134 cfa37a7b 2004-04-10 devnull .I Announce
136 cfa37a7b 2004-04-10 devnull .I listen
137 cfa37a7b 2004-04-10 devnull are the complements of
138 cfa37a7b 2004-04-10 devnull .IR dial .
139 cfa37a7b 2004-04-10 devnull .I Announce
140 cfa37a7b 2004-04-10 devnull establishes a network
141 cfa37a7b 2004-04-10 devnull name to which calls can be made.
143 cfa37a7b 2004-04-10 devnull .IR dial ,
144 cfa37a7b 2004-04-10 devnull .I announce
145 cfa37a7b 2004-04-10 devnull returns an open
149 cfa37a7b 2004-04-10 devnull .I netaddr
150 cfa37a7b 2004-04-10 devnull used in announce may be a local address or an asterisk,
151 cfa37a7b 2004-04-10 devnull to indicate all local addresses, e.g.
152 cfa37a7b 2004-04-10 devnull .BR tcp!*!echo .
154 cfa37a7b 2004-04-10 devnull .I listen
155 cfa37a7b 2004-04-10 devnull routine takes as its first argument the
157 cfa37a7b 2004-04-10 devnull of a previous
158 cfa37a7b 2004-04-10 devnull .IR announce .
159 cfa37a7b 2004-04-10 devnull When a call is received,
160 cfa37a7b 2004-04-10 devnull .I listen
161 cfa37a7b 2004-04-10 devnull returns an open
163 cfa37a7b 2004-04-10 devnull file for the line the call was received on.
165 cfa37a7b 2004-04-10 devnull .I newdir
166 cfa37a7b 2004-04-10 devnull to the path name of the new line directory.
167 cfa37a7b 2004-04-10 devnull .I Accept
168 cfa37a7b 2004-04-10 devnull accepts a call received by
169 cfa37a7b 2004-04-10 devnull .IR listen ,
171 cfa37a7b 2004-04-10 devnull .I reject
172 cfa37a7b 2004-04-10 devnull refuses the call because of
173 cfa37a7b 2004-04-10 devnull .IR cause .
174 cfa37a7b 2004-04-10 devnull .I Accept
175 cfa37a7b 2004-04-10 devnull returns a file descriptor for the data file opened
176 cfa37a7b 2004-04-10 devnull .BR ORDWR .
178 cfa37a7b 2004-04-10 devnull .I Netmkaddr
179 cfa37a7b 2004-04-10 devnull makes an address suitable for dialing or announcing.
180 cfa37a7b 2004-04-10 devnull It takes an address along with a default network and service to use
181 cfa37a7b 2004-04-10 devnull if they are not specified in the address.
182 cfa37a7b 2004-04-10 devnull It returns a pointer to static data holding the actual address to use.
184 cfa37a7b 2004-04-10 devnull .I Getnetconninfo
185 cfa37a7b 2004-04-10 devnull returns a structure containing information about a
186 cfa37a7b 2004-04-10 devnull network connection. The structure is:
188 cfa37a7b 2004-04-10 devnull typedef struct NetConnInfo NetConnInfo;
189 cfa37a7b 2004-04-10 devnull struct NetConnInfo
191 cfa37a7b 2004-04-10 devnull char *dir; /* connection directory */
192 cfa37a7b 2004-04-10 devnull char *root; /* network root */
193 cfa37a7b 2004-04-10 devnull char *spec; /* binding spec */
194 cfa37a7b 2004-04-10 devnull char *lsys; /* local system */
195 cfa37a7b 2004-04-10 devnull char *lserv; /* local service */
196 cfa37a7b 2004-04-10 devnull char *rsys; /* remote system */
197 cfa37a7b 2004-04-10 devnull char *rserv; /* remote service */
201 cfa37a7b 2004-04-10 devnull The information is obtained from the connection directory,
202 cfa37a7b 2004-04-10 devnull .IR conndir .
204 cfa37a7b 2004-04-10 devnull .I conndir
205 cfa37a7b 2004-04-10 devnull is nil, the directory is obtained by performing
206 bf8a59fa 2004-04-11 devnull .IR fd2path (3)
208 cfa37a7b 2004-04-10 devnull .IR fd .
209 cfa37a7b 2004-04-10 devnull .I Getnetconninfo
210 cfa37a7b 2004-04-10 devnull returns either a completely specified structure, or
211 cfa37a7b 2004-04-10 devnull nil if either the structure can't be allocated or the
212 cfa37a7b 2004-04-10 devnull network directory can't be determined.
213 cfa37a7b 2004-04-10 devnull The structure
214 cfa37a7b 2004-04-10 devnull is freed using
215 cfa37a7b 2004-04-10 devnull .IR freenetconninfo .
217 cfa37a7b 2004-04-10 devnull .I Setnetmtpt
218 cfa37a7b 2004-04-10 devnull copies the name of the network mount point into
219 cfa37a7b 2004-04-10 devnull the buffer
220 cfa37a7b 2004-04-10 devnull .IR to ,
221 cfa37a7b 2004-04-10 devnull whose length is
222 cfa37a7b 2004-04-10 devnull .IR tolen .
223 cfa37a7b 2004-04-10 devnull It exists to merge two pre-existing conventions for specifying
224 cfa37a7b 2004-04-10 devnull the mount point.
225 cfa37a7b 2004-04-10 devnull Commands that take a network mount point as a parameter
226 cfa37a7b 2004-04-10 devnull (such as
227 cfa37a7b 2004-04-10 devnull .BR dns ,
230 cfa37a7b 2004-04-10 devnull .IR ndb (8)),
232 cfa37a7b 2004-04-10 devnull .IR ipconfig (8))
233 cfa37a7b 2004-04-10 devnull should now call
234 cfa37a7b 2004-04-10 devnull .IR setnetmtpt .
238 cfa37a7b 2004-04-10 devnull .BR nil ,
239 cfa37a7b 2004-04-10 devnull the mount point is set to the default,
240 cfa37a7b 2004-04-10 devnull .BR /net .
243 cfa37a7b 2004-04-10 devnull points to a string starting with a slash,
244 cfa37a7b 2004-04-10 devnull the mount point is that path.
245 cfa37a7b 2004-04-10 devnull Otherwise, the mount point is the string pointed to by
247 cfa37a7b 2004-04-10 devnull appended to the string
248 cfa37a7b 2004-04-10 devnull .BR /net .
249 cfa37a7b 2004-04-10 devnull The last form is obsolete and is should be avoided.
250 cfa37a7b 2004-04-10 devnull It exists only to aid in conversion.
251 cfa37a7b 2004-04-10 devnull .SH EXAMPLES
252 cfa37a7b 2004-04-10 devnull Make a call and return an open file descriptor to
253 cfa37a7b 2004-04-10 devnull use for communications:
256 cfa37a7b 2004-04-10 devnull int callkremvax(void)
258 cfa37a7b 2004-04-10 devnull return dial("kremvax", 0, 0, 0);
262 cfa37a7b 2004-04-10 devnull Call the local authentication server:
265 cfa37a7b 2004-04-10 devnull int dialauth(char *service)
267 cfa37a7b 2004-04-10 devnull return dial(netmkaddr("$auth", 0, service), 0, 0, 0);
271 cfa37a7b 2004-04-10 devnull Announce as
272 cfa37a7b 2004-04-10 devnull .B kremvax
273 cfa37a7b 2004-04-10 devnull on TCP/IP and
274 cfa37a7b 2004-04-10 devnull loop forever receiving calls and echoing back
275 cfa37a7b 2004-04-10 devnull to the caller anything sent:
279 cfa37a7b 2004-04-10 devnull bekremvax(void)
281 cfa37a7b 2004-04-10 devnull int dfd, acfd, lcfd;
282 cfa37a7b 2004-04-10 devnull char adir[40], ldir[40];
284 cfa37a7b 2004-04-10 devnull char buf[256];
286 cfa37a7b 2004-04-10 devnull acfd = announce("tcp!*!7", adir);
287 cfa37a7b 2004-04-10 devnull if(acfd < 0)
288 cfa37a7b 2004-04-10 devnull return -1;
289 cfa37a7b 2004-04-10 devnull for(;;){
290 cfa37a7b 2004-04-10 devnull /* listen for a call */
291 cfa37a7b 2004-04-10 devnull lcfd = listen(adir, ldir);
292 cfa37a7b 2004-04-10 devnull if(lcfd < 0)
293 cfa37a7b 2004-04-10 devnull return -1;
294 cfa37a7b 2004-04-10 devnull /* fork a process to echo */
295 cfa37a7b 2004-04-10 devnull switch(fork()){
296 cfa37a7b 2004-04-10 devnull case -1:
297 cfa37a7b 2004-04-10 devnull perror("forking");
298 cfa37a7b 2004-04-10 devnull close(lcfd);
301 cfa37a7b 2004-04-10 devnull /* accept the call and open the data file */
302 cfa37a7b 2004-04-10 devnull dfd = accept(lcfd, ldir);
303 cfa37a7b 2004-04-10 devnull if(dfd < 0)
304 cfa37a7b 2004-04-10 devnull return -1;
306 cfa37a7b 2004-04-10 devnull /* echo until EOF */
307 cfa37a7b 2004-04-10 devnull while((n = read(dfd, buf, sizeof(buf))) > 0)
308 cfa37a7b 2004-04-10 devnull write(dfd, buf, n);
309 cfa37a7b 2004-04-10 devnull exits(0);
310 cfa37a7b 2004-04-10 devnull default:
311 cfa37a7b 2004-04-10 devnull close(lcfd);
317 cfa37a7b 2004-04-10 devnull .SH SOURCE
318 b5fdffee 2004-04-19 devnull .BR /usr/local/plan9/src/libc/9sys ,
319 b5fdffee 2004-04-19 devnull .B /usr/local/plan9/src/libc/port
320 cfa37a7b 2004-04-10 devnull .SH "SEE ALSO"
321 bf8a59fa 2004-04-11 devnull .IR auth (3),
322 cfa37a7b 2004-04-10 devnull .IR ip (3),
323 cfa37a7b 2004-04-10 devnull .IR ndb (8)
324 cfa37a7b 2004-04-10 devnull .SH DIAGNOSTICS
325 cfa37a7b 2004-04-10 devnull .IR Dial ,
326 cfa37a7b 2004-04-10 devnull .IR announce ,
328 cfa37a7b 2004-04-10 devnull .I listen
329 cfa37a7b 2004-04-10 devnull return \-1 if they fail.
330 cfa37a7b 2004-04-10 devnull .I Hangup
331 cfa37a7b 2004-04-10 devnull returns nonzero if it fails.
