Lots of man pages.
This commit is contained in:
rsc
parent
08df2a433e
commit
cfa37a7b11
152 changed files with 25407 additions and 148 deletions
331
man/man3/dial.3
Normal file
331
man/man3/dial.3
Normal file
|
|
@ -0,0 +1,331 @@
|
|||
.TH DIAL 3
|
||||
.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 succession all
|
||||
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 */
|
||||
};
|
||||
.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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue