/usr/share/doc/clc-intercal/html/internet.html is in clc-intercal 1:1.0~4pre1.-94.-2-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 | <HTML>
<HEAD>
<TITLE>CLC-INTERCAL Reference</TITLE>
</HEAD>
<BODY>
<H1>CLC-INTERCAL Reference</H1>
<H2>... INTERcal NETworking</H2>
<P>
Table of contents:
<UL>
<LI><A HREF="index.html">Parent directory</A>
<LI><A HREF="#compiling">Compiling a program with INTERNET
support</A>
<LI><A HREF="#using">Using INTERNET</A>
<LI><A HREF="#internals">Internals - or how you can interface
to INTERNET enabled INTERCAL programs from other languages</A>
</UL>
</P>
<H2><A NAME="compiling">Compiling a program with INTERNET support</A></H2>
<P>
Starting with CLC-INTERCAL 1.-94.-2, INTERNET is provided as a
separate package, CLC-INTERCAL-INET. The rest of this chapter
assumes that you have installed that package.
</P>
<P>
INTERNET is a standard compiler extension, so programs must include the
appropriate compile option to use it.
</P>
<P>
The command-line compiler tool,
<I>sick</I>, automatically enables the INTERNET extension if the program
suffix includes the letter "r" (for remote - the letter "i"
was already used to indicate that the program is an INTERCAL program).
Alternatively, if you are not relying on <I>sick</I>'s guesses and
are specifying a list of preloads yourself, just add <I>-pinternet</I>
to your command line.
</P>
<P>
Using the INTERCAL Calculator, INTERCALC, you can easily add INTERNET
support by selecting "internet" from the Options menu or by
adding <I>-ointernet</I> to the command line.
</P>
<P>
The <I>internet</I> compiler object, which implements this extension,
extends the compiler's syntax to include the STEAL, SMUGGLE and CASE
statements; it also informs the runtime that the program should be
listening for theft requests, and start a theft server if required:
this is described below in the <A HREF="#internals">internals</A>
section.
</P>
<H2><A NAME="using">Using INTERNET</A></H2>
<P>
Once you've enabled INTERNET support, using it is a simple matter of
using STEAL, SMUGGLE or CASE statements as required; in this context,
IGNORE and REMEMBER are also useful to allow/disallow access to
your registers from other programs using STEAL and SMUGGLE. Details
on these statements can be found in <A HREF="statements.html">the
chapter about statements</A>.
</P>
<P>
Here is a simple example of an INTERNET program acting as a server:
<PRE>
DO IGNORE @1
(1) PLEASE COME FROM (1)
</PRE>
It may seem rather pointless, but in fact this program will wait
for network connections to SMUGGLE its standard write filehandle
(normally stored in register @1). The filehandle can not be stolen,
because it is ignored. The second statement is automatically caught
by the runtime, which recognises an infinite loop when it sees one,
and replaced with whatever is internally necessary to wait for a
network connection: in other words, the busy wait specified by the
COME FROM statement is replaced by an operating system specific
wait for network connections, which does not consume any CPU until
you try to SMUGGLE the standard write.
</P>
<P>
A client could do the following, after initialising the .1 register
to contain the server's process ID, and the :1 register to contain
the server's IP address:
<PRE>
DO SMUGGLE @1 ON .1 FROM :1
DO WRITE IN .2
</PRE>
what happens here is that one line of input is obtained from the
<I>server</I>'s standard read, and used in the <I>client</I> to
assign a value to .2. The server and the client could be in completely
different networks.
</P>
<P>
Note that this example would still work, once,
if the server did not IGNORE @1 and the client used STEAL instead
of SMUGGLE, however this would prevent a second client from using
the same mechanism, because the server would no longer have the
standard read filehandle available after the first client stole it.
</P>
<P>
We can develop this example a bit further. The server could use the
system call interface to open a temporary file somewhere on the
server, and make it available for smuggling to give other INTERCAL
programs a chance to access the same file - even if they don't have
access to the computer where the server runs. This program should
be compiled with both the <I>internet</I> and <I>syscall</I>
extensions, perhaps by giving it suffix <I>.rsi</I>:
<PRE>
PLEASE ,10 <- #18
DO ,10 SUB #1 <- #95
DO ,10 SUB #2 <- #91
DO ,10 SUB #3 <- #93
PLEASE ,10 SUB #4 <- #95
DO ,10 SUB #5 <- #95
DO ,10 SUB #6 <- #80
DO ,10 SUB #7 <- #92
PLEASE ,10 SUB #8 <- #86
DO ,10 SUB #9 <- #91
DO ,10 SUB #10 <- #93
DO ,10 SUB #11 <- #95
PLEASE ,10 SUB #12 <- #95
DO ,10 SUB #13 <- #69
DO ,10 SUB #14 <- #65
DO ,10 SUB #15 <- #74
PLEASE ,10 SUB #16 <- #94
DO ,10 SUB #17 <- #65
DO ,10 SUB #18 <- #74
DO :10 <- #117
(666) PLEASE .10 <- #3
DO IGNORE @10
(1) DO COME FROM (1)
</PRE>
The first part, from the start to the line with label (666),
opens a file <CODE>/tmp/server</CODE> for reading and writing;
the file name is stored in ,10 and the required access mode
in :10, then system call #3 does the rest. The file will be
associated with class variable @10. All the server has to do
at this point is IGNORE @10 and wait for it to be smuggled.
</P>
<P>
A client could SMUGGLE @10 and just do normal file operations
on it (using READ OUT, WRITE IN, and system call #4 and #5
to perform seeks). Any changes made to the underlying file
will be visible to other clients, as well as any user on the
server computer who has access to the underlying file.
The implementation of the client is left as an exercise to
the reader.
</P>
<H2><A NAME="internals">Internals</A></H2>
<P>
This section will document the underlying protocol used to
STEAL and SMUGGLE variables, as well as executing CASE statements;
it will also show how programs written in other languages can
communicate with INTERCAL programs using the INTERNET.
</P>
<P>
It's just unfortunate that this section hasn't been written yet.
</P>
</BODY>
</HTML>
|