.TH DIAL 2.SH NAMEdial, hangup, announce, listen, accept, reject, netmkaddr, setnetmtpt, getnetconninfo, freenetconninfo \- make and break network connections.SH SYNOPSIS.B #include <u.h>.br.B #include <libc.h>.PP.Bint dial(char *addr, char *local, char *dir, int *cfdp).PP.Bint hangup(int ctl).PP.Bint announce(char *addr, char *dir).PP.Bint listen(char *dir, char *newdir).PP.Bint accept(int ctl, char *dir).PP.Bint reject(int ctl, char *dir, char *cause).PP.Bchar* netmkaddr(char *addr, char *defnet, char *defservice).PP.Bvoid setnetmtpt(char *to, int tolen, char *from).PP.BNetConnInfo* getnetconninfo(char *conndir, int fd).PP.Bvoid freenetconninfo(NetConnInfo*).SH DESCRIPTIONFor these routines,.I addris a network address of the form.IB network ! netaddr ! service\f1,.IB network ! netaddr\f1,or simply.IR netaddr ..I Networkis any directory listed in .B /netor the special token,.BR net ..B Netis a free variable that stands for any network in commonbetween the source and the host.IR netaddr ..I Netaddrcan be a host name, a domain name, a network address,or a meta-name of the form.BI $ attribute\f1,whichis replaced by.I valuefrom the value-attribute pair.IB attribute = valuemost closely associated with the source host in thenetwork data base (see.IR ndb (6))..PPIf a connection attempt is successful and.I diris non-zero,the path name of a.I line directorythat has files for accessing the connectionis copied into.IR dir .The path name is guaranteed to be less than 40bytes long.One line directory exists for each possible connection.The.B datafile in the line directory should be used to communicate with the destination.The.B ctlfile in the line directory can be used to send commands to the line.See.IR ip (3)for messages that can be written to the.B ctlfile.The last close of the.B dataor.B ctlfile will close the connection..PP.I Dialmakes a call to destination.I addron a multiplexed network.If the network in.I addris.BR net ,.I dialwill try in parallel all addresses onnetworks in common between source and destinationuntil a call succeeds.It returns a file descriptor open for reading and writing the.B datafile in the line directory.The.B addrfile 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.IR localis non-zero, the local address will be set to.IR local .If.I cfdpis non-zero,.BI * cfdpis set to a file descriptor open for reading andwriting the control file..PP.I Hangupis a means of forcing a connection to hang up withoutclosing the.B ctland.B datafiles..P.I Announceand.I listenare the complements of.IR dial ..I Announceestablishes a networkname to which calls can be made.Like.IR dial ,.I announcereturns an open.B ctlfile.The .I netaddrused in announce may be a local address or an asterisk,to indicate all local addresses, e.g..BR tcp!*!echo .The.I listenroutine takes as its first argument the.I dirof a previous.IR announce .When a call is received,.I listenreturns an open.B ctlfile for the line the call was received on.It sets.I newdirto the path name of the new line directory..I Acceptaccepts a call received by.IR listen ,while.I rejectrefuses the call because of.IR cause ..I Acceptreturns a file descriptor for the data file opened.BR ORDWR ..PP.I Netmkaddrmakes an address suitable for dialing or announcing.It takes an address along with a default network and service to useif they are not specified in the address.It returns a pointer to static data holding the actual address to use..PP.I Getnetconninforeturns a structure containing information about anetwork connection. The structure is:.EX 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 */ };.EE.PPThe information is obtained from the connection directory,.IR conndir .If.I conndiris nil, the directory is obtained by performing.IR fd2path (2)on.IR fd ..I Getnetconninforeturns either a completely specified structure, ornil if either the structure can't be allocated or thenetwork directory can't be determined.The structureis freed using.IR freenetconninfo ..PP.I Setnetmtptcopies the name of the network mount point intothe buffer.IR to ,whose length is.IR tolen .It exists to merge two pre-existing conventions for specifyingthe mount point.Commands that take a network mount point as a parameter(such as.BR dns ,.BR cs(see.IR ndb (8)),and.IR ipconfig (8))should now call.IR setnetmtpt .If.I fromis.BR nil ,the mount point is set to the default,.BR /net .If.I frompoints to a string starting with a slash,the mount point is that path.Otherwise, the mount point is the string pointed to by.I fromappended to the string.BR /net .The last form is obsolete and is should be avoided.It exists only to aid in conversion..SH EXAMPLESMake a call and return an open file descriptor touse for communications:.IP.EXint callkremvax(void){ return dial("kremvax", 0, 0, 0);}.EE.PPCall the local authentication server:.IP.EXint dialauth(char *service){ return dial(netmkaddr("$auth", 0, service), 0, 0, 0);}.EE.PPAnnounce as.B kremvaxon TCP/IP andloop forever receiving calls and echoing backto the caller anything sent:.IP.EXintbekremvax(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) write(dfd, buf, n); exits(0); default: close(lcfd); break; } }}.EE.SH SOURCE.BR /sys/src/libc/9sys ,.B /sys/src/libc/port.SH "SEE ALSO".IR auth (2),.IR ip (3),.IR ndb (8).SH DIAGNOSTICS.IR Dial ,.IR announce ,and.I listenreturn \-1 if they fail..I Hangupreturns nonzero if it fails.
.TH DIAL 2
.SH NAME
dial, hangup, announce, listen, accept, reject, netmkaddr, setnetmtpt, getnetconninfo, freenetconninfo \- make and break network connections
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.PP
.B
int dial(char *addr, char *local, char *dir, int *cfdp)
.PP
.B
int hangup(int ctl)
.PP
.B
int announce(char *addr, char *dir)
.PP
.B
int listen(char *dir, char *newdir)
.PP
.B
int accept(int ctl, char *dir)
.PP
.B
int reject(int ctl, char *dir, char *cause)
.PP
.B
char* netmkaddr(char *addr, char *defnet, char *defservice)
.PP
.B
void setnetmtpt(char *to, int tolen, char *from)
.PP
.B
NetConnInfo* getnetconninfo(char *conndir, int fd)
.PP
.B
void freenetconninfo(NetConnInfo*)
.SH DESCRIPTION
For these routines,
.I addr
is a network address of the form
.IB network ! netaddr ! service\f1,
.IB network ! netaddr\f1,
or simply
.IR netaddr .
.I Network
is any directory listed in
.B /net
or the special token,
.BR net .
.B Net
is a free variable that stands for any network in common
between the source and the host
.IR netaddr .
.I Netaddr
can be a host name, a domain name, a network address,
or a meta-name of the form
.BI $ attribute\f1,
which
is replaced by
.I value
from the value-attribute pair
.IB attribute = value
most closely associated with the source host in the
network data base (see
.IR ndb (6)).
.PP
If a connection attempt is successful and
.I dir
is non-zero,
the path name of a
.I line directory
that has files for accessing the connection
is copied into
.IR dir .
The path name is guaranteed to be less than 40
bytes long.
One line directory exists for each possible connection.
The
.B data
file in the line directory should be used to communicate with the destination.
The
.B ctl
file in the line directory can be used to send commands to the line.
See
.IR ip (3)
for messages that can be written to the
.B ctl
file.
The last close of the
.B data
or
.B ctl
file will close the connection.
.PP
.I Dial
makes a call to destination
.I addr
on a multiplexed network.
If the network in
.I addr
is
.BR net ,
.I dial
will try in parallel all addresses on
networks in common between source and destination
until a call succeeds.
It returns a file descriptor open for reading and writing the
.B data
file in the line directory.
The
.B 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
.IR local
is non-zero, the local address will be set to
.IR local .
If
.I cfdp
is non-zero,
.BI * cfdp
is set to a file descriptor open for reading and
writing the control file.
.PP
.I Hangup
is a means of forcing a connection to hang up without
closing the
.B ctl
and
.B data
files.
.P
.I Announce
and
.I listen
are the complements of
.IR dial .
.I Announce
establishes a network
name to which calls can be made.
Like
.IR dial ,
.I announce
returns an open
.B ctl
file.
The
.I netaddr
used in announce may be a local address or an asterisk,
to indicate all local addresses, e.g.
.BR tcp!*!echo .
The
.I listen
routine takes as its first argument the
.I dir
of a previous
.IR announce .
When a call is received,
.I listen
returns an open
.B ctl
file for the line the call was received on.
It sets
.I newdir
to the path name of the new line directory.
.I Accept
accepts a call received by
.IR listen ,
while
.I reject
refuses the call because of
.IR cause .
.I Accept
returns a file descriptor for the data file opened
.BR ORDWR .
.PP
.I 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.
.PP
.I Getnetconninfo
returns a structure containing information about a
network connection. The structure is:
.EX
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 */
};
.EE
.PP
The information is obtained from the connection directory,
.IR conndir .
If
.I conndir
is nil, the directory is obtained by performing
.IR fd2path (2)
on
.IR fd .
.I 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
.IR freenetconninfo .
.PP
.I Setnetmtpt
copies the name of the network mount point into
the buffer
.IR to ,
whose length is
.IR 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
.BR dns ,
.BR cs
(see
.IR ndb (8)),
and
.IR ipconfig (8))
should now call
.IR setnetmtpt .
If
.I from
is
.BR nil ,
the mount point is set to the default,
.BR /net .
If
.I 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
.I from
appended to the string
.BR /net .
The last form is obsolete and is should be avoided.
It exists only to aid in conversion.
.SH EXAMPLES
Make a call and return an open file descriptor to
use for communications:
.IP
.EX
int callkremvax(void)
{
return dial("kremvax", 0, 0, 0);
}
.EE
.PP
Call the local authentication server:
.IP
.EX
int dialauth(char *service)
{
return dial(netmkaddr("$auth", 0, service), 0, 0, 0);
}
.EE
.PP
Announce as
.B kremvax
on TCP/IP and
loop forever receiving calls and echoing back
to the caller anything sent:
.IP
.EX
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)
write(dfd, buf, n);
exits(0);
default:
close(lcfd);
break;
}
}
}
.EE
.SH SOURCE
.BR /sys/src/libc/9sys ,
.B /sys/src/libc/port
.SH "SEE ALSO"
.IR auth (2),
.IR ip (3),
.IR ndb (8)
.SH DIAGNOSTICS
.IR Dial ,
.IR announce ,
and
.I listen
return \-1 if they fail.
.I Hangup
returns nonzero if it fails.