1FAKETIME(1) wolfcw FAKETIME(1)
2
6 faketime - manipulate the system time for a given command
7
9 faketime [options] timestamp program [arguments...]
10
12 The given command will be tricked into believing that the current sys‐
13 tem time is the one specified in the timestamp. Filesystem timestamps
14 will also be reported relative to this timestamp. The wall clock will
15 continue to run from this date and time unless specified otherwise (see
16 advanced options). Actually, faketime is a simple wrapper for libfake‐
17 time, which uses the LD_PRELOAD mechanism to load a small library which
18 intercepts system calls to functions such as time(2) and fstat(2).
19 This wrapper exposes only a subset of libfaketime's functionality;
20 please refer to the README file that came with faketime for more de‐
21 tails and advanced options, or have a look at
22 https://github.com/wolfcw/libfaketime
23
25 --help show usage information and quit.
26 --version
28 show version information and quit.
29 -m use the multi-threading variant of libfaketime.
31 -p <PID>
33 pretend that the program's process ID is PID. (only available if
34 built with FAKE_PID)
35 -f use the advanced timestamp specification format.
37 --exclude-monotonic
39 Do not fake time when the program makes a call to clock_gettime
40 with a CLOCK_MONOTONIC clock.
41 --date-prog <PATH>
43 Use a specific GNU-date compatible implementation of the helper
44 used to transform "timestamp format" strings into programmati‐
45 cally usable dates, instead of a compile-time default guess for
46 the generic target platform.
47
50 faketime 'last Friday 5 pm' /bin/date
51 faketime '2008-12-24 08:15:42' /bin/date
52 faketime -f '+2,5y x10,0' /bin/bash -c 'date; while true; do echo $SECONDS ; sleep 1 ; done'
53 faketime -f '+2,5y x0,50' /bin/bash -c 'date; while true; do echo $SECONDS ; sleep 1 ; done'
54 faketime -f '+2,5y i2,0' /bin/bash -c 'while true; do date ; sleep 1 ; done'
55 In this single case all spawned processes will use the same global clock without restarting it at the start of each process.
56 (Please note that it depends on your locale settings whether . or , has to be used for fractional offsets)
58
60 The simple timestamp format used by default applies the /bin/date -d
61 command to parse user-friendly specifications such as 'last friday'.
62 When using the faketime option -f, the timestamp specified on the com‐
63 mand line is directly passed to libfaketime, which enables a couple of
64 additional features such as speeding the clock up or slowing it down
65 for the target program. It is strongly recommended that you have a
66 look at the libfaketime documentation. Summary:
67 Freeze clock at absolute timestamp: "YYYY-MM-DD hh:mm:ss"
69 If you want to specify an absolute point in time, exactly this
70 format must be used. Please note that freezing the clock is
71 usually not what you want and may break the application. Only
72 use if you know what you're doing!
73 Relative time offset: "[+/-]123[m/h/d/y]", e.g., "+60m", "+2y"
75 This is the most often used format and specifies the faked time
76 relatively to the current real time. The first character of the
77 format string must be a + or a -. The numeric value by default
78 represents seconds, but the modifiers m, h, d, and y can be used
79 to specify minutes, hours, days, or years, respectively. For
80 example, "-2y" means "two years ago". Fractional time offsets
81 can be used, e.g., "+2,5y", which means "two and a half years in
82 the future". Please note that the fraction delimiter depends on
83 your locale settings, so if "+2,5y" does not work, you might
84 want to try "+2.5y".
85 Start-at timestamps: "@YYYY-MM-DD hh:mm:ss"
87 The wall clock will start counting at the given timestamp for
88 the program. This can be used for specifying absolute time‐
89 stamps without freezing the clock.
90
92 When using relative time offsets or start-at timestamps (see ADVANCED
93 TIMESTAMP FORMAT above and option -f), the clock speed can be adjusted,
94 i.e., time may run faster or slower for the executed program. For ex‐
95 ample, "+5y x10" will set the faked time 5 years into the future and
96 make the time pass 10 times as fast (one real second equals 10 seconds
97 measured by the program). Similarly, the flow of time can be slowed,
98 e.g., using "-7d x0,2", which will set the faked time 7 days in the
99 past and set the clock speed to 20 percent, i.e., it takes five real
100 world seconds for one second measured by the program. Again, depending
101 on your locale, either "x2.0" or "x2,0" may be required regarding the
102 delimiter. You can also make faketime to advance the reported time by
103 a preset interval upon each time() call independently from the system's
104 time using "-7d i2,0", where "i" is followed by the increase interval
105 in seconds.
106 Faking times for multiple programs or even system-wide can be simpli‐
108 fied by using ~/.faketimerc files and /etc/faketimerc. Please refer to
109 the README that came with faketime for warnings and details.
110 Faking of filesystem timestamps may be disabled by setting the
112 NO_FAKE_STAT environment variable to a non-empty value.
113
115 Please see the README and NEWS files for contributors.
116
118 Due to limitations of the LD_PRELOAD mechanism, faketime will not work
119 with suidroot and statically linked programs. While timestamps and
120 time offsets will work for child processes, speeding the clock up or
121 slowing it down might not work for child processes spawned by the exe‐
122 cuted program as expected; a new instance of libfaketime is used for
123 each child process, which means that the libfaketime start time, which
124 is used in speed adjustments, will also be re-initialized. Some pro‐
125 grams may dynamically load system libraries, such as librt, at run-time
126 and therefore bypass libfaketime. You may report programs that do not
127 work with libfaketime, but only if they are available as open source.
128
130 Please use https://github.com/wolfcw/libfaketime/issues
131
133 Copyright © 2003-2021 by the libfaketime authors.
134 There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
136 PARTICULAR PURPOSE. You may redistribute copies of faketime under the
137 terms of the GNU General Public License.
138 For more information about these matters, see the file named COPYING.
139
141 ld.so(1), time(2), fstat(2)
142faketime 0.9.10 March 2022 FAKETIME(1)