Google Git
Sign in
plan9port / plan9 / 3afc6b5e70c2a589f8ca9f8feb5470d2975a2915 / . / man / man3 / dial.html
blob: e10148590f1d5a5eaf0b12983b8e11d688321324 [file] [log] [blame]
<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 &ndash;
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 &lt;u.h&gt;<br>
#include &lt;libc.h&gt;
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int &nbsp;&nbsp;&nbsp;&nbsp;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 &nbsp;&nbsp;&nbsp;&nbsp;announce(char *addr, char *dir)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int &nbsp;&nbsp;&nbsp;&nbsp;listen(char *dir, char *newdir)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int &nbsp;&nbsp;&nbsp;&nbsp;accept(int ctl, char *dir)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int &nbsp;&nbsp;&nbsp;&nbsp;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 &nbsp;&nbsp;&nbsp;&nbsp;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>&#8217;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(&quot;kremvax&quot;, 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(&quot;unix!/tmp/ns.ken.:0/acme&quot;, 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(&quot;tcp!*!7&quot;, adir);<br>
if(acfd &lt; 0)<br>
return &#8722;1;<br>
for(;;){<br>
/* listen for a call */<br>
lcfd = listen(adir, ldir);<br>
if(lcfd &lt; 0)<br>
return &#8722;1;<br>
/* fork a process to echo */<br>
switch(fork()){<br>
case &#8722;1:<br>
perror(&quot;forking&quot;);<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 &lt; 0)<br>
return &#8722;1;<br>
/* echo until EOF */<br>
while((n = read(dfd, buf, sizeof(buf))) &gt; 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 &ndash;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>