itsscb/rust
1
0
Fork 0
mirror of https://github.com/rust-lang/rust.git synced 2025-12-01 13:27:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

Rollup merge of #146925 - DiuDiu777:va-doc-fix, r=tgross35

Browse Source 
Add doc for va_list APIs

I observed that [PR146521](https://github.com/rust-lang/rust/pull/146521) submitted two weeks ago resolved some documentation issues related to `VaListImpl`, similar to the previous [PR136969](https://github.com/rust-lang/rust/pull/136969).

This PR specifically adds requirements about argument availability for `VaListImpl::arg`, and also adds safety descriptions to the three associated intrinsic APIs.
This commit is contained in:
Matthias Krüger 2025-11-20 11:15:49 +01:00 committed by GitHub
commit 2eeec770fe
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 26 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
library/core/src/ffi/va_list.rs
View File

@ -243,10 +243,11 @@ impl<'f> VaListImpl<'f> {
/// ///
/// # Safety /// # Safety
/// ///
/// This function is only sound to call when the next variable argument: /// This function is only sound to call when:
/// ///
/// - has a type that is ABI-compatible with the type `T` /// - there is a next variable argument available.
/// - has a value that is a properly initialized value of type `T` /// - the next argument's type must be ABI-compatible with the type `T`.
/// - the next argument must have a properly initialized value of type `T`.
/// ///
/// Calling this function with an incompatible type, an invalid value, or when there /// Calling this function with an incompatible type, an invalid value, or when there
/// are no more variable arguments, is unsound. /// are no more variable arguments, is unsound.

25
library/core/src/intrinsics/mod.rs
View File

@ -3350,7 +3350,13 @@ pub(crate) const fn miri_promise_symbolic_alignment(ptr: *const (), align: usize
/// Copies the current location of arglist `src` to the arglist `dst`. /// Copies the current location of arglist `src` to the arglist `dst`.
/// ///
/// FIXME: document safety requirements /// # Safety
///
/// You must check the following invariants before you call this function:
///
/// - `dest` must be non-null and point to valid, writable memory.
/// - `dest` must not alias `src`.
///
#[rustc_intrinsic] #[rustc_intrinsic]
#[rustc_nounwind] #[rustc_nounwind]
pub unsafe fn va_copy<'f>(dest: *mut VaListImpl<'f>, src: &VaListImpl<'f>); pub unsafe fn va_copy<'f>(dest: *mut VaListImpl<'f>, src: &VaListImpl<'f>);
@ -3358,14 +3364,27 @@ pub unsafe fn va_copy<'f>(dest: *mut VaListImpl<'f>, src: &VaListImpl<'f>);
/// Loads an argument of type `T` from the `va_list` `ap` and increment the /// Loads an argument of type `T` from the `va_list` `ap` and increment the
/// argument `ap` points to. /// argument `ap` points to.
/// ///
/// FIXME: document safety requirements /// # Safety
///
/// This function is only sound to call when:
///
/// - there is a next variable argument available.
/// - the next argument's type must be ABI-compatible with the type `T`.
/// - the next argument must have a properly initialized value of type `T`.
///
/// Calling this function with an incompatible type, an invalid value, or when there
/// are no more variable arguments, is unsound.
///
#[rustc_intrinsic] #[rustc_intrinsic]
#[rustc_nounwind] #[rustc_nounwind]
pub unsafe fn va_arg<T: VaArgSafe>(ap: &mut VaListImpl<'_>) -> T; pub unsafe fn va_arg<T: VaArgSafe>(ap: &mut VaListImpl<'_>) -> T;
/// Destroy the arglist `ap` after initialization with `va_start` or `va_copy`. /// Destroy the arglist `ap` after initialization with `va_start` or `va_copy`.
/// ///
/// FIXME: document safety requirements /// # Safety
///
/// `ap` must not be used to access variable arguments after this call.
///
#[rustc_intrinsic] #[rustc_intrinsic]
#[rustc_nounwind] #[rustc_nounwind]
pub unsafe fn va_end(ap: &mut VaListImpl<'_>); pub unsafe fn va_end(ap: &mut VaListImpl<'_>);