m(easuring) buffer
==================
AUTHOR:		Thomas Maier-Komor
e-mail:		thomas@maier-komor.de
homepage:	http://www.maier-komor.de/mbuffer.html


LICENSE:
========
GNU GPLv3 (see file LICENSE for details)


DESCRIPTION:
============
mbuffer is a replacement for buffer with additional functionality:

# display of i/o speed
# optional use of memory mapped i/o for huge buffer files
# multithreaded instead of sharedmemory ipc
# multi-volume support
# auto-loader support
# network support
# buffer compatible command-line options


NETWORKING:
===========
The included networking code is based on TCP/IP.  To use it you should
know the basics of TCP/IP. Use it only on a trusted LAN, as there is no
builtin security.


TESTING:
========
to test the program I do the following:
# tar cf - /usr | mbuffer | tar tf - > out
# tar cf - /usr | mbuffer -t | tar tf - > out


ARCHITECTURES and PLATFORMS:
============================
This software has been tested under the following operating systems:
- solaris 8 (SPARC and x86) and later
  - no known issues
  - do not put your temporary files on a tmpfs filesystem,
    as this is equivalent to a normal memory allocated buffer
- linux 2.2 (x86) and later
  - some pthread versions of linux seem to have problems with
    cancellation, causing a segmentation fault upon SIGINTR
- tru64-alpha 
  - broken display
- FreeBSD 5.x (x86)


MacOS:
======
mbuffer compiles and runs on macOS.

Previous versions required sem_getvalue(), which macOS does not implement for
unnamed semaphores. This limitation was overcome With the usage of POSIX
condition variables.

macOS-specific features:
- Memory detection using Mach VM APIs (host_statistics64)
- Proper fsync error handling for APFS and other macOS filesystems


Buffer limitations:
===================
Buffer size is only limited by available system memory and address model.

The number of blocks within a buffer can be limited by the infrastructure on
specific platforms. This limit is high enough to be no practical issue, as it
is adviced to create buffers with less than 10000 blocks. Increasing the number
of block further can impact performance negatively.

If the maximum buffer size should be possible larger than 2GB, you need to
compile mbuffer as a 64bit executable. This is usually the default on machines
with 64-bit address space. In special cases you must consult the compiler
manual to add the necessary compiler switches to CFLAGS.


TODO:
=====
# fix: unknown bugs


FEEDBACK:
=========
It is always nice to get feedback. If you encounter
a problem or a bug, send me a note. Requests for enhancements
are also welcome.
(software@maier-komor.de)


DONATIONS:
==========
If you like this software, and use it for production purposes in your
company, please consider making a donation to support this work. 
You can donate via PayPal to the author's e-mail address:
thomas@maier-komor.de
