                FakeTime Preload Library, version 0.5
                =====================================


Introduction
------------

FTPL intercepts various system calls which programs use to retrieve the 
current date and time. It can then report faked dates and times (as 
specified by you, the user) to these programs. This means you can modify
the system time a program sees without changing the time system-wide.

FTPL allows you to specify both absolute dates (e.g., 1.1.2004) and 
relative dates (e.g., 10 days ago).

FTPL might be used for various purposes, for example

- running legacy software with y2k bugs
- testing software for year-2038 compliance
- debugging time-related issues
- run software which ceases to run outside a certain timeframe



Compatibility issues
--------------------

FTPL has been designed on and for Linux, but is supposed and has been 
reported to work on other *NIXes as well. 

FTPL uses the library preload mechanism and thus cannot work with statically
linked binaries. 



Installation and usage
----------------------

Running "make" should compile the library and a test program, which it then
also executes. 

If the test works fine, you should copy the FTPL library (libfaketime.so.1)
to the place you want it in (e.g. /usr/local/lib).


Using FTPL on a program of your choice consists of two steps:

1. Making sure FTPL gets loaded.
2. Specify the faked time.


As an example, we want the "date" command to report our faked time. To do so,
we could use the following command line:

user@host> date
Tue Sep 23 12:01:05 CEST 2003

user@host> LD_PRELOAD=/usr/local/lib/libfaketime.so.1 FAKETIME="-15d" date
Mon Sep  8 12:01:12 CEST 2003


The basic way of running any command/program with FTPL enabled is to make sure
the environment variable LD_PRELOAD contains the full path and filename of the
FTPL library. This can either be done by setting it once beforehand:

export LD_PRELOAD=/path/to/libfaketime.so.1
(now run any command you want)


Or it can be done by specifying it on the command line itself:

LD_PRELOAD=/path/to/libfaketime.so.1 your_command_here


However, also the faked time should be specified; otherwise, FTPL will be 
loaded, but just report the real system time. There are two ways to specify
the faked time:

a) By setting the environment variable FAKETIME
b) By using the file .faketimerc in your home directory.

If you want to use b), .faketimerc consists of only one line with exactly the
same content as the FAKETIME environment variable, which is described next.


The format which _must_ be used for _absolute_ dates is "YYYY-MM-DD hh:mm:ss". 
For example, the 24th of December, 2002, 8:30 PM would have to be written as
"2002-12-24 20:30:00". 


Relative date offsets can be positive or negative, thus what you put into
FAKETIME _must_ either start with a + or a -, followed by a number, and
optionally followed by a multiplier:

- by default, the offset you specify is in seconds. Example: 
  
  export FAKETIME="-120" will set the faked time 2 minutes (120 seconds) behind
  the real time.
  
- the multipliers "m", "h", "d" and "y" can be used to specify the offset in 
  minutes, hours, days and years (365 days each), respectively. Examples:
  
  export FAKETIME="-10m" sets the faked time 10 minutes behind the real time.
  export FAKETIME="+14d" sets the faked time to 14 days in the future.


You now should be able to understand the complete example we've used before:

LD_PRELOAD=/usr/local/lib/libfaketime.so.1 FAKETIME="-15d" date

This command line makes sure FTPL gets loaded and sets the faked time to
15 days in the past.

Moreno Baricevic has contributed support for the FAKETIME_FMT environment
variable, which allows to optionally set the strptime() format:

Some simple examples:
LD_PRELOAD=./libfaketime.so.1 FAKETIME_FMT=%s FAKETIME="`date +%s -d'1 year ago'`" date 
LD_PRELOAD=./libfaketime.so.1 FAKETIME_FMT=%s FAKETIME="`stat -c %Y somefile`" date
LD_PRELOAD=./libfaketime.so.1 FAKETIME_FMT=%c FAKETIME="`date`" date


Caveat:

Whenever possible, you should use relative offsets and not absolute dates.

Why? Because the absolute date/time you set is fixed, i.e. if a program asks
for the current time, and asks for the current time again 5 minutes later, it
will still get the same result twice. This is likely to break programs which
measure the time passing by (e.g. a mail program which checks for new mail
every X minutes).

Using relative offsets solves this problem. It will always report the faked
time based on the real current time and the offset you've specified. 



Internals
---------

FTPL currently intercepts the following system calls: time(), ftime(),
gettimeofday(), clock_gettime().



License
-------

FTPL has been released under the GNU Public License, GPL. Please see the
included COPYING file.



Contact
-------

Bug reports, feature suggestions, success reports and patches are welcome.

email: wolf /at/ code-wizards.com


