libfaketime

https://github.com/wolfcw/libfaketime
Admin
libfaketime is a tool that intercepts system calls to fake date and time for programs without...
Tokens:33,700
Snippets:431
Trust Score:7.6
License:GPL-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install libfaketime from Source

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/README.md

Build and install the library directly from the source repository.

```bash
cd libfaketime
make
sudo make install
```

--------------------------------

### Install libfaketime via Package Manager

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/README.md

Install pre-compiled packages for common operating systems.

```bash
# Ubuntu/Debian
sudo apt-get install faketime libfaketime

# Fedora/RHEL
sudo dnf install libfaketime

# macOS
brew install libfaketime
```

--------------------------------

### Troubleshoot missing library errors

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/faketime-wrapper.md

Installs the library or uses the --date-prog flag for debugging.

```bash
# Install faketime
sudo apt-get install libfaketime

# Or use --date-prog to debug
faketime --date-prog /usr/bin/date '2020-01-01' date
```

--------------------------------

### Troubleshoot command not found

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/faketime-wrapper.md

Verifies installation or uses the full path to the faketime binary.

```bash
# Check installation
which faketime
# If not found, install: sudo apt-get install faketime

# Or use full path
/usr/local/bin/faketime '2020-01-01' date
```

--------------------------------

### Check wrapper version

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/faketime-wrapper.md

Verify the installed version of the faketime wrapper.

```bash
faketime --version
# Output: faketime (libfaketime) 0.9.12
```

--------------------------------

### Using clock_gettime with libfaketime

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/system-time-functions.md

Example demonstrating how to retrieve faked REALTIME and MONOTONIC clock values using libfaketime.

```c
#include <time.h>
#include <stdio.h>

// With environment: LD_PRELOAD=libfaketime.so.1 FAKETIME="@2000-01-01 12:00:00"
int main() {
  struct timespec ts;
  clock_gettime(CLOCK_REALTIME, &ts);
  printf("Faked REALTIME: %ld.%09ld\n", ts.tv_sec, ts.tv_nsec);
  
  clock_gettime(CLOCK_MONOTONIC, &ts);
  printf("Faked MONOTONIC: %ld.%09ld\n", ts.tv_sec, ts.tv_nsec);
  
  return 0;
}
```

--------------------------------

### statx usage example

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/file-timestamp-functions.md

Demonstrates retrieving faked timestamps using statx on Linux 4.11+.

```c
#include <sys/stat.h>
#include <stdio.h>

// Linux 4.11+ with environment: LD_PRELOAD=libfaketime.so.1 FAKETIME="@2020-01-01 00:00:00"
int main() {
  struct statx stx;
  
  statx(AT_FDCWD, "/tmp/testfile", 0,
        STATX_ALL, &stx);
  
  printf("Modified: %ld.%09ld\n",
         stx.stx_mtime.tv_sec,
         stx.stx_mtime.tv_nsec);
  
  return 0;
}
```

--------------------------------

### Verify libfaketime Installation

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/README.md

Set the LD_PRELOAD environment variable and test the time manipulation with the date command.

```bash
export LD_PRELOAD=$(which faketime)/../lib/libfaketime.so.1
faketime '2020-01-01' date
```

--------------------------------

### nanosleep C Example

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/sleep-and-delay-functions.md

Demonstrates sleeping for a specific duration using nanosleep, including handling for interruptions.

```c
#include <time.h>
#include <stdio.h>

// With environment: LD_PRELOAD=libfaketime.so.1 FAKETIME="@2000-01-01 12:00:00"
int main() {
  struct timespec req, rem;
  req.tv_sec = 10;
  req.tv_nsec = 500000000;  // 10.5 seconds
  
  while (nanosleep(&req, &rem) == -1) {
    printf("Interrupted, %ld.%09ld seconds remaining\n",
           rem.tv_sec, rem.tv_nsec);
    req = rem;
  }
  
  printf("Sleep complete\n");
  return 0;
}
```

--------------------------------

### timerfd_gettime Usage Example

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/timer-functions.md

Demonstrates creating a timerfd and retrieving its current value using the faked time implementation.

```c
#include <sys/timerfd.h>
#include <stdio.h>

int main() {
  int fd = timerfd_create(CLOCK_REALTIME, 0);
  
  struct itimerspec spec;
  timerfd_gettime(fd, &spec);
  
  printf("Remaining: %ld.%09ld\n",
         spec.it_value.tv_sec,
         spec.it_value.tv_nsec);
  
  close(fd);
  return 0;
}
```

--------------------------------

### Retrieve libfaketime version

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/README.md

Command to check the installed version of libfaketime.

```bash
cat /usr/local/lib/faketime/README | head -1
```

--------------------------------

### Example Usage of stat() with Libfaketime

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/file-timestamp-functions.md

Demonstrates retrieving a file's modification time while Libfaketime is active via LD_PRELOAD.

```c
#include <sys/stat.h>
#include <stdio.h>
#include <time.h>

// With environment: LD_PRELOAD=libfaketime.so.1 FAKETIME="+1d"
int main() {
  struct stat sb;
  stat("/etc/passwd", &sb);
  
  // Modification time will appear to be 1 day in the future
  printf("File mtime: %s", ctime(&sb.st_mtime));
  printf("Real mtime would be earlier\n");
  
  return 0;
}
```

--------------------------------

### Valid FAKETIME formats

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/errors.md

Examples of supported syntax for the FAKETIME environment variable.

```bash
FAKETIME="2020-12-24 20:30:00"        # Absolute
FAKETIME="@2000-01-01 12:00:00"       # Start-at
FAKETIME="+1d"                        # Offset
FAKETIME="+1d x2"                     # With speed
FAKETIME="+0 i1"                      # Per-tick increment
```

--------------------------------

### Configure Speed Multipliers with libfaketime

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/clock-setting-functions.md

Sets a specific start time and applies a 5x speed multiplier using a timestamp file.

```bash
# Set time to year 2000, then run 5x faster
export FAKETIME_TIMESTAMP_FILE="/tmp/time.rc"
export FAKETIME_UPDATE_TIMESTAMP_FILE=1
export LD_PRELOAD=/usr/local/lib/libfaketime.so.1

echo "2000-01-01 00:00:00 x5" > /tmp/time.rc
date -s "2000-01-01 00:00:00"
```

--------------------------------

### Integrate faketime with Docker

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/faketime-wrapper.md

Installs libfaketime in a Dockerfile and sets the entrypoint command to use a faked date.

```dockerfile
FROM ubuntu:20.04

RUN apt-get update && apt-get install -y libfaketime

CMD ["faketime", "2020-01-01", "/app/entrypoint.sh"]
```

--------------------------------

### Identify explicit libc loading

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/errors.md

Example of code that bypasses LD_PRELOAD by loading libc dynamically.

```c
// Go and Java do this, bypassing LD_PRELOAD
dlopen("libc.so.6", RTLD_NOW);  // Bypasses LD_PRELOAD
```

--------------------------------

### Handle nanosleep failures

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/errors.md

Examples of invalid nanosleep parameters and handling signal interruptions.

```c
struct timespec req;
req.tv_sec = -1;  // Invalid
nanosleep(&req, NULL);  // Returns -1, errno = EINVAL
```

```c
int ret = nanosleep(&req, &rem);
if (ret == -1 && errno == EINTR) {
  printf("Interrupted after %ld.%09ld\n", rem.tv_sec, rem.tv_nsec);
  // Can retry with rem
}
```

--------------------------------

### clock_nanosleep C Example

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/sleep-and-delay-functions.md

Demonstrates both relative and absolute sleep intervals using clock_nanosleep with faked time.

```c
#include <time.h>
#include <stdio.h>

// With environment: LD_PRELOAD=libfaketime.so.1 FAKETIME="+1d x5"
int main() {
  struct timespec req;
  
  // Sleep relative (10 seconds in faked time)
  req.tv_sec = 10;
  req.tv_nsec = 0;
  clock_nanosleep(CLOCK_MONOTONIC, 0, &req, NULL);
  printf("Relative sleep done\n");
  
  // Sleep absolute (until timestamp)
  clock_gettime(CLOCK_REALTIME, &req);
  req.tv_sec += 30;  // 30 seconds in faked time from now
  clock_nanosleep(CLOCK_REALTIME, TIMER_ABSTIME, &req, NULL);
  printf("Absolute sleep done\n");
  
  return 0;
}
```

--------------------------------

### Timestamp File Format

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/clock-setting-functions.md

Example content for a timestamp file, which accepts any valid FAKETIME format.

```text
+0 x1
-15d
@2020-01-01 12:00:00
2020-12-24 20:30:00
```

--------------------------------

### Configure Per-Tick Increments with libfaketime

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/clock-setting-functions.md

Sets a start time and configures the system to increment the time by one second per call.

```bash
# Set time, then increment by 1 second per call
export FAKETIME_TIMESTAMP_FILE="/tmp/time.rc"
export FAKETIME_UPDATE_TIMESTAMP_FILE=1
export LD_PRELOAD=/usr/local/lib/libfaketime.so.1

echo "@2000-01-01 00:00:00 i1" > /tmp/time.rc
date
# Each time() call increments by 1 second
```

--------------------------------

### Configure Deterministic Time for Threaded Applications

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/thread-synchronization-functions.md

Sets a fixed start time for a multi-threaded application using the thread-safe libfaketime library.

```bash
export LD_PRELOAD=/usr/local/lib/libfaketimeMT.so.1
export FAKETIME="@2000-01-01 12:00:00"
export FAKETIME_DONT_RESET=1
./my_multithreaded_app
```

--------------------------------

### C Function Signature Example

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/INDEX.md

Standard format used for displaying C function declarations in the documentation.

```c
int clock_gettime(clockid_t clk_id, struct timespec *tp)
```

--------------------------------

### Use struct itimerspec with timer_settime

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/types.md

Example of configuring an interval timer using itimerspec.

```c
#include <time.h>

struct itimerspec spec;
spec.it_interval.tv_sec = 5;
spec.it_interval.tv_nsec = 0;
spec.it_value.tv_sec = 10;
spec.it_value.tv_nsec = 0;

timer_settime(timerid, 0, &spec, NULL);
```

--------------------------------

### Configure Deterministic Timing

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/sleep-and-delay-functions.md

Sets a fixed starting time and prevents time resets to ensure consistent sleep durations.

```bash
# All sleeps consume exactly their duration, starting from fixed time
export LD_PRELOAD=/usr/local/lib/libfaketime.so.1
export FAKETIME="@2000-01-01 00:00:00"
export FAKETIME_DONT_RESET=1
./my_app
```

--------------------------------

### Use struct timespec with clock_gettime

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/types.md

Example of initializing and populating a timespec structure using the system clock.

```c
#include <time.h>

struct timespec ts;
clock_gettime(CLOCK_REALTIME, &ts);
printf("%ld.%09ld\n", ts.tv_sec, ts.tv_nsec);
```

--------------------------------

### pthread_cond_timedwait usage example

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/thread-synchronization-functions.md

Demonstrates waiting on a condition variable with a timeout relative to faked time.

```c
#include <pthread.h>
#include <time.h>
#include <stdio.h>
#include <string.h>

// With environment: LD_PRELOAD=libfaketime.so.1 FAKETIME="@2020-01-01 12:00:00"
pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER;
pthread_cond_t cond = PTHREAD_COND_INITIALIZER;

int main() {
  struct timespec abstime;
  clock_gettime(CLOCK_REALTIME, &abstime);
  abstime.tv_sec += 10;  // Timeout 10 faked seconds from now
  
  pthread_mutex_lock(&mutex);
  int ret = pthread_cond_timedwait(&cond, &mutex, &abstime);
  if (ret == ETIMEDOUT) {
    printf("Condition wait timed out\n");
  } else if (ret == 0) {
    printf("Condition was signaled\n");
  }
  pthread_mutex_unlock(&mutex);
  
  return 0;
}
```

--------------------------------

### Configure Deterministic Testing

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/README.md

Sets a fixed start time and random seed to ensure identical time behavior across test runs.

```bash
export LD_PRELOAD=/usr/local/lib/libfaketime.so.1
export FAKETIME="@2000-01-01 00:00:00"
export FAKETIME_DONT_RESET=1
export FAKERANDOM_SEED="0xDEADBEEFCAFEBABE"

# Each run produces identical time behavior
./my_test
```

--------------------------------

### Integrate faketime with CI/CD pipelines

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/faketime-wrapper.md

Examples for running tests with faked dates in GitHub Actions and GitLab CI.

```yaml
- name: Test with faked date
  run: |
    faketime '2020-12-24' ./run_tests.sh
```

```yaml
test:
  script:
    - faketime '2020-12-24 20:30:00' pytest tests/
```

--------------------------------

### Configure global timestamp faking

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/file-timestamp-functions.md

Examples of using environment variables to set specific timestamps, offsets, or duration-limited faking for file operations.

```bash
export LD_PRELOAD=/usr/local/lib/libfaketime.so.1
export FAKETIME="@2000-01-01 00:00:00"
export FAKETIME_DONT_RESET=1
ls -la /tmp  # All timestamps show year 2000
```

```bash
export LD_PRELOAD=/usr/local/lib/libfaketime.so.1
export FAKETIME="+1y"  # All files appear 1 year newer
touch /tmp/newfile  # File gets mtime = 1 year in future
stat /tmp/newfile
```

```bash
# Fake for first 10 seconds only
export LD_PRELOAD=/usr/local/lib/libfaketime.so.1
export FAKETIME="+100d"
export FAKETIME_STOP_AFTER_SECONDS=10
# After 10 seconds, file operations see real timestamps
```

--------------------------------

### Set absolute start time for timers

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/timer-functions.md

Forces timers to initiate from a specific timestamp while preventing reset via FAKETIME_DONT_RESET.

```bash
# All timers start from Jan 1, 2000 12:00:00
export LD_PRELOAD=/usr/local/lib/libfaketime.so.1
export FAKETIME="@2000-01-01 12:00:00"
export FAKETIME_DONT_RESET=1
./my_timer_app
```

--------------------------------

### Display help information

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/faketime-wrapper.md

Show usage instructions and available options.

```bash
faketime --help
```

--------------------------------

### Run application with direct LD_PRELOAD

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/faketime-wrapper.md

Manually configures the environment to use libfaketime for full control over options.

```bash
export LD_PRELOAD=/usr/local/lib/libfaketime.so.1
export FAKETIME="2020-12-24 20:30:00"
./my_app
```

--------------------------------

### Using timer_settime with libfaketime

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/timer-functions.md

Demonstrates configuring a timer that respects the FAKETIME environment variable settings.

```c
#include <time.h>
#include <signal.h>
#include <string.h>
#include <stdio.h>

// With environment: LD_PRELOAD=libfaketime.so.1 FAKETIME="+1d x2"
void handler(int sig) {
  printf("Timer fired\n");
}

int main() {
  timer_t timerid;
  struct sigevent se;
  struct itimerspec spec;
  
  // Create timer
  memset(&se, 0, sizeof(se));
  se.sigev_notify = SIGEV_SIGNAL;
  se.sigev_signo = SIGALRM;
  timer_create(CLOCK_REALTIME, &se, &timerid);
  
  // Set timer for 10 seconds from now
  spec.it_interval.tv_sec = 0;
  spec.it_interval.tv_nsec = 0;
  spec.it_value.tv_sec = 10;
  spec.it_value.tv_nsec = 0;
  
  signal(SIGALRM, handler);
  timer_settime(timerid, 0, &spec, NULL);
  
  return 0;
}
```

--------------------------------

### Configure dynamic time via FAKETIME_TIMESTAMP_FILE

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/configuration.md

Demonstrates creating a configuration file and using it to control application time at runtime.

```bash
# Create initial time file
echo "+0 x1" > /tmp/fake_time.cfg

# Run application with time from file
export FAKETIME_TIMESTAMP_FILE="/tmp/fake_time.cfg"
export LD_PRELOAD=/usr/local/lib/libfaketime.so.1
./my_app &

# Change time while app is running
sleep 10
echo "+1d x1" > /tmp/fake_time.cfg
```

--------------------------------

### Handle clock_gettime failures

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/errors.md

Examples of invalid usage of clock_gettime that result in EINVAL errors.

```c
struct timespec *ts = NULL;
clock_gettime(CLOCK_REALTIME, ts);  // Returns -1, errno = EINVAL
```

```c
clock_gettime(999, &ts);  // Returns -1, errno = EINVAL
```

--------------------------------

### Using utimensat with libfaketime

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/file-timestamp-functions.md

Demonstrates setting file timestamps to the current faked time or specific nanosecond-precise values using the LD_PRELOAD environment variable.

```c
#include <sys/stat.h>
#include <time.h>
#include <stdio.h>
#include <fcntl.h>

// With environment: LD_PRELOAD=libfaketime.so.1 FAKETIME="+1w"
int main() {
  struct timespec times[2];
  
  // Set both times to current faked time
  times[0].tv_sec = 0;
  times[0].tv_nsec = UTIME_NOW;
  times[1].tv_sec = 0;
  times[1].tv_nsec = UTIME_NOW;
  
  utimensat(AT_FDCWD, "/tmp/testfile", times, 0);
  
  // Or set specific nanosecond-precise times
  times[0].tv_sec = 946684800;
  times[0].tv_nsec = 123456789;
  times[1].tv_sec = 946684800;
  times[1].tv_nsec = 987654321;
  
  utimensat(AT_FDCWD, "/tmp/testfile", times, 0);
  
  return 0;
}
```

--------------------------------

### statx()

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/file-timestamp-functions.md

Get extended file attributes with faked timestamps for Linux 4.11+ systems.

```APIDOC
## int statx(int dirfd, const char *pathname, int flags, unsigned int mask, struct statx *statxbuf)

### Description
Retrieves extended file attributes while applying faked timestamps to STATX_ATIME, STATX_MTIME, and STATX_CTIME fields. It respects the requested mask and provides nanosecond precision.

### Parameters
- **dirfd** (int) - Required - Directory file descriptor (use AT_FDCWD for current directory).
- **pathname** (const char *) - Required - Path to the file.
- **flags** (int) - Required - Flags such as AT_SYMLINK_NOFOLLOW.
- **mask** (unsigned int) - Required - Requested fields (e.g., STATX_ATIME, STATX_MTIME).
- **statxbuf** (struct statx *) - Required - Result buffer.

### Return Value
- **int** - Returns 0 on success, -1 on error.
```

--------------------------------

### Configure Timestamp File

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/errors.md

Create a timestamp file and point the environment variable to it.

```bash
echo "+0" > /tmp/time.cfg
export FAKETIME_TIMESTAMP_FILE="/tmp/time.cfg"
```

--------------------------------

### Integrate with Testing Frameworks

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/README.md

Configure environment variables to run tests with a faked system time.

```bash
export LD_PRELOAD=/usr/local/lib/libfaketime.so.1
export FAKETIME="2020-12-24"
pytest tests/
```

--------------------------------

### Compare wrapper and direct LD_PRELOAD performance

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/faketime-wrapper.md

Directly setting LD_PRELOAD is faster than using the wrapper as it avoids the wrapper's date parsing overhead.

```bash
# Direct approach (faster)
export LD_PRELOAD=/usr/local/lib/libfaketime.so.1
export FAKETIME="2020-01-01"
./my_app

# Wrapper approach (adds date parsing)
faketime '2020-01-01' ./my_app
```

--------------------------------

### Integrate with Make Build Systems

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/README.md

Define a target in a Makefile to execute tests with specific time settings.

```makefile
test-date-specific:
	LD_PRELOAD=$(LIBFAKETIME) FAKETIME='2020-06-15' pytest
```

--------------------------------

### Build libfaketime with Thread Support

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/thread-synchronization-functions.md

Commands to compile the standard and multi-threaded versions of the library.

```bash
# Compile standard version
make

# Compile multi-threaded version (included in default make)
# Creates libfaketimeMT.so.1 with PTHREAD_SINGLETHREADED_TIME
```

--------------------------------

### Verify LD_PRELOAD environment

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/errors.md

Commands to debug LD_PRELOAD configuration and library loading.

```bash
# Verify LD_PRELOAD is set
echo $LD_PRELOAD

# Check if library exists
ls -la $LD_PRELOAD

# Use ldd to verify library is loaded
ldd /path/to/binary | grep faketime
```

--------------------------------

### Configure Conditional Faking

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/README.md

Delays the start and stop of time faking relative to real-world execution time.

```bash
export LD_PRELOAD=/usr/local/lib/libfaketime.so.1
export FAKETIME="+1d"
export FAKETIME_START_AFTER_SECONDS=60  # Start after 60 real seconds
export FAKETIME_STOP_AFTER_SECONDS=120  # Stop after 120 real seconds

# Real time for first 60 seconds, faked for next 60, real again after
./my_app
```

--------------------------------

### Coordinate Time Across Processes

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/clock-setting-functions.md

Demonstrates setting up a shared timestamp file and environment variables to synchronize time between two processes.

```c
// Process 1: Set time
export FAKETIME_TIMESTAMP_FILE="/tmp/shared_time.rc"
export FAKETIME_UPDATE_TIMESTAMP_FILE=1
export LD_PRELOAD=libfaketime.so.1
date -s "2020-12-24 16:00:00"

// Process 2: Reads the same time
export FAKETIME_TIMESTAMP_FILE="/tmp/shared_time.rc"
export LD_PRELOAD=libfaketime.so.1
date  # Shows same time as Process 1
```

--------------------------------

### Handle poll failures and timeout precision

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/errors.md

Examples of invalid file descriptors in poll and adjusting timeout behavior.

```c
struct pollfd pfd;
pfd.fd = -1;  // Invalid
pfd.events = POLLIN;
poll(&pfd, 1, 1000);  // Returns -1, errno = EBADF
```

```bash
# If timeout is affected by speed multiplier, disable it
export FAKETIME="+0 x1"  # x1 = no speed change
```

--------------------------------

### Configure libfaketime environment variables

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/configuration.md

Sets up environment variables for a multithreaded application to use a deterministic time environment.

```bash
#!/bin/bash

# Deterministic test environment
export LD_PRELOAD=/usr/local/lib/libfaketimeMT.so.1
export FAKETIME="@2020-01-01 12:00:00"
export FAKETIME_TIMESTAMP_FILE="/tmp/test_time.rc"
export FAKETIME_UPDATE_TIMESTAMP_FILE=0
export FAKETIME_DONT_RESET=1
export FAKETIME_DONT_FAKE_MONOTONIC=0
export FAKETIME_NO_CACHE=0
export FAKETIME_CACHE_DURATION=5
export FAKETIME_DISABLE_SHM=0
export FAKERANDOM_SEED="0x123456789ABCDEF0"

# Acceleration example
# export FAKETIME="+0 x10"

# Reproducible sequence
# export FAKETIME="+0 i1"

./my_multithreaded_app
```

--------------------------------

### Initialize a condition variable with pthread_cond_init

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/thread-synchronization-functions.md

Demonstrates the initialization and subsequent cleanup of a condition variable using pthread_cond_init and pthread_cond_destroy.

```c
#include <pthread.h>
#include <stdio.h>

int main() {
  pthread_cond_t cond;
  pthread_condattr_t attr;
  
  pthread_condattr_init(&attr);
  // Set attributes if needed
  
  pthread_cond_init(&cond, &attr);
  
  // Use condition variable
  // ...
  
  pthread_cond_destroy(&cond);
  pthread_condattr_destroy(&attr);
  
  return 0;
}
```

--------------------------------

### Configure conditional timer faking

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/timer-functions.md

Limits the faking of timers to a specific duration window after application execution starts.

```bash
# Only fake timers for the first 5 seconds of execution
export LD_PRELOAD=/usr/local/lib/libfaketime.so.1
export FAKETIME="+1d"
export FAKETIME_START_AFTER_SECONDS=0
export FAKETIME_STOP_AFTER_SECONDS=5
./my_timer_app
```

--------------------------------

### Configure file-based time following

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/configuration.md

Sets up libfaketime to track a specific file's modification time. Requires FAKETIME to be set to '%' and the LD_PRELOAD environment variable to point to the library.

```bash
# Create control file with specific timestamp
touch -t 202012241230.00 /tmp/time_control

# Run application following the file
export FAKETIME="%"
export FAKETIME_FOLLOW_FILE="/tmp/time_control"
export LD_PRELOAD=/usr/local/lib/libfaketime.so.1
./my_app &

# Advance time by updating file timestamp
sleep 5
touch -t 202012251200.00 /tmp/time_control
```

--------------------------------

### Speed up timers with libfaketime

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/timer-functions.md

Configures the application to run timers at a 10x speed multiplier relative to real time.

```bash
# Timers will fire 10x faster than real time
export LD_PRELOAD=/usr/local/lib/libfaketime.so.1
export FAKETIME="+0 x10"
./my_timer_app
```

--------------------------------

### Define and create saved_timestamp binary files

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/types.md

Binary structure definition and example code for writing timestamps in big-endian format.

```c
struct saved_timestamp {
  int64_t sec;       /* Seconds since epoch (big-endian) */
  uint64_t nsec;     /* Nanoseconds (big-endian) */
};
```

```c
#include <stdio.h>
#include <time.h>
#include <arpa/inet.h>

int main() {
  FILE *f = fopen("timestamps.bin", "wb");
  
  struct timespec ts;
  clock_gettime(CLOCK_REALTIME, &ts);
  
  int64_t sec = htonl((int32_t)ts.tv_sec);
  uint64_t nsec = htonl((uint32_t)ts.tv_nsec);
  
  fwrite(&sec, sizeof(sec), 1, f);
  fwrite(&nsec, sizeof(nsec), 1, f);
  
  fclose(f);
  return 0;
}
```

--------------------------------

### Emulate ntpdate with libfaketime

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/clock-setting-functions.md

Configures environment variables and a timestamp file to simulate ntpdate behavior.

```bash
# Test ntpdate functionality with faked time
export FAKETIME_TIMESTAMP_FILE="/tmp/virtual_time.rc"
export FAKETIME_UPDATE_TIMESTAMP_FILE=1
export LD_PRELOAD=/usr/local/lib/libfaketime.so.1

# Initialize time
echo "2020-01-01 12:00:00" > /tmp/virtual_time.rc

# Run ntpdate (or similar)
ntpdate -u pool.ntp.org

# Check updated time
date
```

--------------------------------

### Configure Locale-Specific Fraction Delimiters

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/configuration.md

Demonstrates how to set the FAKETIME environment variable using different decimal separators based on locale settings.

```bash
# English/C locale uses dot
export FAKETIME="+1.5h x2.5"

# European locales use comma
export FAKETIME="+1,5h x2,5"
```

--------------------------------

### Display version information

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/faketime-wrapper.md

Output the current version of the faketime wrapper.

```bash
faketime --version
```

--------------------------------

### Test Time-Setting Code in C

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/clock-setting-functions.md

Demonstrates using clock_settime to modify the system clock within a C application.

```c
#include <time.h>
#include <stdio.h>
#include <unistd.h>

int main() {
  struct timespec ts;
  
  printf("Initial time: ");
  clock_gettime(CLOCK_REALTIME, &ts);
  printf("%ld\n", ts.tv_sec);
  
  // Application sets time to specific value
  ts.tv_sec = 1000000000;  // 2001-09-09 01:46:40 UTC
  ts.tv_nsec = 0;
  clock_settime(CLOCK_REALTIME, &ts);
  
  printf("After settime: ");
  clock_gettime(CLOCK_REALTIME, &ts);
  printf("%ld\n", ts.tv_sec);
  
  return 0;
}
```

--------------------------------

### Schedule a signal with alarm()

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/sleep-and-delay-functions.md

Demonstrates setting a SIGALRM signal to trigger after a specified duration in faked time.

```c
#include <unistd.h>
#include <signal.h>
#include <stdio.h>

volatile int alarm_fired = 0;

void alarm_handler(int sig) {
  alarm_fired = 1;
  printf("Alarm fired!\n");
}

int main() {
  signal(SIGALRM, alarm_handler);
  
  alarm(10);  // Signal after 10 faked seconds
  
  while (!alarm_fired) {
    sleep(1);  // Faked sleep
  }
  
  return 0;
}
```

--------------------------------

### Build libfaketime with custom flags

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/README.md

Use these commands to clean the build environment and compile the library with specific interception features enabled.

```bash
cd src
make clean
make FAKETIME_COMPILE_CFLAGS="-DFAKE_SETTIME -DFAKE_RANDOM"
```

--------------------------------

### Set clock time with clock_settime in C

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/clock-setting-functions.md

Demonstrates setting the system clock to a specific timestamp using clock_settime. Requires the -DFAKE_SETTIME compilation flag and libfaketime to be preloaded.

```c
#include <time.h>
#include <stdio.h>
#include <string.h>

// Requires: -DFAKE_SETTIME compilation flag
// With environment: LD_PRELOAD=libfaketime.so.1
int main() {
  struct timespec ts;
  
  // Set time to a specific value
  ts.tv_sec = 946684800;   // 2000-01-01 00:00:00 UTC
  ts.tv_nsec = 0;
  
  if (clock_settime(CLOCK_REALTIME, &ts) == 0) {
    printf("Time set successfully\n");
  } else {
    perror("clock_settime");
  }
  
  // Verify by reading back
  clock_gettime(CLOCK_REALTIME, &ts);
  printf("Current time: %ld.%09ld\n", ts.tv_sec, ts.tv_nsec);
  
  return 0;
}
```

--------------------------------

### Configure Instant Sleep with libfaketime

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/sleep-and-delay-functions.md

Forces all sleep calls to complete instantly by setting the time increment to zero.

```bash
# All sleeps complete instantly (effectively x999999 speed)
export LD_PRELOAD=/usr/local/lib/libfaketime.so.1
export FAKETIME="+0 i0"  # No time increment per call
./my_app
```

--------------------------------

### Configure Smooth Speed Transitions

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/configuration.md

Enables smooth clock transitions when modifying the speed multiplier at runtime via a timestamp file.

```bash
# Start at x1 speed
echo "+0 x1" > /tmp/time.cfg
export FAKETIME_TIMESTAMP_FILE="/tmp/time.cfg"
export FAKETIME_NO_CACHE=1
export FAKETIME_XRESET=1
./my_app &

# Change to x10 after 5 seconds
sleep 5
echo "+0 x10" > /tmp/time.cfg
```

--------------------------------

### Execute Multi-Threaded Applications

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/thread-synchronization-functions.md

Environment variable configuration to preload the multi-threaded library for threaded applications.

```bash
# Use MT version for multi-threaded applications
export LD_PRELOAD=/usr/local/lib/libfaketimeMT.so.1
export FAKETIME="+1d"
./my_threaded_app
```

--------------------------------

### Run application with faketime wrapper

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/faketime-wrapper.md

Executes an application with a faked system time using the simple wrapper syntax.

```bash
faketime '2020-12-24' ./my_app
```

--------------------------------

### Troubleshoot binary execution errors

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/faketime-wrapper.md

Checks system architecture to ensure compatibility with the faketime binary.

```bash
# Check architecture
file $(which faketime)

# Verify against system
uname -m
```

--------------------------------

### Accelerate time for timers

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/faketime-wrapper.md

Runs an application with a time multiplier to test time-sensitive logic quickly.

```bash
# Run program with 10x speed, starting from specific date
faketime -f '+2000-01-01 x10' ./timer_test_app
```

--------------------------------

### Diagnostic Commands

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/errors.md

Run a full diagnostic report to collect version, system, and library information for troubleshooting.

```bash
# Full diagnostic report
echo "=== Version ==="
cat /usr/local/lib/faketime/README | head -1
echo "=== System ==="
uname -a
echo "=== Library ==="
file /usr/local/lib/libfaketime.so.1
echo "=== Test ==="
export LD_PRELOAD=/usr/local/lib/libfaketime.so.1
export FAKETIME="2020-01-01 00:00:00"
date
echo "=== Environment ==="
env | grep FAKE
```

--------------------------------

### Replay past behavior

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/README.md

Execute a legacy application with the clock frozen at a specific past date.

```bash
faketime '2000-01-01' ./legacy_app
```

--------------------------------

### Enable Debug Output

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/errors.md

Use environment variables to enable verbose logging and symbol resolution debugging for libfaketime.

```bash
export FAKETIME_DEBUG=1
export FAKETIME_DEBUG_DLSYM=1
export LD_PRELOAD=/usr/local/lib/libfaketime.so.1
./my_app 2>&1 | head -100
```

--------------------------------

### Monitor CPU Usage

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/errors.md

Monitor the CPU usage of the application using top.

```bash
# Monitor CPU while running
top -p $(pgrep -f my_app)
```

--------------------------------

### Optimize Performance via Caching

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/errors.md

Enable caching or adjust the cache duration to reduce CPU overhead.

```bash
# Enable caching (default is on)
unset FAKETIME_NO_CACHE

# Or set reasonable cache duration
export FAKETIME_CACHE_DURATION=5
```

--------------------------------

### Run application with debug output

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/README.md

Command to execute a test with verbose debugging enabled for libfaketime.

```bash
FAKETIME_DEBUG=1 FAKETIME_DEBUG_DLSYM=1 ./test
```

--------------------------------

### Reset to Real Time

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/errors.md

Disable libfaketime by unsetting the relevant environment variables.

```bash
# Disable faking completely
unset LD_PRELOAD
unset FAKETIME
date  # Shows real time
```

--------------------------------

### Monitor file descriptors with select()

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/sleep-and-delay-functions.md

Uses select to wait for input on stdin with a 10-second timeout that respects faked time.

```c
#include <sys/select.h>
#include <unistd.h>
#include <stdio.h>

int main() {
  fd_set readfds;
  struct timeval tv;
  
  FD_ZERO(&readfds);
  FD_SET(STDIN_FILENO, &readfds);
  
  tv.tv_sec = 10;  // 10 faked seconds
  tv.tv_usec = 0;
  
  int ret = select(STDIN_FILENO + 1, &readfds, NULL, NULL, &tv);
  
  if (ret > 0 && FD_ISSET(STDIN_FILENO, &readfds)) {
    printf("Input available\n");
  }
  
  return 0;
}
```

--------------------------------

### Retrieve timer value with timer_gettime

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/timer-functions.md

Demonstrates how to fetch the remaining time for a timer using the faked clock.

```c
#include <time.h>
#include <stdio.h>

int main() {
  timer_t timerid;
  struct itimerspec spec;
  
  // Assume timer was created and set previously
  timer_gettime(timerid, &spec);
  
  printf("Timer remaining: %ld.%09ld seconds\n",
         spec.it_value.tv_sec,
         spec.it_value.tv_nsec);
  
  return 0;
}
```

--------------------------------

### Accelerated testing

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/README.md

Run an application with the clock progressing at 10 times the real-time speed.

```bash
faketime -f '+0 x10' ./my_app  # 10x faster
```

--------------------------------

### Manual Testing

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/errors.md

Verify faking behavior using specific dates, relative offsets, or time acceleration factors.

```bash
# Test basic faking
export LD_PRELOAD=/usr/local/lib/libfaketime.so.1
export FAKETIME="2020-12-24 20:30:00"
date  # Should show specified date

# Test with offset
export FAKETIME="+1d"
date  # Should show tomorrow

# Test with speed
export FAKETIME="+0 x10"
bash -c 'for i in {1..5}; do date; sleep 1; done'  # Time jumps 10 seconds per sleep
```

--------------------------------

### Test legacy application behavior

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/faketime-wrapper.md

Sets a specific historical date to verify legacy software compatibility.

```bash
# Test year-2000 behavior
faketime '2000-01-01' ./legacy_app
```

--------------------------------

### Initialize and wait on a pthread_cond_t

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/types.md

Demonstrates using a condition variable with a mutex and a timed wait. Requires pthread.h.

```c
#include <pthread.h>

pthread_cond_t cond = PTHREAD_COND_INITIALIZER;
pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER;
struct timespec abstime;

clock_gettime(CLOCK_REALTIME, &abstime);
abstime.tv_sec += 10;

pthread_mutex_lock(&mutex);
pthread_cond_timedwait(&cond, &mutex, &abstime);
pthread_mutex_unlock(&mutex);
```

--------------------------------

### Record and Replay Timestamps

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/configuration.md

Configure file paths to capture timestamps during execution and replay them in subsequent runs.

```bash
# Record timestamps during first run
export FAKETIME_SAVE_FILE="/tmp/timestamps.bin"
./my_app

# Replay timestamps during second run
export FAKETIME_LOAD_FILE="/tmp/timestamps.bin"
./my_app
```

--------------------------------

### Configure Java Application

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/README.md

Uses the multi-threaded library variant and disables monotonic clock faking, which is required for Java environments.

```bash
export LD_PRELOAD=/usr/local/lib/libfaketimeMT.so.1
export FAKETIME="2020-01-01"
export FAKETIME_DONT_FAKE_MONOTONIC=1

java -jar app.jar
```

--------------------------------

### select() and pselect()

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/sleep-and-delay-functions.md

Functions to monitor multiple file descriptors with timeouts that respect faked time settings.

```APIDOC
## select() and pselect()

### Description
Monitor multiple file descriptors with timeout in faked time. Timeout durations are affected by speed multipliers.

### Signature
int select(int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout)
int pselect(int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, const struct timespec *timeout, const sigset_t *sigmask)

### Return Value
- **Type**: int
- **Value**: Number of ready file descriptors, 0 on timeout, -1 on error
```

--------------------------------

### Configure Shared Memory

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/faketime-wrapper.md

The wrapper manages shared memory for multi-process coordination automatically. Use the --disable-shm flag if conflicts arise.

```bash
# Wrapper sets up shared memory for multi-process coordination
# Automatically cleans up when wrapper exits
# Use --disable-shm if conflicts occur
```

--------------------------------

### Integrate with GitHub Actions

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/README.md

Set environment variables within a workflow step to apply libfaketime during CI execution.

```yaml
- name: Test with faked date
  env:
    LD_PRELOAD: /usr/local/lib/libfaketime.so.1
    FAKETIME: '2020-01-01'
  run: make test
```

--------------------------------

### Compile with FAKE_SETTIME

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/clock-setting-functions.md

Commands to build libfaketime with the FAKE_SETTIME feature enabled.

```bash
cd src
make clean
make FAKETIME_COMPILE_CFLAGS="-DFAKE_SETTIME"
```

--------------------------------

### Specify custom date program

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/faketime-wrapper.md

Point to a specific date binary, such as gdate on macOS or Solaris.

```bash
faketime --date-prog /usr/bin/gdate '2020-01-01' date
```

--------------------------------

### Integrate faketime with Make

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/faketime-wrapper.md

Uses faketime to run build targets with specific dates for testing.

```makefile
test-date-dependent:
	faketime '2020-01-01' make build
	faketime '2025-12-31' make build  # Test future date
```

--------------------------------

### Retrieve faked time with time()

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/system-time-functions.md

Demonstrates using the time() function to retrieve the current faked epoch time, either via return value or pointer storage.

```c
#include <time.h>
#include <stdio.h>

// With environment: LD_PRELOAD=libfaketime.so.1 FAKETIME="+1d"
int main() {
  time_t t = time(NULL);
  printf("Faked time: %ld\n", t);  // Shows time 1 day in future
  
  time_t t2;
  time(&t2);  // Also stores in t2
  printf("Same time: %ld\n", t2);
  
  return 0;
}
```

--------------------------------

### Modify file timestamps with utimes()

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/file-timestamp-functions.md

Demonstrates setting file access and modification times with microsecond precision using the utimes() function.

```c
#include <sys/time.h>
#include <stdio.h>
#include <string.h>

// With environment: LD_PRELOAD=libfaketime.so.1 FAKETIME="@2015-06-15 12:00:00"
int main() {
  struct timeval times[2];
  
  // Set to specific faked times
  times[0].tv_sec = 1434369600;  // 2015-06-15 12:00:00
  times[0].tv_usec = 0;
  times[1].tv_sec = 1434369600;
  times[1].tv_usec = 500000;
  
  utimes("/tmp/testfile", times);
  
  return 0;
}
```

--------------------------------

### Verify Process ID Spoofing Support

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/faketime-wrapper.md

The -p option requires specific compilation support. Verify availability by checking the exit code of a test command.

```bash
# Check if supported
faketime -p 12345 'now' true
# If works: exit code 0
# If fails: error message about FAKE_PID not compiled
```

--------------------------------

### Configure timerfd with timerfd_settime

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/timer-functions.md

Configures a timer file descriptor to fire after a specific duration in faked time.

```c
#include <sys/timerfd.h>
#include <unistd.h>
#include <stdio.h>
#include <string.h>

// With environment: LD_PRELOAD=libfaketime.so.1 FAKETIME="+1h"
int main() {
  int fd = timerfd_create(CLOCK_REALTIME, 0);
  
  struct itimerspec spec;
  memset(&spec, 0, sizeof(spec));
  spec.it_value.tv_sec = 5;  // 5 seconds in faked time
  
  timerfd_settime(fd, 0, &spec, NULL);
  
  // Read will return after 5 faked seconds
  uint64_t count;
  read(fd, &count, sizeof(count));
  printf("Timer fired %lld times\n", count);
  
  close(fd);
  return 0;
}
```

--------------------------------

### time()

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/system-time-functions.md

Returns the current time in seconds since the Unix epoch, modified by libfaketime.

```APIDOC
## time(time_t *time_tptr)

### Description
Returns the current time in seconds since the Unix epoch. The function is intercepted to return a faked timestamp based on the FAKETIME specification.

### Parameters
- **time_tptr** (time_t *) - Optional - Pointer to store the result; if NULL, only the return value is used.

### Return Value
- **Type**: time_t
- **Value**: Current faked time in seconds since Unix epoch (1970-01-01 00:00:00 UTC). Returns -1 on error.
```

--------------------------------

### Basic faketime command syntax

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/faketime-wrapper.md

The standard structure for executing a command with a faked timestamp.

```bash
faketime [options] <timestamp> <command> [arguments...]
```

--------------------------------

### Configure Monotonic Clock Faking for Java

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/configuration.md

Use these environment variables to prevent CLOCK_MONOTONIC faking while maintaining faked CLOCK_REALTIME, which is recommended for JVM applications.

```bash
# For Java applications
export FAKETIME="-15d"
export FAKETIME_DONT_FAKE_MONOTONIC=1
java -version
```

--------------------------------

### utimensat()

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/file-timestamp-functions.md

Changes file timestamps with nanosecond precision, supporting directory-relative paths and integration with libfaketime's faked time environment.

```APIDOC
## utimensat(int dirfd, const char *pathname, const struct timespec times[2], int flags)

### Description
Changes file times with nanosecond precision and directory-relative paths. When used with libfaketime, it respects the faked time environment.

### Signature
`int utimensat(int dirfd, const char *pathname, const struct timespec times[2], int flags)`

### Parameters
- **dirfd** (int) - Required - Directory file descriptor (use AT_FDCWD for current directory).
- **pathname** (const char *) - Required - Path to the target file.
- **times[2]** (const struct timespec *) - Optional - Array containing access time (times[0]) and modification time (times[1]). If NULL, uses current faked time.
- **flags** (int) - Required - Flags such as AT_SYMLINK_NOFOLLOW to prevent following symlinks.

### Return Value
- **Type**: int
- **Value**: 0 on success, -1 on error.

### Behavior
- times[0] represents access time.
- times[1] represents modification time.
- UTIME_NOW uses the current faked time.
- UTIME_OMIT leaves the specific time unchanged.
```

--------------------------------

### Create archives with fixed timestamps

Source: https://github.com/wolfcw/libfaketime/blob/master/_autodocs/api-reference/file-timestamp-functions.md

Set the FAKETIME environment variable to a specific date to apply that timestamp to all files included in the archive.

```bash
# Create tar with all files timestamped to 2000
export LD_PRELOAD=/usr/local/lib/libfaketime.so.1
export FAKETIME="2000-01-01 00:00:00"
tar czf archive.tar.gz /path/to/files
```
Tokens:
Raw