[libc-commits] [libc] [libc] Implement futimens (PR #222251)
Anirudh Mathur via libc-commits
libc-commits at lists.llvm.org
Wed Sep 9 00:06:05 PDT 2026
https://github.com/AnirudhMathur12 created https://github.com/llvm/llvm-project/pull/222251
futimens(fd, times) is implemented on Linux by delegating to utimensat(fd, NULL, times, 0), matching the approach used by glibc.
Fixes #220764
>From 823dc63b7449cf0ef91f54489a1eb5c884cbe285 Mon Sep 17 00:00:00 2001
From: AnirudhMathur12 <anirudhmathur12 at gmail.com>
Date: Wed, 9 Sep 2026 12:23:17 +0530
Subject: [PATCH] [libc] Implement futimens
futimens(fd, times) is implemented on Linux by delegating to
utimensat(fd, NULL, times, 0), matching the approach used by glibc.
Fixes #220764
---
libc/config/linux/aarch64/entrypoints.txt | 1 +
libc/config/linux/riscv/entrypoints.txt | 1 +
libc/config/linux/x86_64/entrypoints.txt | 1 +
libc/src/sys/stat/CMakeLists.txt | 7 ++
libc/src/sys/stat/futimens.h | 19 ++++
libc/src/sys/stat/linux/CMakeLists.txt | 13 +++
libc/src/sys/stat/linux/futimens.cpp | 26 +++++
libc/test/src/sys/stat/CMakeLists.txt | 22 ++++
libc/test/src/sys/stat/futimens_test.cpp | 131 ++++++++++++++++++++++
9 files changed, 221 insertions(+)
create mode 100644 libc/src/sys/stat/futimens.h
create mode 100644 libc/src/sys/stat/linux/futimens.cpp
create mode 100644 libc/test/src/sys/stat/futimens_test.cpp
diff --git a/libc/config/linux/aarch64/entrypoints.txt b/libc/config/linux/aarch64/entrypoints.txt
index fbd9239728bac..16271905c2430 100644
--- a/libc/config/linux/aarch64/entrypoints.txt
+++ b/libc/config/linux/aarch64/entrypoints.txt
@@ -343,6 +343,7 @@ set(TARGET_LIBC_ENTRYPOINTS
libc.src.sys.stat.mkdirat
libc.src.sys.stat.stat
libc.src.sys.stat.utimensat
+ libc.src.sys.stat.futimens
# sys/statfs.h entrypoints
libc.src.sys.statfs.fstatfs
diff --git a/libc/config/linux/riscv/entrypoints.txt b/libc/config/linux/riscv/entrypoints.txt
index bd906c6900008..a39590b55881e 100644
--- a/libc/config/linux/riscv/entrypoints.txt
+++ b/libc/config/linux/riscv/entrypoints.txt
@@ -374,6 +374,7 @@ set(TARGET_LIBC_ENTRYPOINTS
libc.src.sys.stat.mkdirat
libc.src.sys.stat.stat
libc.src.sys.stat.utimensat
+ libc.src.sys.stat.futimens
# sys/statfs.h entrypoints
libc.src.sys.statfs.fstatfs
diff --git a/libc/config/linux/x86_64/entrypoints.txt b/libc/config/linux/x86_64/entrypoints.txt
index e6aeb3abe0672..7c67f50b6f299 100644
--- a/libc/config/linux/x86_64/entrypoints.txt
+++ b/libc/config/linux/x86_64/entrypoints.txt
@@ -379,6 +379,7 @@ set(TARGET_LIBC_ENTRYPOINTS
libc.src.sys.stat.mkdirat
libc.src.sys.stat.stat
libc.src.sys.stat.utimensat
+ libc.src.sys.stat.futimens
# sys/statfs.h entrypoints
libc.src.sys.statfs.fstatfs
diff --git a/libc/src/sys/stat/CMakeLists.txt b/libc/src/sys/stat/CMakeLists.txt
index 6bc8ad64bd0df..c873814a6f9f0 100644
--- a/libc/src/sys/stat/CMakeLists.txt
+++ b/libc/src/sys/stat/CMakeLists.txt
@@ -64,3 +64,10 @@ add_entrypoint_object(
DEPENDS
.${LIBC_TARGET_OS}.utimensat
)
+
+add_entrypoint_object(
+ futimens
+ ALIAS
+ DEPENDS
+ .${LIBC_TARGET_OS}.futimens
+)
diff --git a/libc/src/sys/stat/futimens.h b/libc/src/sys/stat/futimens.h
new file mode 100644
index 0000000000000..17248c278f49b
--- /dev/null
+++ b/libc/src/sys/stat/futimens.h
@@ -0,0 +1,19 @@
+//===-- Implementation header for futimens ---------------------*- C++ -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_LIBC_SRC_SYS_STAT_FUTIMENS_H
+#define LLVM_LIBC_SRC_SYS_STAT_FUTIMENS_H
+
+#include "hdr/types/struct_timespec.h"
+#include "src/__support/macros/config.h"
+
+namespace LIBC_NAMESPACE_DECL {
+int futimens(int fd, const struct timespec times[2]);
+} // namespace LIBC_NAMESPACE_DECL
+
+#endif // LLVM_LIBC_SRC_SYS_STAT_FUTIMENS_H
diff --git a/libc/src/sys/stat/linux/CMakeLists.txt b/libc/src/sys/stat/linux/CMakeLists.txt
index 271cdccc42f60..1722fd501e5a3 100644
--- a/libc/src/sys/stat/linux/CMakeLists.txt
+++ b/libc/src/sys/stat/linux/CMakeLists.txt
@@ -114,3 +114,16 @@ add_entrypoint_object(
libc.src.__support.common
libc.src.__support.libc_errno
)
+
+add_entrypoint_object(
+ futimens
+ SRCS
+ futimens.cpp
+ HDRS
+ ../futimens.h
+ DEPENDS
+ libc.hdr.types.struct_timespec
+ libc.src.__support.OSUtil.linux.syscall_wrappers.utimensat
+ libc.src.__support.common
+ libc.src.__support.libc_errno
+)
diff --git a/libc/src/sys/stat/linux/futimens.cpp b/libc/src/sys/stat/linux/futimens.cpp
new file mode 100644
index 0000000000000..fb96b6f52742a
--- /dev/null
+++ b/libc/src/sys/stat/linux/futimens.cpp
@@ -0,0 +1,26 @@
+//===-- Linux implementation of futimens ---------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "src/sys/stat/futimens.h"
+
+#include "src/__support/OSUtil/linux/syscall_wrappers/utimensat.h"
+#include "src/__support/common.h"
+#include "src/__support/libc_errno.h"
+#include "src/__support/macros/config.h"
+
+namespace LIBC_NAMESPACE_DECL {
+LLVM_LIBC_FUNCTION(int, futimens, (int fd, const struct timespec times[2])) {
+ auto result = linux_syscalls::utimensat(fd, nullptr, times, 0);
+ if (!result.has_value()) {
+ libc_errno = result.error();
+ return -1;
+ }
+
+ return result.value();
+}
+} // namespace LIBC_NAMESPACE_DECL
diff --git a/libc/test/src/sys/stat/CMakeLists.txt b/libc/test/src/sys/stat/CMakeLists.txt
index 8b6aba7c99a86..11b81351a00d0 100644
--- a/libc/test/src/sys/stat/CMakeLists.txt
+++ b/libc/test/src/sys/stat/CMakeLists.txt
@@ -153,3 +153,25 @@ add_libc_test(
libc.test.UnitTest.ErrnoCheckingTest
libc.test.UnitTest.ErrnoSetterMatcher
)
+
+add_libc_test(
+ futimens_test
+ SUITE
+ libc_sys_stat_unittests
+ SRCS
+ futimens_test.cpp
+ DEPENDS
+ libc.hdr.fcntl_macros
+ libc.hdr.sys_stat_macros
+ libc.hdr.types.struct_timespec
+ libc.hdr.sys_stat_macros
+ libc.hdr.types.struct_stat
+ libc.src.errno.errno
+ libc.src.sys.stat.futimens
+ libc.src.fcntl.open
+ libc.src.sys.stat.stat
+ libc.src.unistd.close
+ libc.src.stdio.remove
+ libc.test.UnitTest.ErrnoCheckingTest
+ libc.test.UnitTest.ErrnoSetterMatcher
+)
diff --git a/libc/test/src/sys/stat/futimens_test.cpp b/libc/test/src/sys/stat/futimens_test.cpp
new file mode 100644
index 0000000000000..268ebb829b12e
--- /dev/null
+++ b/libc/test/src/sys/stat/futimens_test.cpp
@@ -0,0 +1,131 @@
+//===-- Unittests for futimens ---------------------------------------------===/
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "hdr/fcntl_macros.h"
+#include "hdr/sys_stat_macros.h"
+#include "hdr/types/struct_timespec.h"
+#include "src/fcntl/open.h"
+#include "src/stdio/remove.h"
+#include "src/sys/stat/futimens.h"
+#include "src/sys/stat/stat.h"
+#include "src/unistd/close.h"
+
+#include "test/UnitTest/ErrnoCheckingTest.h"
+#include "test/UnitTest/ErrnoSetterMatcher.h"
+#include "test/UnitTest/Test.h"
+
+using LlvmLibcFutimensTest = LIBC_NAMESPACE::testing::ErrnoCheckingTest;
+
+// SUCCESS: Takes an open file descriptor and successfully updates
+// its last access and modified times.
+TEST_F(LlvmLibcFutimensTest, ChangeTimesSpecific) {
+ using LIBC_NAMESPACE::testing::ErrnoSetterMatcher::Succeeds;
+
+ constexpr const char *FILE_PATH = "futimens_pass.test";
+ auto TEST_FILE = libc_make_test_file_path(FILE_PATH);
+ int fd = LIBC_NAMESPACE::open(TEST_FILE, O_WRONLY | O_CREAT, S_IRWXU);
+ ASSERT_ERRNO_SUCCESS();
+ ASSERT_GT(fd, 0);
+
+ // make a dummy timespec struct
+ struct timespec times[2];
+ times[0].tv_sec = 54321;
+ times[0].tv_nsec = 12345000;
+ times[1].tv_sec = 43210;
+ times[1].tv_nsec = 23456000;
+
+ // ensure futimens succeeds, operating on the fd directly
+ ASSERT_THAT(LIBC_NAMESPACE::futimens(fd, times), Succeeds(0));
+
+ ASSERT_THAT(LIBC_NAMESPACE::close(fd), Succeeds(0));
+
+ // verify the times values against stat of the TEST_FILE
+ struct stat statbuf;
+ ASSERT_EQ(LIBC_NAMESPACE::stat(TEST_FILE, &statbuf), 0);
+
+ // seconds
+ ASSERT_EQ(statbuf.st_atim.tv_sec, times[0].tv_sec);
+ ASSERT_EQ(statbuf.st_mtim.tv_sec, times[1].tv_sec);
+
+ // nanoseconds
+ ASSERT_EQ(statbuf.st_atim.tv_nsec, times[0].tv_nsec);
+ ASSERT_EQ(statbuf.st_mtim.tv_nsec, times[1].tv_nsec);
+
+ ASSERT_THAT(LIBC_NAMESPACE::remove(TEST_FILE), Succeeds(0));
+}
+
+// FAILURE: Invalid values in the timespec struct
+// to check that futimens rejects it.
+TEST_F(LlvmLibcFutimensTest, InvalidNanoseconds) {
+ using LIBC_NAMESPACE::testing::ErrnoSetterMatcher::Fails;
+ using LIBC_NAMESPACE::testing::ErrnoSetterMatcher::Succeeds;
+
+ constexpr const char *FILE_PATH = "futimens_fail.test";
+ auto TEST_FILE = libc_make_test_file_path(FILE_PATH);
+ int fd = LIBC_NAMESPACE::open(TEST_FILE, O_WRONLY | O_CREAT, S_IRWXU);
+ ASSERT_GT(fd, 0);
+
+ // make a dummy timespec struct
+ // populated with bad nsec values
+ struct timespec times[2];
+ times[0].tv_sec = 54321;
+ times[0].tv_nsec = 4567;
+ times[1].tv_sec = 43210;
+ times[1].tv_nsec = 1000000000; // invalid
+
+ // ensure futimens fails
+ ASSERT_THAT(LIBC_NAMESPACE::futimens(fd, times), Fails(EINVAL));
+
+ // check for failure on
+ // the other possible bad values
+ times[0].tv_sec = 54321;
+ times[0].tv_nsec = -4567; // invalid
+ times[1].tv_sec = 43210;
+ times[1].tv_nsec = 1000;
+
+ // ensure futimens fails once more
+ ASSERT_THAT(LIBC_NAMESPACE::futimens(fd, times), Fails(EINVAL));
+
+ ASSERT_THAT(LIBC_NAMESPACE::close(fd), Succeeds(0));
+ ASSERT_THAT(LIBC_NAMESPACE::remove(TEST_FILE), Succeeds(0));
+}
+
+// SUCCESS: Test UTIME_NOW and UTIME_OMIT macros
+TEST_F(LlvmLibcFutimensTest, UtimeNowAndOmit) {
+ using LIBC_NAMESPACE::testing::ErrnoSetterMatcher::Succeeds;
+
+ constexpr const char *FILE_PATH = "futimens_now.test";
+ auto TEST_FILE = libc_make_test_file_path(FILE_PATH);
+ int fd = LIBC_NAMESPACE::open(TEST_FILE, O_WRONLY | O_CREAT, S_IRWXU);
+ ASSERT_GT(fd, 0);
+ ASSERT_ERRNO_SUCCESS();
+
+ struct timespec times[2];
+ times[0].tv_sec = 0;
+ times[0].tv_nsec = UTIME_NOW;
+ times[1].tv_sec = 0;
+ times[1].tv_nsec = UTIME_OMIT;
+
+ ASSERT_THAT(LIBC_NAMESPACE::futimens(fd, times), Succeeds(0));
+
+ ASSERT_THAT(LIBC_NAMESPACE::close(fd), Succeeds(0));
+ ASSERT_THAT(LIBC_NAMESPACE::remove(TEST_FILE), Succeeds(0));
+}
+
+// FAILURE: Bad file descriptor should return EBADF
+TEST_F(LlvmLibcFutimensTest, BadFileDescriptor) {
+ using LIBC_NAMESPACE::testing::ErrnoSetterMatcher::Fails;
+
+ struct timespec times[2];
+ times[0].tv_sec = 0;
+ times[0].tv_nsec = UTIME_NOW;
+ times[1].tv_sec = 0;
+ times[1].tv_nsec = UTIME_NOW;
+
+ ASSERT_THAT(LIBC_NAMESPACE::futimens(-1, times), Fails(EBADF));
+}
More information about the libc-commits
mailing list