diff options
Diffstat (limited to 'man/man3/dial.3')
| -rw-r--r-- | man/man3/dial.3 | 331 |
1 files changed, 331 insertions, 0 deletions
diff --git a/man/man3/dial.3 b/man/man3/dial.3 new file mode 100644 index 00000000..fe1837c9 --- /dev/null +++ b/man/man3/dial.3 @@ -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. |