----          ABOUT THE VFILE INTERFACE FOR SLang                ----


vfile-module implements some file-IO functions supporting both normal files
and TCP/UDP sockets.  It may be extended to support other asynchronous
devices such as modems, pipes to programs, and the ttyp* devices.

It also implements a sort of `scheduler' through the functions
set_action() clr_action() and do_actions().

----   DIGRESSION ON THE SUBJECT OF 'MULTI-THREADING' with SLang ----

Since SLang itself is not multi-threaded, there is need for some way
to let it handle data asynchronously arriving from multiple sources.
set_action() and do_actions() provide a weak kind of multi-threading
for SLang applications.

After one opens an I/O device, one may specify what it means for
input to be `ready' in the sense of there being enough input to be
processed by a SLang function (known as it's handler).  Actions
on arriving data may require either a certain minimum number of
bytes of data, or perhaps they may require a line of data terminated
by "\n".  in the latter case, we also specify a 'threshold' such
that when a certain number of bytes have arrived, the handler will
be called even if there has been no terminating character.

To use the vfile module, first of all your *.sl script must have,
near the top:
       import("vfile");

Having opened, say, a TCP connection, via
       sock = tcp_open("tsx-11.mit.edu",getservbyname("daytime"));
we may then define the `ready' meaning by:
       () = set_rmode(sock,'\n',512);
which means don't consider me 'readable' until either a newline has
arrived or at least 512 chars have.  Then we specify a certain function
(handler) to be executed when data is ready:
       () = set_action(sock,0,"MyInputHandler",cookie);
where `cookie' is an optional arbitrary object, perhaps a structure,
which may be useful for the handler. (The 0 parameter means 'read',
as in the UN*X select() function.)

When ready data is available, the handler will be called with
3 parameters: the VFile_Type sock, Integer_Type i, and the cookie...
so Handler will be declared like:
     definition Handler(sock,i,cookie) { ... }
The `i' parameter is 0,1,2 representing read,write,exception condition,
as with select();

We will also specify a handler for stdin (StdIn for VFile interface,
so as not to conflict with slfile's stdin).  Then the whole program
will execute out of a main loop using do_actions().  In this way a
program can 'simultaneously' deal with input/output to multiple devices.

There is an underlying assumption here that updates to the screen are
relatively fast, because of course we will still at least not be responsive
to the keyboard during the time while the screen is actually being updated.
If the screen is, for example, the Linux console, this assumption is
justified.  In any event, this is as close as we can come (speed-wise)
to multi-threading given the current implementation of libslang (IMHO).
And a truly multi-threaded re-implementation of slang would probably
be quite a large project (also IMHO).

If slang could save/restore stack-contexts then we could have an easier
to use `multi-threading' method by simply doing a context-switch upon
any IO-action which would otherwise block.  Not knowing the internals
of slang well enough to consider context-switching, this `event-driven'
approach seemed the more practical to implement for use with SLirc.
It works quite well, but is sometimes a bit awkward to program, since
frequently state-information must be propagated with 'cookie' structures,
so that the handlers know where they are.  It's a bit like writing
interrupt handlers.

----         END THE GENERAL PHILOSOPHICAL DIGRESSION          ----

Now for a brief description of the intrinsics provided by VFile.

Functions for dealing with internet services, hostnames, etc:

   Integer_Type getservbyname(String_Type service)
   Integer_Type gethostbyname(String_Type host)
   Integer_Type inet_addr(String_Type DottedQuad)
   String_Type gethostbyaddr(Integer_Type IPnumber)
   String_Type inet_ntoa(Integer_Type IPnumber)

   IPnumbers are internet addresses carried in slang's Integer_Type,
   which is generally >= 32 bits.  They are really unsigned 32 bit.

Functions for opening files, sockets, and connected sockets:

   VFile_Type vf_open(String_Type filename, (int) flags, (int) mode)
	 Integer_Type vf_close(VFile_Type)
	 Integer_Type vf_reset()   close all.. especially to kill spawned proc's
	 Integer_Type unlink(String_Type filename)  [delete a local file]

   VFile_Type tcp_open(String_Type hostname, (int) port)
   VFile_Type tcp_connect((int) IPnum, (int) port)
   VFile_Type tcp_listen()
   VFile_Type tcp_accept(VFile_Type ListenSocket)

   VFile_Type udp_open((int) IPnum, (int) port) [IPnum,port local, usually 0,0]
   VFile_Type udp_connect((int) IPnum, (int) port)

Functions for getting information about opened files or sockets:

	Integer_Type vf_fileno(VFile_Type)

	Integer_Type vf_eof(VFile_Type)
	Integer_Type vf_error(VFile_Type)
	Integer_Type vf_clearerr(VFile_Type)
	Integer_Type vf_size(VFile_Type)    returns length of an open file
	Integer_Type vf_seek(VFile_Type, offset, whence)  like posix lseek
	Integer_Type vf_rbuffct(VFile_Type) returns #bytes of buffered data

  (IPnum,port) = get_local_ipp(VFile_type)
  (IPnum,port) = get_remote_ipp(VFile_type)

  variable Integer_Type vf_errno
  variable String_Type  vf_errmsg
	String_Type vf_strerr(int)

Functions for setting characteristics of opened files or sockets:

  Integer_Type set_rmode(VFile_Type file, (int) delim, (int) threshold)
  Integer_Type set_wrdep(VFile wr,VFile rd,int 0 or 1)
	Integer_Type set_nodelay(Vfile TCPsock, (int) on)  [set/clear TCP_NODELAY]

Functions for reading/writing opened files or sockets:

	int vf_read(VFile, &(String_Type buf) | Array_Type [, int n])
	int vf_write(VFile, String_Type | Array_Type | BString_Type [, int n])
  int copy_bytes(VFile dest, VFile src, int MaxBytesToCopy)

	in the case of an un-connected UDP socket, write is really sendto(),
  which requires 2 additional params to specify the destination IPnum,port,
  so the write call is like:
     int vf_write((int) IPnum, (int) port, VFile, ...)


Functions for polling `readiness' of opened VFiles:

	int wait_next_readable(int MaxSecsToWait)  [does `select' on all readables]
	int is_readable(VFile, int MaxSecsToWait)
	int is_writeable(VFile, int MaxSecsToWait)

  These polling functions are sometimes useful for simple scripts,
  but are deprecated in favor of defining handlers and executing
  via the do_actions() `scheduler'.

Functions for defining IO functions, and triggering them upon `readiness'.

	int set_action(VFile, int which, "Handler" [,cookie])  (which is 0,1,2)
	int clr_action(VFile)   (clears ALL handlers for the file)
	int do_actions(int MaxSecsToWait)

Miscellaneous (glue) Functions:

	Integer_Type array_get_u32(Char_Array_Type, (int) ByteOffset)
	Void_Type    array_put_u32(Char_Array_Type, (int) ByteOffset, (int) Value)
	Integer_Type unlink(String_Type filename)  [delete a local file]
	String_Type  ftp_hostport((int) IPnum, (int) port)
    [above makes the weird "a,a,a,a,p,p" string used by FTP-protocol]


----              SOME EXAMPLES OF USING VFILE                    ----

There are some small scripts in the ./tests/ directory of SLirc...

To try them out, you have to make the `vf' program to load them.
This is done by doing `make tests/vf' in the base directory of SLirc.

Then, cd to ../tests directory, and try out the test-scripts by:
              ./vf NameOfScript.sl
  or LD_PRELOAD=../lib/libslang.so ./vf NameOfScript.sl
  (the latter in case you used the local, not global, libslang.so)

They are minimally self-documented...

   vfilew.sl   Creates a local file, writes 50k of zeros to it.
   udp.sl      Does a UDP netdate time lookup on tsx-11.mit.edu
   udpc.sl     Same as udp.sl, only using a `connected' UDP socket.
   vdaytime.sl Prompts for `hostname', then reads TCP daytime service.
   vfinger.sl  Prompts for a `user@host', then does TCP finger.
   vtest.sl    Opens a TCP listen socket, connects to it, accepts connection.
   Vwget.sl    Prompts for URL of a webpage `host/dir/file', reads it
               and dumps the whole mess on your screen.  This one uses
               the set_action(),do_actions() functions.
   vbabel.sl   Pipes stdin (an english text) through
               babelfish.altavista.digital.com's translator and outputs
               the french version on stdout.
   vMAPS.sl    Prompts for a hostname, and tells you whether it's on
               the MAPS rbl spammer list.
               See http://maps.vix.com/rbl/usage.html for more details
               about MAPS, it looks like a good idea.

----         BELOW HERE IS UNFINISHED WORK         ----

Variables exported by VFile interface:
	vf_errno
	vf_errmsg

Constants exported by VFile interface:
	O_RDONLY
	O_WRONLY
	O_RDWR
	O_CREAT
	O_EXCL
	O_NOCTTY
	O_TRUNC
	O_APPEND
	O_NONBLOCK
	O_NDELAY
	O_FSYNC
	SEEK_SET
	SEEK_CUR
	SEEK_END

