UTIMES(2)

💖 UTIMES(2) — bestie, we're setting file times 💖

okay so this is a page from the System Calls Manual, and it's all about utimes, lutimes, futimes, and futimesat. yes that's four whole functions. no cap, they all do the same vibe: touching a file's timestamps. let's get into it 🫶

---

✨ NAME ✨

utimes, lutimes, futimes, futimesat — set file access and modification times

---

📚 LIBRARY 📚

Standard C Library (libc, -lc)

---

🎀 SYNOPSIS 🎀

#include <sys/time.h>

int
utimes(const char *path, const struct timeval *times);

int
lutimes(const char *path, const struct timeval *times);

int
futimes(int fd, const struct timeval *times);

int
futimesat(int fd, const char *path, const struct timeval times[2]);

---

🌸 DESCRIPTION 🌸

so first things first, bestie, and I need you to hear me on this one:

These interfaces are obsoleted by futimens(2) and utimensat(2) because they are not accurate to nanoseconds. 💀

like, they still work, but they're the old-school way. the new girls (futimens and utimensat) got that nanosecond precision. these ones? not so much. iykyk.

so here's the tea ☕ — the access time and the modification time of the file named by path, or referenced by fd, get changed to whatever the times argument says.

if times is NULL — the access and modification times both get set to the current time. but! the caller has to be the owner of the file, or have permission to write the file, or be the super-user. one of those three, pick your fighter 💅

if times is non-NULL — it's assumed to point at an array of two timeval structures. here's the mapping:

• 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 okay this next part is kinda niche but it's giving UFS2 energy: for 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. 🦋

and because life is complicated, to set both a birth time and a modification time, you need two calls:

1. the first call sets the birth time
2. the second call sets the (presumably newer) modification time

and the manpage literally says: "Ideally a new system call will be added that allows the setting of all three times at once." 😭 not them manifesting.

also when times is non-NULL, the caller must be the owner of the file or be the super-user.

either way, the inode-change-time of the file gets set to the current time. every time. periodt.

---

🧚 lutimes() vs utimes() 🧚

the lutimes() system call is like utimes() except when the named file is a symbolic link:

• lutimes() changes the access and modification times of the link itself 🔗
• utimes() changes the times of the file the link references 🎯

subtle but iconic.

---

🌈 futimesat() 🌈

the futimesat() system call is equivalent to utimes() except when path specifies a relative path. in that case, the access and modification time is set to that of a file relative to the directory associated with the file descriptor fd — instead of the current working directory. 📁

and if you pass futimesat() the special value AT_FDCWD in the fd parameter? the current working directory gets used, and the behavior is identical to a call to utimes(). slay, consistency. ✨

---

👑 RETURN VALUES 👑

• on a successful completion, the value 0 is returned 🎉
• otherwise, the value -1 is returned, and the global variable errno is set to indicate the error 😔

---

💅 ERRORS 💅

all of the system calls will fail if:

• [EACCES] — Search permission is denied for a component of the path prefix.
• [EACCES] — The times argument is NULL 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 path or times argument points outside the process's allocated address space.
• [EFAULT] — The times argument points outside the process's allocated address space.
• [EINVAL] — The tv_usec component of at least one of the values specified by the times argument has a value less than 0 or greater than 999999.
• [EIO] — An I/O error occurred while reading or writing the affected inode.
• [EINTEGRITY] — Corrupted data was detected while reading from the file system.
• [ELOOP] — Too many symbolic links were encountered in translating the pathname.
• [ENAMETOOLONG] — A component of a pathname exceeded NAME_MAX characters, or an entire path name exceeded PATH_MAX characters.
• [ENOENT] — The named file does not exist.
• [ENOTDIR] — A component of the path prefix is not a directory.
• [EPERM] — The times argument is not NULL 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 flags set. See the chflags(2) manual page for more information.
• [EROFS] — The file system containing the file is mounted read-only.

---

the futimes() system call will fail if:

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

---

and in addition to the errors returned by utimes(), futimesat() may fail if:

• [EBADF] — The path argument does not specify an absolute path and the fd argument is neither AT_FDCWD nor a valid file descriptor open for searching.
• [ENOTDIR] — The path argument is not an absolute path and fd is neither AT_FDCWD nor a file descriptor associated with a directory.

ngl that's a lot of error codes but honestly? knowing them is main character energy. 🔥

---

🦋 SEE ALSO 🦋

chflags(2), stat(2), utimensat(2), utime(3)

---

⭐ STANDARDS ⭐

the utimes() function is expected to conform to X/Open Portability Guide Issue 4, Version 2 ("XPG4.2"). 💫

the futimesat() system call follows The Open Group Extended API Set 2 specification, but was replaced by utimensat() in IEEE Std 1003.1-2008 ("POSIX.1"). so yeah, it had its era and then it got upgraded. 🎀

---

🕰️ HISTORY 🕰️

• the utimes() system call appeared in 4.2BSD
• the futimes() and lutimes() system calls first appeared in FreeBSD 3.0
• the futimesat() system call appeared in FreeBSD 8.0

look at the timeline bestie, they were all born at different times. very on brand for a manpage about times. 😭

---

and that's the whole page! this one came from the Debian folks, dated March 30, 2020 — go set some timestamps, you absolute icon 💖✨👑