term% cat index.txt DIAL(2) System Calls Manual DIAL(2)
NAME
dial, hangup, announce, listen, accept, reject, netmkaddr, 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 *defservice)
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!ne‐
taddr!service, network!netaddr, or simply netaddr. Network is any di‐
rectory listed in /net or the special token, net. Net is a free vari‐
able that stands for any network in common between the source and the
host netaddr. Netaddr can be a host name, a domain name, a network ad‐
dress, or a meta-name of the form $attribute, which is replaced by
value from the value-attribute pair attribute=value most closely asso‐
ciated 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 accessing the connection is
copied into dir. The path name, including terminating NUL, is guaran‐
teed to fit in (40) bytes. One line directory exists for each possible
connection. The data file in the line directory should be used to com‐
municate with the 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 network. If the
network in addr is net, dial will try in parallel all addresses on net‐
works in common between source and destination 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. Like dial, announce 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 an‐
nounce. 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 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.
Getnetconninfo returns a structure containing information about a net‐
work 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 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 structure 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 conven‐
tions for specifying the mount point. Commands that take a network
mount point as a parameter (such as dns, cs (see ndb(8)), and ipcon‐
fig(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 is should be avoided. It exists only to aid in conver‐
sion.
EXAMPLES
Make a call and return an open file descriptor to use for communica‐
tions:
int callkremvax(void)
{
return dial("kremvax", 0, 0, 0);
}
Call the local authentication server:
int dialauth(char *service)
{
return dial(netmkaddr("$auth", 0, service), 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[NETPATHLEN], ldir[NETPATHLEN];
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)
write(dfd, buf, n);
exits(0);
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 non‐
zero if it fails.
DIAL(2)