gh-148286: Fix undefined behaviour in the ctypes bit field accessors

BIT_MASK, GET_BITFIELD and SET in Modules/_ctypes/cfield.c did their bit
manipulation in the bit field's own type. When that type is signed, both
shifting a negative value left and shifting a one into the sign bit are
undefined behaviour, so UBSan reported, among others:

  cfield.c:644: left shift of 1 by 63 places cannot be represented in 'int64_t'
  cfield.c:640: signed integer overflow: -2147483648 - 1
  cfield.c:636: left shift of negative value -32768

Do the arithmetic in uint64_t -- the widest type the accessors support --
and convert back to the field's own type at the end. BIT_MASK is replaced
by LOW_BITS_MASK(), which no longer needs a type argument now that the
mask is always computed unsigned. GET_BITFIELD takes the field type so it
can still sign-extend signed fields, and is wrapped in do/while(0).

Verified against the old macros with an exhaustive differential test:
for every fixed-width type (int8_t..uint64_t), every num_bits and low_bit
combination, ten storage patterns and twenty stored values -- 1,167,600
cases, no behaviour change, under both gcc and clang.

The two Modules/_ctypes/cfield.c entries in Tools/ubsan/suppressions.txt
are no longer needed. With them removed, test_ctypes passes under
UBSAN_OPTIONS=halt_on_error=1; before this change it aborts at
cfield.c:644 in i64_set.

Author: matthiasgoergens

Misc/NEWS.d/next/Library/2026-07-30-12-00-00.gh-issue-148286.Kx7Qm2.rst

@@ -0,0 +1,7 @@
+Fix undefined behaviour in the :mod:`ctypes` bit field accessors. The
+``BIT_MASK``, ``GET_BITFIELD`` and ``SET`` macros in
+``Modules/_ctypes/cfield.c`` shifted negative values left and shifted ones
+into the sign bit of a signed type. The bit manipulation is now done in
+``uint64_t`` and converted back to the field's own type, which removes the
+two ``Modules/_ctypes/cfield.c`` entries from
+``Tools/ubsan/suppressions.txt``.

Modules/_ctypes/cfield.c

@@ -492,23 +492,49 @@ Py_ssize_t NUM_BITS(Py_ssize_t bitsize) {
     return bitsize >> 16;
 }
 
-/* Doesn't work if NUM_BITS(size) == 0, but it never happens in SET() call. */
-#define BIT_MASK(type, size) (((((type)1 << (NUM_BITS(size) - 1)) - 1) << 1) + 1)
+/* Bit fields are manipulated as uint64_t -- the widest type the accessors
+   below support -- and converted back to the field's own type at the end.
+   Doing the arithmetic in the field's type would be undefined behaviour
+   whenever that type is signed: shifting a negative value left, and shifting
+   a one into the sign bit, are both UB. */
+
+/* A mask with the low `num_bits` bits set.
+   Doesn't work if num_bits == 0, but that never happens here. */
+static inline
+uint64_t LOW_BITS_MASK(Py_ssize_t num_bits) {
+    assert(0 < num_bits);
+    assert(num_bits <= 64);
+    return (~(uint64_t)0) >> (64 - num_bits);
+}
 
-/* This macro CHANGES the first parameter IN PLACE. For proper sign handling,
-   we must first shift left, then right.
-*/
-#define GET_BITFIELD(v, size)                                           \
-    if (NUM_BITS(size)) {                                               \
-        v <<= (sizeof(v)*8 - LOW_BIT(size) - NUM_BITS(size));           \
-        v >>= (sizeof(v)*8 - NUM_BITS(size));                           \
-    }
+/* True if `type` is signed. Spelled so that neither comparison is the
+   `unsigned < 0` pattern that compilers warn about. */
+#define IS_SIGNED_TYPE(type) (!((type)0 < (type)-1))
+
+/* This macro CHANGES the `v` parameter IN PLACE. */
+#define GET_BITFIELD(type, v, size)                                           \
+    do {                                                                      \
+        if (NUM_BITS(size)) {                                                 \
+            uint64_t bitfield_bits = ((uint64_t)(v) >> LOW_BIT(size))         \
+                                     & LOW_BITS_MASK(NUM_BITS(size));         \
+            if (IS_SIGNED_TYPE(type)                                          \
+                && (bitfield_bits >> (NUM_BITS(size) - 1)))                   \
+            {                                                                 \
+                /* The field's top bit is set: sign-extend it. */             \
+                bitfield_bits |= ~LOW_BITS_MASK(NUM_BITS(size));              \
+            }                                                                 \
+            (v) = (type)bitfield_bits;                                        \
+        }                                                                     \
+    } while (0)
 
-/* This macro RETURNS the first parameter with the bit field CHANGED. */
+/* This macro RETURNS the `x` parameter with the bit field CHANGED. */
 #define SET(type, x, v, size)                                                 \
-    (NUM_BITS(size) ?                                                   \
-     ( ( (type)(x) & ~(BIT_MASK(type, size) << LOW_BIT(size)) ) | ( ((type)(v) & BIT_MASK(type, size)) << LOW_BIT(size) ) ) \
-     : (type)(v))
+    ((type)(NUM_BITS(size)                                                    \
+            ? (((uint64_t)(x)                                                 \
+                & ~(LOW_BITS_MASK(NUM_BITS(size)) << LOW_BIT(size)))          \
+               | (((uint64_t)(v) & LOW_BITS_MASK(NUM_BITS(size)))             \
+                  << LOW_BIT(size)))                                          \
+            : (uint64_t)(v)))
 
 /*****************************************************************
  * The setter methods return an object which must be kept alive, to keep the
@@ -571,7 +597,7 @@ Py_ssize_t NUM_BITS(Py_ssize_t bitsize) {
         assert(NUM_BITS(size_arg) || (size_arg == (NBITS) / 8));              \
         CTYPE val;                                                            \
         memcpy(&val, ptr, sizeof(val));                                       \
-        GET_BITFIELD(val, size_arg);                                          \
+        GET_BITFIELD(CTYPE, val, size_arg);                                   \
         return PYAPI_FROMFUNC(val);                                           \
     }                                                                         \
     ///////////////////////////////////////////////////////////////////////////
@@ -604,7 +630,7 @@ Py_ssize_t NUM_BITS(Py_ssize_t bitsize) {
         CTYPE val;                                                            \
         memcpy(&val, ptr, sizeof(val));                                       \
         val = PY_SWAPFUNC(val);                                               \
-        GET_BITFIELD(val, size_arg);                                          \
+        GET_BITFIELD(CTYPE, val, size_arg);                                   \
         return PYAPI_FROMFUNC(val);                                           \
     }                                                                         \
     ///////////////////////////////////////////////////////////////////////////

Tools/ubsan/suppressions.txt

@@ -9,11 +9,5 @@
 # Objects/object.c:97:5: runtime error: member access within null pointer of type 'PyThreadState' (aka 'struct _ts')
 null:Objects/object.c
 
-# Modules/_ctypes/cfield.c:644:1: runtime error: left shift of 1 by 63 places cannot be represented in type 'int64_t' (aka 'long')
-shift-base:Modules/_ctypes/cfield.c
-
-# Modules/_ctypes/cfield.c:640:1: runtime error: signed integer overflow: -2147483648 - 1 cannot be represented in type 'int'
-signed-integer-overflow:Modules/_ctypes/cfield.c
-
 # Modules/_io/stringio.c:350:24: runtime error: addition of unsigned offset to 0x7fd01ec25850 overflowed to 0x7fd01ec2584c
 pointer-overflow:Modules/_io/stringio.c