dial.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) .