DIAL(3) DIAL(3)
NAME
dial, announce, listen, accept, reject, netmkaddr,
getnetconninfo, freenetconninfo, dialparse - make and break
network connections
SYNOPSIS
#include <u.h>
#include <libc.h>
int dial(char *addr, char *local, char *dir, int *cfdp)
int announce(char *addr, char *dir)
int listen(char *dir, char *newdir)
int accept(int ctl, char *dir)
int reject(int ctl, char *dir, char *cause)
char* netmkaddr(char *addr, char *defnet, char *defservice)
NetConnInfo* getnetconninfo(char *dir, int fd)
void freenetconninfo(NetConnINfo*)
int dialparse(char *addr, char **net, char **unix,
void *host, int *port)
DESCRIPTION
For these routines, addr is a network address of the form
network!netaddr!service, network!netaddr, or simply netaddr.
Network is tcp, udp, unix, or the special token, net. Net
is a free variable that stands for any network in common
between the source and the host netaddr. Netaddr can be a
host name, a domain name, or a network address.
On Plan 9, the dir argument is a path name to a line
directory that has files for accessing the connection. To
keep the same function signatures, the Unix port of these
routines uses strings of the form /dev/fd/n instead of line
directory paths. These strings should be treated as opaque
data and ignored.
Dial makes a call to destination addr on a multiplexed net-
work. If the network in addr is net, dial will try in suc-
cession all networks in common between source and destina-
tion until a call succeeds. It returns a file descriptor
open for reading and writing the call. If the network
allows the local address to be set, as is the case with UDP
and TCP port numbers, and local is non-zero, the local
Page 1 Plan 9 (printed 12/21/24)
DIAL(3) DIAL(3)
address will be set to local. Dial's dir and cfdp arguments
are not supported and must be zero.
Announce and listen are the complements of dial. Announce
establishes a network name to which calls can be made. Like
dial, announce returns an open ctl file. The netaddr used
in announce may be a local address or an asterisk, to indi-
cate all local addresses, e.g. tcp!*!echo. The listen rou-
tine takes as its first argument the dir of a previous
announce. When a call is received, listen returns an open
ctl file for the line the call was received on. It sets
newdir to the path name of the new line directory. Accept
accepts a call received by listen, while reject refuses the
call because of cause. Accept returns a file descriptor for
the data file opened ORDWR.
Netmkaddr makes an address suitable for dialing or announc-
ing. 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.
Netmkaddr also translates Unix conventions into Plan 9 syn-
tax. If addr is the name of a local file or Unix domain
socket, netmkaddr will return unix!addr. If addr is of the
form host:port, netmkaddr will return net!host!port.
Dialparse parses a network address as described above into a
network name, a Unix domain socket address, an IP host
address, and an IP port number.
Getnetconninfo returns a structure containing information
about a network connection. The structure is:
typedef struct NetConnInfo NetConnInfo;
struct NetConnInfo
{
char *dir; /* connection directory */
char *root; /* network root */
char *spec; /* binding spec */
char *lsys; /* local system */
char *lserv; /* local service */
char *rsys; /* remote system */
char *rserv; /* remote service */
char *laddr; /* local address */
char *raddr; /* remote address */
};
The information is obtained from the `line directory' dir,
or if dir is nil, from the connection file descriptor fd.
Getnetconninfo returns either a completely specified struc-
ture, or nil if either the structure can't be allocated or
Page 2 Plan 9 (printed 12/21/24)
DIAL(3) DIAL(3)
the network directory can't be determined. The structure is
freed using freenetconninfo.
EXAMPLES
Make a call and return an open file descriptor to use for
communications:
int callkremvax(void)
{
return dial("kremvax", 0, 0, 0);
}
Connect to a Unix socket served by acme(4):
int dialacme(void)
{
return dial("unix!/tmp/ns.ken.:0/acme", 0, 0, 0);
}
Announce as kremvax on TCP/IP and loop forever receiving
calls and echoing back to the caller anything sent:
int
bekremvax(void)
{
int dfd, acfd, lcfd;
char adir[40], ldir[40];
int n;
char buf[256];
acfd = announce("tcp!*!7", adir);
if(acfd < 0)
return -1;
for(;;){
/* listen for a call */
lcfd = listen(adir, ldir);
if(lcfd < 0)
return -1;
/* fork a process to echo */
switch(fork()){
case -1:
perror("forking");
close(lcfd);
break;
case 0:
/* accept the call and open the data file */
dfd = accept(lcfd, ldir);
if(dfd < 0)
return -1;
/* echo until EOF */
while((n = read(dfd, buf, sizeof(buf))) > 0)
Page 3 Plan 9 (printed 12/21/24)
DIAL(3) DIAL(3)
write(dfd, buf, n);
exits(0);
default:
close(lcfd);
break;
}
}
}
SOURCE
/usr/local/plan9/src/lib9/dial.c
/usr/local/plan9/src/lib9/announce.c
/usr/local/plan9/src/lib9/_p9dialparse.c
/usr/local/plan9/src/lib9/getnetconn.c
DIAGNOSTICS
Dial, announce, and listen return -1 if they fail.
BUGS
To avoid name conflicts with the underlying system, dial,
announce, listen, netmkaddr, and reject are preprocessor
macros defined as p9dial, p9announce, and so on; see
intro(3).
Page 4 Plan 9 (printed 12/21/24)