diff options
Diffstat (limited to 'man/man3/dial.html')
| -rw-r--r-- | man/man3/dial.html | 241 |
1 files changed, 241 insertions, 0 deletions
diff --git a/man/man3/dial.html b/man/man3/dial.html new file mode 100644 index 00000000..e1014859 --- /dev/null +++ b/man/man3/dial.html @@ -0,0 +1,241 @@ +<head> +<title>dial(3) - Plan 9 from User Space</title> +<meta content="text/html; charset=utf-8" http-equiv=Content-Type> +</head> +<body bgcolor=#ffffff> +<table border=0 cellpadding=0 cellspacing=0 width=100%> +<tr height=10><td> +<tr><td width=20><td> +<tr><td width=20><td><b>DIAL(3)</b><td align=right><b>DIAL(3)</b> +<tr><td width=20><td colspan=2> + <br> +<p><font size=+1><b>NAME </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + dial, announce, listen, accept, reject, netmkaddr, dialparse – + make and break network connections<br> + +</table> +<p><font size=+1><b>SYNOPSIS </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>#include <u.h><br> + #include <libc.h> + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int dial(char *addr, char *local, char *dir, int *cfdp) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int announce(char *addr, char *dir) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int listen(char *dir, char *newdir) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int accept(int ctl, char *dir) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int reject(int ctl, char *dir, char *cause) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>char* netmkaddr(char *addr, char *defnet, char *defservice) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int dialparse(char *addr, char **net, char **unix,<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + u32int *host, int *port)<br> + + </table> + + </table> + </font></tt> +</table> +<p><font size=+1><b>DESCRIPTION </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + For these routines, <i>addr</i> is a network address of the form <i>network</i><tt><font size=+1>!</font></tt><i>netaddr</i><tt><font size=+1>!</font></tt><i>service</i>, + <i>network</i><tt><font size=+1>!</font></tt><i>netaddr</i>, or simply <i>netaddr</i>. <i>Network</i> is <tt><font size=+1>tcp</font></tt>, <tt><font size=+1>udp</font></tt>, <tt><font size=+1>unix</font></tt>, + or the special token, <tt><font size=+1>net</font></tt>. <tt><font size=+1>Net</font></tt> is a free variable that stands + for any network in common between the source and the host <i>netaddr</i>. + <i>Netaddr</i> can be a host name, a + domain name, or a network address. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + On Plan 9, the <i>dir</i> argument is a path name to a <i>line directory</i> + that has files for accessing the connection. To keep the same + function signatures, the Unix port of these routines uses strings + of the form <tt><font size=+1>/dev/fd/</font></tt><i>n</i> instead of line directory paths. These strings + should be treated as opaque data and ignored. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Dial</i> makes a call to destination <i>addr</i> on a multiplexed network. + If the network in <i>addr</i> is <tt><font size=+1>net</font></tt>, <i>dial</i> will try in succession all + networks in common between source and destination until a call + succeeds. It returns a file descriptor open for reading and writing + the <tt><font size=+1>data</font></tt> file in the line directory. The <tt><font size=+1>addr</font></tt> file in the line + directory contains the address called. <i>Dial</i>’s <i>local</i>, <i>dir</i>, and + <i>cfdp</i> arguments are not supported and must be zero. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Announce</i> and <i>listen</i> are the complements of <i>dial</i>. <i>Announce</i> establishes + a network name to which calls can be made. Like <i>dial</i>, <i>announce</i> + returns an open <tt><font size=+1>ctl</font></tt> file. The <i>netaddr</i> used in announce may be + a local address or an asterisk, to indicate all local addresses, + e.g. <tt><font size=+1>tcp!*!echo</font></tt>. The <i>listen</i> routine takes as its + first argument the <i>dir</i> of a previous <i>announce</i>. When a call is + received, <i>listen</i> returns an open <tt><font size=+1>ctl</font></tt> file for the line the call + was received on. It sets <i>newdir</i> to the path name of the new line + directory. <i>Accept</i> accepts a call received by <i>listen</i>, while <i>reject</i> + refuses the call because of <i>cause</i>. <i>Accept</i> returns a file descriptor + for + the data file opened <tt><font size=+1>ORDWR</font></tt>. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Netmkaddr</i> makes an address suitable for dialing or announcing. + It takes an address along with a default network and service to + use if they are not specified in the address. It returns a pointer + to static data holding the actual address to use. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Dialparse</i> parses a network address as described above into a network + name, a Unix domain socket address, an IPv4 host address, and + an IPv4 port number.<br> + +</table> +<p><font size=+1><b>EXAMPLES </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + Make a call and return an open file descriptor to use for communications:<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>int callkremvax(void)<br> + {<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + return dial("kremvax", 0, 0, 0);<br> + + </table> + }<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + + </table> + Connect to a Unix socket served by <a href="../man4/acme.html"><i>acme</i>(4)</a>:<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>int dialacme(void)<br> + {<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + return dial("unix!/tmp/ns.ken.:0/acme", 0, 0, 0);<br> + + </table> + }<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + + </table> + Announce as <tt><font size=+1>kremvax</font></tt> on TCP/IP and loop forever receiving calls + and echoing back to the caller anything sent:<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>int<br> + bekremvax(void)<br> + {<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + int dfd, acfd, lcfd;<br> + char adir[40], ldir[40];<br> + int n;<br> + char buf[256];<br> + acfd = announce("tcp!*!7", adir);<br> + if(acfd < 0)<br> + return −1;<br> + for(;;){<br> + /* listen for a call */<br> + lcfd = listen(adir, ldir);<br> + if(lcfd < 0)<br> + return −1;<br> + /* fork a process to echo */<br> + switch(fork()){<br> + case −1:<br> + perror("forking");<br> + close(lcfd);<br> + break;<br> + case 0:<br> + /* accept the call and open the data file */<br> + dfd = accept(lcfd, ldir);<br> + if(dfd < 0)<br> + return −1;<br> + /* echo until EOF */<br> + while((n = read(dfd, buf, sizeof(buf))) > 0)<br> + write(dfd, buf, n);<br> + exits(0);<br> + default:<br> + close(lcfd);<br> + break;<br> + }<br> + }<br> + + </table> + }<br> + </font></tt> + </table> + +</table> +<p><font size=+1><b>SOURCE </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>/usr/local/plan9/src/lib9/dial.c<br> + /usr/local/plan9/src/lib9/announce.c<br> + /usr/local/plan9/src/lib9/_p9dialparse.c<br> + </font></tt> +</table> +<p><font size=+1><b>DIAGNOSTICS </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <i>Dial</i>, <i>announce</i>, and <i>listen</i> return –1 if they fail.<br> + +</table> +<p><font size=+1><b>BUGS </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + To avoid name conflicts with the underlying system, <i>dial</i>, <i>announce</i>, + <i>listen</i>, <i>netmkaddr</i>, and <i>reject</i> are preprocessor macros defined + as <i>p9dial</i>, <i>p9announce</i>, and so on; see <a href="../man3/intro.html"><i>intro</i>(3)</a>.<br> + +</table> + +<td width=20> +<tr height=20><td> +</table> +<!-- TRAILER --> +<table border=0 cellpadding=0 cellspacing=0 width=100%> +<tr height=15><td width=10><td><td width=10> +<tr><td><td> +<center> +<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a> +</center> +</table> +<!-- TRAILER --> +</body></html> |