fasttime library documentation


fasttime is a user-mode replacement for the gettimeofday(2) system call present on POSIX systems. Using this library an application may be able to get timestamps faster, and/or more accurately than with gettimeofday.

This document is targeted at application developers and describes how to quickly get started using it, as well as some details on using the more advanced features. The API is described in full in the man pages that accompany the source distribution, available from the project home page.

Building and installing the library

fasttime has been tested successfully on Linux, FreeBSD, Solaris and Mac OS X, with x86, AMD64, SPARC and PowerPC processors. You will require the GNU toolchain (gcc and make) to build the library.

make install

Before compiling, make will run the configure script included. This checks what kind of system you have and creates the remaining makefiles and the config.h header file. If your system is not detected successfully you may need to create config.h from and src/Makefile from src/ manually. Please send these patches to us so we can provide support for your system in future releases.

The library is installed into /usr/local/lib and /usr/local/include by default. Edit the makefile if you need to install it in a different location.

Starting the daemon

fasttime works best when it has been running for at least a few minutes. You may wish to start the fasttimed daemon, which will service all applications using the fasttime library. If you do not start the daemon, applications that use fasttime will each start the daemon in a separate thread within their own process space.

To start the daemon:

fasttimed &

If you need to stop it, send a signal:

killall -HUP fasttimed

There is no need to run fasttimed as root.

Writing applications that use fasttime

Regardless of whether the daemon is being used or not, applications compile and link with it in the same way. Source files can include fasttime.h:

#include <fasttime.h&rt;

Executables need to link against libfasttime.a:

gcc -o app app.c -lfasttime

On some platforms you may also need to link in -pthread or -lpthread, and -lrt.

Before making any calls to fasttime_gettimeofday, applications need to initialise the library (typically this should be done once during startup):


From this point, anywhere gettimeofday would ordinarily be called, fasttime_gettimeofday can be substituted:

struct timeval tv;

Note that fasttime has no support for returning timezone information. Many implementations of gettimeofday don't either, so applications should seek some other way to get this information if required.

Controlling the calibration source

By default, during fasttime_init the library will attempt to use the calibration supplied by the daemon, if it is running. If not, it will start its own thread. During startup, when calibration is incomplete, fasttime will pass fasttime_gettimeofday calls through to the system gettimeofday. You can change this behaviour by calling fasttime_init_context instead of fasttime_init.

fasttime_init_context takes as parameters a fasttime_context pointer and bitwise-OR combination of allowable calibration sources. Normally you can just use the static context used by the no-argument fasttime_init, by passing in NULL. In this case you just specify the methods you want to use:


In this example the daemon will be tried first, if it is not running fasttime will pass all fasttime_gettimeofday calls through to gettimeofday (avoids creating a separate thread). The available methods are tried in the order listed below:

Use the calibration tables provided by the daemon process
Start a thread to do calibration
Pass calls through to gettimeofday

If none of the requested methods can be used the context will not be initialised and an error code is returned.