[libc-commits] [libc] [libc][docs] Document printf NULL handling for %s/%n (PR #180067)

[via libc-commits]

https://github.com/petbernt updated https://github.com/llvm/llvm-project/pull/180067

>From d75e7057313c86c506f6a7804fdddec237b72c37 Mon Sep 17 00:00:00 2001
From: Petter Berntsson <petter.berntsson at arm.com>
Date: Wed, 4 Feb 2026 17:39:12 +0000
Subject: [PATCH] [libc][docs] Document printf NULL handling for %s/%n

- Fix printf_behavior to describe NULL %s as printing "(null)" when nullptr checks are enabled
- Point undefined_behavior NULL %s/%n entry at LIBC_COPT_PRINTF_NO_NULLPTR_CHECKS
- Add Sphinx labels to link directly to the flag and Conversion sections
---
 libc/docs/dev/printf_behavior.rst    | 10 ++++++++--
 libc/docs/dev/undefined_behavior.rst | 12 +++++-------
 2 files changed, 13 insertions(+), 9 deletions(-)

diff --git a/libc/docs/dev/printf_behavior.rst b/libc/docs/dev/printf_behavior.rst
index ba0578aee3fd8..a825da55367bb 100644
--- a/libc/docs/dev/printf_behavior.rst
+++ b/libc/docs/dev/printf_behavior.rst
@@ -78,9 +78,13 @@ conversions will be ignored. This reduces code size. This will be set by default
 on windows platforms as current printf implementation does not support UTF-16 wide
 characters.
 
+.. _printf_no_nullptr_checks:
+
 LIBC_COPT_PRINTF_NO_NULLPTR_CHECKS
 ----------------------------------
-When set, this flag disables the nullptr checks in %n and %s.
+When set, this flag disables the nullptr checks in %n and %s; passing a null
+pointer is undefined behavior. See :ref:`printf_conversion` for the behavior
+when nullptr checks are enabled.
 
 LIBC_COPT_PRINTF_CONV_ATLAS
 ---------------------------
@@ -188,6 +192,8 @@ If a number passed as a bit width is less than or equal to zero, the conversion
 is considered invalid. If the provided bit width is larger than the width of
 uintmax_t, it will be clamped to the width of uintmax_t.
 
+.. _printf_conversion:
+
 ----------
 Conversion
 ----------
@@ -199,7 +205,7 @@ If a conversion specification ends in %, then it will be treated as if it is
 "%%", ignoring all options.
 
 If a null pointer is passed to a %s conversion specification and null pointer
-checks are enabled, it will be treated as if the provided string is "null".
+checks are enabled, it will be treated as if the provided string is "(null)".
 
 If a null pointer is passed to a %n conversion specification and null pointer
 checks are enabled, the conversion will fail and printf will return a negative
diff --git a/libc/docs/dev/undefined_behavior.rst b/libc/docs/dev/undefined_behavior.rst
index 4f8ac22919b0a..d0cd4c9c921a9 100644
--- a/libc/docs/dev/undefined_behavior.rst
+++ b/libc/docs/dev/undefined_behavior.rst
@@ -75,13 +75,11 @@ Path without Leading Slashs in shm_open
 ----------------------------------------
 POSIX.1 leaves that when the name of a shared memory object does not begin with a slash, the behavior is implementation defined. In such cases, the shm_open in LLVM libc is implemented to behave as if the name began with a slash.
 
-Handling of NULL arguments to the 's' format specifier
-------------------------------------------------------
-The C standard does not specify behavior for ``printf("%s", NULL)``. We will
-print the string literal ``(null)`` unless using the
-``LIBC_COPT_PRINTF_NO_NULLPTR_CHECKS`` option described in :ref:`printf
-behavior<printf_behavior>`.
-TODO: Move this to printf_behavior.
+Handling of NULL arguments to the 's' and 'n' format specifiers
+---------------------------------------------------------------
+The C standard does not specify behavior for ``printf("%s", NULL)`` or
+``printf("%n", NULL)``. For LLVM-libc, see
+:ref:`LIBC_COPT_PRINTF_NO_NULLPTR_CHECKS <printf_no_nullptr_checks>` for details.
 
 Unknown Math Rounding Direction
 -------------------------------