Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Expand addr_of[_mut] UB documentation #95117

Closed
wants to merge 1 commit into from
Closed

Expand addr_of[_mut] UB documentation #95117

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 16 additions & 6 deletions library/core/src/ptr/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1451,9 +1451,11 @@ fnptr_impls_args! { A, B, C, D, E, F, G, H, I, J, K, L }
/// as all other references. This macro can create a raw pointer *without* creating
/// a reference first.
///
/// Note, however, that the `expr` in `addr_of!(expr)` is still subject to all
/// the usual rules. In particular, `addr_of!(*ptr::null())` is Undefined
/// Behavior because it dereferences a null pointer.
/// Note, however, that the `expr` in `addr_of!(expr)` is still subject to other rules:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it would be a good idea to make it clear that these are just the normal rules for all expr in place context, and not something specific to addr_of!.

For example, addr_of!(unsafe { unreachable_unchecked() }) is also still UB, of course. We don't want to list all language UB again here.

/// * A [dangling] pointer cannot be dereferenced. In particular, `addr_of!(*ptr::null_mut())`
/// is undefined behavior because it dereferences a null pointer.
/// * An [unaligned] pointer cannot be dereferenced. For example, `addr_of!((*an_unaligned_ptr).field)`
/// is undefined behavior.
///
/// # Example
///
Expand All @@ -1475,6 +1477,9 @@ fnptr_impls_args! { A, B, C, D, E, F, G, H, I, J, K, L }
/// See [`addr_of_mut`] for how to create a pointer to unininitialized data.
/// Doing that with `addr_of` would not make much sense since one could only
/// read the data, and that would be Undefined Behavior.
///
/// [dangling]: ../../reference/behavior-considered-undefined.html#dangling-pointers
/// [unaligned]: ../../reference/type-layout.html
#[stable(feature = "raw_ref_macros", since = "1.51.0")]
#[rustc_macro_transparency = "semitransparent"]
#[allow_internal_unstable(raw_ref_op)]
Expand All @@ -1491,9 +1496,11 @@ pub macro addr_of($place:expr) {
/// as all other references. This macro can create a raw pointer *without* creating
/// a reference first.
///
/// Note, however, that the `expr` in `addr_of_mut!(expr)` is still subject to all
/// the usual rules. In particular, `addr_of_mut!(*ptr::null_mut())` is Undefined
/// Behavior because it dereferences a null pointer.
/// Note, however, that the `expr` in `addr_of_mut!(expr)` is still subject to other rules:
/// * A [dangling] pointer cannot be dereferenced. In particular, `addr_of_mut!(*ptr::null_mut())`
/// is undefined behavior because it dereferences a null pointer.
/// * An [unaligned] pointer cannot be dereferenced. For example, `addr_of_mut!((*an_unaligned_ptr).field)`
/// is undefined behavior.
///
/// # Examples
///
Expand Down Expand Up @@ -1531,6 +1538,9 @@ pub macro addr_of($place:expr) {
/// unsafe { f1_ptr.write(true); }
/// let init = unsafe { uninit.assume_init() };
/// ```
///
/// [dangling]: ../../reference/behavior-considered-undefined.html#dangling-pointers
/// [unaligned]: ../../reference/type-layout.html
#[stable(feature = "raw_ref_macros", since = "1.51.0")]
#[rustc_macro_transparency = "semitransparent"]
#[allow_internal_unstable(raw_ref_op)]
Expand Down