[libc-commits] [libc] [libc] Add tmpnam implementation (PR #204901)
Shubh Pachchigar via libc-commits
libc-commits at lists.llvm.org
Tue Jun 23 14:01:46 PDT 2026
https://github.com/shubhe25p updated https://github.com/llvm/llvm-project/pull/204901
>From 2a2db4eba4924d62e979909059db11a6e73ceb04 Mon Sep 17 00:00:00 2001
From: shubhe25p <shubhp at Mac.lan>
Date: Tue, 23 Jun 2026 14:00:59 -0700
Subject: [PATCH] [libc] Add tmpnam implementation
Implements tmpnam per the POSIX specification and adds
unit tests.
---
libc/config/linux/x86_64/entrypoints.txt | 1 +
libc/include/llvm-libc-macros/stdio-macros.h | 93 ++++++++++++
libc/include/stdio.yaml | 6 +
libc/src/stdio/CMakeLists.txt | 15 ++
libc/src/stdio/tmpnam.cpp | 79 ++++++++++
libc/src/stdio/tmpnam.h | 28 ++++
libc/test/src/stdio/CMakeLists.txt | 12 ++
libc/test/src/stdio/tmpnam_test.cpp | 150 +++++++++++++++++++
8 files changed, 384 insertions(+)
create mode 100644 libc/src/stdio/tmpnam.cpp
create mode 100644 libc/src/stdio/tmpnam.h
create mode 100644 libc/test/src/stdio/tmpnam_test.cpp
diff --git a/libc/config/linux/x86_64/entrypoints.txt b/libc/config/linux/x86_64/entrypoints.txt
index ce88a6749d9dc..a684f8930494b 100644
--- a/libc/config/linux/x86_64/entrypoints.txt
+++ b/libc/config/linux/x86_64/entrypoints.txt
@@ -1356,6 +1356,7 @@ if(LLVM_LIBC_FULL_BUILD)
libc.src.stdio.stdin
libc.src.stdio.stdout
libc.src.stdio.ungetc
+ libc.src.stdio.tmpnam
# stdlib.h entrypoints
libc.src.stdlib._Exit
diff --git a/libc/include/llvm-libc-macros/stdio-macros.h b/libc/include/llvm-libc-macros/stdio-macros.h
index 96f0e6933ade6..c15294ef65672 100644
--- a/libc/include/llvm-libc-macros/stdio-macros.h
+++ b/libc/include/llvm-libc-macros/stdio-macros.h
@@ -54,5 +54,98 @@ extern FILE *stderr;
#ifndef SEEK_END
#define SEEK_END 2
#endif
+/*
+ * Derivation of L_tmpnam
+ * ------------------------------------------------------------
+ *
+ * Generated pathnames have the form: /tmp/XXXXXXXXXXXXXX
+ * - "/tmp/" is a 5-byte prefix.
+ * - N random characters follow, drawn independently and uniformly from
+ * a 65-character alphabet (the POSIX portable filename character set)
+ * - 1 byte for the NULL terminator.
+ * So: L_tmpnam = 5 + N + 1.
+ *
+ * Choosing N: we want the probability of two independently generated
+ * suffixes colliding to stay below a target threshold P, even after up to
+ * k calls to tmpnam() over the lifetime of a process.
+ *
+ * Let M = 65^N be the keyspace which is the total number of distinct
+ * N-character suffixes that can be generated (NOT the number actually
+ * generated; M is the size of the space they are drawn from).
+ *
+ * Among k calls, the number of distinct pairs of calls is:
+ * C(k, 2) = k(k-1)/2 ~= k^2 / 2 (approximation valid for large k)
+ *
+ * Each individual pair collides (picks the identical suffix) with
+ * probability 1/M, since each call draws independently and uniformly from
+ * the M possible suffixes.
+ *
+ * Treating pairwise collisions as approximately independent low-probability
+ * events, the probability that AT LEAST ONE collision occurs among all
+ * pairs is approximately the sum over all pairs of the per-pair probability:
+ *
+ * P ~= (k^2 / 2) * (1 / M) = k^2 / (2M)
+ *
+ * This is the standard birthday-bound approximation.
+ *
+ * Solving for the keyspace required to keep P under a chosen target, given
+ * an assumed call-volume ceiling k:
+ *
+ * M >= k^2 / (2P)
+ *
+ * Design inputs (stated, not borrowed):
+ * k = 10^6 (one million calls: a generous upper bound on how many
+ * times a single long-running process could realistically
+ * call tmpnam() in its lifetime)
+ * P = 10^-12 (one-in-a-trillion target collision probability)
+ *
+ * Required keyspace:
+ * M >= (10^6)^2 / (2 * 10^-12) = 5 x 10^23
+ *
+ * Solving 65^N >= 5x10^23 for N:
+ * N >= log_65(5x10^23) ~= 14 (round up)
+ *
+ * Verification with N = 14:
+ * M = 65^14 ~= 2.40 x 10^25
+ * Actual P at k = 10^6: k^2 / (2M) ~= 2.08 x 10^-14
+ * (about 48x more conservative than the 10^-12 target -- the integer
+ * rounding of N gives us comfortable extra margin for free.)
+ *
+ * Therefore:
+ * N = 14
+ * L_tmpnam = 5 (prefix) + 14 (suffix) + 1 (NULL) = 20
+ */
+#ifndef L_tmpnam
+#define L_tmpnam 20
+#endif
+/*
+ * TMP_MAX:
+ * ---------
+ * TMP_MAX is a separate policy decision, that states the call-volume ceiling
+ * for which we are willing to stand behind the P = 10^-12 collision-probability
+ * guarantee derived above. Per POSIX, behavior beyond TMP_MAX calls in a single
+ * process is implementation-defined; we simply decline to make any guarantee
+ * past this point, even though the keyspace could technically support more.
+ *
+ * TMP_MAX = 1,000,000
+ *
+ * This is chosen as a round, easily-reasoned-about figure equal to the k
+ * used in the derivation above.
+ *
+ * Note on glibc's TMP_MAX = 238328: this value has no documented derivation.
+ * A glibc/gnulib contributor publicly stated in 2001 that the figure's
+ * origin is unknown and "as good as any other number larger than a couple
+ * of thousand" (bug-textutils mailing list, Oct 26 2001:
+ * https://lists.gnu.org/archive/html/bug-textutils/2001-10/msg00032.html).
+ * We do not inherit this value; the derivation above is independent and
+ * stated in full above.
+ */
+#ifndef TMP_MAX
+#define TMP_MAX 1000000
+#endif
+
+#ifndef P_tmpdir
+#define P_tmpdir "/tmp"
+#endif
#endif // LLVM_LIBC_MACROS_STDIO_MACROS_H
diff --git a/libc/include/stdio.yaml b/libc/include/stdio.yaml
index 4b12698e2484d..aaa1fec8eac61 100644
--- a/libc/include/stdio.yaml
+++ b/libc/include/stdio.yaml
@@ -396,6 +396,12 @@ functions:
- type: const char *__restrict
- type: const char *__restrict
- type: '...'
+ - name: tmpnam
+ standards:
+ - stdc
+ return_type: char *
+ arguments:
+ - type: char *
- name: ungetc
standards:
- stdc
diff --git a/libc/src/stdio/CMakeLists.txt b/libc/src/stdio/CMakeLists.txt
index feee8d60d1c60..f8375a2a7905a 100644
--- a/libc/src/stdio/CMakeLists.txt
+++ b/libc/src/stdio/CMakeLists.txt
@@ -243,6 +243,21 @@ add_entrypoint_object(
.${LIBC_TARGET_OS}.remove
)
+add_entrypoint_object(
+ tmpnam
+ SRCS
+ tmpnam.cpp
+ HDRS
+ tmpnam.h
+ DEPENDS
+ libc.hdr.stdio_macros
+ libc.hdr.errno_macros
+ libc.src.stdio.snprintf
+ libc.src.__support.CPP.atomic
+ libc.hdr.unistd_macros
+ libc.src.__support.OSUtil.osutil
+)
+
add_entrypoint_object(
rename
ALIAS
diff --git a/libc/src/stdio/tmpnam.cpp b/libc/src/stdio/tmpnam.cpp
new file mode 100644
index 0000000000000..34e86da9c7d16
--- /dev/null
+++ b/libc/src/stdio/tmpnam.cpp
@@ -0,0 +1,79 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+///
+/// \file
+/// Declaration of tmpnam, a POSIX function that generate a string that is a
+/// valid pathname that does not name an existing file.
+/// See:
+/// https://pubs.opengroup.org/onlinepubs/9799919799/functions/tmpnam.html
+///
+//===----------------------------------------------------------------------===//
+
+#include "src/stdio/tmpnam.h"
+#include "hdr/errno_macros.h"
+#include "hdr/stdio_macros.h"
+#include "hdr/unistd_macros.h"
+#include "src/__support/CPP/atomic.h"
+#include "src/__support/OSUtil/linux/syscall_wrappers/access.h"
+#include "src/__support/OSUtil/linux/syscall_wrappers/getrandom.h"
+#include "src/__support/macros/config.h"
+#include "src/stdio/snprintf.h"
+
+namespace LIBC_NAMESPACE_DECL {
+
+static char tmpbuf[L_tmpnam];
+static cpp::Atomic<size_t> tmpnam_budget = TMP_MAX;
+
+/* partially thread-safe */
+LLVM_LIBC_FUNCTION(char *, tmpnam, (char *s)) {
+ if (s == nullptr)
+ s = tmpbuf;
+
+ // here if the s is null then use tmpbuf and if sizeof
+ // POSIX portable filename character set, sorted by ASCII value.
+ // See
+ // https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap03.html#tag_03_265
+ const char charset[] = "-._0123456789"
+ "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+ "abcdefghijklmnopqrstuvwxyz";
+
+ int prefix_size = LIBC_NAMESPACE::snprintf(s, L_tmpnam, "%s/", P_tmpdir);
+
+ bool is_unique = false;
+ while (!is_unique) {
+ size_t curr_budget = tmpnam_budget.load(cpp::MemoryOrder::RELAXED);
+
+ do {
+ if (curr_budget == 0)
+ break;
+ } while (
+ !tmpnam_budget.compare_exchange_strong(curr_budget, curr_budget - 1));
+
+ if (curr_budget == 0)
+ break;
+
+ for (size_t i = prefix_size; i < L_tmpnam - 1; i++) {
+ uint8_t rand_byte;
+ auto ret = linux_syscalls::getrandom(&rand_byte, 1, 0);
+ if (!ret.has_value()) {
+ /* return nullptr when getrandom fails but consume tmpnam budget */
+ return nullptr;
+ }
+ s[i] = charset[rand_byte % (sizeof(charset) - 1)];
+ }
+ s[L_tmpnam - 1] = '\0';
+ auto res = linux_syscalls::access(s, F_OK);
+ is_unique = res.has_value() ? false : true;
+ }
+
+ if (is_unique)
+ return s;
+
+ return nullptr; /* if we exhaust budget we return */
+}
+} // namespace LIBC_NAMESPACE_DECL
diff --git a/libc/src/stdio/tmpnam.h b/libc/src/stdio/tmpnam.h
new file mode 100644
index 0000000000000..38d40d17a8a55
--- /dev/null
+++ b/libc/src/stdio/tmpnam.h
@@ -0,0 +1,28 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+///
+/// \file
+/// Declaration of tmpnam, a POSIX function that generate a string that is a
+/// valid pathname that does not name an existing file.
+/// See:
+/// https://pubs.opengroup.org/onlinepubs/9799919799/functions/tmpnam.html
+///
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_LIBC_SRC_STDIO_TMPNAM_H
+#define LLVM_LIBC_SRC_STDIO_TMPNAM_H
+
+#include "src/__support/macros/config.h"
+
+namespace LIBC_NAMESPACE_DECL {
+
+char *tmpnam(char *s);
+
+} // namespace LIBC_NAMESPACE_DECL
+
+#endif // LLVM_LIBC_SRC_STDIO_TMPNAM_H
diff --git a/libc/test/src/stdio/CMakeLists.txt b/libc/test/src/stdio/CMakeLists.txt
index 9737dcba7f904..9e5a2b001b12b 100644
--- a/libc/test/src/stdio/CMakeLists.txt
+++ b/libc/test/src/stdio/CMakeLists.txt
@@ -599,6 +599,18 @@ add_libc_test(
libc.src.stdio.setvbuf
)
+add_libc_test(
+ tmpnam_test
+ SUITE
+ libc_stdio_unittests
+ SRCS
+ tmpnam_test.cpp
+ DEPENDS
+ libc.src.stdio.tmpnam
+ libc.src.__support.CPP.string_view
+ libc.hdr.stdio_macros
+)
+
# Create an output directory for any temporary test files.
file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/testdata)
diff --git a/libc/test/src/stdio/tmpnam_test.cpp b/libc/test/src/stdio/tmpnam_test.cpp
new file mode 100644
index 0000000000000..23e645b3c4e69
--- /dev/null
+++ b/libc/test/src/stdio/tmpnam_test.cpp
@@ -0,0 +1,150 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+///
+/// \file
+/// Tests for tmpnam
+/// See: https://pubs.opengroup.org/onlinepubs/9799919799/functions/tmpnam.html
+///
+//===----------------------------------------------------------------------===//
+#include "src/stdio/tmpnam.h"
+
+#include "hdr/stdio_macros.h"
+#include "src/__support/CPP/string_view.h"
+#include "src/__support/macros/config.h"
+#include "test/UnitTest/Test.h"
+
+#include <stddef.h> // size_t
+
+namespace {
+
+using LIBC_NAMESPACE::cpp::string_view;
+
+// The portable filename character set the implementation draws from, plus the
+// '/' that appears in the P_tmpdir prefix. Any byte in a returned name must be
+// one of these.
+constexpr char kAllowed[] = "-._/"
+ "0123456789"
+ "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+ "abcdefghijklmnopqrstuvwxyz";
+
+bool only_allowed_chars(string_view sv) {
+ for (char c : sv) {
+ bool found = false;
+ for (size_t i = 0; kAllowed[i] != '\0'; ++i) {
+ if (c == kAllowed[i]) {
+ found = true;
+ break;
+ }
+ }
+ if (!found)
+ return false;
+ }
+ return true;
+}
+
+} // namespace
+
+// Caller-supplied buffer: the spec requires the return value to be exactly the
+// argument pointer, the string to be null-terminated within L_tmpnam bytes,
+// and the result to begin with the temp-dir prefix.
+TEST(LlvmLibcTmpnamTest, NonNullBufferReturnsSamePointer) {
+ char buf[L_tmpnam];
+ char *result = LIBC_NAMESPACE::tmpnam(buf);
+ ASSERT_EQ(result, buf);
+}
+
+TEST(LlvmLibcTmpnamTest, NonNullBufferIsNullTerminated) {
+ char buf[L_tmpnam];
+ char *result = LIBC_NAMESPACE::tmpnam(buf);
+ ASSERT_NE(result, static_cast<char *>(nullptr));
+ // A NULL must appear within the buffer bounds.
+ bool terminated = false;
+ for (size_t i = 0; i < L_tmpnam; ++i) {
+ if (result[i] == '\0') {
+ terminated = true;
+ break;
+ }
+ }
+ ASSERT_TRUE(terminated);
+}
+
+TEST(LlvmLibcTmpnamTest, ResultHasTempDirPrefix) {
+ char buf[L_tmpnam];
+ char *result = LIBC_NAMESPACE::tmpnam(buf);
+ ASSERT_NE(result, static_cast<char *>(nullptr));
+ string_view sv(result);
+ string_view prefix(P_tmpdir);
+ // P_tmpdir may not carry a trailing slash; the implementation always
+ // emits one separator, so check the directory portion is present at the head.
+ ASSERT_TRUE(sv.starts_with(prefix));
+}
+
+TEST(LlvmLibcTmpnamTest, ResultUsesOnlyPortableChars) {
+ char buf[L_tmpnam];
+ char *result = LIBC_NAMESPACE::tmpnam(buf);
+ ASSERT_NE(result, static_cast<char *>(nullptr));
+ ASSERT_TRUE(only_allowed_chars(string_view(result)));
+}
+
+// Null argument: the result lives in an internal static object; the returned
+// pointer must be non-null and carry the same structural guarantees.
+TEST(LlvmLibcTmpnamTest, NullBufferReturnsInternalObject) {
+ char *result = LIBC_NAMESPACE::tmpnam(nullptr);
+ ASSERT_NE(result, static_cast<char *>(nullptr));
+ string_view sv(result);
+ ASSERT_TRUE(sv.starts_with(string_view(P_tmpdir)));
+ ASSERT_TRUE(only_allowed_chars(sv));
+}
+
+// The core contract: the generated name must not already exist on disk.
+// We re-check existence here via the public access() entry point if available.
+TEST(LlvmLibcTmpnamTest, ResultLengthWithinBound) {
+ char buf[L_tmpnam];
+ char *result = LIBC_NAMESPACE::tmpnam(buf);
+ ASSERT_NE(result, static_cast<char *>(nullptr));
+ string_view sv(result);
+ ASSERT_LT(sv.size(), static_cast<size_t>(L_tmpnam));
+ // Must be strictly longer than the prefix: a prefix with no random suffix
+ // would mean the generator produced an empty suffix.
+ ASSERT_GT(sv.size(), string_view(P_tmpdir).size());
+}
+
+// Successive calls should produce distinct strings.
+TEST(LlvmLibcTmpnamTest, SuccessiveCallsDiffer) {
+ char a[L_tmpnam];
+ char b[L_tmpnam];
+ char *ra = LIBC_NAMESPACE::tmpnam(a);
+ char *rb = LIBC_NAMESPACE::tmpnam(b);
+ ASSERT_NE(ra, static_cast<char *>(nullptr));
+ ASSERT_NE(rb, static_cast<char *>(nullptr));
+ ASSERT_FALSE(string_view(ra) == string_view(rb));
+}
+
+// Two calls with a null argument must return the SAME pointer (the address of
+// the single internal static object) The contents, however, are overwritten by
+// the second call.
+TEST(LlvmLibcTmpnamTest, NullCallsShareObjectButDifferInContent) {
+ char *first = LIBC_NAMESPACE::tmpnam(nullptr);
+ ASSERT_NE(first, static_cast<char *>(nullptr));
+
+ // Snapshot the first result before it is overwritten.
+ char snapshot[L_tmpnam];
+ size_t i = 0;
+ for (; i < L_tmpnam && first[i] != '\0'; ++i)
+ snapshot[i] = first[i];
+ snapshot[i < L_tmpnam ? i : L_tmpnam - 1] = '\0';
+
+ char *second = LIBC_NAMESPACE::tmpnam(nullptr);
+ ASSERT_NE(second, static_cast<char *>(nullptr));
+
+ // Same backing object: identical address.
+ ASSERT_EQ(first, second);
+
+ // But the generated string changed
+ ASSERT_FALSE(string_view(snapshot) == string_view(second));
+}
More information about the libc-commits
mailing list