Function std::ptr::write_unaligned

1.17.0 (const: unstable) · source ·
pub unsafe fn write_unaligned<T>(dst: *mut T, src: T)
Expand description

用给定值覆盖存储位置,而无需读取或丢弃旧值。

write() 不同,指针可能未对齐。

write_unaligned 不会丢弃 dst 的内容。这是安全的,但可能会泄漏分配或资源,因此应注意不要覆盖应丢弃的对象。

此外,它不会丢弃 src。在语义上,src 被移到 dst 指向的位置。

这适用于初始化未初始化的内存,或覆盖以前用 read_unaligned 读取的内存。

Safety

如果违反以下任一条件,则行为是未定义的:

请注意,即使 T 的大小为 0,指针也必须非空。

packed 结构体上

尝试使用诸如 &packed.unaligned as *const FieldType 的表达式创建指向 unaligned 结构体字段的裸指针,然后再将其转换为裸指针,这会产生一个中间未对齐的引用。

引用是临时的并且立即强制转换是无关紧要的,因为编译器始终希望引用正确对齐。 结果,使用 &packed.unaligned as *const FieldType 会在程序中立即导致* undefined 行为 *。

相反,您必须使用 ptr::addr_of_mut! 宏来创建指针。您可以将返回的指针与此函数一起使用。

如何做到这一点以及这与 write_unaligned 的关系的一个例子是:

#[repr(packed, C)]
struct Packed {
    _padding: u8,
    unaligned: u32,
}

let mut packed: Packed = unsafe { std::mem::zeroed() };

// 取一个未对齐的 32 位整数的地址。
// 与 `&packed.unaligned as *mut _` 相比,它没有未定义的行为。
let unaligned = std::ptr::addr_of_mut!(packed.unaligned);

unsafe { std::ptr::write_unaligned(unaligned, 42) };

assert_eq!({packed.unaligned}, 42); // `{...}` 强制复制字段而不是创建引用。
Run

然而,直接使用例如 packed.unaligned 访问未对齐的字段是安全的 (如上面的 assert_eq! 所示)。

Examples

将 usize 值写入字节缓冲区:

use std::mem;

fn write_usize(x: &mut [u8], val: usize) {
    assert!(x.len() >= mem::size_of::<usize>());

    let ptr = x.as_mut_ptr() as *mut usize;

    unsafe { ptr.write_unaligned(val) }
}
Run