DIAL(2) DIAL(2)
NAME
dial, hangup, announce, listen, accept, reject, netmkaddr,
netmkaddrbuf, setnetmtpt, getnetconninfo, freenetconninfo -
make and break network connections
SYNOPSIS
#include <u.h>
#include <libc.h>
int dial(char *addr, char *local, char *dir, int *cfdp)
int hangup(int ctl)
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 *defsrv)
char* netmkaddrbuf(char *addr, char *defnet, char *defsrv,
char *buf, int len)
void setnetmtpt(char *to, int tolen, char *from)
NetConnInfo* getnetconninfo(char *conndir, int fd)
void freenetconninfo(NetConnInfo*)
DESCRIPTION
For these routines, addr is a network address of the form
network!netaddr!service, network!netaddr, or simply netaddr.
Network is any directory listed in /net or the special
token, net. Net is a free variable that stands for any net-
work in common between the source and the host netaddr.
Netaddr can be a host name, a domain name, a network
address, or a meta-name of the form $attribute, which is
replaced by value from the value-attribute pair
attribute=value most closely associated with the source host
in the network data base (see ndb(6)).
If a connection attempt is successful and dir is non-zero,
the path name of a line directory that has files for access-
ing the connection is copied into dir. The path name is
guaranteed to be less than 40 bytes long. One line direc-
tory exists for each possible connection. The data file in
the line directory should be used to communicate with the
Page 1 Plan 9 (printed 10/28/25)
DIAL(2) DIAL(2)
destination. The ctl file in the line directory can be used
to send commands to the line. See ip(3) for messages that
can be written to the ctl file. The last close of the data
or ctl file will close the connection.
Dial makes a call to destination addr on a multiplexed net-
work. If the network in addr is net, dial will try all
addresses on networks in common between source and destina-
tion until a call succeeds. It returns a file descriptor
open for reading and writing the data file in the line
directory. The addr file in the line directory contains the
address called. 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 address will be set to local.
If cfdp is non-zero, *cfdp is set to a file descriptor open
for reading and writing the control file.
Hangup is a means of forcing a connection to hang up without
closing the ctl and data files.
Announce and listen are the complements of dial. Announce
establishes a network name to which calls can be made, and
returns an open ctl file. The netaddr used in announce may
be a local address or an asterisk, to indicate all local
addresses, e.g. tcp!*!echo. The listen routine 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 and netmkaddrbuf make an address suitable for
dialing or announcing. They take an address along with a
default network and service to use if they are not specified
in the address. Netmkaddrbuf stores the resulting dial-
string in buf up to a maximum length of len and returns a
pointer to it. Netmkaddr returns a pointer to a static
buffer.
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 */
Page 2 Plan 9 (printed 10/28/25)
DIAL(2) DIAL(2)
char *rserv; /* remote service */
char *laddr; /* local address */
char *raddr; /* remote address */
};
The information is obtained from the connection directory,
conndir. If conndir is nil, the directory is obtained by
performing fd2path(2) on fd. Getnetconninfo returns either a
completely specified structure, or nil if either the struc-
ture can't be allocated or the network directory can't be
determined. The structure is freed using freenetconninfo.
Setnetmtpt copies the name of the network mount point into
the buffer to, whose length is tolen. It exists to merge two
pre-existing conventions for specifying the mount point.
Commands that take a network mount point as a parameter
(such as dns, cs (see ndb(8)), and ipconfig(8)) should now
call setnetmtpt. If from is nil, the mount point is set to
the default, /net. If from points to a string starting with
a slash, the mount point is that path. Otherwise, the mount
point is the string pointed to by from appended to the
string /net. The last form is obsolete and it should be
avoided. It exists only to aid in conversion.
EXAMPLES
Make a call and return an open file descriptor to use for
communications:
int callkremvax(void)
{
return dial("kremvax", nil, nil, nil);
}
Call the local authentication server:
int dialauth(char *service)
{
return dial(netmkaddr("$auth", nil, service), nil, nil, nil);
}
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);
Page 3 Plan 9 (printed 10/28/25)
DIAL(2) DIAL(2)
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)
write(dfd, buf, n);
exits(nil);
default:
close(lcfd);
break;
}
}
}
SOURCE
/sys/src/libc/9sys, /sys/src/libc/port
SEE ALSO
auth(2), ip(3), ndb(8)
DIAGNOSTICS
Dial, announce, and listen return -1 if they fail. Hangup
returns nonzero if it fails.
Page 4 Plan 9 (printed 10/28/25)