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

petbernt · web-flow · commit 30533d07578e · 2026-02-06T15:40:50.000Z
- 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
diff --git 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
@@ -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
 -------------------------------
