diff options
Diffstat (limited to 'static/v10/man3/ipc.3')
| -rw-r--r-- | static/v10/man3/ipc.3 | 348 |
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. |