UTIMENSAT(2)

💅 UTIMENSAT(2) — bestie's guide to the futimens / utimensat system calls (that's the System Calls Manual, section 2, iykyk) 🎀

Okay so like. You know how files have vibes attached to them — like when they were last looked at and when they were last messed with? Yeah. This page is literally just "how do I change those vibes on purpose." Two whole system calls for it. Iconic. Let's go. ✨

---

🌸 NAME 🌸

futimens, utimensat — set file access and modification times

Translated: change when a file was last read and last written, basically rewriting its little personal diary. 🦋

---

📚 LIBRARY 📚

Standard C Library (libc, -lc)

That's it, that's the whole section. Link the libc, live your life. 🫶

---

⭐ SYNOPSIS ⭐

#include <sys/stat.h>

int
futimens(int fd, const struct timespec times[2]);

int
utimensat(int fd, const char *path, const struct timespec times[2],
    int flag);

Two functions, same energy, different entry points. futimens() takes a file descriptor, utimensat() takes a path and an fd and a flag. She's high-maintenance and we respect that. 👑

---

✨ DESCRIPTION ✨

So here's the tea ☕: the access time and the modification time of the file named by path — or referenced by fd — get changed exactly as specified by the times argument. And then, as a little bonus, the inode-change-time of the file gets set to the current time. Free of charge. Every time. No opt-out, that's just how it is. 💫

If path is a relative path, here's how the resolution goes:

• if fd is AT_FDCWD → relative to the current working directory,
• otherwise → relative to the directory associated with the file descriptor fd. 🗂️

Now the fun part. The tv_nsec field of a timespec structure can be set to two special little values:

• UTIME_NOW → set the current time ✨
• UTIME_OMIT → leave the time unchanged 🙈

And in either of those cases, the tv_sec field gets straight-up ignored. Like it's not even there. Bye. 👋

If times is non-NULL, it's assumed to point at an array of two timespec structures:

• the access time gets set to the value of the first element,
• the modification time gets set to the value of the second element. 🎯

And here's a niche-but-real detail for the file systems that support file birth (creation) times (such as UFS2): the birth time will be set to the value of the second element if the second element is older than the currently set birth time. Which means — plot twist — if you want to set both a birth time and a modification time, you need two calls:

1. the first one to set the birth time,
2. the second one to set the (presumably newer) modification time. 🕰️

And ideally — like, in a perfect world — a new system call will be added that lets you set all three times at once. We're manifesting it. ✨🙏

If times is NULL, that's exactly equivalent to passing a pointer to an array of two timespec structures with both tv_nsec fields set to UTIME_NOW. Same thing, fewer characters typed. Efficiency queen. 💅

Permissions check time, bc this is where people get humbled:

• If both tv_nsec fields are UTIME_OMIT → the timestamps remain unchanged and no permissions are needed for the file itself, although search permissions may be required for the path prefix. Also, the call may or may not succeed if the named file doesn't exist. (Yes, "may or may not." She's mysterious. 😭)
• If both tv_nsec fields are UTIME_NOW → the caller must be the owner of the file, have permission to write the file, or be the super-user.
• For all other values of the timestamps → the caller must be the owner of the file or be the super-user. No write bit loophole here, bestie.

---

🎀 the flag values for utimensat() 🎀

The flag argument of the utimensat() system call is built by bitwise-inclusive OR-ing flags from this list, all defined in <fcntl.h>:

• AT_SYMLINK_NOFOLLOW — if path names a symbolic link, the symbolic link's times get changed. By default, utimensat() changes the times of the file referenced by the symbolic link instead. So this flag is you saying "no, the link herself, not her target." 🔗
• AT_RESOLVE_BENEATH — only walk paths below the directory specified by the fd descriptor. See the description of the O_RESOLVE_BENEATH flag in the open(2) manual page for the full lore. 🚧
• AT_EMPTY_PATH — if the path argument is an empty string, operate on the file or directory referenced by the descriptor fd. And if fd is equal to AT_FDCWD, operate on the current working directory. 🫧

---

🌈 RETURN VALUES 🌈

Upon successful completion, the value 0 is returned. Slay. ✨

Otherwise, the value -1 is returned and the global variable errno is set to indicate the error. Sad but informative. 😭

---

💀 ERRORS 💀

these system calls will fail if:

• [EACCES] — the times argument is NULL, or both tv_nsec values are UTIME_NOW, and the effective user ID of the process does not match the owner of the file, and is not the super-user, and write access is denied.
• [EFAULT] — the times argument points outside the process's allocated address space. Rude.
• [EINVAL] — the tv_nsec component of at least one of the values specified by the times argument has a value less than 0 or greater than 999999999 and is not equal to UTIME_NOW or UTIME_OMIT. Out of range, babes.
• [EIO] — an I/O error occurred while reading or writing the affected inode. 💀
• [EINTEGRITY] — corrupted data was detected while reading from the file system. 🫠
• [EPERM] — the times argument is not NULL, nor are both tv_nsec values UTIME_NOW, nor are both tv_nsec values UTIME_OMIT, and the calling process's effective user ID does not match the owner of the file and is not the super-user.
• [EPERM] — the named file has its immutable or append-only flag set. See the chflags(2) manual page for more information. (Yes, this one shows up twice. Two separate EPERM reasons, both real. 👯)
• [EROFS] — the file system containing the file is mounted read-only. Nothing you can do, bestie, the disk said no.

the futimens() system call will fail if:

• [EBADF] — the fd argument does not refer to a valid descriptor. 🚫

the utimensat() system call will fail if:

• [EACCES] — search permission is denied for a component of the path prefix.
• [EBADF] — the path argument does not specify an absolute path and the fd argument is neither AT_FDCWD nor a valid file descriptor.
• [EFAULT] — the path argument points outside the process's allocated address space.
• [ELOOP] — too many symbolic links were encountered in translating the pathname. The links said "one more loop" and there were, in fact, no more loops available. 😵‍💫
• [ENAMETOOLONG] — a component of a pathname exceeded NAME_MAX characters, or an entire path name exceeded PATH_MAX characters. She's doing too much.
• [ENOENT] — the named file does not exist.
• [ENOTDIR] — a component of the path prefix is not a directory.
• [ENOTDIR] — the path argument is not an absolute path and fd is neither AT_FDCWD nor a file descriptor associated with a directory. (Yep, ENOTDIR twice too. Twin behavior. 💅)
• [ENOTCAPABLE] — path is an absolute path, or contained a ".." component leading to a directory outside of the directory hierarchy specified by fd, and the process is in capability mode or the AT_RESOLVE_BENEATH flag was specified. No escaping the sandbox, bestie. 🏰

---

👀 SEE ALSO 👀

chflags(2), stat(2), symlink(2), utimes(2), utime(3), symlink(7)

The whole friend group. Go say hi. 🫶

---

📜 STANDARDS 📜

The futimens() and utimensat() system calls are expected to conform to IEEE Std 1003.1-2008 (“POSIX.1”).

Certified standard-issue behavior. 📋✨

---

🕰️ HISTORY 🕰️

The futimens() and utimensat() system calls appeared in FreeBSD 10.3.

Vintage, but make it functional. 💜

---

tl;dr — one of these takes a descriptor, the other takes a path plus a descriptor plus a flag, both change your atime/mtime (and silently your inode-change-time), UTIME_NOW and UTIME_OMIT are your two little cheat codes, and the permissions you need depend entirely on which of those you used. Read the EPERMs twice, there are literally two of them. 😭

---

this page was served up by the Debian fam, dated June 12, 2022 — UTIMENSAT(2), that's the one, stan her 💖