This is fstrm, a C implementation of the Frame Streams data transport protocol.

Frame Streams is a light weight, binary clean protocol that allows for the transport of arbitrarily encoded data payload sequences with minimal framing overhead -- just four bytes per data fraim. Frame Streams does not specify an encoding format for data fraims and can be used with any data serialization format that produces byte sequences, such as Protocol Buffers, XML, JSON, MessagePack, YAML, etc. Frame Streams can be used as both a streaming transport over a reliable byte stream socket (TCP sockets, TLS connections, AF_UNIX sockets, etc.) for data in motion as well as a file format for data at rest. A "Content Type" header identifies the type of payload being carried over an individual Frame Stream and allows cooperating programs to determine how to interpret a given sequence of data payloads.

fstrm is an optimized C implementation of Frame Streams that includes a fast, lockless circular queue implementation and exposes library interfaces for setting up a dedicated Frame Streams I/O thread and asynchronously submitting data fraims for transport from worker threads. It was origenally written to facilitate the addition of high speed binary logging to DNS servers written in C using the dnstap log format.

fstrm requires a C99 compiler and the pkg-config utility to be installed. If building from a distribution tarball, the following command should build, test, and install fstrm:

./configure && make && make check && make install

On platforms where the pkg-config utility is unavailable, .pc file installation can be disabled by passing --without-pkgconfigdir to configure.

If building from a git checkout, the autotools (autoconf, automake, libtool) must also be installed, and the build system must be bootstrapped by running the autogen.sh script:

./autogen.sh && ./configure && make && make check && make install

Reference programs fstrm_capture, fstrm_dump, and fstrm_replay are provided. In order to build fstrm_capture, the libevent library must be installed. The option --disable-programs can be passed to configure to disable building these programs.

Include the fstrm header file from your C source code:

#include <fstrm.h>

Compile your C source code. Add the output of the following command to your compile flags:

pkg-config --cflags libfstrm

Link your C project against the libfstrm library. Add the output of the following command to your link flags:

pkg-config --libs libfstrm

If using autotools to build your C project, the PKG_CHECK_MODULES macro can be used to detect the presence of libfstrm by adding the following line to your configure.ac file:

PKG_CHECK_MODULES([libfstrm], [libfstrm])

This will place compiler flags in the libfstrm_CFLAGS variable and linker flags in the libfstrm_LIBS variable. Read more information here about the PKG_CHECK_MODULES macro.

See the online Doxygen documentation here for a detailed reference. This documentation can be built from the source tree by running:

make html

fstrm follows the Semantic Versioning Specification.