Revising buffered I/O return values.

Changing two buffered I/O functions to return more homogeneous values.
Error is now -1 everywhere. 
pipe_buffers no longer returns a counter of piped chars, but a value
related to the reason of returning.
Improved documentation.

A new PROTOCOL file explains Basicmail protocol.
Several functions and global variables got a brief documentation.