{"id":13420302,"url":"https://github.com/wolfcw/libfaketime","last_synced_at":"2025-05-13T18:14:32.654Z","repository":{"id":37753165,"uuid":"1657215","full_name":"wolfcw/libfaketime","owner":"wolfcw","description":"libfaketime modifies the system time for a single application","archived":false,"fork":false,"pushed_at":"2025-03-29T10:37:27.000Z","size":923,"stargazers_count":2849,"open_issues_count":55,"forks_count":344,"subscribers_count":62,"default_branch":"master","last_synced_at":"2025-04-25T17:58:02.203Z","etag":null,"topics":["datetime","hacktoberfest","intercept-calls","ld-preload","reproducible-builds","wrapper"],"latest_commit_sha":null,"homepage":"https://github.com/wolfcw/libfaketime","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wolfcw.png","metadata":{"files":{"readme":"README","changelog":"NEWS","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2011-04-24T17:46:57.000Z","updated_at":"2025-04-25T09:55:18.000Z","dependencies_parsed_at":"2025-02-25T21:01:36.089Z","dependency_job_id":"fa24ec41-048a-4321-94cb-1fb4d5ec586e","html_url":"https://github.com/wolfcw/libfaketime","commit_stats":{"total_commits":475,"total_committers":75,"mean_commits":6.333333333333333,"dds":0.8084210526315789,"last_synced_commit":"a04750217b8dc890ac584b92229d8c4a3f23c3e0"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wolfcw%2Flibfaketime","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wolfcw%2Flibfaketime/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wolfcw%2Flibfaketime/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wolfcw%2Flibfaketime/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wolfcw","download_url":"https://codeload.github.com/wolfcw/libfaketime/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254000885,"owners_count":21997443,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["datetime","hacktoberfest","intercept-calls","ld-preload","reproducible-builds","wrapper"],"created_at":"2024-07-30T22:01:30.813Z","updated_at":"2025-05-13T18:14:32.620Z","avatar_url":"https://github.com/wolfcw.png","language":"C","funding_links":[],"categories":["TODO scan for Android support in followings","C","CLI tools","Libraries"],"sub_categories":["Other CLI tools"],"readme":"libfaketime, version 0.9.10 (March 2022)\n========================================\n\n\nContent of this file:\n---------------------\n\n1. Introduction\n2. Compatibility issues\n3. Installation\n4. Usage\n   a) Basics\n   b) Using absolute dates\n   c) Using 'start at' dates\n   d) Using offsets for relative dates\n   e) Advanced features and caveats\n   f) Faking the date and time system-wide\n   g) Using the \"faketime\" wrapper script\n   h) \"Limiting\" libfaketime based on elapsed time or number of calls\n   i) \"Limiting\" libfaketime per process\n   j) Spawning an external process\n   k) Saving timestamps to file, loading them from file\n   l) Replacing random numbers with deterministic number sequences\n5. License\n6. Contact\n\n\n1. Introduction\n---------------\n\nlibfaketime intercepts various system calls that programs use to retrieve the\ncurrent date and time. It then reports modified (faked) dates and times (as\nspecified by you, the user) to these programs. This means you can modify the\nsystem time a program sees without having to change the time system-wide.\n\nlibfaketime allows you to specify both absolute dates (e.g., 01/01/2004) and\nrelative dates (e.g., 10 days ago).\n\nlibfaketime might be used for various purposes, for example\n\n- deterministic build processes\n- debugging time-related issues, such as expired SSL certificates\n- testing software for year-2038 compliance\n\nlibfaketime ships with a command line wrapper called \"faketime\" that makes it\neasier to use, but does not expose all of libfaketime's functionality. If your\nuse case is not covered by the faketime command, make sure to look in this\ndocumentation whether it can be achieved by using libfaketime directly.\n\n\n2. Compatibility issues\n-----------------------\n\n- libfaketime is supposed to work on Linux and macOS.\n  Your mileage may vary; some other *NIXes have been reported to work as well.\n\n- libfaketime uses the library preload mechanism of your operating system's\n  linker (which is involved in starting programs) and thus cannot work with\n  statically linked binaries or binaries that have the setuid-flag set (e.g.,\n  suidroot programs like \"ping\" or \"passwd\"). Please see you system linker's\n  manpage for further details.\n\n- libfaketime supports the pthreads environment. A separate library is built\n  (libfaketimeMT.so.1), which contains the pthread synchronization calls. This\n  library also single-threads calls through the time() intercept because\n  several variables are statically cached by the library and could cause issues\n  when accessed without synchronization.\n\n  However, the performance penalty for this might be an issue for some\n  applications. If this is the case, you can try using an unsynchronized time()\n  intercept by removing the -DPTHREAD_SINGLETHREADED_TIME from the Makefile and\n  rebuilding libfaketimeMT.so.1\n\n* Java-/JVM-based applications work but you need to pass in an extra argument\n  (FAKETIME_DONT_FAKE_MONOTONIC).  See usage basics below for details.  Without\n  this argument the java command usually hangs.\n\n* libfaketime will eventually be bypassed by applications that dynamically load\n  system libraries, such as librt, explicitly themselves instead of relying on\n  the linker to do so at application start time. libfaketime will not work with\n  those applications unless you can modify them.\n\n  This apparently happens a lot in complex run-time environments, e.g., for\n  programs written in golang, for some Java Virtual Machine implementations,\n  etc. Since libfaketime is effectively bypassed in such situations, there's\n  nothing we can do about it. Please consider asking the appropriate developers\n  and vendors to implement their runtime environment in a way that supports\n  intercepting selected system calls through LD_PRELOAD.\n\n* Applications can explicitly be designed to prevent libfaketime from working,\n  e.g., by checking whether certain environment variables are set or whether\n  libfaketime-specific files are present.\n\n* CLOCK_MONOTONIC test: Running \"make test\" performs a series of tests after\n  successful compilation of the libfaketime library. On some platforms, the\n  \"CLOCK_MONOTONIC test\" will apparently hang forever. If and only if this\n  happens on your platform, add the CFLAG -DFORCE_MONOTONIC_FIX to\n  src/Makefile and recompile libfaketime. Do not set FORCE_MONOTONIC_FIX on\n  platforms where the test does not hang.\n\n  If you observe hangs on the CLOCK_REALTIME test, add the CFLAG\n  -DFORCE_PTHREAD_NONVER. Also set this FORCE_PTHREAD_NONVER flag in case\n  FORCE_MONOTONIC_FIX alone does not solve the hang on the MONOTONIC_CLOCK\n  test.\n\n  If FORCE_MONOTONIC_FIX was not set as a compile-time flag, you can also\n  set an environment variable FAKETIME_FORCE_MONOTONIC_FIX=1 if you want\n  to enable the fix at run-time, or to 0 if you explicitly want to disable\n  it. The fix is automatically enabled if libfaketime was compiled on a\n  system with glibc as the underlying libc implementation, and a glibc\n  version is detected at run-time that is assumed to need this workaround.\n  Please use Github issues at https://github.com/wolfcw/libfaketime/issues\n  to report any observed hangs during CLOCK_MONOTONIC tests and report\n  your CPU architecture, libc implementation (e.g., glibc 2.30) and any\n  other details that might help (e.g., Linux distribution, use within, e.g.,\n  Docker containers etc.).\n\n  Please try to avoid compiling with FORCE_MONOTONIC_FIX on platforms that\n  do not need it. While it won't make a difference in most cases, depending\n  on the specific FAKETIME settings in use, it would cause certain\n  intercepted functions such as pthread_cond_timedwait() return with a\n  time-out too early or too late, which could break some applications.\n  Try compiling without FORCE_MONOTONIC_FIX first and check whether the\n  tests appear to hang. If they do, you can either set the\n  FAKETIME_FORCE_MONOTONIC_FIX environment variable to 1, or re-compile\n  with FORCE_MONOTONIC_FIX set.\n\n\n3. Installation\n---------------\n\nRunning \"make\" compiles both library versions and a test program, which it then\nalso executes.\n\nIf the test works fine, you should copy the libfaketime libraries\n(libfaketime.so.1, and libfaketimeMT.so.1) to the place you want them in.\nRunning \"make install\" will attempt to place them in /usr/local/lib/faketime\nand will install the wrapper shell script \"faketime\" in /usr/local/bin, both of\nwhich most likely will require root privileges. However, from a technical point\nof view, there is no necessity for a system-wide installation, so you can use\nlibfaketime also on machines where you do not have root privileges. You may\nwant to adjust the PREFIX variable in the Makefiles accordingly.\n\nBy default, the Makefile compiles/links libfaketime for your default system\narchitecture. If you need to build, e.g., 32-bit files on a 64-bit platform,\nplease see the notes about CFLAGS and LDFLAGS in src/Makefile.\n\nSince version 0.6, system calls to file timestamps are also intercepted,\nthanks to a contribution by Philipp Hachtmann. This is especially useful in\ncombination with relative time offsets as explained in section 4d) below, if a\nprogram writes and reads files whose timestamps also shall be faked. If you do\nnot need this feature or if it confuses the application you want to use FTPL\nwith, define the environment variable NO_FAKE_STAT, and the intercepted stat\ncalls will be passed through unaltered.\n\nOn macOS, it is necessary to compile differently, due to the different\nbehavior dyld has. Use the Makefile.OSX file provided to compile\nlibfaketime.1.dylib. Additionally, instead of using LD_PRELOAD,\nthe variable DYLD_INSERT_LIBRARIES should be set to the path to\nlibfaketime.1.dylib, and the variable DYLD_FORCE_FLAT_NAMESPACE should be\nset (to anything). macOS users should read README.OSX for additional\ndetails.\n\n\n4. Usage\n--------\n\n4a) Usage basics\n----------------\n\nUsing libfaketime on a program of your choice consists of two steps:\n\n1. Making sure libfaketime gets loaded by the system's linker.\n2. Specify the faked time.\n\nAs an example, we want the \"date\" command to report our faked time. To do so,\nwe could use the following command line on Linux:\n\nuser@host\u003e date\nTue Nov 23 12:01:05 CEST 2016\n\nuser@host\u003e LD_PRELOAD=/usr/local/lib/libfaketime.so.1 FAKETIME=\"-15d\" date\nMon Nov  8 12:01:12 CEST 2016\n\nuser@host\u003e LD_PRELOAD=/usr/local/lib/libfaketime.so.1 FAKETIME=\"-15d\"\nFAKETIME_DONT_FAKE_MONOTONIC=1 java -version\njava version \"1.8.0_111\"\nJava(TM) SE Runtime Environment (build 1.8.0_111-b14)\nJava HotSpot(TM) 64-Bit Server VM (build 25.111-b14, mixed mode)\n\nThe basic way of running any command/program with libfaketime enabled is to\nmake sure the environment variable LD_PRELOAD contains the path and\nfilename of the libfaketime library. This can either be done by setting it once\nbeforehand:\n\nexport LD_PRELOAD=/path/to/libfaketime.so.1\n(now run any command you want)\n\nOr it can be done by specifying it on the command line itself:\n\nLD_PRELOAD=/path/to/libfaketime.so.1 your_command_here\n\n(These examples are for the bash shell; how environment variables are set may\nvary on your system.)\n\nOn Linux, library search paths can be set as part of the linker configuration.\nLD_PRELOAD then also works with relative paths. For example, when libfaketime.so.1\nis installed as /path/to/libfaketime.so.1, you can add /path/to to an appropriate\nlinker configuration file, e.g., /etc/ld.so.conf.d/local.conf, and then run\nthe \"ldconfig\" command. Afterwards, using LD_PRELOAD=libfaketime.so.1 suffices.\n\nHowever, also the faked time should be specified; otherwise, libfaketime will\nbe loaded, but just report the real system time. There are multiple ways to\nspecify the faked time:\n\na) By setting the environment variable FAKETIME.\nb) By using the file given in the environment variable FAKETIME_TIMESTAMP_FILE\nc) By using the file .faketimerc in your home directory.\nd) By using the file /etc/faketimerc for a system-wide default.\ne) By using FAKETIME_UPDATE_TIMESTAMP_FILE and date -s \"\u003ctime\u003e\" or alike.\n\nIf you want to use b) c) or d), $HOME/.faketimerc or /etc/faketimerc consist of\nonly one line of text with exactly the same content as the FAKETIME environment\nvariable, which is described below. Note that /etc/faketimerc will only be used\nif there is no $HOME/.faketimerc and no FAKETIME_TIMESTAMP_FILE file exists.\nAlso, the FAKETIME environment variable _always_ has priority over the files.\nFor FAKETIME_UPDATE_TIMESTAMP_FILE please see below.\n\n\n4b) Using absolute dates\n------------------------\n\nThe format that _must_ be used for _absolute_ dates is \"YYYY-MM-DD hh:mm:ss\".\nFor example, the 24th of December, 2020, 8:30 PM would have to be specified as\nFAKETIME=\"2020-12-24 20:30:00\".\n\n\n4c) Using 'start at' dates\n--------------------------\n\n(Thanks to a major contribution by David North, TDI in version 0.7)\n\nThe format that _must_ be used for _start_at_ dates is \"@YYYY-MM-DD hh:mm:ss\".\nFor example, the 24th of December, 2020, 8:30 PM would have to be specified as\nFAKETIME=\"@2020-12-24 20:30:00\".\n\nThe absolute dates described in 4b) simulate a STOPPED system clock at the\nspecified absolute time. The 'start at' format allows a 'relative' clock\noperation as described below in section 4d), but using a 'start at' time\ninstead of an offset time.\n\nIf the started process itself starts other (child) processes, they by default\nwill start with the specified start-at-date again. If this is not what you need,\nset the environment variable FAKETIME_DONT_RESET=1. Try these examples to see\nthe difference:\n\nLD_PRELOAD=src/libfaketime.so.1 FAKETIME=\"@2000-01-01 11:12:13\" \\\n  FAKETIME_DONT_RESET=1 \\\n  /bin/bash -c 'while [ $SECONDS -lt 5 ]; do date; sleep 1; done'\n\nLD_PRELOAD=src/libfaketime.so.1 FAKETIME=\"@2000-01-01 11:12:13\" \\\n  /bin/bash -c 'while [ $SECONDS -lt 5 ]; do date; sleep 1; done'\n\nIn the second example, the \"date\" command will always print the same time,\nwhile in the first example, with FAKETIME_DONT_RESET set, time will increment\neven though all the \"date\" commands are new processes.\n\n\n4d) Using offsets for relative dates\n------------------------------------\n\nRelative date offsets can be positive or negative, thus what you put into\nFAKETIME _must_ either start with a + or a -, followed by a number, and\noptionally followed by a multiplier:\n\n- By default, the offset you specify is in seconds. Example:\n\n  export FAKETIME=\"-120\" will set the faked time 2 minutes (120 seconds) behind\n  the real time.\n\n- The multipliers \"m\", \"h\", \"d\" and \"y\" can be used to specify the offset in\n  minutes, hours, days and years (365 days each), respectively. Examples:\n\n  export FAKETIME=\"-10m\" sets the faked time 10 minutes behind the real time.\n  export FAKETIME=\"+14d\" sets the faked time to 14 days in the future.\n\n  Please note that if you need other multipliers (weeks, months etc.) or higher\n  precision (e.g., correct leap year handling), you should use either the\n  faketime wrapper or the GNU date command as shown in the first of the three\n  examples below.\n\nYou now should understand the complete example we've used before:\n\nLD_PRELOAD=/usr/local/lib/libfaketime.so.1 FAKETIME=\"-15d\" date\n\nThis command line makes sure libfaketime gets loaded and sets the faked time to\n15 days in the past.\n\nMoreno Baricevic has contributed support for the FAKETIME_FMT environment\nvariable, which allows you to optionally set the strptime() format:\n\nSome simple examples:\nLD_PRELOAD=./libfaketime.so.1 FAKETIME_FMT=%s FAKETIME=\"`date +%s -d'1 year ago'`\" date\nLD_PRELOAD=./libfaketime.so.1 FAKETIME_FMT=%s FAKETIME=\"`stat -c %Y somefile`\" date\nLD_PRELOAD=./libfaketime.so.1 FAKETIME_FMT=%c FAKETIME=\"`date`\" date\n\n\n4e) Advanced features and caveats\n---------------------------------\n\nAdvanced time specification options:\n------------------------------------\n\nSince version 0.8, thanks to a contribution by Karl Chen, fractions can be used\nin the specification of time offsets. For example,\n\nFAKETIME=\"+1,5h\"\n\nis equivalent to FAKETIME=\"+90m\". Please be aware that the fraction delimiter\ndepends on your locale settings, so actually you might need to use\n\nFAKETIME=\"+1.5h\"\n\nYou should figure out the proper delimiter, e.g., by using libfaketime on\na command like /bin/date where you immediately can verify whether it worked as\nexpected.\n\nAlso contributed by Karl Chen in v0.8 is the option to speed up or slow\ndown the wall clock time for the program which is executed using libfaketime.\nFor example,\n\nFAKETIME=\"+1y x2\"\n\nwill set the faked time one year into the future and will make the clock run\ntwice as fast. Similarly,\n\nFAKETIME=\"+1y x0,5\"\n\nwill make the clock run only half as fast. As stated above, the fraction\ndelimiter depends on your locale. Furthermore,\n\nFAKETIME=\"+1y i2,0\"\n\nwill make the clock step two seconds per each time(), etc. call, being\ncompletely independently of the system clock. It helps running programs\nwith some determinism. In this single case all spawned processes will use\nthe same global clock without restarting it at the start of each process.\n\nPlease note that using \"x\" or \"i\" in FAKETIME still requires giving an offset\n(see section 4d). This means that \"+1y x2\" will work, but \"x2\" only will not.\nIf you do not want to fake the time, but just modify clock speed, use something\nlike \"+0 x2\", i.e., use an explicit zero offset as a prefix in your FAKETIME.\n\nFor testing, your should run a command like\n\nLD_PRELOAD=./libfaketime.so.1 FAKETIME=\"+1,5y x10,0\" \\\n/bin/bash -c 'while true; do echo $SECONDS ; sleep 1 ; done'\n\nFor each second that the endless loop sleeps, the executed bash shell will\nthink that 10 seconds have passed ($SECONDS is a bash-internal variable\nmeasuring the time since the shell was started).\n\n(Please note that replacing \"echo $SECONDS\" e.g. with a call to \"/bin/date\"\nwill not give the expected result, since /bin/date will always be started as a\nnew process for which also libfaketime will be re-initialized. It will show the\ncorrect offset (1.5 years in the future), but no speed-ups or slow-downs.)\n\nFor applications that should use a different date \u0026 time each time they are\nrun, consider using the included timeprivacy wrapper shellscript (contributed\nby adrelanos at riseup dot net).\n\n\nCaveats:\n--------\n\nWhenever possible, you should use relative offsets or 'start at' dates,\nand not use absolute dates.\n\nWhy? Because the absolute date/time you set is fixed, i.e., if a program\nretrieves the current time, and retrieves the current time again 5 minutes\nlater, it will still get the same result twice. This is likely to break\nprograms which measure the time passing by (e.g., a mail program which checks\nfor new mail every X minutes).\n\nUsing relative offsets or 'start at' dates solves this problem.\nlibfaketime then will always report the faked time based on the real\ncurrent time and the offset you've specified.\n\nPlease also note that your default specification of the fake time is cached for\n10 seconds in order to enhance the library's performance. Thus, if you change the\ncontent of $HOME/.faketimerc or /etc/faketimerc while a program is running, it\nmay take up to 10 seconds before the new fake time is applied. If this is a\nproblem in your scenario, you can change number of seconds before the file is read\nagain with environment variable FAKETIME_CACHE_DURATION, or disable caching at all\nwith FAKETIME_NO_CACHE=1. Remember that disabling the cache may negatively\ninfluence the performance (especially when not using FAKETIME environment\nbut configuration files, such as FAKETIME_TIMESTAMP_FILE).\n\n\nSetting FAKETIME by means of a file timestamp\n---------------------------------------------\n\nBased on a proposal by Hitoshi Harada (umitanuki), the \"start at\" time can now be\nset through any file in the file system by setting the FAKETIME environment variable\nto \"%\" (a percent sign) and FAKETIME_FOLLOW_FILE to the name of the file whose\nmodification timestamp shall be used as source for the \"start at\" time.\n\nUsage example:\n\n# create any file with December 24th, 2009, 12:34:56 as timestamp\ntouch -t 0912241234.56 /tmp/my-demo-file.tmp\n\n# run a bash shell with an endless loop printing the current time\nLD_PRELOAD=/path/to/libfaketime.so.1 \\\n  FAKETIME='%' FAKETIME_FOLLOW_FILE=/tmp/my-demo-file.tmp \\\n  FAKETIME_DONT_RESET=1 \\\n  bash -c 'while true ; do date ; sleep 1 ; done'\n\n# now, while the above is running, change the file's timestamp\n# (in a different terminal window or whatever)\ntouch -t 2002290123.45 /tmp/my-demo-file.tmp\n\n\nChanging the 'x' modifier during run-time\n-----------------------------------------\n\nUsing FAKETIME_TIMESTAMP_FILE allows for easily changing the FAKETIME setting\nwhile a program is running:\n\necho \"+0 x1\" \u003e /tmp/my-faketime.rc\nLD_PRELOAD=libfaketime.so.1 FAKETIME_TIMESTAMP_FILE=\"/tmp/my-faketime.rc\" \\\n  FAKETIME_NO_CACHE=1 ./some-program \u0026\nsleep 10 ; echo \"+0 x10\" \u003e /tmp/my-faketime.rc\n\nChanging the speed of the wall clock time, i.e., using a different 'x' modifier\nduring run-time, by default can lead to greater jumps that may confuse the\nprogram. For example, if the program has been running for 10 seconds on 'x1',\nand then the setting is changed to 'x10', the faked time will look to the\nprogram as if it has been running for more than 100 instead of just more than\n10 seconds.\n\nBy setting the environment variable FAKETIME_XRESET to any value, transitions\nbetween different 'x' modifier values will be significantly smoothed:\n\nLD_PRELOAD=libfaketime.so.1 FAKETIME_TIMESTAMP_FILE=\"/tmp/my-faketime.rc\" \\\n  FAKETIME_NO_CACHE=1 FAKETIME_XRESET=1 ./some-program \u0026\n\nSetting FAKETIME_XRESET ensures that wall clock time begins to run faster\nonly after the 'x' modifier has been changed (when increasing it) and also\nensures that the reported faked time does not jump back to past values\n(when decreasing it).\n\nPlease note that FAKETIME_XRESET internally works by resetting libfaketime's\ninternal time-keeping data structures, which may have side effects on reported\nfile timestamps. Using FAKETIME_XRESET should be considered experimental at\nthe moment.\n\n\nCleaning up shared memory\n-------------------------\n\nlibfaketime uses semaphores and shared memory on platforms that support it in\norder to sync faketime settings across parent-child processes.\n\nPlease note that this does not share the time set by settimeofday (for that\nsee FAKETIME_UPDATE_TIMESTAMP_FILE below).\n\nlibfaketime will clean up when it exits properly.\nHowever, when processes are terminated (e.g., by Ctrl-C on command line),\nshared memory cannot be cleaned up properly. In such\ncases, you should occasionally delete\n\n  /dev/shm/faketime_shm_* and\n  /dev/shm/sem.faketime_sem_*\n\nmanually (or properly automated). Leftover files there from processes that\nalready have been terminated are not a problem in general, but result in a\nlibfaketime error the next time a process is started with a process id for\nwhich such a stale semaphore/shared memory exists. Thus, if you run across\nthe following error message\n\n  libfaketime: In ft_shm_create(), shm_open failed: File exists\n\nplease cleanup /dev/shm as described above. This is especially relevant\nfor long-running systems (servers with high uptime) and systems on which\na lot of processes are started (e.g., servers handling many containers\nor similar virtualization mechanisms).\n\nUse of shared memory can be disabled by setting the FAKETIME_DISABLE_SHM\nenvironment variable, or equivalently, passing --disable-shm to faketime.\n\n\nIntercepting time-setting calls\n-------------------------------\n\nlibfaketime can be compiled with the CFLAG \"-DFAKE_SETTIME\" in order\nto also intercept time-setting functions, i.e., clock_settime(),\nsettimeofday(), and adjtime(). The FAKETIME environment\nvariable will be adjusted on each call.\n\nWhen the environment variable FAKETIME_TIMESTAMP_FILE is set, points to a\nwriteable (creatable) custom config file and the environment variable\nFAKETIME_UPDATE_TIMESTAMP_FILE is \"1\", then the file also is updated on each\ncall. By this, a common \"virtual time\" can be shared by several\nprocesses, where each can adjust the time for all.\n\n\nSharing \"virtual settable time\" between independent processes\n-------------------------------------------------------------\n\nWhen libfaketime was compiled with FAKETIME_COMPILE_CFLAGS=\"-DFAKE_SETTIME\",\nit can be configured to support a common time offset for multiple processes.\nThis for example allows to use \"ntpdate\" as normal user without affecting\nsystem clock, interactively testing software with different dates or testing\ncomplex software with multiple independent processes that themself use\nsettime internally.\n\nExamples:\n\n  $ export LD_PRELOAD=libfaketime.so.1\n  $ export FAKETIME_TIMESTAMP_FILE=\"/tmp/my-faketime.rc\"\n  $ export FAKETIME_UPDATE_TIMESTAMP_FILE=1\n  $ export FAKETIME_CACHE_DURATION=1 # in seconds\n  # or: export FAKETIME_NO_CACHE=1\n\n  $ date -s \"1999-12-24 16:00:00\"\n  Fri Dec 24 16:00:00 CET 1999\n  $ LD_PRELOAD=\"\" date\n  Thu Apr  9 15:19:38 CEST 2020\n  $ date\n  Fri Dec 24 16:00:02 CET 1999\n  $ /usr/sbin/ntpdate -u clock.isc.org\n   9 Apr 15:18:37 ntpdate[718]: step time server xx offset 640390517.057257 sec\n  $ date\n  Thu Apr  9 15:18:40 CEST 2020\n\nIn another terminal, script or environmment the same variables could be set\nand the same time would be printed.\nThis also avoid the need to directly update the rc config file to use\ndifferent times, but of course only supports time offsets.\n\nPlease note that this feature is not compatible with several other features,\nsuch as FAKETIME_FOLLOW_FILE, FAKETIME_XRESET and maybe others. After first\nsettime, offsets will be used in FAKETIME_TIMESTAMP_FILE, even if it\ninitially used advanced time specification options.\n\n\n4f) Faking the date and time system-wide\n----------------------------------------\n\nDavid Burley of SourceForge, Inc. reported an interesting use case of applying\nlibfaketime system-wide: Currently, all virtual machines running inside\nan OpenVZ host have the same system date and time. In order to use multiple\nsandboxes with different system dates, the libfaketime library can be put into\n/etc/ld.so.preload; it will then be applied to all commands and programs\nautomatically. This is of course best used with a system-wide /etc/faketimerc\nfile. Kudos to SourceForge, Inc. for providing the patch!\n\nCaveat: If you run a virtual machine, its real-time clock might be reset to the\nreal world date \u0026 time when you reboot. Depending on your FAKETIME setting,\nthis may lead to side effects, such as forced file system checks on each reboot.\nSystem-wide faked time may also lead to unexpected side effects with software\nauto-update tools, if the offset between real world time and faked system time\nis too large. If in doubt, set your system's date to the faked time and try out\nwhether everything still works as expected before applying libfaketime\nsystem-wide.\n\n\n4g) Using the \"faketime\" wrapper\n--------------------------------\n\nAs of version 0.8, libfaketime provides a command named \"faketime\", which is\nplaced into /usr/bin by \"make install\". It spares the hassle of setting\nthe LD_PRELOAD and FAKETIME environment variables manually, but only exposes\na subset of libfaketime's functionality. On the other hand, it uses the date\ninterpretation function by /bin/date in order to provide higher flexibility\nregarding the specification of the faked date and time. For example, you\ncan use\n\nfaketime 'last Friday 5 pm' /your/command/here\n\nOf course, also absolute dates can be used, such as in\n\nfaketime '2018-12-24 08:15:42' /bin/date\n\nThanks to Daniel Kahn Gillmor for providing these suggestions!\n\nBalint Reczey has rewritten the wrapper in 0.9.5 from a simple shell script\nto an efficient wrapper application.\n\n\n4h) \"Limiting\" libfaketime based on elapsed time or number of calls\n-------------------------------------------------------------------\n\nStarting with version 0.9, libfaketime can be configured to not be continuously\nactive, but only during a certain time interval.\n\nFor example, you might want to start a program with the real current time, but\nafter 5 minutes of usage, you might want it to see a faked time, e.g., a year\nin the future.\n\nDynamic changes to the faked time are alternatively possible by\n\n- changing the FAKETIME environment variable at run-time; this is the preferred\n  way if you use libfaketime for debugging and testing as a programmer, as it\n  gives you the most direct control of libfaketime without any performance\n  penalties.\n\n- not using the FAKETIME environment variable, but specifying the fake time in\n  a file (such as ~/.faketimerc). You can change the content of this file at\n  run-time. This works best with caching disabled, but comes at a performance\n  cost because this file has to be read and evaluated each time.\n\nThe feature described here works based on two pairs of environment variables,\n\n  FAKETIME_START_AFTER_SECONDS and FAKETIME_STOP_AFTER_SECONDS, and\n  FAKETIME_START_AFTER_NUMCALLS and FAKETIME_STOP_AFTER_NUMCALLS\n\nThe default value for each of these environment variables is -1, which means\n\"ignore this value\".\n\nIf you want libfaketime to be only active during the run-time minutes 2 to 5\nof your application, you would set\n\n  FAKETIME_START_AFTER_SECONDS=60\n  FAKETIME_STOP_AFTER_SECONDS=300\n\nThis means that your application will work with the real time from start (second\n0) up to second 60. It will then see a faked time from run-time seconds 60 to\n300 (minutes 2, 3, 4, and 5). After run-time second 600, it will again see the\nreal (not-faked) time.\n\nThis approach is not as flexible as changing the FAKETIME environment variable\nduring runtime, but may be easier to use, works on a per-program (and not a\nper-user or system-wide) scope, and has only a minor performance overhead.\n\nUsing the other pair of environment variables, you can limit the activity time\nof libfaketime not based on wall-clock seconds, but on the number of\ntime-related function calls the started program performs. This alternative is\nprobably only suitable for programmers who either know the code of the program\nin order to determine useful start/stop values or want to perform fuzzing\ntests.\n\nBoth pairs of environment variables can be combined to further restrict\nlibfaketime activity, although this is only useful in very few scenarios.\n\nLimiting libfaketime activity in this way is not recommended in general. Many\nprograms will break when they are subject to sudden changes in time, especially\nif they are started using the current (real) time and are then sent back into\nthe past after, e.g., 5 minutes. For example, they may appear to be frozen or\nstuck because they are waiting until a certain point in time that, however, is\nnever reached due to the delayed libfaketime activity. Avoid using this\nfunctionality unless you are sure you really need it and know what you are\ndoing.\n\n\n4i) \"Limiting\" libfaketime per process\n--------------------------------------\n\nfaketime can be instructed to fake time related calls only for selected\ncommands or to fake time for each command except for a certain subset of\ncommands.\n\nThe environment variables are FAKETIME_ONLY_CMDS and FAKETIME_SKIP_CMDS\nrespectively.\n\nExample:\n    FAKETIME_ONLY_CMDS=javadoc faketime '2008-12-24 08:15:42' make\nwill run the \"make\" command but the time faking will only be applied\nto javadoc processes.\n\nMultiple commands are separated by commas.\n\nExample:\n    FAKETIME_SKIP_CMDS=\"javadoc,ctags\" faketime '2008-12-24 08:15:42' make\nwill run the \"make\" command and apply time faking for everything \"make\"\ndoes except for javadoc and ctags processes.\n\nFAKETIME_ONLY_CMDS and FAKETIME_SKIP_CMDS are mutually exclusive, i.e.,\nyou cannot set them both at the same time. faketime will terminate with\nan error message if both environment variables are set.\n\n\n4j) Spawning an external process\n--------------------------------\n\nFrom version 0.9 on, libfaketime can execute a shell command once after a) an\narbitrary number of seconds has passed or b) a number of time-related system\ncalls has been made by the program since it started. This has two limitations\none needs to be aware of:\n\n* Spawning the external process happens during a time-related system call\n  of the original program. If you want the external process to be started\n  5 seconds after program start, but this program does not make any time-\n  related system calls before run-time second 8, the start of your external\n  process will be delayed until run-time second 8.\n\n* The original program is blocked until the external process is finished,\n  because the intercepting time-related system call will not return earlier. If\n  you need to start a long-running external process, make sure it forks into the\n  background.\n\nSpawning the external process is controlled using three environment variables:\nFAKETIME_SPAWN_TARGET, FAKETIME_SPAWN_SECONDS, FAKETIME_SPAWN_NUMCALLS.\n\nExample (using bash on Linux):\n\n(... usual libfaketime setup here, setting LD_PRELOAD and FAKETIME ...)\nexport FAKETIME_SPAWN_TARGET=\"/bin/echo 'Hello world'\"\nexport FAKETIME_SPAWN_SECONDS=5\n/opt/local/bin/myprogram\n\nThis will run the \"echo\" command with the given parameter during the first\ntime-related system function call that \"myprogram\" performs after running for 5\nseconds.\n\n\n4k) Saving timestamps to file, loading them from file\n-----------------------------------------------------\n\nTo store and load timestamp _offsets_ using _one and the same_ file allowing\nto share a common \"virtual time\" between independent processes, please see\nFAKETIME_UPDATE_TIMESTAMP_FILE above. The FAKETIME_SAVE_FILE feature is\ndifferent.\n\nfaketime can save faked timestamps to a file specified by FAKETIME_SAVE_FILE\nenvironment variable. It can also use the file specified by FAKETIME_LOAD_FILE\nto replay timestamps from it. After consuming the whole file, libfaketime\nreturns to using the rule set in FAKETIME variable, but the timestamp processes\nwill start counting from will be the last timestamp in the file.\n\nThe file stores each timestamp in a stream of saved_timestamp structs\nwithout any metadata or padding:\n\n/* Storage format for timestamps written to file. Big endian. */\nstruct saved_timestamp {\n  int64_t sec;\n  uint64_t nsec;\n};\n\nfaketime needs to be run using the faketime wrapper to use these files. This\nfunctionality has been added by Balint Reczey in v0.9.5.\n\n\n4l) Replacing random numbers with deterministic number sequences\n----------------------------------------------------------------\n\nlibfaketime can be compiled with the CFLAG FAKE_RANDOM set (see src/Makefile).\n\nWhen compiled this way, libfaketime additionally intercepts calls to the\nfunction getrandom(), which currently is Linux-specific.\n\nThis functionality is intended to feed a sequence of deterministic, repeatable\nnumbers to applications, which use getrandom(), instead of the random numbers\nprovided by /dev/[u]random.\n\nFor creating the deterministic number sequence, libfaketime internally\nuses Bernard Widynski's Middle Square Weyl Sequence Random Number Generator,\nsee https://mswsrng.wixsite.com/rand.\n\nIt requires a 64-bit seed value, which has to be passed via the environment\nvariable FAKERANDOM_SEED, as in, for example\n\n  LD_PRELOAD=src/libfaketime.so.1 \\\n  FAKERANDOM_SEED=\"0x12345678DEADBEEF\" \\\n  test/getrandom_test\n\nWhenever the same seed value is used, the same sequence of \"random-looking\"\nnumbers is generated.\n\nPlease be aware that this definitely breaks any security properties that\nmay be attributed to random numbers delivered by getrandom(), e.g., in the\ncontext of cryptographic operations. Use it for deterministic testing\npurposes only. Never use it in production.\n\nFor a discussion on why this apparently not date-/time-related function\nhas been added to libfaketime and how it may evolve, see Github issue #275.\n\n\n5. License\n----------\n\nlibfaketime has been released under the GNU General Public License, GPL.\nPlease see the included COPYING file.\n\n\n6. Contact\n-----------\n\nBug reports, feature suggestions, success reports, and patches/pull\nrequests are highly appreciated:\n\n            https://github.com/wolfcw/libfaketime\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwolfcw%2Flibfaketime","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwolfcw%2Flibfaketime","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwolfcw%2Flibfaketime/lists"}