329 lines
6.4 KiB
Plaintext
329 lines
6.4 KiB
Plaintext
.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 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, and 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 it 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", nil, nil, nil);
|
|
}
|
|
.EE
|
|
.PP
|
|
Call the local authentication server:
|
|
.IP
|
|
.EX
|
|
int dialauth(char *service)
|
|
{
|
|
return dial(netmkaddr("$auth", nil, service), nil, nil, nil);
|
|
}
|
|
.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(nil);
|
|
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.
|