[libc++] Deprecates std::errc constants.

[mordante]

Implements:

• LWG3869 Deprecate std::errc constants related to UNIX STREAMS

[llvmbot]

@llvm/pr-subscribers-libcxx

Author: Mark de Wever (mordante)

Changes

Implements:

• LWG3869 Deprecate std::errc constants related to UNIX STREAMS

---

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

5 Files Affected:

• (modified) libcxx/include/__system_error/errc.h (+45-12)
• (modified) libcxx/include/cerrno (+13)
• (added) libcxx/test/std/depr.cerro/cerrno.syn.verify.cpp (+34)
• (added) libcxx/test/std/depr.cerro/system.error.syn.verify.cpp (+22)
• (modified) libcxx/test/std/diagnostics/syserr/errc.pass.cpp (+2)

diff --git a/libcxx/include/__system_error/errc.h b/libcxx/include/__system_error/errc.h
index f87df86a71e15..3d49cb186877f 100644
--- a/libcxx/include/__system_error/errc.h
+++ b/libcxx/include/__system_error/errc.h
@@ -58,18 +58,18 @@ enum class errc
     no_child_process,                   // ECHILD
     no_link,                            // ENOLINK
     no_lock_available,                  // ENOLCK
-    no_message_available,               // ENODATA
+    no_message_available,               // ENODATA         // deprecated
     no_message,                         // ENOMSG
     no_protocol_option,                 // ENOPROTOOPT
     no_space_on_device,                 // ENOSPC
-    no_stream_resources,                // ENOSR
+    no_stream_resources,                // ENOSR           // deprecated
     no_such_device_or_address,          // ENXIO
     no_such_device,                     // ENODEV
     no_such_file_or_directory,          // ENOENT
     no_such_process,                    // ESRCH
     not_a_directory,                    // ENOTDIR
     not_a_socket,                       // ENOTSOCK
-    not_a_stream,                       // ENOSTR
+    not_a_stream,                       // ENOSTR          // deprecated
     not_connected,                      // ENOTCONN
     not_enough_memory,                  // ENOMEM
     not_supported,                      // ENOTSUP
@@ -87,7 +87,7 @@ enum class errc
     resource_unavailable_try_again,     // EAGAIN
     result_out_of_range,                // ERANGE
     state_not_recoverable,              // ENOTRECOVERABLE
-    stream_timeout,                     // ETIME
+    stream_timeout,                     // ETIME           // deprecated
     text_file_busy,                     // ETXTBSY
     timed_out,                          // ETIMEDOUT
     too_many_files_open_in_system,      // ENFILE
@@ -113,6 +113,15 @@ _LIBCPP_BEGIN_NAMESPACE_STD
 // for them:
 
 // enum class errc
+//
+// LWG3869 deprecates the UNIX STREAMS macros and enum values.
+// This makes the code clumbersome:
+// - the enum value is deprecated and should show a diagnostic,
+// - the macro is deprecated and should _not_ show a diagnostic in this
+//   context, and
+// - the macro is not always available.
+// This leads to the odd pushing and popping of the deprecated
+// diagnostic.
 _LIBCPP_DECLARE_STRONG_ENUM(errc){
     address_family_not_supported       = EAFNOSUPPORT,
     address_in_use                     = EADDRINUSE,
@@ -154,30 +163,48 @@ _LIBCPP_DECLARE_STRONG_ENUM(errc){
     no_child_process                   = ECHILD,
     no_link                            = ENOLINK,
     no_lock_available                  = ENOLCK,
+    // clang-format off
+    no_message_available _LIBCPP_DEPRECATED =
+    _LIBCPP_SUPPRESS_DEPRECATED_PUSH
 #ifdef ENODATA
-    no_message_available = ENODATA,
+                                              ENODATA
 #else
-    no_message_available = ENOMSG,
+                                              ENOMSG
 #endif
+    _LIBCPP_SUPPRESS_DEPRECATED_POP
+		,
+    // clang-format on
     no_message         = ENOMSG,
     no_protocol_option = ENOPROTOOPT,
     no_space_on_device = ENOSPC,
+    // clang-format off
+    no_stream_resources _LIBCPP_DEPRECATED =
+    _LIBCPP_SUPPRESS_DEPRECATED_PUSH
 #ifdef ENOSR
-    no_stream_resources = ENOSR,
+                                              ENOSR
 #else
-    no_stream_resources = ENOMEM,
+                                              ENOMEM
 #endif
+    _LIBCPP_SUPPRESS_DEPRECATED_POP
+		,
+    // clang-format on
     no_such_device_or_address = ENXIO,
     no_such_device            = ENODEV,
     no_such_file_or_directory = ENOENT,
     no_such_process           = ESRCH,
     not_a_directory           = ENOTDIR,
     not_a_socket              = ENOTSOCK,
+    // clang-format off
+    _LIBCPP_SUPPRESS_DEPRECATED_PUSH
+    not_a_stream _LIBCPP_DEPRECATED =
 #ifdef ENOSTR
-    not_a_stream = ENOSTR,
+                                      ENOSTR
 #else
-    not_a_stream = EINVAL,
+                                      EINVAL
 #endif
+    _LIBCPP_SUPPRESS_DEPRECATED_POP
+		,
+    // clang-format on
     not_connected                  = ENOTCONN,
     not_enough_memory              = ENOMEM,
     not_supported                  = ENOTSUP,
@@ -195,11 +222,17 @@ _LIBCPP_DECLARE_STRONG_ENUM(errc){
     resource_unavailable_try_again = EAGAIN,
     result_out_of_range            = ERANGE,
     state_not_recoverable          = ENOTRECOVERABLE,
+    // clang-format off
+    _LIBCPP_SUPPRESS_DEPRECATED_PUSH
+    stream_timeout _LIBCPP_DEPRECATED =
 #ifdef ETIME
-    stream_timeout = ETIME,
+                                        ETIME
 #else
-    stream_timeout = ETIMEDOUT,
+                                        ETIMEDOUT
 #endif
+    _LIBCPP_SUPPRESS_DEPRECATED_POP
+		,
+    // clang-format on
     text_file_busy                = ETXTBSY,
     timed_out                     = ETIMEDOUT,
     too_many_files_open_in_system = ENFILE,
diff --git a/libcxx/include/cerrno b/libcxx/include/cerrno
index 937ec23c6971a..1cb6b8ada7679 100644
--- a/libcxx/include/cerrno
+++ b/libcxx/include/cerrno
@@ -39,4 +39,17 @@ Macros:
 #  pragma GCC system_header
 #endif
 
+#ifdef ENODATA
+#  pragma clang deprecated(ENODATA, "ENODATA is deprecated in ISO C++")
+#endif
+#ifdef ENOSR
+#  pragma clang deprecated(ENOSR, "ENOSR is deprecated in ISO C++")
+#endif
+#ifdef ENOSTR
+#  pragma clang deprecated(ENOSTR, "ENOSTR is deprecated in ISO C++")
+#endif
+#ifdef ETIME
+#  pragma clang deprecated(ETIME, "ETIME is deprecated in ISO C++")
+#endif
+
 #endif // _LIBCPP_CERRNO
diff --git a/libcxx/test/std/depr.cerro/cerrno.syn.verify.cpp b/libcxx/test/std/depr.cerro/cerrno.syn.verify.cpp
new file mode 100644
index 0000000000000..8257f7dd11641
--- /dev/null
+++ b/libcxx/test/std/depr.cerro/cerrno.syn.verify.cpp
@@ -0,0 +1,34 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+
+// <cerrno>
+
+// tests LWG 3869 deprecated macros.
+//
+// Note the macros may not be defined. When they are not defined the
+// ifdef XXX does not trigger a deprecated message. So use them in the
+// ifdef and test for 2 deprecated messages.
+
+#include <cerrno>
+
+#ifdef ENODATA
+[[maybe_unused]] int nodata =
+    ENODATA; // [email protected]:* 2 {{macro 'ENODATA' has been marked as deprecated}}
+#endif
+#ifdef ENOSR
+[[maybe_unused]] int nosr =
+    ENOSR; // [email protected]:* 2 {{macro 'ENOSR' has been marked as deprecated}}
+#endif
+#ifdef ENOSTR
+[[maybe_unused]] int nostr =
+    ENOSTR; // [email protected]:* 2 {{macro 'ENOSTR' has been marked as deprecated}}
+#endif
+#ifdef ETIME
+[[maybe_unused]] int timeout =
+    ETIME; // [email protected]:* 2 {{macro 'ETIME' has been marked as deprecated}}
+#endif
diff --git a/libcxx/test/std/depr.cerro/system.error.syn.verify.cpp b/libcxx/test/std/depr.cerro/system.error.syn.verify.cpp
new file mode 100644
index 0000000000000..b6f160b1d04fb
--- /dev/null
+++ b/libcxx/test/std/depr.cerro/system.error.syn.verify.cpp
@@ -0,0 +1,22 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+
+// <system_error>
+
+// enum errc {...}
+
+// tests LWG 3869 deprecated enum members.
+
+#include <system_error>
+
+[[maybe_unused]] std::errc nodata =
+    std::errc::no_message_available; // expected-warning {{'no_message_available' is deprecated}}
+[[maybe_unused]] std::errc nosr =
+    std::errc::no_stream_resources; // expected-warning {{'no_stream_resources' is deprecated}}
+[[maybe_unused]] std::errc nostr   = std::errc::not_a_stream;   // expected-warning {{'not_a_stream' is deprecated}}
+[[maybe_unused]] std::errc timeout = std::errc::stream_timeout; // expected-warning {{'stream_timeout' is deprecated}}
diff --git a/libcxx/test/std/diagnostics/syserr/errc.pass.cpp b/libcxx/test/std/diagnostics/syserr/errc.pass.cpp
index e44cb50102e3e..4abee08ddc662 100644
--- a/libcxx/test/std/diagnostics/syserr/errc.pass.cpp
+++ b/libcxx/test/std/diagnostics/syserr/errc.pass.cpp
@@ -6,6 +6,8 @@
 //
 //===----------------------------------------------------------------------===//
 
+// ADDITIONAL_COMPILE_FLAGS: -D_LIBCPP_DISABLE_DEPRECATION_WARNINGS
+
 // <system_error>
 
 // enum errc {...}

[github-actions]

✅ With the latest revision this PR passed the C/C++ code formatter.

[nico]

We get diags about ENOSTR now. Is that intentional? (I'm asking because the commit description talks about std::errc, but ENOSTR is not std::errc::not_a_stream.)

…hm, looking at libcxx/include/cerrno, it looks pretty intentional. But the commit description and the changelog entry could maybe call this out more (?).

[nico]

Is there a way to opt out of this, to be able to fix async? I thought maybe defining _LIBCPP_SUPPRESS_DEPRECATED_PUSH might work, but that apparently isn't an extension point.

[mordante]

Fair point the message could have been clearer. What do you mean with an opt out? This is a deprecation that we like people to fix, I expect there will be a removal which will be retroactively applied. (Note this is a change by POSIX and C++ follows its lead.)

[nico]

I mean some way (preprocessor define I suppose) that says "I have seen this deprecation message, please silence it for now". That's useful to be able to update your libc++ and then work on new deprecations asynchronously. Without opt-outs, you always have to fix all issues before you can updating again. That opens the risk that upstream lands some bug that you don't notice until the next update attempt, and if that adds a new deprecation before the new bug, you now have to fix that deprecation before you can roll in the bug fix.

MSVC's STL has opt-out macros for every deprecation they add, as far as I know. That is very useful for consumers, since it makes updating independent from fixing deprecation warnings. (It's enough to have these opt-outs for a little while, not forever, of course.)

(For some data points, https://autoroll.skia.org/r/libcxx-chromium/roll-history shows that libc++ updates have been very rough for us this year, with several weeks between successful updates. When things work, we usually update within hours. The last time, it took us a few weeks to clean up the iterator change in #74482 since that didn't have an effective opt-out. In the meantime, 79 changes landed. Several of them cleaned up includes, but luckily it looks like we only had to add a single #include line for that. And then this here landed. Which might not need a ton of cleanup, not sure yet, but it's in a dependency, not in direct code, so it'll take a while to pick up the fix again. Every single of these changes isn't super big, but there have been like 5 medium-sized once this year so far, and it's just so much easier if there's an opt-out flag.)

Edit: Even for more traditional projects that uprev libc++ only when new LLVM releases happen, these flags could be useful: it a) allows them to update before fixing all deprecation messages and b) allows them to fix deprecation issues one-by-one and then remove the opt-out macros one by one. That way, they can be sure they don't accidentally add new uses of some deprecated thing while they work on addressing remaining deprecated issues.

[mordante]

Thanks for the additional information.

Typically we only add opt-out macros when we remove features, not when we add deprecation flags. I think usually these depredations only affect newer language versions. But I've added some for long deprecated features too; they were added before we had deprecated messages.

I've no objection to add an opt-out macro. @ldionne any objection from your side? And should we always do this when we add a new deprecation? For example. for barrier, latch, and friends prior to C++20.

[ldionne]

We provide _LIBCPP_DISABLE_DEPRECATION_WARNINGS to allow turning those off. Sure, that will turn off all deprecation warnings, but in practice is it really a problem if it takes only a day or so to clean up the deprecated uses in most cases?

Alternatively, we could systematically introduce such macros but this is stuff that we'd be stuck with "forever" unless we agree on some kind of process to clean them up after N releases. If we do that, I'd argue that we want to remove them after a single release: if you need to silence deprecation warnings for an extended period of time, I would argue you shouldn't compile with deprecation warnings turned into errors.

I've no objection to add an opt-out macro. @ldionne any objection from your side? And should we always do this when we add a new deprecation? For example. for barrier, latch, and friends prior to C++20.

This is an example where the deprecation + removal process is made more complicated. So we would do this, I guess?

• LLVM 19: Deprecation warning for <barrier> & friends in < C++20, with _LIBCPP_DISABLE_DEPRECATION_WARNING_SYNC_BEFORE_CXX20
• LLVM 20: Remove _LIBCPP_DISABLE_DEPRECATION_WARNING_SYNC_BEFORE_CXX20, at the same time remove <barrier> & friends from < C++20 ?

Or would the deprecation-warning opt-out also imply that we should have the same for the removal from C++20? If that's the expectation, I would push back on that: we need the ability to make breaking changes (not huge ones) in less than 1 year.

[nico]

FWIW, a per-deprecation warning disable toggle for a single release would be more than enough for our use case, and it would make our lifes a lot easier.

[gulfemsavrun]

We started observing an interesting behavior in our codebase after this patch, and let me explain it with a simple example:

Case 1: There is no -Wdeprecated-pragma warning:

#include <errno.h>
int main() {
    return ENODATA;
}

Case2: There is a -Wdeprecated-pragma warning, where the only difference is #include <iostream>.

#include <errno.h>
#include <iostream>
int main() {
    return ENODATA;
}

test-pragma.cpp:5:12: warning: macro 'ENODATA' has been marked as deprecated: ENODATA is deprecated in ISO C++ [-Wdeprecated-pragma]
    5 |     return ENODATA;
      |            ^
/usr/local/google/home/gulfem/fuchsia/out/clang-0f6105/bin/../include/c++/v1/cerrno:42:71: note: macro marked 'deprecated' here
   42 | #  pragma clang deprecated(ENODATA, "ENODATA is deprecated in ISO C++")
      |                                                                       ^

Is this the expected behavior? ENODATA is defined in <errno.h> and is not deprecated. But, I think include <iostream> might transitively include some other headers like <cerrno> which causes -Wdeprecated-pragma warning.

[AaronBallman]

Is this the expected behavior?

At first blush, I was surprised by this. However, ENODATA is a POSIX errno value, and it is obsolescent in POSIX as well: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/errno.h.html The same is true for ETIME, ENOSTR, and ENOSR.

That said, this is obsolete for strictly conforming POSIX and that requires defining _POSIX_C_SOURCE to a specific value before including any headers, so maybe there's an argument to be made for only issuing the diagnostic in that case and when the value matches whatever POSIX standard initially deprecated these?

[mordante]

@gulfemsavrun I like to discuss the way forward before deciding the changes I'm going to make.

I agree with @AaronBallman the behaviour is correct. However I wonder whether we're doing our users a service with the correct behaviour. When C++ removes the POSIX macros from cerrno in C++XX they may still be available in errno.h. In that case the user no longer gets a deprecation message from libc++ and can keep using them until their C library removes the macros. So some users may be happier when C++ removes them.

I think we should keep the behaviour for the std::errc and add a toggle for one release as requested by @nico.

For the macros I wonder what the best way would be:

1. remove the deprecation entirely
2. keep the deprecation, but only in C++26 (so don't retroactively apply this part of the LWG issue). Since there are few user of C++26 I see no strong motivation to add the std::errc toggle here.
3. keep the deprecation and use the std::errc toggle for one release

Personally I'm leaning towards 2, but I like to hear your opinions.

[AaronBallman]

FWIW, the POSIX macros can be deprecated in errno.h as well, via #pragma clang deprecate: https://godbolt.org/z/f8hdcs3Mf

Personally, I think deprecation is only valuable if users are warned about it explicitly. So I tend to lean towards (3) because it gets the notification out to users. It might be worth reaching out to libc folks supporting POSIX to see if they'd consider adding the deprecation warnings to errno.h as well?

[ldionne]

Personally, I'd tend towards (1), i.e. do not deprecate the macros at all. After re-consideration, I feel like we might be overstepping the boundary between libc++ and the C Standard Library. We don't define these errno.h macros, the C Standard Library does. If they decide to mark these macros as deprecated as per POSIX, it's their choice. If they don't, it's their choice too and I feel like trying to force that upon them is only going to create compatibility problems between libc++ and the underlying C library.

@nico Were you asking for an opt-out for the std::errc constants being deprecated, or for the <errno.h> macros being deprecated? If the latter, we don't need to add one if we do (1). If you wanted an opt-out for the former, I think we can do that as a one-off thing but in general, deprecation warnings are introduced in newer standards only so that acts as the "opt in", as Mark made me realize just now. So in general, I'd rather not start adding opt-outs for every single deprecation warning we add in newer standard modes. This std::errc deprecation is special though, since it is applied as a DR and so I think it would make sense to do a one-off opt-out.

[tbodt]

At first blush, I was surprised by this. However, ENODATA is a POSIX errno value, and it is obsolescent in POSIX as well: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/errno.h.html The same is true for ETIME, ENOSTR, and ENOSR.

The thing is, there's a name collision here. Linux never implemented STREAMS and thus never added these error codes as defined in POSIX, but they did define ENODATA as a Linux specific error used (afaik) only to mean "the extended attribute you tried to reference does not exist". This code is not deprecated and is often necessary in code that deals with extended attributes. For example: https://godbolt.org/z/xsqsas5Ea. This isn't really using anything deprecated and shouldn't warn when compiled on Linux.

[ldionne]

Re above: So here again, simply not deprecating the macros in libc++ and letting the C Library handle that business seems to do the right thing. I think this reinforces that we should go for (1).

[mordante]

Based on the feedback and a private discussion with Louis I've implemented option 1 in #88296.

@gulfemsavrun That should disable the deprecation message in your Case 1 and Case 2.
@nico From your messages I understand you only have an issue with the deprecation of the macros. The new PR should fix your issues too. This means there is no need for a deprecation toggle anymore. Please let me know when you still need a deprecation toggle.

[gulfemsavrun]

@gulfemsavrun That should disable the deprecation message in your Case 1 and Case 2.

Thanks for the update @mordante!

[AaronBallman]

FWIW, I'm also happy enough going with option 1, so thank you for the quick fix here!

[nico]

Were you asking for an opt-out for the std::errc constants being deprecated, or for the <errno.h> macros being deprecated? If the latter, we don't need to add one if we do (1)
From your messages I understand you only have an issue with the deprecation of the macros.

Yes, correct, just the errno.h macros. Thanks!