summaryrefslogtreecommitdiff
path: root/README
diff options
context:
space:
mode:
authorTomi Ollila <too@iki.fi>2012-08-26 22:34:39 +0300
committerTomi Ollila <too@iki.fi>2012-08-30 10:46:58 +0300
commitb648b7712d02670089228a22544708abe5b048b1 (patch)
tree446cad86aa6fa7116392aa556ebed5d5ea5b4378 /README
parentd8053c280c0091f51df8715607b8e2535940790b (diff)
downloadlibfaketime-b648b7712d02670089228a22544708abe5b048b1.tar.gz
whitespace cleanup
Used (emacs) M-x untabify for whole faketime.c as the prevailing style in that file used spaces for indentation. Used M-x delete-trailing-whitespace to all files that had either trailing whitespace or empty lines at the end of file to remove those.
Diffstat (limited to 'README')
-rw-r--r--README97
1 files changed, 48 insertions, 49 deletions
diff --git a/README b/README
index 4041d65..9a035b8 100644
--- a/README
+++ b/README
@@ -27,13 +27,13 @@ Content of this file:
1. 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
+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 having to change the time system-
wide.
-FTPL allows you to specify both absolute dates (e.g., 01/01/2004) and
+FTPL allows you to specify both absolute dates (e.g., 01/01/2004) and
relative dates (e.g., 10 days ago).
FTPL might be used for various purposes, for example
@@ -50,12 +50,12 @@ FTPL might be used for various purposes, for example
2. Compatibility issues
-----------------------
-* FTPL has been designed on and for Linux 2.x, but is supposed and has been
- reported to work on other *NIXes as well.
+* FTPL has been designed on and for Linux 2.x, 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 or binaries that have the setuid-flag set (e.g., suidroot
- programs like "ping" or "passwd").
+ programs like "ping" or "passwd").
* As of version 0.7, support has been added for use in a pthreads environment. A
separate library is built (libfaketimeMT.so.1) which contains the pthread
@@ -79,15 +79,15 @@ FTPL might be used for various purposes, for example
---------------
Running "make" should compile both library versions and a test program, which
-it then also executes.
+it then also executes.
If the test works fine, you should copy the FTPL libraries (libfaketime.so.1,
-and libfaketimeMT.so.1) to the place you want them in. Running "make install"
-will attempt to place them in /usr/local/lib/faketime and will install the wrapper
+and libfaketimeMT.so.1) to the place you want them in. Running "make install"
+will attempt to place them in /usr/local/lib/faketime and will install the wrapper
shell script "faketime" in /usr/local/bin, both of which most likely will require
-root privileges; however, from a technical point of view, there is no
+root privileges; however, from a technical point of view, there is no
necessity for a system-wide installation, so you can use FTPL also on machines
-where you do not have root privileges. You may want to adjust the PREFIX
+where you do not have root privileges. You may want to adjust the PREFIX
variable in the Makefiles accordingly.
Since version 0.6, system calls to file timestamps are also intercepted now,
@@ -139,11 +139,11 @@ Or it can be done by specifying it on the command line itself:
LD_PRELOAD=/path/to/libfaketime.so.1 your_command_here
-(These examples are for the bash shell; how environment variables are set may
+(These examples are for the bash shell; how environment variables are set may
vary on your system.)
-However, also the faked time should be specified; otherwise, FTPL will be
+However, also the faked time should be specified; otherwise, FTPL will be
loaded, but just report the real system time. There are three ways to specify
the faked time:
@@ -151,19 +151,19 @@ a) By setting the environment variable FAKETIME.
b) By using the file .faketimerc in your home directory.
c) By using the file /etc/faketimerc for a system-wide default.
-If you want to use b) or c), $HOME/.faketimerc or /etc/faketimerc consist of
-only one line of text with exactly the same content as the FAKETIME environment
+If you want to use b) or c), $HOME/.faketimerc or /etc/faketimerc consist of
+only one line of text with exactly the same content as the FAKETIME environment
variable, which is described below. Note that /etc/faketimerc will only be used
if there is no $HOME/.faketimerc, and the FAKETIME environment variable always
has priority over the files.
-
+
4b) Using absolute dates
------------------------
-The format which _must_ be used for _absolute_ dates is "YYYY-MM-DD hh:mm:ss".
+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 specified as
-FAKETIME="2002-12-24 20:30:00".
+FAKETIME="2002-12-24 20:30:00".
4c) Using 'start at' dates
@@ -171,9 +171,9 @@ FAKETIME="2002-12-24 20:30:00".
(Thanks to a major contribution by David North, TDI in version 0.7)
-The format which _must_ be used for _start_at_ dates is "@YYYY-MM-DD hh:mm:ss".
+The format which _must_ be used for _start_at_ dates is "@YYYY-MM-DD hh:mm:ss".
For example, the 24th of December, 2002, 8:30 PM would have to be specified as
-FAKETIME="@2002-12-24 20:30:00".
+FAKETIME="@2002-12-24 20:30:00".
The absolute dates described in 4b simulate a STOPPED system clock at the
specified absolute time. The 'start at' format allows a 'relative' clock
@@ -188,14 +188,14 @@ 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:
-
+- 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
+
+- 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.
@@ -211,7 +211,7 @@ 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="`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
@@ -246,21 +246,21 @@ twice as fast. Similarly,
FAKETIME="+1y x0,5"
will make the clock run only half as fast. As stated above, the fraction
-delimiter depends on your locale.
+delimiter depends on your locale.
For testing, your should run a command like
LD_PRELOAD=./libfaketime.so.1 FAKETIME="+1,5y x10,0" \
/bin/bash -c 'while true; do echo $SECONDS ; sleep 1 ; done'
-For each second that the endless loop sleeps, the executed bash shell will
-think that 10 seconds have passed ($SECONDS is a bash-internal variable
+For each second that the endless loop sleeps, the executed bash shell will
+think that 10 seconds have passed ($SECONDS is a bash-internal variable
measuring the time since the shell was started).
(Please note that replacing "echo $SECONDS" e.g. with a call to "/bin/date"
will not give the expected result, since /bin/date will always be started
as a new process for which also FTPL will be re-initialized. It will show
-the correct offset (1.5 years in the future), but no speed-ups or
+the correct offset (1.5 years in the future), but no speed-ups or
slow-downs.)
@@ -278,7 +278,7 @@ for new mail every X minutes).
Using relative offsets or 'start at' dates solves this problem. FTPL then will
always report the faked time based on the real current time and the offset
-you've specified.
+you've specified.
Please also note that your specification of the fake time is cached for 10
seconds in order to enhance the library's performance. Thus, if you change the
@@ -291,12 +291,12 @@ command line option -DNO_CACHING to this library's Makefile.
4f) Faking the date and time system-wide
----------------------------------------
-David Burley of SourceForge, Inc. reported an interesting use case of applying
-FTPL system-wide: Currently, all virtual machines running inside an OpenVZ host
-have the same system date and time. In order to use multiple sandboxes with
-different system dates, the FTPL library can be put into /etc/ld.so.preload;
+David Burley of SourceForge, Inc. reported an interesting use case of applying
+FTPL system-wide: Currently, all virtual machines running inside an OpenVZ host
+have the same system date and time. In order to use multiple sandboxes with
+different system dates, the FTPL library can be put into /etc/ld.so.preload;
it will then be applied to all commands and programs automatically. This is
-of course best used with a system-wide /etc/faketimerc file. Kudos to
+of course best used with a system-wide /etc/faketimerc file. Kudos to
SourceForge, Inc. for providing the patch!
@@ -324,7 +324,7 @@ Thanks to Daniel Kahn Gillmor for providing these suggestions!
--------------------------
Starting with version 0.9, libfaketime can be configured to not be continuously
-active, but only during a certain time interval.
+active, but only during a certain time interval.
For example, you might want to start a program with the real current time, but
after 5 minutes of usage, you might want it to see a faked time, e.g., a year
@@ -340,7 +340,7 @@ Dynamic changes to the faked time are alternatively possible by
- not using the FAKETIME environment variable, but specifying the fake time in a
file (such as ~/.faketimerc). You can change the content of this file at
run-time. This works best with caching disabled (see Makefile), but comes at a
- performance cost because this file has to be read and evaluated each time.
+ performance cost because this file has to be read and evaluated each time.
The feature described here works based on two pairs of environment variables,
@@ -348,7 +348,7 @@ The feature described here works based on two pairs of environment variables,
FAKETIME_START_AFTER_NUMCALLS and FAKETIME_STOP_AFTER_NUMCALLS
The default value for each of these environment variables is -1, which means
-"ignore this value".
+"ignore this value".
If you want libfaketime to be only active during the run-time minutes 2 to 5
of your application, you would set
@@ -359,7 +359,7 @@ of your application, you would set
This means that your application will work with the real time from start (second
0) up to second 60. It will then see a faked time from run-time seconds 60 to
300 (minutes 2, 3, 4, and 5). After run-time second 600, it will again see the
-real (not-faked) time.
+real (not-faked) time.
This approach is not as flexible as changing the FAKETIME environment variable
during runtime, but may be easier to use, works on a per-program (and not a
@@ -368,9 +368,9 @@ per-user or system-wide) scope, and has only a minor performance overhead.
Using the other pair of environment variables, you can limit the activity time
of libfaketime not based on wall-clock seconds, but on the number of
time-related function calls the started program performs. This alternative is
-probably only suitable for programmers who either know the code of the program
-in order to determine useful start/stop values or want to perform fuzzing
-tests.
+probably only suitable for programmers who either know the code of the program
+in order to determine useful start/stop values or want to perform fuzzing
+tests.
Both pairs of environment variables can be combined to further restrict
libfaketime activity, although this is only useful in very few scenarios.
@@ -379,9 +379,9 @@ Limiting libfaketime activity in this way is not recommended in general. Many
programs will break when they are subject to sudden changes in time, especially
if they are started using the current (real) time and are then sent back into
the past after, e.g., 5 minutes. For example, they may appear to be frozen or
-stuck because they are waiting until a certain point in time that, however, is
-never reached due to the delayed libfaketime activity. Avoid using this
-functionality unless you are sure you really need it and know what you are
+stuck because they are waiting until a certain point in time that, however, is
+never reached due to the delayed libfaketime activity. Avoid using this
+functionality unless you are sure you really need it and know what you are
doing.
@@ -401,7 +401,7 @@ program started. This has two limitations one needs to be aware of:
* The original program is blocked until the external process is finished,
because the intercepting time-related system call will not return earlier. If
you need to start a long-running external process, make sure it forks into the
- background.
+ background.
Spawning the external process is controlled using three environment variables:
FAKETIME_SPAWN_TARGET, FAKETIME_SPAWN_SECONDS, FAKETIME_SPAWN_NUMCALLS.
@@ -415,7 +415,7 @@ export FAKETIME_SPAWN_SECONDS=5
This will run the "echo" command with the given parameter during the first
time-related system function call that "myprogram" performs after running for 5
-seconds.
+seconds.
5. License
@@ -435,4 +435,3 @@ appreciated.
Please send an email to: wolf /at/ code-wizards.com
git pull requests are welcome, see https://github.com/wolfcw/libfaketime
-