futimesat - Linux

Overview

futimesat is a Linux command used to change the file or directory timestamps of a file. It sets the access time (atime), modification time (mtime), and status change time (ctime) of a file. This command is commonly used for updating file metadata or synchronizing timestamps across multiple systems.

Syntax

futimesat(int dirfd, const char *pathname, const struct timespec times[2])

Options/Flags

  • dirfd – File descriptor of the directory containing the file.
  • pathname – Path to the file to modify timestamps.
  • times – Array of two timespec structures representing:
    • times[0] – New access time.
    • times[1] – New modification time.

Examples

Example 1: Set Access and Modification Time

timespec times[2];
times[0].tv_sec = 1656377200; // Set access time to 2023-06-28 23:00:00
times[0].tv_nsec = 0;
times[1].tv_sec = 1656377200; // Set modification time to 2023-06-28 23:00:00
times[1].tv_nsec = 0;
futimesat(AT_FDCWD, "myfile.txt", times);

Example 2: Set Time to Current Value

struct timespec times[2];
times[0] = times[1] = (struct timespec){.tv_sec = time(NULL)};
futimesat(AT_FDCWD, "myfile.txt", times);

Common Issues

  • Invalid File Descriptor: Ensure the dirfd parameter is a valid file descriptor of the containing directory.
  • Permission Denied: The user must have write permissions to update the file timestamps.

Integration

Example: Synchronize File Timestamps with a Remote Server

char *remotepath = "remote_server:remote_file";
struct timespec times[2];
times[0] = times[1] = (struct timespec){.tv_sec = time(NULL)};
futimesat(AT_FDCWD, localpath, times);
ssh "remote_user@remote_server" "futimesat AT_FDCWD \"$remotepath\" \"$times[0].tv_sec\" \"$times[1].tv_sec\""

Related Commands

  • stat: Gets file status, including timestamps.
  • touch: Updates file timestamps.
  • ln: Creates links to files, preserving timestamps.