repr(C) 内存布局 ​

核心概念 ​

#[repr(C)] 是一个属性,用于指定结构体、枚举或联合体使用 C 语言的内存布局规则。默认情况下,Rust 编译器可以自由重排结构体字段的顺序、调整对齐方式以优化内存使用和访问性能。这意味着 Rust 结构体的内存布局是不确定的,可能随编译器版本、优化级别甚至编译目标的变化而改变。

当使用 #[repr(C)] 时,编译器会严格按照 C 语言的规则来排列字段:字段按声明顺序排列,每个字段对齐到其类型要求的边界,结构体的总大小对齐到最大字段的对齐要求。这保证了 Rust 结构体和 C 结构体在内存中的布局完全一致,是 FFI 交互的基础。

rust
// 默认 Rust 布局:编译器可能重排字段
struct RustLayout {
    a: u8,    // 1 字节
    b: u32,   // 4 字节
    c: u8,    // 1 字节
    d: u16,   // 2 字节
}
// Rust 可能重排为 b, d, a, c 以减少填充

// C 兼容布局:字段严格按声明顺序
#[repr(C)]
struct CLayout {
    a: u8,    // 偏移 0,大小 1
    // 填充 3 字节(对齐 b 到 4 字节边界)
    b: u32,   // 偏移 4,大小 4
    c: u8,    // 偏移 8,大小 1
    // 填充 1 字节(对齐 d 到 2 字节边界)
    d: u16,   // 偏移 10,大小 2
}
// 总大小 12 字节(对齐到 4 字节边界)

fn main() {
    println!("Rust 布局大小: {} 字节", std::mem::size_of::<RustLayout>());
    println!("C 布局大小:    {} 字节", std::mem::size_of::<CLayout>());

    // Rust 布局可能更小(通过重排减少填充)
    // C 布局大小是确定的,与 C 编译器生成的一致
}

C 语言的布局规则 ​

rust
// C 语言的结构体布局规则:
// 1. 字段按声明顺序排列
// 2. 每个字段对齐到其自身大小的倍数地址
// 3. 结构体总大小对齐到最大字段对齐要求的倍数
// 4. 必要时插入填充字节

#[repr(C)]
struct Example1 {
    a: u8,    // 偏移 0,大小 1
              // 填充 1 字节
    b: u16,   // 偏移 2,大小 2(对齐到 2)
    c: u32,   // 偏移 4,大小 4(对齐到 4)
}
// 总大小 8 字节

#[repr(C)]
struct Example2 {
    a: u8,    // 偏移 0,大小 1
              // 填充 3 字节
    b: u32,   // 偏移 4,大小 4(对齐到 4)
    c: u8,    // 偏移 8,大小 1
              // 填充 3 字节(总大小对齐到 4)
}
// 总大小 12 字节

#[repr(C)]
struct Example3 {
    a: u8,    // 偏移 0
              // 填充 7 字节
    b: u64,   // 偏移 8,大小 8(对齐到 8)
    c: u8,    // 偏移 16
              // 填充 7 字节(总大小对齐到 8)
}
// 总大小 24 字节

// 优化布局:手动重排字段减少填充
#[repr(C)]
struct Example3Optimized {
    b: u64,   // 偏移 0
    a: u8,    // 偏移 8
    c: u8,    // 偏移 9
              // 填充 6 字节
}
// 总大小 16 字节(比 Example3 少 8 字节)

fn main() {
    println!("=== 布局大小和对齐 ===");
    println!("Example1: 大小={}, 对齐={}",
        std::mem::size_of::<Example1>(), std::mem::align_of::<Example1>());
    println!("Example2: 大小={}, 对齐={}",
        std::mem::size_of::<Example2>(), std::mem::align_of::<Example2>());
    println!("Example3: 大小={}, 对齐={}",
        std::mem::size_of::<Example3>(), std::mem::align_of::<Example3>());
    println!("Example3Opt: 大小={}, 对齐={}",
        std::mem::size_of::<Example3Optimized>(), std::mem::align_of::<Example3Optimized>());

    // 验证字段偏移
    println!("\n=== Example2 字段偏移 ===");
    let e = Example2 { a: 0xAA, b: 0xBBBBBBBB, c: 0xCC };
    let base = &e as *const Example2 as usize;
    let a_offset = &e.a as *const u8 as usize - base;
    let b_offset = &e.b as *const u32 as usize - base;
    let c_offset = &e.c as *const u8 as usize - base;
    println!("a 偏移: {}", a_offset);  // 0
    println!("b 偏移: {}", b_offset);  // 4
    println!("c 偏移: {}", c_offset);  // 8
}

repr(C) 用于枚举 ​

rust
// C 兼容的枚举
#[repr(C)]
enum Color {
    Red,     // 0
    Green,   // 1
    Blue,    // 2
}

// 指定底层类型的枚举
#[repr(u8)]
enum SmallEnum {
    A = 0,
    B = 1,
    C = 255,
}

#[repr(i32)]
enum ErrorCode {
    Success = 0,
    NotFound = -1,
    PermissionDenied = -2,
    IoError = -3,
}

// C 兼容的带数据枚举(tagged union)
#[repr(C)]
enum Shape {
    Circle(f64),                    // 半径
    Rectangle(f64, f64),            // 宽、高
    Triangle(f64, f64, f64),        // 三条边
}

fn main() {
    println!("=== 枚举大小 ===");
    println!("Color (repr(C)): {} 字节", std::mem::size_of::<Color>());
    println!("SmallEnum (repr(u8)): {} 字节", std::mem::size_of::<SmallEnum>());
    println!("ErrorCode (repr(i32)): {} 字节", std::mem::size_of::<ErrorCode>());
    println!("Shape (repr(C)): {} 字节", std::mem::size_of::<Shape>());

    // 枚举值
    println!("\n=== 枚举值 ===");
    println!("Red = {}", Color::Red as i32);
    println!("Green = {}", Color::Green as i32);
    println!("Blue = {}", Color::Blue as i32);

    println!("Success = {}", ErrorCode::Success as i32);
    println!("NotFound = {}", ErrorCode::NotFound as i32);
}
repr 属性大小用途
#[repr(C)]平台相关(通常 4 字节)FFI 兼容枚举
#[repr(u8)]1 字节紧凑的小枚举
#[repr(u16)]2 字节中等大小枚举
#[repr(i32)]4 字节C 的 int 枚举
#[repr(u32)]4 字节无符号 int 枚举

repr(C) 用于联合体 ​

rust
#[repr(C)]
union IntOrFloat {
    i: i32,
    f: f32,
}

#[repr(C)]
union MultiType {
    byte: u8,
    word: u16,
    dword: u32,
    qword: u64,
}

fn main() {
    // C 兼容的 union
    let u = IntOrFloat { f: 3.14 };
    // SAFETY: 类型双关
    unsafe {
        println!("f32 3.14 的位模式: 0x{:08X}", u.i);
    }

    let u = MultiType { qword: 0x0102030405060708 };
    // SAFETY: 类型双关,查看不同大小的视图
    unsafe {
        println!("\n0x0102030405060708 的各视图:");
        println!("  byte:  0x{:02X}", u.byte);
        println!("  word:  0x{:04X}", u.word);
        println!("  dword: 0x{:08X}", u.dword);
        println!("  qword: 0x{:016X}", u.qword);
    }

    println!("\n大小:");
    println!("IntOrFloat: {} 字节", std::mem::size_of::<IntOrFloat>());
    println!("MultiType: {} 字节", std::mem::size_of::<MultiType>());
}

其他 repr 属性 ​

rust
// === #[repr(transparent)] ===
// 保证与内部类型有相同的布局
// 只能有一个非零大小的字段
#[repr(transparent)]
struct Wrapper(i32);

#[repr(transparent)]
struct Meters(f64);

// Wrapper 和 i32 在内存中完全相同
// 可以安全地在 FFI 中互换

// === #[repr(packed)] ===
// 移除所有填充,紧凑排列
// 可能导致未对齐访问
#[repr(C, packed)]
struct Packed {
    a: u8,    // 偏移 0
    b: u32,   // 偏移 1(未对齐!)
    c: u8,    // 偏移 5
}
// 总大小 6 字节(没有填充)

// === #[repr(align(N))] ===
// 指定最小对齐要求
#[repr(C, align(16))]
struct Aligned16 {
    data: [u8; 4],
}
// 大小 16 字节(对齐到 16 字节边界)

// 可以组合使用
#[repr(C, align(64))]
struct CacheLine {
    data: [u8; 64],
}

fn main() {
    println!("=== 各种 repr ===");
    println!("Wrapper (transparent): 大小={}, 对齐={}",
        std::mem::size_of::<Wrapper>(), std::mem::align_of::<Wrapper>());
    println!("i32: 大小={}, 对齐={}",
        std::mem::size_of::<i32>(), std::mem::align_of::<i32>());

    println!("Packed: 大小={}, 对齐={}",
        std::mem::size_of::<Packed>(), std::mem::align_of::<Packed>());

    println!("Aligned16: 大小={}, 对齐={}",
        std::mem::size_of::<Aligned16>(), std::mem::align_of::<Aligned16>());

    println!("CacheLine: 大小={}, 对齐={}",
        std::mem::size_of::<CacheLine>(), std::mem::align_of::<CacheLine>());

    // transparent 的等价性
    let w = Wrapper(42);
    let ptr = &w as *const Wrapper as *const i32;
    // SAFETY: repr(transparent) 保证布局相同
    println!("\ntransparent: Wrapper(42) = {}", unsafe { *ptr });
}
repr 属性效果用途
repr(C)C 兼容布局FFI
repr(transparent)与内部类型相同newtype 模式 FFI
repr(packed)无填充紧凑布局协议解析、节省内存
repr(align(N))指定最小对齐缓存行对齐、SIMD
repr(C, packed)C 顺序 + 无填充二进制协议
repr(C, align(N))C 顺序 + 自定义对齐特殊硬件要求

基本示例 ​

用 #[repr(C)] 实现二进制文件头部解析:

rust
use std::mem;

// BMP 文件头(14 字节)
#[repr(C, packed)]
#[derive(Debug, Clone, Copy)]
struct BmpFileHeader {
    signature: [u8; 2],     // "BM"
    file_size: u32,         // 文件大小
    reserved: u32,          // 保留(0)
    data_offset: u32,       // 像素数据偏移
}

// BMP 信息头(40 字节)
#[repr(C)]
#[derive(Debug, Clone, Copy)]
struct BmpInfoHeader {
    header_size: u32,       // 信息头大小(40)
    width: i32,             // 图像宽度
    height: i32,            // 图像高度
    planes: u16,            // 颜色平面数(1)
    bits_per_pixel: u16,    // 每像素位数(24 或 32)
    compression: u32,       // 压缩方式
    image_size: u32,        // 图像数据大小
    x_ppm: i32,             // 水平分辨率
    y_ppm: i32,             // 垂直分辨率
    colors_used: u32,       // 使用的颜色数
    important_colors: u32,  // 重要的颜色数
}

// 像素
#[repr(C)]
#[derive(Debug, Clone, Copy)]
struct Pixel {
    b: u8,
    g: u8,
    r: u8,
}

fn create_bmp_data(width: i32, height: i32) -> Vec<u8> {
    let row_size = ((width * 3 + 3) / 4 * 4) as usize;  // 行大小对齐到 4 字节
    let image_size = row_size * height as usize;
    let file_size = mem::size_of::<BmpFileHeader>() + mem::size_of::<BmpInfoHeader>() + image_size;
    let data_offset = (mem::size_of::<BmpFileHeader>() + mem::size_of::<BmpInfoHeader>()) as u32;

    let file_header = BmpFileHeader {
        signature: [b'B', b'M'],
        file_size: file_size as u32,
        reserved: 0,
        data_offset,
    };

    let info_header = BmpInfoHeader {
        header_size: mem::size_of::<BmpInfoHeader>() as u32,
        width,
        height,
        planes: 1,
        bits_per_pixel: 24,
        compression: 0,
        image_size: image_size as u32,
        x_ppm: 2835,
        y_ppm: 2835,
        colors_used: 0,
        important_colors: 0,
    };

    let mut data = Vec::with_capacity(file_size);

    // 写入文件头
    let header_bytes = unsafe {
        std::slice::from_raw_parts(
            &file_header as *const BmpFileHeader as *const u8,
            mem::size_of::<BmpFileHeader>(),
        )
    };
    data.extend_from_slice(header_bytes);

    // 写入信息头
    let info_bytes = unsafe {
        std::slice::from_raw_parts(
            &info_header as *const BmpInfoHeader as *const u8,
            mem::size_of::<BmpInfoHeader>(),
        )
    };
    data.extend_from_slice(info_bytes);

    // 写入像素数据(简单的渐变图案)
    for y in 0..height {
        for x in 0..width {
            let pixel = Pixel {
                r: (x * 255 / width) as u8,
                g: (y * 255 / height) as u8,
                b: 128,
            };
            data.push(pixel.b);
            data.push(pixel.g);
            data.push(pixel.r);
        }
        // 行填充到 4 字节对齐
        let padding = row_size - (width * 3) as usize;
        for _ in 0..padding {
            data.push(0);
        }
    }

    data
}

fn parse_bmp_header(data: &[u8]) {
    let fh_size = mem::size_of::<BmpFileHeader>();
    let ih_size = mem::size_of::<BmpInfoHeader>();

    if data.len() < fh_size + ih_size {
        println!("数据太短");
        return;
    }

    // SAFETY: data 足够长,BmpFileHeader 是 packed 的所以不用担心对齐
    let file_header: BmpFileHeader = unsafe {
        std::ptr::read_unaligned(data.as_ptr() as *const BmpFileHeader)
    };

    // SAFETY: 偏移后的数据足够长
    let info_header: BmpInfoHeader = unsafe {
        std::ptr::read(data.as_ptr().add(fh_size) as *const BmpInfoHeader)
    };

    println!("=== BMP 文件头 ===");
    println!("签名: {}{}", file_header.signature[0] as char, file_header.signature[1] as char);
    println!("文件大小: {} 字节", file_header.file_size);
    println!("数据偏移: {} 字节", file_header.data_offset);

    println!("\n=== BMP 信息头 ===");
    println!("宽度: {} 像素", info_header.width);
    println!("高度: {} 像素", info_header.height);
    println!("位深: {} bit", info_header.bits_per_pixel);
    println!("压缩: {}", info_header.compression);
    println!("图像大小: {} 字节", info_header.image_size);
}

fn main() {
    // 结构体大小验证
    println!("=== 结构体大小 ===");
    println!("BmpFileHeader: {} 字节(预期 14)", mem::size_of::<BmpFileHeader>());
    println!("BmpInfoHeader: {} 字节(预期 40)", mem::size_of::<BmpInfoHeader>());
    println!("Pixel: {} 字节(预期 3)", mem::size_of::<Pixel>());

    // 创建 BMP 数据
    let bmp_data = create_bmp_data(4, 3);
    println!("\n生成 BMP 数据: {} 字节", bmp_data.len());

    // 解析头部
    println!();
    parse_bmp_header(&bmp_data);
}

常见问题 ​

问题一:不加 repr(C) 的结构体可以用于 FFI 吗?

不行。Rust 默认布局不确定,可能随编译器版本变化。FFI 要求布局确定且与 C 一致,必须使用 #[repr(C)]。

问题二:repr(C) 会影响性能吗?

可能会。Rust 默认布局通过重排字段减少填充,提高缓存效率。#[repr(C)] 禁止重排,可能导致更多填充和更大的结构体。对性能敏感的纯 Rust 结构体不应使用 #[repr(C)]。

问题三:repr(packed) 安全吗?

创建 packed 结构体的引用可能产生未对齐引用,这在某些架构上会崩溃。Rust 2024 对 packed 结构体字段取引用会发出警告。应使用 &raw const 或 read_unaligned 来安全访问 packed 字段。

问题四:repr(transparent) 和 repr(C) 有什么区别?

repr(transparent) 保证类型与其唯一的非零大小字段有完全相同的布局,适合 newtype 模式。repr(C) 使用 C 的布局规则,适合多字段结构体。单字段结构体两者效果类似,但 repr(transparent) 的语义更明确。

适用场景 ​

  • FFI:与 C 代码交互的结构体
  • 二进制协议:网络协议、文件格式的头部解析
  • 内存映射:将内存区域解释为特定结构
  • 硬件寄存器:映射设备寄存器的布局

注意事项 ​

  • FFI 结构体必须使用 #[repr(C)]
  • #[repr(C)] 不重排字段,可能有更多填充
  • #[repr(packed)] 要注意未对齐访问问题
  • 大字段放前面可以减少填充浪费
  • 枚举使用 #[repr(C)] 或 #[repr(u32)] 等指定大小
  • #[repr(transparent)] 适合单字段的 newtype

总结 ​

#[repr(C)] 指定类型使用 C 语言的内存布局规则:字段按声明顺序排列,对齐到各自类型的对齐要求,结构体总大小对齐到最大对齐的倍数。这是 FFI 交互的基础——保证 Rust 和 C 结构体在内存中的布局一致。Rust 默认布局允许编译器重排字段优化内存,#[repr(C)] 禁止这种优化。其他布局属性包括 repr(transparent)(与内部类型相同)、repr(packed)(无填充)、repr(align(N))(指定对齐)。实际使用中,只有需要 FFI 交互或精确控制内存布局的类型才需要 #[repr(C)],纯 Rust 类型应使用默认布局以获得更好的性能。