BLib.Skt - TCP/IP Socket Library Routines
                 =========================================
                          File: Skt - Update: 0.11
                  Author: J.G.Harston - Date: 18-Dec-2010


  The Skt library provides functions to communicate over a TCP/IP network,
for example an Ethernet interface, such as the Sprow Master Ethernet
Interface[1]. It uses a different namespace to the Socket library, but
provides idential functionality.

Requirements and Dependancies
=============================
  The library requires a global control block large enough to hold the data
required for the calls accessible with X% holding the address of this
block, and Y% holding X% DIV 256. A control block size of 32 bytes is
sufficient for most calls. This can easily be set up with DIM ctrl% 31 near
the start of the program and X%=ctrl%:Y%=X%DIV256 at the begining of the
major program code and at the start of any main program loop.

  The resolver calls require name% to point to a block of at least 80
bytes, set up with DIM name% 80.

Definitions
===========
socket%   - a socket number to identify a connection
addr%     - address of data to transfer or socket structure
len%      - length of data or size of socket sctruture
domain%   - communications domain, usually 2 for PF_INIT
protocol% - communications protocol

Socket Function Calls
=====================
  Functions return a positive number (or zero) to indicate success, and a
negative number to indicate failure. This allows the following sort of code
to be used:

  A%=FNskt_xxxx(parameters):IF A%<0 THEN REM Failed...

FNskt_open(domain%,type%,protocol%)
-----------------------------------
Opens a new socket for communication. Returns a socket number for future
communication, or a negative number if the call failed. domain% is usually
2 for PF_INET. type% can be 1=stream, 2=datagram, 3=raw.

FNskt_bind(socket%,addr%,len%)
------------------------------
Binds a socket to the socket structure at the specified address.

FNskt_listen(socket%,count%)
----------------------------
Listen for connections on a socket.

FNskt_accept(socket%,addr%,len%)
--------------------------------
Waits for an incoming connection on a socket. Once an incoming connection
has been accepted, the socket structure at the specified address is updated
with the incoming connection details.

FNskt_connect(socket%,addr%,len%)
---------------------------------
Connects a socket to the remote connection at the specified address.

FNskt_recv(socket%,addr%,len%,opts%)
------------------------------------
Attempts to read data from the specified socket. Returns a negative number
if the call failed, or the number of bytes transfered if successful.

FNskt_send(socket%,addr%,len%,opts%)
------------------------------------
Attempts to send data to the specified socket. Returns a negative number if
the call failed, or the number of bytes transfered if successful.

PROCskt_shutdown(socket%,type%)
-------------------------------
Partially shuts down a socket.

PROCskt_close(socket%)
----------------------
Closes an open socket.

Socket Structure
================
  The socket structure used by bind, accept and connect has the following
layout:
     0     = Size of socket structure, usually 16
     1     = address type, usually 2 for AF_INET
     2..3  = port number
     4..7  = IPv4 internet address
     8..11 = 0
    12..15 = 0

Resolver Function Calls
=======================
  If a resolver call fails it returns zero, otherwise returns the address
of a hostent structure holding the following data:
     0..3  = pointer to name looked up
     4..7  = IP address type, 2 for AF_INET
     8..11 = length of address type, 4 for IPv4
    12..15 = pointer to a null-terminated list of pointers to IP addresses

FNdns_gethostbyname(name$)
--------------------------
Searches for the specified hostname and waits until a match is found.

FNdns_gethost(name$)
--------------------
Searches for the specified host name, returns immediatedly returning 0 if
no match. Can be called repeatedly until a match is found.

See Also
========
* Socket library http://mdfs.net/blib/Socket
* Socket documentaion http://mdfs.net/blib/Docs/Socket.txt

References
==========
[1]Sprow Ethernet Interface, http://sprow.co.uk/bbc/masternet.htm

Version History
===============
0.11 18-Dec-2010 Version written as short-name version of Socket library.