futimesat(2)

💖 futimesat(2) 💖 — the System Calls Manual, but make it a group chat

okay so bestie, gather round, because we're talking about futimesat(2) from the System Calls Manual and honestly? she's a legacy queen. we stan an icon but we also gently suggest you move on. let's get into it 💅

✨ NAME ✨

futimesat — change timestamps of a file relative to a directory file descriptor

like, you're touching a file's timestamps, but you're doing it relative to a directory file descriptor. very "it's not about the destination, it's about the dirfd" of it all 🦋

📚 LIBRARY 📚

Standard C library (libc, -lc)

---

🎀 SYNOPSIS 🎀

#include <fcntl.h>            /* Definition of AT_* constants */
#include <sys/time.h>

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

Feature Test Macro Requirements for glibc (peep feature_test_macros(7) if you're nosy 👀):

futimesat():
    _GNU_SOURCE

bestie. see that [[deprecated]] sitting right there in the signature? that's not a vibe, that's a warning label. the compiler is side-eyeing you fr fr 💀

🌸 DESCRIPTION 🌸

okay so first thing first, and I need you to hear me on this one:

This system call is obsolete. Use utimensat(2) instead.

periodt. that's the whole assignment. she's retired, she's living her best life in the man-pages archives, and there's a newer, shinier syscall doing her job.

but if you're here for the lore (respect, honestly), the futimesat() system call operates in exactly the same way as utimes(2), except for the differences described in this manual page. so like… same energy, tiny plot twists ✨

the twists:

• If path is relative, then it is interpreted relative to the directory referred to by the file descriptor dirfd — not relative to the current working directory of the calling process, which is what utimes(2) does for a relative pathname. she does things her way, with her dirfd 👑
• If path is relative and dirfd is the special value AT_FDCWD, then path is interpreted relative to the current working directory of the calling process (just like utimes(2) does it — so, the classic behaviour, no notes).
• If path is absolute, then dirfd is ignored. like, fully ghosted. (If you're sitting there like "why does dirfd even exist then??", go read openat(2) for an explanation of why the dirfd argument is useful. she explains everything, she's so good to us 🫶)

---

🦋 RETURN VALUE 🦋

• On success, futimesat() returns a 0. slay.
• On error, -1 is returned and errno is set to indicate the error. not slay, but informative 💀

💜 ERRORS 💜

The same errors that occur for utimes(2) can also occur for futimesat(). so if you already know utimes(2)'s drama, you know hers — it's a shared trauma kind of situation 😭

The following additional errors can occur for futimesat():

• EBADF — path is relative but dirfd is neither AT_FDCWD nor a valid file descriptor. girl, that's not a directory fd, that's ✨nothing✨
• ENOTDIR — path is relative and dirfd is a file descriptor referring to a file other than a directory. the audacity of a regular file trying to act like a directory smh, we don't do that here 🙈

🌈 VERSIONS 🌈

🧚 glibc 🧚

If path is NULL, then the glibc futimesat() wrapper function updates the times for the file referred to by dirfd.

yes bestie, NULL path is a real thing here. that's the little glibc-exclusive party trick 🎀

⭐ STANDARDS ⭐

None.

not a POSIX girlie, not an ISO girlie, just out here existing on vibes alone. literally no standard claims her. it's giving independent 🦋

👑 HISTORY 👑

Linux 2.6.16, glibc 2.4.

she's been around. she was implemented from a specification that was proposed for POSIX.1, but that specification was replaced by the one for utimensat(2). so she got drafted, then the draft got replaced, and now she's on the deprecated list. character development, honestly 😭

A similar system call exists on Solaris. (hi Solaris, we see you 💖)

💀 NOTES 💀

...it's giving empty. bestie there is genuinely nothing in this section. no cap. we're just here, standing in the notes section, vibing in silence 🕳️✨

🔥 SEE ALSO 🔥

• stat(2)
• utimensat(2)
• utimes(2)
• futimes(3)
• path_resolution(7)

---

and that's the whole page, bestie! 🎀 one last thing before you go: this little masterpiece came from Linux man-pages 6.20, dated 2026-02-08 — so go thank the man-pages girlies for their service, and go use utimensat(2) instead of this one, fr fr. mwah 💅💖