From 132caec0ee6e67e72bd7e352f52c506814f82cd8 Mon Sep 17 00:00:00 2001 From: Folkert de Vries Date: Tue, 17 Feb 2026 19:33:27 +0100 Subject: [PATCH 1/4] add c-variadic function definitions --- src/items/functions.md | 64 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/src/items/functions.md b/src/items/functions.md index cf3d114886..a9176f13f7 100644 --- a/src/items/functions.md +++ b/src/items/functions.md @@ -332,6 +332,69 @@ Note that this behavior is a consequence of the desugaring to a function that re Unsafe is used on an async function in precisely the same way that it is used on other functions: it indicates that the function imposes some additional obligations on its caller to ensure soundness. As in any other unsafe function, these conditions may extend beyond the initial call itself -- in the snippet above, for example, the `unsafe_example` function took a pointer `x` as argument, and then (when awaited) dereferenced that pointer. This implies that `x` would have to be valid until the future is finished executing, and it is the caller's responsibility to ensure that. +r[items.fn.c-variadic] +## C-variadic functions + +r[items.fn.c-variadic.intro] +A *c-variadic* function accepts a variable argument list `pat: ...` as its final parameter. + +```rust +unsafe extern "C" fn example(arg0: i32, ap: ...) { } +``` + +This parameter stands in for an arbitrary number of arguments that may be passed by the caller. + +> [!WARNING] +> Passing an unexpected number of arguments or arguments of unexpected type to a variadic function may lead to [undefined behavior][undefined]. + +r[items.fn.async.desugar-brief] +A c-variadic function definition is roughly equivalent to a function operating on a [`VaList`]. + + + +```rust +// Source +unsafe extern "C" fn example(mut ap: ...) -> i32 { + unsafe { ap.arg::() } +} +``` + +is roughly equivalent to: + +```rust +# use std::ffi::VaList; +# use std::mem::MaybeUninit; +# fn va_start() {} +// Desugared +unsafe extern "C" fn example() -> i32 { + let mut storage = MaybeUninit::>::uninit(); + va_start(storage.as_mut_ptr()); // Initializes the VaList. + let mut ap: &mut VaList<'_> = ap.assume_init_mut(); + + unsafe { ap.arg::() } + + va_end(ap) +} +``` + +r[items.fn.c-variadic.lifetime] +The lifetime of a `VaList` is that of the function that created it. Hence, the `VaList` value can never outlive the function that created it. + +r[items.fn.c-variadic.ffi-compatibility] +The rust [`VaList`] is ABI-compatible with the C `va_list` type. + +r[items.fn.c-variadic.abi] +Only `extern "C"` and `extern "C-unwind"` functions can accept a variable argument list. + +r[items.fn.c-variadic.safety] +Only `unsafe` functions can accept a variable argument list. + +r[items.fn.c-variadic.async] +A c-variadic functions cannot be `async` + +r[items.fn.c-variadic.const] +A c-variadic functions cannot be `const` + r[items.fn.attributes] ## Attributes on functions @@ -426,3 +489,4 @@ fn foo_oof(#[some_inert_attribute] arg: u8) { [value namespace]: ../names/namespaces.md [variadic function]: external-blocks.md#variadic-functions [`extern` block]: external-blocks.md +[`VaList`]: std::ffi::VaList From dc9cfa70404e9930911754d17e6c30c4a798d781 Mon Sep 17 00:00:00 2001 From: Folkert de Vries Date: Wed, 18 Feb 2026 12:30:14 +0100 Subject: [PATCH 2/4] add 2 more details --- src/items/functions.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/src/items/functions.md b/src/items/functions.md index a9176f13f7..c0b3243a86 100644 --- a/src/items/functions.md +++ b/src/items/functions.md @@ -395,6 +395,20 @@ A c-variadic functions cannot be `async` r[items.fn.c-variadic.const] A c-variadic functions cannot be `const` +r[items.fn.c-variadic.platform-support] +Some ABIs do not support c-variadic function definitions. The compiler errors in this case. + +``` +error: the `bpfel` target does not support c-variadic functions + --> $DIR/not-supported.rs:23:31 + | +LL | unsafe extern "C" fn variadic(_: ...) {} + | ^^^^^^ +``` + +r[items.fn.c-variadic.dyn-compat] +When a trait method is c-variadic, the trait is no longer dyn-compatible. + r[items.fn.attributes] ## Attributes on functions From 385b130821afd0cced5c38b0d4259bad10dbb5ee Mon Sep 17 00:00:00 2001 From: Folkert de Vries Date: Tue, 3 Mar 2026 21:31:43 +0100 Subject: [PATCH 3/4] changes after code review --- src/items/functions.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/src/items/functions.md b/src/items/functions.md index c0b3243a86..451109627d 100644 --- a/src/items/functions.md +++ b/src/items/functions.md @@ -83,7 +83,7 @@ r[items.fn.params.self-restriction] Functions with a self parameter may only appear as an [associated function] in a [trait] or [implementation]. r[items.fn.params.varargs] -A parameter with the `...` token indicates a [variadic function], and may only be used as the last parameter of an [external block] function. The variadic parameter may have an optional identifier, such as `args: ...`. +A parameter with the `...` token indicates a [c-variadic function]. The variadic parameter may have an optional identifier, such as `args: ...`. r[items.fn.body] ## Function body @@ -339,7 +339,9 @@ r[items.fn.c-variadic.intro] A *c-variadic* function accepts a variable argument list `pat: ...` as its final parameter. ```rust -unsafe extern "C" fn example(arg0: i32, ap: ...) { } +unsafe extern "C" fn example(ap: ...) -> f64 { + unsafe { ap.arg::() } +} ``` This parameter stands in for an arbitrary number of arguments that may be passed by the caller. @@ -347,7 +349,10 @@ This parameter stands in for an arbitrary number of arguments that may be passed > [!WARNING] > Passing an unexpected number of arguments or arguments of unexpected type to a variadic function may lead to [undefined behavior][undefined]. -r[items.fn.async.desugar-brief] +r[items.fn.c-variadic.variadic-parameter-type] +The type of `pat` in the function body is [`VaList`]. + +r[items.fn.c-variadic.desugar-brief] A c-variadic function definition is roughly equivalent to a function operating on a [`VaList`]. @@ -501,6 +506,6 @@ fn foo_oof(#[some_inert_attribute] arg: u8) { [associated function]: associated-items.md#associated-functions-and-methods [implementation]: implementations.md [value namespace]: ../names/namespaces.md -[variadic function]: external-blocks.md#variadic-functions +[c-variadic function]: external-blocks.md#variadic-functions [`extern` block]: external-blocks.md [`VaList`]: std::ffi::VaList From 63b268ba59e853ed2affa6f59b776a3838114f81 Mon Sep 17 00:00:00 2001 From: Folkert de Vries Date: Thu, 23 Apr 2026 17:27:18 +0200 Subject: [PATCH 4/4] tweak and simplify --- src/items/functions.md | 27 +++++++++++---------------- 1 file changed, 11 insertions(+), 16 deletions(-) diff --git a/src/items/functions.md b/src/items/functions.md index 451109627d..be64c93470 100644 --- a/src/items/functions.md +++ b/src/items/functions.md @@ -83,7 +83,7 @@ r[items.fn.params.self-restriction] Functions with a self parameter may only appear as an [associated function] in a [trait] or [implementation]. r[items.fn.params.varargs] -A parameter with the `...` token indicates a [c-variadic function]. The variadic parameter may have an optional identifier, such as `args: ...`. +A parameter with the `...` token indicates a [c-variadic function], and may only be used as the last parameter. In an [`extern` block] the c-variadic parameter may have an optional identifier, such as `args: ...`, in a [c-variadic function definition] the identifier is mandatory. r[items.fn.body] ## Function body @@ -340,27 +340,25 @@ A *c-variadic* function accepts a variable argument list `pat: ...` as its final ```rust unsafe extern "C" fn example(ap: ...) -> f64 { - unsafe { ap.arg::() } + unsafe { ap.next_arg::() } } ``` This parameter stands in for an arbitrary number of arguments that may be passed by the caller. > [!WARNING] -> Passing an unexpected number of arguments or arguments of unexpected type to a variadic function may lead to [undefined behavior][undefined]. +> Passing an unexpected number of arguments or arguments of unexpected type to a c-variadic function may lead to [undefined behavior][undefined]. -r[items.fn.c-variadic.variadic-parameter-type] +r[items.fn.c-variadic.c-variadic-parameter-type] The type of `pat` in the function body is [`VaList`]. r[items.fn.c-variadic.desugar-brief] A c-variadic function definition is roughly equivalent to a function operating on a [`VaList`]. - - ```rust // Source unsafe extern "C" fn example(mut ap: ...) -> i32 { - unsafe { ap.arg::() } + unsafe { ap.next_arg::() } } ``` @@ -368,15 +366,11 @@ is roughly equivalent to: ```rust # use std::ffi::VaList; -# use std::mem::MaybeUninit; -# fn va_start() {} // Desugared unsafe extern "C" fn example() -> i32 { - let mut storage = MaybeUninit::>::uninit(); - va_start(storage.as_mut_ptr()); // Initializes the VaList. - let mut ap: &mut VaList<'_> = ap.assume_init_mut(); + let mut ap: VaList<'_> = /* compiler initializes the VaList */; - unsafe { ap.arg::() } + unsafe { ap.next_arg::() } va_end(ap) } @@ -389,7 +383,7 @@ r[items.fn.c-variadic.ffi-compatibility] The rust [`VaList`] is ABI-compatible with the C `va_list` type. r[items.fn.c-variadic.abi] -Only `extern "C"` and `extern "C-unwind"` functions can accept a variable argument list. +Only `extern "C"` and `extern "C-unwind"` function defintions can accept a variable argument list. r[items.fn.c-variadic.safety] Only `unsafe` functions can accept a variable argument list. @@ -403,7 +397,7 @@ A c-variadic functions cannot be `const` r[items.fn.c-variadic.platform-support] Some ABIs do not support c-variadic function definitions. The compiler errors in this case. -``` +```text error: the `bpfel` target does not support c-variadic functions --> $DIR/not-supported.rs:23:31 | @@ -412,7 +406,7 @@ LL | unsafe extern "C" fn variadic(_: ...) {} ``` r[items.fn.c-variadic.dyn-compat] -When a trait method is c-variadic, the trait is no longer dyn-compatible. +When a trait method is c-variadic, the trait is no longer [dyn-compatible]. r[items.fn.attributes] ## Attributes on functions @@ -509,3 +503,4 @@ fn foo_oof(#[some_inert_attribute] arg: u8) { [c-variadic function]: external-blocks.md#variadic-functions [`extern` block]: external-blocks.md [`VaList`]: std::ffi::VaList +[dyn-compatible]: traits.md#dyn-compatibility