Readme for Brutalcopy 
Brutalcopy (c) 2000, 2001 Karel 'Clock' Kulhavy, <clock at atrey dot karlin dot
mff dot cuni dot cz>

What is bcpc good for? For copying files over faulty lines using UDP protocol.
bcp is very robust and will flawlessly work on lines where TCP connections
would normally fail.

Read INSTALL to see how to install bcp.

User manual
-----------

There are two programs: bcps and bcpc. bcps=server. bcpc=client.
user action: run bcps on destination and bcpc on source.

Tell bcps the port number (1235 is the default), file name (to send), EOT
period (normally unnecessary), number of EOT retries (normally unnecessary),
info cache flush timeout (normally unnecessary), info loop timeout (normally
unnecessary), info packet size (number of useful bytes per packet).

Tell bcpc the server host name, the server port (1235 default), the filename
(to dump the data into), length of payload in bytes, bit rate (in bits per
second), SOT loop timeout.

It is possible to reset the speed of the client by editing .speed in the
program's current directory, writing the bytes per second number, saving
the file and killall -1 bcpc (or kill -1 pid if more bcpc are running).
If killed with 1 and can't read the number, the setting remains unchanged.

All times are in usec or in usec from 1970.

The remainder of this file talks about the way bcp works inside.
================================================================

Message format (messages are idempotent):

1 byte command
--------------

0-SOT. Contains session ID (4 bytes), bitrate (8 bytes), length of payload in
bytes (4 bytes), length of file in bytes (4 bytes), max. number of
info entries (4 bytes).

1-data packet. Contains packet sequence number (4 bytes) and data.

2-info packet. Contains info packet seq# (4 bytes) and info fields.  Each info field contains
sequence number of a data packet. Each info field is 4-byte.

3-EOT packet. Contains nothing.

4-SOT ACK. Contains nothing.

5-info ACK. Contains info packet seq# .

Packet format
-------------
Packet contains 32-bit CRC32 checksum. The resulting checksum from crc32()
function is 32-bit unsigned long integer that is stored in the packet in LSB
first order.
Session ID is chosen randomly by reading /dev/random.

Action:
-------

Client:
-------

client sends SOT to server. If SOT ACK doesn't come until timeout, repeats.

Clients takes the file and makes a bitmap, one bit for one packet payload.
Starts going throught the bitmap and sending the packets at specified bitrate.
If goes to the end, the packet will be maybe shorter. Then the bit counter
will be zeroed out. If no bit is found, returns from the program.

If info comes, sends info ACK and marks the appropriate bits. Then returns
to sending data.

If EOT comes, ends sending and returns from the program.

Server:
-------
Waits for SOT. As SOT comes, initializes bitmap and opens file. sends SOT ACK. Then waits
for data. Also makes counter how many packets to receive.

As data comes, puts data ACK into info cache, writes data. If data are first to
be written on that place, decs the packet counter. If counter is 0, starts
sending EOT packets and then ends.

If they are not first to be written and they are still in info cache, the cache
is flushed.

If a packet is in info cache and gets full, is sent. If it gets old, is sent.
If it's sent and info ACK doesn't come until info timeout, is resent.

Data structures:
----------------

Client: bitmap. A field of chars. If you have bit n, it's in byte (n>>3) on bit
with weight of 1<<(n&7).
Bitmap pointer.

Server: the same bitmap.
Counter of remaining packets.
Info half packet structure: how many are filled, the field with the numbers, the
first available seq#.
Info queue: link list. Each member contains seq#, the payload of the packet and
time -- unsigned long long in usec from 1970.

fd -- the socket.

Routines:
---------
Input: nothing. Tells the next time, when the info que gets moving.
Input: nothing. Sends the half packet.
Input: bit pos. Output: next (maybe also wrapped) unsent bit pos. If -1,
everything is sent
Input: packet. Sends the packet to the other side.
Input: nothing. initializes the UDP port.
Input: nothing. closes the UDP port.

