NAME¶
faketime - manipulate the system time for a given command
SYNOPSIS¶
faketime [options] timestamp program [arguments...]
DESCRIPTION¶
The given command will be tricked into believing that the current system time is
the one specified in the timestamp. The wall clock will continue to run from
this date and time unless specified otherwise (see advanced options).
Actually, faketime is a simple wrapper for libfaketime, which uses the
LD_PRELOAD mechanism to load a small library which intercepts system calls to
functions such as
time(2) and
fstat(2). This wrapper exposes
only a subset of libfaketime's functionality; please refer to the README file
that came with faketime for more details and advanced options.
OPTIONS¶
- --help
- show usage information and quit.
- --version
- show version information and quit.
- -m
- use the multi-threading variant of libfaketime.
- -f
- use the advanced timestamp specification format.
EXAMPLES¶
faketime 'last Friday 5 pm' /bin/date
faketime '2008-12-24 08:15:42' /bin/date
faketime -f '+2,5y x10,0' /bin/bash -c 'date; while true; do echo $SECONDS ; sleep 1 ; done'
faketime -f '+2,5y x0,50' /bin/bash -c 'date; while true; do echo $SECONDS ; sleep 1 ; done'
(Please note that it depends on your locale settings whether . or , has to be used for fractional offsets)
The simple timestamp format used by default applies the
/bin/date -d
command to parse user-friendly specifications such as 'last friday'. When
using the faketime option
-f, the timestamp specified on the command
line is directly passed to libfaketime, which enables a couple of additional
features such as speeding the clock up or slowing it down for the target
program. It is strongly recommended that you have a look at the README file
that came with faketime for the details. Summary:
- Freeze clock at absolute timestamp: "YYYY-MM-DD
hh:mm:ss"
- If you want to specify an absolute point in time, exactly
this format must be used. Please note that freezing the clock is usually
not what you want and may break the application. Only use if you know what
you're doing!
- Relative time offset: "[+/-]123[m/h/d/y], e.g.
"+60m", "+2y"
- This is the most often used format and specifies the faked
time relatively to the current real time. The first character of the
format string must be a + or a -. The numeric value by default
represents seconds, but the modifiers m, h, d, and y can be used to
specify minutes, hours, days, or years, respectively. For example,
"-2y" means "two years ago". Fractional time offsets
can be used, e.g. "+2,5y", which means "two and a half
years in the future". Please note that the fraction delimiter depends
on your locale settings, so if "+2,5y" does not work, you might
want to try "+2.5y".
- Start-at timestamps: "@YYYY-MM-DD
hh:mm:ss"
- The wall clock will start counting at the given timestamp
for the program. This can be used for specifying absolute timestamps
without freezing the clock.
ADVANCED USAGE¶
When using relative time offsets or start-at timestamps (see ADVANCED TIMESTAMP
FORMAT above and option
-f), the clock speed can be adjusted, i.e. time
may run faster or slower for the executed program. For example,
"+5y
x10" will set the faked time 5 years into the future and make the
time pass 10 times as fast (one real second equals 10 seconds measured by the
program). Similarly, the flow of time can be slowed, e.g. using
"-7d
x0,2", which will set the faked time 7 days in the past and set the
clock speed to 20 percent, i.e. it takes five real world seconds for one
second measured by the program. Again, depending on your locale, either
"x2.0" or "x2,0" may be required regarding the delimiter.
Faking times for multiple programs or even system-wide can be simplified by
using ~/.faketimerc files and /etc/faketimerc. Please refer to the README that
came with faketime for warnings and details.
AUTHOR¶
Maintained by Wolfgang Hommel <wolf@code-wizards.com>. Please see the
README and Changelog files for contributers.
BUGS¶
Due to limitations of the LD_PRELOAD mechanism, faketime will not work with
suidroot and statically linked programs. While timestamps and time offsets
will work for child processes, speeding the clock up or slowing it down might
not work for child processes spawned by the executed program as expected; a
new instance of libfaketime is used for each child process, which means that
the libfaketime start time, which is used in speed adjustments, will also be
re-initialized.
REPORTING BUGS¶
Please send an e-mail to Wolfgang Hommel <wolf@code-wizards.com>
COPYRIGHT¶
Copyright © 2003-2008 by Wolfgang Hommel.
There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE. You may redistribute copies of faketime under the terms of the GNU
General Public License.
For more information about these matters, see the file named COPYING.
SEE ALSO¶
ld.so(1),
time(2),
fstat(2)