Ubuntu Manpage: faketime - manipulate the system time for a given command

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.   Filesystem timestamps will also be reported relative to this 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, or have a look at https://github.com/wolfcw/libfaketime

OPTIONS

       --help show usage information and quit.

       --version
              show version information and quit.

       -m     use the multi-threading variant of libfaketime.

       -p <PID>
              pretend that the program's process ID is PID. (only available if built with FAKE_PID)

       -f     use the advanced timestamp specification format.

       --exclude-monotonic
              Do not fake time when the program makes a call to clock_gettime with a CLOCK_MONOTONIC clock.

       --date-prog <PATH>
              Use  a  specific  GNU-date  compatible  implementation  of the helper used to transform "timestamp
              format" strings into programmatically usable dates, instead of a compile-time  default  guess  for
              the generic target platform.

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'
       faketime -f '+2,5y i2,0' /bin/bash -c 'while true; do date ; sleep 1 ; done'
       In this single case all spawned processes will use the same global clock without restarting it at the start of each process.

       (Please note that it depends on your locale settings whether . or , has to be used for fractional offsets)

ADVANCED TIMESTAMP FORMAT

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 libfaketime documentation. 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.  You can also
       make faketime to advance the reported time by a preset interval upon each time() call independently  from
       the system's time using "-7d i2,0", where "i" is followed by the increase interval in seconds.

       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.

       Faking  of  filesystem  timestamps  may be disabled by setting the NO_FAKE_STAT environment variable to a
       non-empty value.

AUTHOR

       Please see the README and NEWS files for contributors.

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.   Some  programs  may  dynamically  load
       system  libraries,  such as librt, at run-time and therefore bypass libfaketime.  You may report programs
       that do not work with libfaketime, but only if they are available as open source.

REPORTING BUGS

       Please use https://github.com/wolfcw/libfaketime/issues

COPYRIGHT

       Copyright © 2003-2021 by the libfaketime authors.

       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.