[libc][docgen] make note of sys/time.h interfaces removed in POSIX.1-2024

[nickdesaulniers]

One of these days, we'll be able to specify time to a computer...

Also, POSIX can remove stuff all they want. Folks probably will
continue to depend on broken interfaces forever.

Link: #124654
Link: https://austingroupbugs.net/view.php?id=1330

[llvmbot]

@llvm/pr-subscribers-libc

Author: Nick Desaulniers (nickdesaulniers)

Changes

One of these days, we'll be able to specify time to a computer...

Link: #124654

---

Full diff: https://github.com/llvm/llvm-project/pull/126612.diff

2 Files Affected:

• (modified) libc/utils/docgen/docgen.py (+5)
• (modified) libc/utils/docgen/sys/time.yaml (+6)

diff --git a/libc/utils/docgen/docgen.py b/libc/utils/docgen/docgen.py
index 09db284ef92824..5a57987b3c51e1 100755
--- a/libc/utils/docgen/docgen.py
+++ b/libc/utils/docgen/docgen.py
@@ -57,6 +57,7 @@ def check_api(header: Header, api: Dict):
         "c-definition",
         "in-latest-posix",
         "removed-in-posix-2008",
+        "removed-in-posix-2024",
     ]
 
     # Validate macros
@@ -140,6 +141,10 @@ def print_functions_rst(header: Header, functions: Dict):
             print(
                 f"    - `removed in POSIX.1-2008 <https://pubs.opengroup.org/onlinepubs/007904875/functions/{name}.html>`__"
             )
+        elif "removed-in-posix-2024" in functions[name]:
+            print(
+                f"    - `removed in POSIX.1-2024 <https://pubs.opengroup.org/onlinepubs/9699919799.2018edition/functions/{name}.html>`__"
+            )
         else:
             print("    -")
 
diff --git a/libc/utils/docgen/sys/time.yaml b/libc/utils/docgen/sys/time.yaml
index 1e3909adafea39..b7678f403cdcfd 100644
--- a/libc/utils/docgen/sys/time.yaml
+++ b/libc/utils/docgen/sys/time.yaml
@@ -3,3 +3,9 @@ functions:
     in-latest-posix: ''
   utimes:
     in-latest-posix: ''
+  getitimer:
+    removed-in-posix-2024: ''
+  gettimeofday:
+    removed-in-posix-2024: ''
+  setitimer:
+    removed-in-posix-2024: ''

[nickdesaulniers]

Deeper question here; do we want to document EVERY interface deprecated from POSIX?

I think for any given removed interface, a user could file a bug against llvm-libc, saying "where is X?" Having some context that this was REMOVED from POSIX is helpful perhaps for first party developers to better understand the bug; rather llvm-libc should implement this removed interface, or close as wontfix.

[enh-google]

One of these days, we'll be able to specify time to a computer...

Also, POSIX can remove stuff all they want. Folks probably will continue to depend on broken interfaces forever.

yeah: "define 'broken'".

i feel like the lesson i learned from the 2008 removals was a strong "i'm never doing that again". obviously things are a little different for me, where i already had implementations, but my experience has been that [in almost all cases] there's little or no benefit to removing these things, but [in almost all cases] you do cause unnecessary disruption and work for others (and/or inconvenience for users).