dial 6.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331
  1. .TH DIAL 2
  2. .SH NAME
  3. dial, hangup, announce, listen, accept, reject, netmkaddr, setnetmtpt, getnetconninfo, freenetconninfo \- 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 hangup(int ctl)
  14. .PP
  15. .B
  16. int announce(char *addr, char *dir)
  17. .PP
  18. .B
  19. int listen(char *dir, char *newdir)
  20. .PP
  21. .B
  22. int accept(int ctl, char *dir)
  23. .PP
  24. .B
  25. int reject(int ctl, char *dir, char *cause)
  26. .PP
  27. .B
  28. char* netmkaddr(char *addr, char *defnet, char *defservice)
  29. .PP
  30. .B
  31. void setnetmtpt(char *to, int tolen, char *from)
  32. .PP
  33. .B
  34. NetConnInfo* getnetconninfo(char *conndir, int fd)
  35. .PP
  36. .B
  37. void freenetconninfo(NetConnINfo*)
  38. .SH DESCRIPTION
  39. For these routines,
  40. .I addr
  41. is a network address of the form
  42. .IB network ! netaddr ! service\f1,
  43. .IB network ! netaddr\f1,
  44. or simply
  45. .IR netaddr .
  46. .I Network
  47. is any directory listed in
  48. .B /net
  49. or the special token,
  50. .BR net .
  51. .B Net
  52. is a free variable that stands for any network in common
  53. between the source and the host
  54. .IR netaddr .
  55. .I Netaddr
  56. can be a host name, a domain name, a network address,
  57. or a meta-name of the form
  58. .BI $ attribute\f1,
  59. which
  60. is replaced by
  61. .I value
  62. from the value-attribute pair
  63. .IB attribute = value
  64. most closely associated with the source host in the
  65. network data base (see
  66. .IR ndb (6)).
  67. .PP
  68. If a connection attempt is successful and
  69. .I dir
  70. is non-zero,
  71. the path name of a
  72. .I line directory
  73. that has files for accessing the connection
  74. is copied into
  75. .IR dir .
  76. The path name is guaranteed to be less than 40
  77. bytes long.
  78. One line directory exists for each possible connection.
  79. The
  80. .B data
  81. file in the line directory should be used to communicate with the destination.
  82. The
  83. .B ctl
  84. file in the line directory can be used to send commands to the line.
  85. See
  86. .IR ip (3)
  87. for messages that can be written to the
  88. .B ctl
  89. file.
  90. The last close of the
  91. .B data
  92. or
  93. .B ctl
  94. file will close the connection.
  95. .PP
  96. .I Dial
  97. makes a call to destination
  98. .I addr
  99. on a multiplexed network.
  100. If the network in
  101. .I addr
  102. is
  103. .BR net ,
  104. .I dial
  105. will try in succession all
  106. networks in common between source and destination
  107. until a call succeeds.
  108. It returns a file descriptor open for reading and writing the
  109. .B data
  110. file in the line directory.
  111. The
  112. .B addr
  113. file in the line directory contains the address called.
  114. If the network allows the local address to be set,
  115. as is the case with UDP and TCP port numbers, and
  116. .IR local
  117. is non-zero, the local address will be set to
  118. .IR local .
  119. If
  120. .I cfdp
  121. is non-zero,
  122. .BI * cfdp
  123. is set to a file descriptor open for reading and
  124. writing the control file.
  125. .PP
  126. .I Hangup
  127. is a means of forcing a connection to hang up without
  128. closing the
  129. .B ctl
  130. and
  131. .B data
  132. files.
  133. .P
  134. .I Announce
  135. and
  136. .I listen
  137. are the complements of
  138. .IR dial .
  139. .I Announce
  140. establishes a network
  141. name to which calls can be made.
  142. Like
  143. .IR dial ,
  144. .I announce
  145. returns an open
  146. .B ctl
  147. file.
  148. The
  149. .I netaddr
  150. used in announce may be a local address or an asterisk,
  151. to indicate all local addresses, e.g.
  152. .BR tcp!*!echo .
  153. The
  154. .I listen
  155. routine takes as its first argument the
  156. .I dir
  157. of a previous
  158. .IR announce .
  159. When a call is received,
  160. .I listen
  161. returns an open
  162. .B ctl
  163. file for the line the call was received on.
  164. It sets
  165. .I newdir
  166. to the path name of the new line directory.
  167. .I Accept
  168. accepts a call received by
  169. .IR listen ,
  170. while
  171. .I reject
  172. refuses the call because of
  173. .IR cause .
  174. .I Accept
  175. returns a file descriptor for the data file opened
  176. .BR ORDWR .
  177. .PP
  178. .I Netmkaddr
  179. makes an address suitable for dialing or announcing.
  180. It takes an address along with a default network and service to use
  181. if they are not specified in the address.
  182. It returns a pointer to static data holding the actual address to use.
  183. .PP
  184. .I Getnetconninfo
  185. returns a structure containing information about a
  186. network connection. The structure is:
  187. .EX
  188. typedef struct NetConnInfo NetConnInfo;
  189. struct NetConnInfo
  190. {
  191. char *dir; /* connection directory */
  192. char *root; /* network root */
  193. char *spec; /* binding spec */
  194. char *lsys; /* local system */
  195. char *lserv; /* local service */
  196. char *rsys; /* remote system */
  197. char *rserv; /* remote service */
  198. };
  199. .EE
  200. .PP
  201. The information is obtained from the connection directory,
  202. .IR conndir .
  203. If
  204. .I conndir
  205. is nil, the directory is obtained by performing
  206. .IR fd2path (2)
  207. on
  208. .IR fd .
  209. .I Getnetconninfo
  210. returns either a completely specified structure, or
  211. nil if either the structure can't be allocated or the
  212. network directory can't be determined.
  213. The structure
  214. is freed using
  215. .IR freenetconninfo .
  216. .PP
  217. .I Setnetmtpt
  218. copies the name of the network mount point into
  219. the buffer
  220. .IR to ,
  221. whose length is
  222. .IR tolen .
  223. It exists to merge two pre-existing conventions for specifying
  224. the mount point.
  225. Commands that take a network mount point as a parameter
  226. (such as
  227. .BR dns ,
  228. .BR cs
  229. (see
  230. .IR ndb (8)),
  231. and
  232. .IR ipconfig (8))
  233. should now call
  234. .IR setnetmtpt .
  235. If
  236. .I from
  237. is
  238. .BR nil ,
  239. the mount point is set to the default,
  240. .BR /net .
  241. If
  242. .I from
  243. points to a string starting with a slash,
  244. the mount point is that path.
  245. Otherwise, the mount point is the string pointed to by
  246. .I from
  247. appended to the string
  248. .BR /net .
  249. The last form is obsolete and is should be avoided.
  250. It exists only to aid in conversion.
  251. .SH EXAMPLES
  252. Make a call and return an open file descriptor to
  253. use for communications:
  254. .IP
  255. .EX
  256. int callkremvax(void)
  257. {
  258. return dial("kremvax", 0, 0, 0);
  259. }
  260. .EE
  261. .PP
  262. Call the local authentication server:
  263. .IP
  264. .EX
  265. int dialauth(char *service)
  266. {
  267. return dial(netmkaddr("$auth", 0, service), 0, 0, 0);
  268. }
  269. .EE
  270. .PP
  271. Announce as
  272. .B kremvax
  273. on TCP/IP and
  274. loop forever receiving calls and echoing back
  275. to the caller anything sent:
  276. .IP
  277. .EX
  278. int
  279. bekremvax(void)
  280. {
  281. int dfd, acfd, lcfd;
  282. char adir[40], ldir[40];
  283. int n;
  284. char buf[256];
  285. acfd = announce("tcp!*!7", adir);
  286. if(acfd < 0)
  287. return -1;
  288. for(;;){
  289. /* listen for a call */
  290. lcfd = listen(adir, ldir);
  291. if(lcfd < 0)
  292. return -1;
  293. /* fork a process to echo */
  294. switch(fork()){
  295. case -1:
  296. perror("forking");
  297. close(lcfd);
  298. break;
  299. case 0:
  300. /* accept the call and open the data file */
  301. dfd = accept(lcfd, ldir);
  302. if(dfd < 0)
  303. return -1;
  304. /* echo until EOF */
  305. while((n = read(dfd, buf, sizeof(buf))) > 0)
  306. write(dfd, buf, n);
  307. exits(0);
  308. default:
  309. close(lcfd);
  310. break;
  311. }
  312. }
  313. }
  314. .EE
  315. .SH SOURCE
  316. .BR /sys/src/libc/9sys ,
  317. .B /sys/src/libc/port
  318. .SH "SEE ALSO"
  319. .IR auth (2),
  320. .IR ip (3),
  321. .IR ndb (8)
  322. .SH DIAGNOSTICS
  323. .IR Dial ,
  324. .IR announce ,
  325. and
  326. .I listen
  327. return \-1 if they fail.
  328. .I Hangup
  329. returns nonzero if it fails.