Introduce a new c_enum macro

Our current `e!` macro makes it easy to run into UB if C headers add a
variant that isn't represented in the Rust version. Add a path to
migrate away from this by introducing the `c_enum!` macro which
represents a C enum as Rust constants and a type alias.

Part of [1].

[1]: #4419

Author: tgross35

src/macros.rs

@@ -193,6 +193,7 @@ macro_rules! missing {
 
 /// Implement `Clone` and `Copy` for an enum, as well as `Debug`, `Eq`, `Hash`, and
 /// `PartialEq` if the `extra_traits` feature is enabled.
+// FIXME(#4419): Replace all uses of `e!` with `c_enum!`
 macro_rules! e {
     ($(
         $(#[$attr:meta])*
@@ -210,6 +211,48 @@ macro_rules! e {
     )*);
 }
 
+/// Represent a C enum as Rust constants and a type.
+///
+/// C enums can't soundly be mapped to Rust enums since C enums are allowed to have duplicates or
+/// unlisted values, but this is UB in Rust. This enum doesn't implement any traits, its main
+/// purpose is to calculate the correct enum values.
+///
+/// See <https://github.com/rust-lang/libc/issues/4419> for more.
+macro_rules! c_enum {
+    (
+        $(#[repr($repr:ty)])?
+        $ty_name:ident {
+            $($variant:ident $(= $value:literal)?,)+
+        }
+    ) => {
+        pub type $ty_name = c_enum!(@ty $($repr)?);
+        c_enum!(@one; $ty_name; 0; $($variant $(= $value)?,)+);
+    };
+
+    // Matcher for a single variant
+    (@one; $_ty_name:ident; $_idx:expr;) => {};
+    (
+        @one; $ty_name:ident; $default_val:expr;
+        $variant:ident $(= $value:literal)?,
+        $($tail:tt)*
+    ) => {
+        pub const $variant: $ty_name = {
+            #[allow(unused_variables)]
+            let r = $default_val;
+            $(let r = $value;)?
+            r
+        };
+
+        // The next value is always one more than the previous value, unless
+        // set explicitly.
+        c_enum!(@one; $ty_name; $variant + 1; $($tail)*);
+    };
+
+    // Use a specific type if provided, otherwise default to `c_uint`
+    (@ty $repr:ty) => { $repr };
+    (@ty) => { $crate::c_uint };
+}
+
 // This is a pretty horrible hack to allow us to conditionally mark some functions as 'const',
 // without requiring users of this macro to care "libc_const_extern_fn".
 //
@@ -325,3 +368,76 @@ macro_rules! __item {
         $i
     };
 }
+
+#[cfg(test)]
+mod tests {
+    #[test]
+    fn c_enumbasic() {
+        // By default, variants get sequential values.
+        c_enum! {
+            e {
+                VAR0,
+                VAR1,
+                VAR2,
+            }
+        }
+
+        assert_eq!(VAR0, 0_u32);
+        assert_eq!(VAR1, 1_u32);
+        assert_eq!(VAR2, 2_u32);
+    }
+
+    #[test]
+    fn c_enumrepr() {
+        // By default, variants get sequential values.
+        c_enum! {
+            #[repr(u16)]
+            e {
+                VAR0,
+            }
+        }
+
+        assert_eq!(VAR0, 0_u16);
+    }
+
+    #[test]
+    fn c_enumset_value() {
+        // Setting an explicit value resets the count.
+        c_enum! {
+            e {
+                VAR2 = 2,
+                VAR3,
+                VAR4,
+            }
+        }
+
+        assert_eq!(VAR2, 2_u32);
+        assert_eq!(VAR3, 3_u32);
+        assert_eq!(VAR4, 4_u32);
+    }
+
+    #[test]
+    fn c_enummultiple_set_value() {
+        // C enums always take one more than the previous value, unless set to a specific
+        // value. Duplicates are allowed.
+        c_enum! {
+            e {
+                VAR0,
+                VAR2_0 = 2,
+                VAR3_0,
+                VAR4_0,
+                VAR2_1 = 2,
+                VAR3_1,
+                VAR4_1,
+            }
+        }
+
+        assert_eq!(VAR0, 0_u32);
+        assert_eq!(VAR2_0, 2_u32);
+        assert_eq!(VAR3_0, 3_u32);
+        assert_eq!(VAR4_0, 4_u32);
+        assert_eq!(VAR2_1, 2_u32);
+        assert_eq!(VAR3_1, 3_u32);
+        assert_eq!(VAR4_1, 4_u32);
+    }
+}