Lots of man pages.

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.