docs: Added UNIX V10 Manuals

1 files changed, 348 insertions, 0 deletions

diff --git a/static/v10/man3/ipc.3 b/static/v10/man3/ipc.3
new file mode 100644
index 00000000..68679457
--- /dev/null
+++ b/static/v10/man3/ipc.3
@@ -0,0 +1,348 @@
+.TH IPC 3X
+.CT 2 comm_proc
+.SH NAME
+ipccreat, ipcopen, ipclisten, ipcaccept, ipcreject, ipcexec, ipcpath , ipclogin, ipcrogin
+\(mi set up connections between processes or machines
+.SH SYNOPSIS
+.B #include <ipc.h>
+.PP
+.B char *ipcpath(name, network, service)
+.br
+.B char *name;
+.br
+.B char *network;
+.br
+.B char *service;
+.PP
+.B int ipcopen(name, param)
+.br
+.B char *name;
+.br
+.B char *param;
+.PP
+.B int ipccreat(name, param)
+.br
+.B char *name;
+.br
+.B char *param;
+.PP
+.B ipcinfo *ipclisten(fd)
+.br
+.B int fd;
+.PP
+.B int ipcaccept(ip)
+.br
+.B ipcinfo *ip;
+.PP
+.B int ipcreject(ip, no, str)
+.br
+.B ipcinfo *ip;
+.br
+.B int no;
+.br
+.B char *str;
+.PP
+.B int ipcexec(name, param, cmd)
+.br
+.B char *name;
+.br
+.B char *param;
+.br
+.B char *cmd;
+.PP
+.B int ipclogin(fd)
+.br
+.B int fd;
+.PP
+.B int ipcrogin(fd, opt)
+.br
+.B int fd;
+.br
+.B char *opt;
+.PP
+.B extern char *errstr;
+.SH DESCRIPTION
+These routines establish communication between unrelated
+processes, often for networking purposes.
+They are loaded by the
+.B -lipc
+option of
+.IR ld (1).
+.PP
+End points in the network are identified by names of the form:
+.BR element [ !element "]... "  .
+The name is translated element by element relative to the name space
+selected by the previous element.
+The first element is always a name in the local file system.
+By convention, all network interfaces and services
+mount themselves in
+.FR /cs .
+For example:
+.TP
+.B /cs/exec
+refers to a local process which has mounted itself (via
+.I ipccreat )
+on 
+.FR /cs/exec .
+.TP
+.B /cs/dk!nj/astro/voice
+refers to a voice synthesizer attached
+to Datakit; process
+.F /cs/dk
+is the Datakit interface.
+.TP
+.B /cs/dk!dutoit!exec
+is the process that has mounted itself on
+.F /cs/exec
+in machine `dutoit'.
+.PP
+.I Ipcpath,
+forms a network name from its arguments and returns a pointer to it.
+It takes three arguments: the destination
+.I name,
+the default
+.I network,
+and the default
+.I service.
+It assumes that 
+.I name
+is a three part name of the form: network!host!service.
+If either network or service is missing from
+.I name, ipcpath
+supplies them
+from the default arguments.
+It then tacks a
+.F /cs
+on the front and returns a pointer to that.
+Thus,
+.IP
+.EX
+ipcpath("dutoit", "dk", "dcon")
+.EE
+.LP
+returns a pointer to the string 
+.LR /cs/dk!dutoit!dcon .
+.PP
+.I Ipcopen
+places a call to a named network end point and returns
+a file descriptor for the resulting connection.
+.I Param,
+a whitespace-delimited string of values, specifies
+properties which the connection must have.
+At present four parameter values are defined:
+.TF heavy
+.TP
+.B heavy
+.br
+.ns
+.TP
+.B light
+Heavy (usually computer-to-computer) or light (computer-to-terminal)
+traffic is expected.
+.TP
+.B delim
+The connection must support delimiters; see
+.IR stream (4).
+.TP
+.B hup
+.B SIGHUP
+must be generated at end of file; see
+.IR signal (2).
+.PD
+.PP
+.I Ipccreat
+attaches a process to a name space.
+It returns a file descriptor representing the attachment.
+.I Name 
+and
+.I param
+mean the same as for 
+.I ipcopen.
+.PP
+.I Ipclisten
+waits for calls (from
+.I ipcopen
+in other processes) appearing on file descriptor
+.I fd
+(obtained from
+.IR ipccreat ).
+When a call arrives, it returns an
+.B ipcinfo
+structure, defined in
+.FR <ipc.h> :
+.IP
+.EX
+.ta \w'typedef\ 'u +\w'char\ 'u +\w'reserved[5];\ 'u
+typedef	struct {
+	int	reserved[5];
+	char	*name;		that being dialed
+	char	*param;		parameters used to set up call
+	char	*machine;	machine id of caller
+	char	*user;		user name of caller
+	int	uid, gid;	uid, gid of caller
+} ipcinfo;
+.EE
+.PP
+The call may be accepted by
+.I ipcaccept
+or rejected by
+.I ipcreject.
+.I Ipcaccept
+returns a file descriptor for the connection.
+.I Ipcreject
+takes an integer error number and an error message string,
+which will be passed back to the caller as
+.I errno
+and 
+.I errstr.
+.PP
+A higher-level routine,
+.I ipcexec,
+executes the command,
+.I cmd,
+on a named machine.
+The file descriptor returned by 
+.I ipcexec
+is the standard input, standard output, and 
+standard error of the command.
+As in
+.I ipcopen,
+.I param
+lists properties required of the channel.
+.PP
+Once a connection is established using
+.I ipcopen
+it is often necessary to authenticate yourself
+to the destination.
+This is done using 
+.I ipclogin
+and
+.I ipcrogin.
+.I Ipclogin
+runs the client side of the authentication protocol
+described in
+.IR svcmgr (8)
+for the 
+.I v9auth
+action.
+The supplied
+.I fd
+is the descriptor returned by 
+.I ipcopen.
+Until the authentication is accepted,
+.I ipclogin
+will prompt the user (using
+.F /dev/tty )
+for a login id and password to be sent over
+.I fd.
+.PP
+.I Ipcrogin
+runs the client side of the authentication protocol
+used by BSD's 
+.I rlogin 
+and 
+.I rsh
+services.
+Unlike
+.I ipclogin,
+it will not prompt the user if the authentication
+fails.
+.I Ipcrogin
+takes a second argument that is written to
+.I fd
+after the authentication is accepted.
+.SH EXAMPLES
+To connect to the voice synthesizer attached to the Datakit:
+.EX
+.ta \w'12345678'u +\w'12345678'u +\w'12345678'u
+#include <ipc.h>
+main() {
+	int fd;
+	fd = ipcopen(ipcpath("voice", "dk", 0), "light");
+	if(fd<0){
+		printf("can't connect: %s\en", errstr);
+		exit(1);
+	}
+	...
+	close(fd);
+}
+.EE
+.PP
+To place a Dataphone call via Datakit; the service name is 
+derived in an obvious way from the ACU service class; see
+.IR dialout (3).
+.EX
+	fd = ipcopen(ipcpath("9-1-201-582-0000", "dk", "dial1200"), "light");
+.EE
+.PP
+To announce as a local service and wait for incoming calls:
+.EX
+.ta \w'12345678'u +\w'12345678'u +\w'12345678'u
+#include <ipc.h>
+main() {
+        int fd;
+        ipcinfo *ip;
+        fd = ipccreat("/tmp/service", 0);
+        if(fd<0){
+                printf("can't announce: %s\en", errstr);
+                exit(1);
+        }
+        while(ip = ipclisten(fd)){
+                int nfd;
+                if(i_hate_this_user(ip->machine, ip->user)) {
+                        ipcreject(ip, EACCES, "i hate you");
+                        continue;
+                }
+                nfd = ipcaccept(ip);
+		...
+                close(nfd);
+        }
+        printf("lost the announced connection somehow\en");
+        exit(1);
+}
+.EE
+.SH FILES
+.TF /cs/tpc
+.TP 
+.F /cs/dk
+the announce point for the Datakit dialer
+.TP
+.F /cs/tcp
+the announce point for the internet dialer
+.SH SEE ALSO
+.IR dialout (3),
+.IR connld (4),
+.IR dkmgr (8),
+.IR svcmgr (8),
+.IR tcpmgr (8)
+.br
+D. L. Presotto,
+`Interprocess Communication in the Eighth Edition
+.SM UNIX
+System',
+this manual, Volume 2
+.SH DIAGNOSTICS
+Integer return values of \-1 and pointer return
+values of 0 denote error.
+.I Errno
+contains an error code (see
+.IR intro (2))
+and
+.I errstr
+points to an explanatory string.
+.SH BUGS
+Files created by
+.I ipccreat
+in the local name space are not removed when
+the file descriptor returned by
+.I ipccreat
+is closed.
+.br
+Information in
+.B ipcinfo
+is no more trustworthy than its origin.
+Information, such as user name, sent by foreign
+machines may be suspect.
+On Ethernet or dialup connections (but not on Datakit)
+machine names can be forged.
+Let's not even think about wire-swappers and wiretappers.