add c-variadic function definitions by folkertdev · Pull Request #2177 · rust-lang/reference

folkertdev · 2026-02-17T21:27:24Z

I think this has all of the raw material, but needs polishing.

Here is a draft of the stabilization report, for additional context: https://hackmd.io/@Q66MPiW4T7yNTKOCaEb-Lw/S1iI3WIwZg

Tracking issue: rust-lang/rust#44930

folkertdev · 2026-02-17T21:33:21Z

+> [!WARNING]
+> Passing an unexpected number of arguments or arguments of unexpected type to a variadic function may lead to [undefined behavior][undefined].


copied from

https://doc.rust-lang.org/reference/items/external-blocks.html?highlight=variadic#r-items.extern.variadic

basically, the responsibility for passing valid arguments is on the caller.

ehuss

I think the rule items.fn.params.varargs will need to be updated, since it says it can only be used in an external block.

View changes since this review

ehuss · 2026-02-27T15:18:06Z

+> 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`].


What is "roughly" about it?

In how arguments are actually passed, these signatures are (very) different

fn foo(ap: ...) { /* ... */ } fn bar(ap: VaList) { /* ... */ }

Those two functions could have exactly the same body though.

Looking at it again, I'm not sure this desugaring answers more questions than it raises? Because really it is not a desugaring, we're hooking into a bunch of custom compiler magic to make this work. We could provide an equivalent C function perhaps to illustrate what parts the rust compiler handles automatically in comparison.

i.e. it is equivalent to

// Assuming C23, so `...` as the only argument is accepted. int example(...) { va_list ap; va_start(ap); int x = va_arg(ap, int); va_end(ap); return x; }

@ghost

…-in-deps, r=mati865 report the `varargs_without_pattern` lint in deps tracking issue: rust-lang#44930 After discussion in rust-lang/reference#2177 (comment). Based on rust-lang#143619 (comment) there was only one actual impacted crate https://crates.io/crates/binrw. The issue was fixed in jam1garner/binrw#342, and has since been released jam1garner/binrw#342 (comment). Hence we may as well report this loudly. r? @ghost

@ghost

…-in-deps, r=mati865 report the `varargs_without_pattern` lint in deps tracking issue: rust-lang#44930 After discussion in rust-lang/reference#2177 (comment). Based on rust-lang#143619 (comment) there was only one actual impacted crate https://crates.io/crates/binrw. The issue was fixed in jam1garner/binrw#342, and has since been released jam1garner/binrw#342 (comment). Hence we may as well report this loudly. r? @ghost

@ghost

…-in-deps, r=mati865 report the `varargs_without_pattern` lint in deps tracking issue: rust-lang#44930 After discussion in rust-lang/reference#2177 (comment). Based on rust-lang#143619 (comment) there was only one actual impacted crate https://crates.io/crates/binrw. The issue was fixed in jam1garner/binrw#342, and has since been released jam1garner/binrw#342 (comment). Hence we may as well report this loudly. r? @ghost

@ghost

Rollup merge of #154599 - folkertdev:varargs-without-pattern-in-deps, r=mati865 report the `varargs_without_pattern` lint in deps tracking issue: #44930 After discussion in rust-lang/reference#2177 (comment). Based on #143619 (comment) there was only one actual impacted crate https://crates.io/crates/binrw. The issue was fixed in jam1garner/binrw#342, and has since been released jam1garner/binrw#342 (comment). Hence we may as well report this loudly. r? @ghost

folkertdev · 2026-04-23T15:29:03Z

The varargs_without_pattern is now reported in dependencies (on nightly).

I've pushed some tweaks, I'm now planning to submit a stabilization PR in coming days, so if you could look at this again that would be helpful.

ehuss · 2026-04-30T02:45:37Z

It looks like from rust-lang/rust#155974 that there is an intent to make this unavailable on certain targets. I don't think we've ever done something like that, and I'm not sure how we're going to document that. I suppose there will be a rule. It will need to be careful to distinguish that it is a compile error during validation. Unfortunately we don't define that as a specific phase in the reference, so I'm not sure how we should approach that.

folkertdev · 2026-04-30T08:55:01Z

I don't think this is very different from https://doc.rust-lang.org/beta/unstable-book/language-features/asm-experimental-arch.html. Consequently the page on inline assembly specifies https://doc.rust-lang.org/nightly/reference/inline-assembly.html?highlight=assemb#r-asm.stable-targets.

So we could have

Support for c-variadic function definitions is stable on the following architectures:

x86 and x86-64

arm

aarch64 and arm64ec

...

The compiler will emit an error if ... is used in a function definition on an unsupported target.

Also spirv and bpf just fundamentally do not support this feature, so there you'd always get an error.

tgross35 · 2026-07-10T12:00:27Z

+- x86 and x86-64
+- ARM
+- AArch64 and Arm64EC
+- RISC-V (except when using the ilp32e ABI)
+- LoongArch
+- s390x
+- PowerPC and PowerPC64
+- AmdGpu and Nvptx64
+- wasm32 and wasm64
+- csky
+- xtensa
+- hexagon
+- sparc64
+- mips


Nit: This mixes lowercase with the arches' name casing (C-SKY, Xtensa, Hexagon, SPARC64, MIPS, Wasm). Also some platforms are explicit about both 32- and 64-bit (x86, ppc) while others aren't (loongarch, mips)

View changes since the review

It is based on the list of stable architectures for asm!, I've tried to correct the names.

folkertdev

The merge of the stabilization PR is now only blocked on the additions to the reference here (I'm not sure that is really needed, previously features have been merged with a reference PR that was "far enough along").

I've tried to address comments here as much possible now.

I'd be happy to look at this together in the reference office hours if they are at a somewhat european-friendly time.

View changes since this review

folkertdev · 2026-07-17T09:20:26Z

+> 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`].


Looking at it again, I'm not sure this desugaring answers more questions than it raises? Because really it is not a desugaring, we're hooking into a bunch of custom compiler magic to make this work. We could provide an equivalent C function perhaps to illustrate what parts the rust compiler handles automatically in comparison.

folkertdev · 2026-07-17T09:21:56Z

+- x86 and x86-64
+- ARM
+- AArch64 and Arm64EC
+- RISC-V (except when using the ilp32e ABI)
+- LoongArch
+- s390x
+- PowerPC and PowerPC64
+- AmdGpu and Nvptx64
+- wasm32 and wasm64
+- csky
+- xtensa
+- hexagon
+- sparc64
+- mips


It is based on the list of stable architectures for asm!, I've tried to correct the names.

folkertdev · 2026-07-17T09:32:27Z

+> 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`].


i.e. it is equivalent to

// Assuming C23, so `...` as the only argument is accepted. int example(...) { va_list ap; va_start(ap); int x = va_arg(ap, int); va_end(ap); return x; }

ehuss

Some quick nits.

View changes since this review

rustbot · 2026-07-21T20:44:44Z

This PR was rebased onto a different master commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

@workingjubilee

…=tgross35,traviscross Stabilize c-variadic function definitions tracking issue: Fixes rust-lang#44930 reference PR: rust-lang/reference#2177 There are some minor things still in flight, but I think we're far enough along now. # Stabilization report ## Summary In C, functions can use a variable argument list `...` to accept an arbitrary number of untyped arguments. Rust is already able to call such functions (e.g. `libc::printf`), the `c_variadic` feature adds the ability to define them. A rust c-variadic function looks like this: ```rust /// SAFETY: must be called with (at least) 2 i32 arguments. unsafe extern "C" fn sum(mut args: ...) -> i32 { let a = args.next_arg::<i32>(); let b = args.next_arg::<i32>(); a + b } fn foo() -> i32 { unsafe { sum(0i32, 2i32) } } ``` This function accepts a variable arguments list `args: ...`, from which it is able to read arguments using the `next_arg` method. The main goal of defining c-variadic functions in rust is interaction with C code. Therefore it is a design goal that the rust types map directly to their C counterparts on all targets. Additionally, we disallow interaction between c-variadic functions and certain rust features that don't make much sense in an FFI context (e.g. `extern "Rust" fn` or `async fn`). ## How variadics work in C The authoritative source for how variadics (also known as "variable arguments") work in C is the C specification. In this document we'll use [section 7.16 of the final draft of the C23 standard](https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3220.pdf#page=302). > A function may be called with a variable number of arguments of varying types if its parameter type list ends with an ellipsis Earlier versions of C furthermore required that the `...` argument is not the first argument of the parameter type list (so at least one other argument was required). Starting in C23 this requirement has been lifted. ### C API surface - `va_list`: an opaque type that stores the information needed to read variadic arguments, or copy the list of variadic arguments. Typically values of this type get the name `ap`. - `va_start`: a `va_list` must be initialized with the `va_start` macro before it can be used. - `va_copy`: the `va_copy` macro copies a `va_list`. The copy starts at the position in the argument list of the original (so **not** at the first variadic argument to the function), and both can be moved forward independently. This means the same argument can be read multiple times. - `va_arg`: reads the next argument from the `va_ist`. - `va_end`: deinitializes a `va_list`. ### Important notes #### Not calling `va_end` is UB Section 7.16.1 > Each invocation of the `va_start` and `va_copy` macros shall be matched by a corresponding invocation of the `va_end` macro in the same function. Section 7.16.1.3: > The `va_end` macro facilitates a normal return from the function whose variable argument list was referred to by the expansion of the `va_start` macro, or the function containing the expansion of the `va_copy` macro, that initialized the `va_list` ap. The `va_end` macro may modify ap so that it is no longer usable (without being reinitialized by the `va_start` or `va_copy` macro). If there is no corresponding invocation of the `va_start` or `va_copy` macro, or if the `va_end` macro is not invoked before the return, the behavior is undefined. We believe that this behavior is this strict because some early C implementations chose to implement `va_list` like so [(source)](https://softwarepreservation.computerhistory.org/c_plus_plus/cfront/release_3.0.3/source/incl-master/proto-headers/stdarg.sol): ```rust #define va_start(ap, parmN) {\ va_buf _va;\ _vastart(ap = (va_list)_va, (char *)&parmN + sizeof parmN) #define va_end(ap) } #define va_arg(ap, mode) *((mode *)_vaarg(ap, sizeof (mode))) ``` To our knowledge no remotely-modern implementation actually implements `va_end` as anything but a no-op. #### A `va_list` may be moved Section 7.16 > The object `ap` may be passed as an argument to another function; if that function invokes the `va_arg` macro with parameter `ap`, the representation of `ap` in the calling function is indeterminate and shall be passed to the `va_end` macro prior to any further reference to `ap`. and > A pointer to a `va_list` can be created and passed to another function, in which case the original function can make further use of the original list after the other function returns So `va_list` can be moved into another function, but `va_end` must still run in the frame that initialized (with `va_start` or `va_copy`) the `va_list` . #### Representation of `va_list` The representation of `va_list` is platform-specific. There are three flavors that are used by current rust targets: - `va_list` is an opaque pointer - `va_list` is a struct - `va_list` is a single-element array, containing a struct The opaque pointer approach is the simplest to implement: the pointer just points to an array of arguments on the caller's stack. The struct and single-element array variants are more complex, but potentially more efficient because the additional state makes it possible to pass c-variadic arguments via registers. #### array-to-pointer decay If the `va_list` is of the single-element array flavor, it is subject to array-to-pointer decay: in C, arrays are passed not by-value, but as pointers. Hence, from an FFI perspective, these two functions are equivalent. ```c #include <stdarg.h> extern int foo(va_list va) { return va_arg(va, int); } extern int bar(va_list *va) { return va_arg(*va, int); } ``` Indeed, they generate the same assembly, see https://godbolt.org/z/n8c4aq5hM. #### other calling conventions Both `clang` and `gcc` refuse to compile a function that uses variadic arguments and a non-default calling convention. See also rust-lang#141618, in particular rust-lang#141618 (comment). The LLVM intrinsics (`va_start`, `va_arg`, etc.) always expand based on the default C ABI on the current platform, not the ABI of the function they are used in. While rust only supports defining C-variadic functions with the `extern "C"` ABI that is fine, but relaxing that restriction would require either changing LLVM to take the calling convention of the current function into account, or implementing `va_start` ourselves for all platforms. ### `va_arg` and argument promotion With some exceptions, the return type of a `va_arg` call must match the type of the supplied argument: Section 7.16.1 > If type is not compatible with the type of the actual next argument (as promoted according to the default argument promotions), the behavior is undefined These default argument promotions are specified in section 6.5.3.3: > The arguments are implicitly converted, as if by assignment, to the types of the corresponding parameters, taking the type of each parameter to be the unqualified version of its declared type. The ellipsis notation in a function prototype declarator causes argument type conversion to stop after the last declared parameter, if present. The integer promotions are performed on each trailing argument, and trailing arguments that have type float are promoted to double. These are called the default argument promotions. No other conversions are performed implicitly There are a couple of additional conversions that are allowed, such as casting signed to/from unsigned integers. A concrete example of what is not allowed is to use `va_arg` to read (signed or unsigned) `char` or `short`, or `float` arguments. Reading such types is UB. See also rust-lang#61275 (comment). ## How c-variadics work in rust ### Rust API surface The rust API has similar capabilities to C but uses rust names and concepts. ```rust pub struct VaList<'f> { /* ... */ _marker: PhantomCovariantLifetime<'f>, } ``` The `VaList` struct has a lifetime parameter that ensures that the `VaList` cannot outlive the function that created it. Semantically `VaList` contains mutable references (to the caller's and/or callee's stack), so the lifetime is covariant. The `#[rustc_pass_indirectly_in_non_rustic_abis]` attribute is applied to the definition if `va_list` is a single-element array on the target platform. This attribute simulates the array-to-pointer decay that the C `va_list` type is subject to on that target. A goal of `c_variadic` is to be able to write portable code that uses c-variadics. When `va_list` is a pointer or struct FFI compatibility with a rust `VaList` is straightforward, the attribute to pass indirectly is needed to also make the types FFI compatible on targets where array-to-pointer decay kicks in. The `#[rustc_pass_indirectly_in_non_rustic_abis]` attribute works as desired because `VaList` is a by-move type: in rust this is enforced by the type system, in C the specification requires it. Mutations to the passed object are not observable in the caller (because the value is semantically moved and hence inaccessible). The `VaList::next_arg` method can be used to read the next argument. ```rust pub unsafe trait VaArgSafe: Copy + Sealed {} impl<'f> VaList<'f> { pub unsafe fn next_arg<T: VaArgSafe>(&mut self) -> T { /* ... */ } } ``` The implementation is equivalent to C `va_arg`, though for all targets that we propose to stabilize here the `va_arg` logic is implemented in `rustc` itself, and does not rely on LLVM (more information on that below). The return type is constrained by `VaArgSafe` so that only valid argument types can be read. In particular this mechanism prevents subtle issues around implicit numeric promotion in C. Reading an argument is unsafe because reading more arguments than were supplied is UB. Implementors of `VaArgSafe` must implement `Copy` because the `VaList` can be cloned and hence the same variable argument can be read twice, which is only safe if the type is `Copy`. The `VaArgSafe` trait is guaranteed to be implemented for: - `c_int`, `c_long` and `c_longlong` - `c_uint`, `c_ulong` and `c_ulonglong` - `c_double` - `*const T` and `*mut T` Implementations for other types are not guaranteed to be portable, so portable programs should not rely on e.g. `usize` or `f64` implementing this trait directly. C argument types are considered to have the rust type that corresponds to `core::ffi::*`, so a C `int` is mapped to `c_int` and so on. We don't consider the C `_BitInt` or `_Float32` types here, rather we (on most platforms) map `f64` to `double` etc. `_BitInt(32)` and `int` are distinct types. `_BitInt` is furthermore special because it does not participate in integer promotion. Calling `VaList::next_arg` to read an argument of type `T` is only safe if all of the following conditions are satisfied: - There is another c-variadic argument to read. - The actual type of the argument `U` is compatible with `T` (as defined below). - If `U` and `T` are both integer types, then the value passed by the caller must be representable in both types. Types `T` and `U` are compatible when: - `T` and `U` are the same type (up to free lifetimes). - `T` and `U` are integer types of the same size. - `T` and `U` are both pointers, and their target types are compatible. - `T` is a pointer to `c_void` and `U` is a pointer to `i8` or `u8`, or vice versa. ```rust // SAFETY: the caller must supply an argument that is compatible with `u64`, // optionally followed by other arguments that are ignored. unsafe extern "C" fn variadic(mut ap: ...) -> u64 { unsafe { ap.next_arg::<u64>() } } // The type is incompatible, Miri will report UB. unsafe { variadic(1u32) } // The value is not representable by u64, Miri will report UB. unsafe { variadic(-1i64) } // This is fine. unsafe { variadic(42i64) } ``` And an example of when equality up to free lifetimes is relevant. ```rust const unsafe extern "C" fn read_as<T: core::ffi::VaArgSafe>(mut ap: ...) -> T { ap.next_arg::<T>() } unsafe fn read_cast_lifetime() { // Allowed const { read_as::<*const &'static i32>(std::ptr::dangling::<&i32>()) }; // Not allowed const { read_as::<*const fn(&'static ())>(std::ptr::dangling::<for<'a> fn(&'a ())>()) }; //~^ ERROR va_arg type mismatch: requested `*const fn(&())` is incompatible with next argument of type `*const for<'a> fn(&'a ())` } ``` The `VaList` type implements `Clone` and `Drop`: ```rust impl<'f> Clone for VaList<'f> { /* ... */ } impl<'f> Drop for VaList<'f> { fn drop(&mut self) { /* no-op */ } } ``` The `Clone` implementation can be used to duplicate a `VaList`. The copy has the same position as the original, but both can be incremented independently. While all current targets could also implement `Copy` for `VaList`, a future target might not, so for now `Copy` is not implemented. LLVM now guarantee that `memcpy` may be used to duplicate a `VaList` when the operation is equivalent to `memcpy` on the platform, which is true for all current LLVM targets. The `Drop` implementation is a no-op, it does call a function named `va_end`, but that itself is a no-op that exists only for Miri to detect UB. In C,`va_end` must run in the frame where the `va_list` was initialized. Because `VaList` can be moved (like the C `va_list`), the frame in which a `VaList` is dropped may not be the frame in which it was initialized. LLVM now guarantees that `va_end` may be omitted when `va_end` is a no-op, which is the case for all current LLVM targets. The `VaList` type is available on all targets, even on targets that don't actually support c-variadic definitions. On such targets, it is impossible to get a valid `VaList` value, because attempting to define a c-variadic function (using the `...` argument) will throw an error. ### Syntax In rust, a C-variadic function looks like this: ```rust unsafe extern "C" fn foo(a: i32, b: i32, args: ...) { /* body */ } ``` The special `args: ...` argument stands in for an arbitrary number of arguments that the caller may pass. The `...` argument must be the last argument in the parameter list of a function. Like in C23 and later, `...` may be the only argument. The `...` syntax is already stable in foreign functions, `c_variadic` additionally allows it in function definitions. In function definitions, the `...` argument must have a pattern. The argument can be ignored by using `_: ...`. In foreign function declarations the pattern can be omitted. A function definition with a `...` argument must be an `unsafe` function. Passing an incorrect number of arguments, or arguments of the wrong type, is UB, and hence every call site has to satisfy the safety conditions. A special case is a function that ignores its `VaList` entirely using `_: ...`: we may decide to allow such functions to be safe. At the time of writing we see insufficient benefits relative to the additional complexity that this entails. A function with the `...` argument must be an `extern "C"` or `extern "C-unwind"` function. In the future we want to extend the set of accepted ABIs to include all ABIs for which we allow calling a c-variadic function (including e.g. `sysv64` and `win64`). The `...` argument can occur in definitions of functions, inherent methods, and trait methods. When any method on a trait uses a c-variadic argument, the trait is no longer dyn-compatible. The technical reason is that there is no sound way to generate a `ReifyShim` that passes on the c-variadic arguments. ### Desugaring In a function like this: ```rust unsafe extern "C" fn foo(args: ...) { // ... } ``` The `args: ...` is internally desugared into a call to LLVM's `va_start` that initializes `args` as a `VaList`. The `VaList` gets the lifetime of a local variable on `foo`'s stack, so that the `VaList` cannot outlive the function that created it. The desugaring will fail with an error when the current target does not support c-variadic definitions. Currently this is the case for `spriv` and `bpf`: ``` error: the `bpfel` target does not support c-variadic functions --> $DIR/not-supported.rs:23:31 | LL | unsafe extern "C" fn variadic(_: ...) {} | ^^^^^^ ``` ### A note on LLVM `va_arg` The LLVM `va_arg` intrinsic is known to silently miscompile. A [comment in the implementation](https://github.com/llvm/llvm-project/blob/72c8f98f74f2b4f9677d0d5e3dc91bc4d6cb39f4/clang/lib/CodeGen/ABIInfoImpl.cpp#L406-L411) notes: > This default implementation defers to the llvm backend's va_arg instruction. It can handle only passing arguments directly (typically only handled in the backend for primitive types), or aggregates passed indirectly by pointer (NOTE: if the "byval" flag has ABI impact in the callee, this implementation cannot work.) > > Only a few cases are covered here at the moment -- those needed by the default abi. Hence, like `clang`, `rustc` implements `va_arg` for the vast majority of targets (specifically including all tier-1 targets) in [`va_arg.rs`](https://github.com/rust-lang/rust/blob/master/compiler/rustc_codegen_llvm/src/va_arg.rs). Note that the match on the architecture is exhaustive, however the behavior on targets where we've not validated the correctness of the implementation is an unresolved question (see below). ## Future extensions ### C-variadics and `const fn` Support for c-variadic `const fn` (and by extension, support in Miri) is implemented in rust-lang#150601 and gated by `const_c_variadic`. Practical usage requires `const_destruct` too because `VaList` has a custom `Drop` implementation. ```rust #![feature(c_variadic, const_c_variadic, const_destruct)] const unsafe extern "C" fn variadic(mut ap: ...) -> i32 { ap.next_arg() } ``` ### Naked variadic functions Currently only `C` and `C-unwind` are valid ABIs for all c-variadic function definitions. With naked functions it is possible to define e.g. a `win64` c-variadic function in a program where `sysv64` is the default. This feature is tracked as [`c_variadic_naked_functions`](rust-lang#148767). ```rust #![feature(c_variadic, c_variadic_naked_functions)] #[unsafe(naked)] unsafe extern "win64" fn variadic_win64(_: u32, _: ...) -> u32 { core::arch::naked_asm!( r#" push rax mov qword ptr [rsp + 40], r9 mov qword ptr [rsp + 24], rdx mov qword ptr [rsp + 32], r8 lea rax, [rsp + 40] mov qword ptr [rsp], rax lea eax, [rdx + rcx] add eax, r8d pop rcx ret "#, ) } ``` ### C-variadics and coroutines An `async fn` or any other type of coroutine cannot be c-variadic. We see no reason to support this. ### Defining safe C-variadic functions In `extern` blocks, it is valid to mark C-variadic functions as safe, under the assumption that the function completely ignores the variable arguments list: ```rust unsafe extern "C" { safe fn foo(...); } ``` Normally, C-variadic function definitions must be unsafe, because calling the function with unexpected (in type or number) elements is UB. We could relax this constraint on C-variadic functions that ignore their C variable argument list, e.g.: ```rust // NOTE: not unsafe extern "C" fn(x: i32, _: ...) -> i32 { x } ``` At the moment we don't have a good reason to add this behavior. It is completely backwards compatible, so if a need arises in the future we can revisit this. ### Accepting more `va_arg` return types Discussed in rust-lang#44930 (comment). We only want to implement `VaArgSafe` for types that have a clear counterpart in C. That rules out types like `Option<NonNull>` or `NonZeroI32`. We might add `MaybeUninit<c_int>` and so on in the future if a use case comes up: this would map to a C `union`. The only planned extension right now is support for `i128` and `u128` where they can be mapped to (unsigned) `__int128`. However `rustc` currently does not know on what targets this type is available, and hence we leave it out of the stabilization for now. Adding 128-bit support is in progress in rust-lang#155429. ### C-variadic support on untested targets Because c-variadic is a platform-specific feature, and extremely unsafe, we're apprehensive about stabilizing it for targets where that implementation has not actually been validated. The [`#[c_variadic_experimental_arch]`](rust-lang#155973) feature gates such targets. The current list of targets which are kept unstable by this PR is: - `riscv32e-unknown-none-elf` because its ABI may change in the future - `sparc` because compilers for it are no longer distributed - `avr`, `m68k` and `msp430` because they are hard to validate - targets categorized as `Other`, e.g. through a custom `target.json` ### Multiple C-variadic ABIs in the same program rust-lang#141618 Both `clang` and `gcc` reject using `...` in functions with a non-default ABI for the target. That makes the layout of `VaList` and expansion of `va_start`, `va_arg` etc. unambiguous. For now we impose a similar restriction for the rust implementation. This restriction could be lifted in the future, but this would requite that `VaList` somehow "stores" its ABI. One approach is to add a type parameter to `VaList` that default's to the platform's default ABI. Each c-variadic argument would then desugar to use the ABI of the c-variadic function that creates it. ## History [RFC 2137](rust-lang/rfcs#2137) proposes to "support defining C-compatible variadic functions in rust" in 2017, and it is still the core of the implementation today. The text lays out a basic rust API and highlights potential issues (e.g. some solution is needed to match C's array-to-pointer decay), but does not always provide concrete solutions. In 2019 rust-lang#59625 introduces a wrapper type to simulate array-to-pointer decay. With this API the C semantics can be matched, but doing so correctly takes a great deal of care. The `VaList` type also has two lifetime arguments in this version, which is inelegant. Then, little seems to have happened for 6 years, until the recent burst of activity that resulted in the current proposal. - [#t-compiler > c_variadic API and ABI](https://rust-lang.zulipchat.com/#narrow/channel/131828-t-compiler/topic/c_variadic.20API.20and.20ABI/with/527115587) - rust-lang#141524 **implementation history** The list of PRs is long, but they have all been labled with [`F-c_variadic`](https://github.com/rust-lang/rust/pulls?q=is%3Apr+label%3AF-c_variadic+). ## Unresolved Questions ### `VaArgSafe` and function pointers rust-lang#153646 Currently `VaArgSafe` is not implemented for function pointers, and doing so would be tricky. There is the practical issue of not being able to be generic over the number of arguments, but there are also some complex constraints on the signature, see https://www.gnu.org/software/c-intro-and-ref/manual/html_node/Compatible-Types.html. ### Thanks Many people have worked on this feature over the years, and many more have provided input. I'd like to credit here the people that have been especially involved in this push for stabilization: @workingjubilee, @RalfJung, @beetrees, @joshtriplett and @tgross35. r? @tgross35

@workingjubilee

…=tgross35,traviscross Stabilize c-variadic function definitions tracking issue: Fixes rust-lang#44930 reference PR: rust-lang/reference#2177 There are some minor things still in flight, but I think we're far enough along now. # Stabilization report ## Summary In C, functions can use a variable argument list `...` to accept an arbitrary number of untyped arguments. Rust is already able to call such functions (e.g. `libc::printf`), the `c_variadic` feature adds the ability to define them. A rust c-variadic function looks like this: ```rust /// SAFETY: must be called with (at least) 2 i32 arguments. unsafe extern "C" fn sum(mut args: ...) -> i32 { let a = args.next_arg::<i32>(); let b = args.next_arg::<i32>(); a + b } fn foo() -> i32 { unsafe { sum(0i32, 2i32) } } ``` This function accepts a variable arguments list `args: ...`, from which it is able to read arguments using the `next_arg` method. The main goal of defining c-variadic functions in rust is interaction with C code. Therefore it is a design goal that the rust types map directly to their C counterparts on all targets. Additionally, we disallow interaction between c-variadic functions and certain rust features that don't make much sense in an FFI context (e.g. `extern "Rust" fn` or `async fn`). ## How variadics work in C The authoritative source for how variadics (also known as "variable arguments") work in C is the C specification. In this document we'll use [section 7.16 of the final draft of the C23 standard](https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3220.pdf#page=302). > A function may be called with a variable number of arguments of varying types if its parameter type list ends with an ellipsis Earlier versions of C furthermore required that the `...` argument is not the first argument of the parameter type list (so at least one other argument was required). Starting in C23 this requirement has been lifted. ### C API surface - `va_list`: an opaque type that stores the information needed to read variadic arguments, or copy the list of variadic arguments. Typically values of this type get the name `ap`. - `va_start`: a `va_list` must be initialized with the `va_start` macro before it can be used. - `va_copy`: the `va_copy` macro copies a `va_list`. The copy starts at the position in the argument list of the original (so **not** at the first variadic argument to the function), and both can be moved forward independently. This means the same argument can be read multiple times. - `va_arg`: reads the next argument from the `va_ist`. - `va_end`: deinitializes a `va_list`. ### Important notes #### Not calling `va_end` is UB Section 7.16.1 > Each invocation of the `va_start` and `va_copy` macros shall be matched by a corresponding invocation of the `va_end` macro in the same function. Section 7.16.1.3: > The `va_end` macro facilitates a normal return from the function whose variable argument list was referred to by the expansion of the `va_start` macro, or the function containing the expansion of the `va_copy` macro, that initialized the `va_list` ap. The `va_end` macro may modify ap so that it is no longer usable (without being reinitialized by the `va_start` or `va_copy` macro). If there is no corresponding invocation of the `va_start` or `va_copy` macro, or if the `va_end` macro is not invoked before the return, the behavior is undefined. We believe that this behavior is this strict because some early C implementations chose to implement `va_list` like so [(source)](https://softwarepreservation.computerhistory.org/c_plus_plus/cfront/release_3.0.3/source/incl-master/proto-headers/stdarg.sol): ```rust #define va_start(ap, parmN) {\ va_buf _va;\ _vastart(ap = (va_list)_va, (char *)&parmN + sizeof parmN) #define va_end(ap) } #define va_arg(ap, mode) *((mode *)_vaarg(ap, sizeof (mode))) ``` To our knowledge no remotely-modern implementation actually implements `va_end` as anything but a no-op. #### A `va_list` may be moved Section 7.16 > The object `ap` may be passed as an argument to another function; if that function invokes the `va_arg` macro with parameter `ap`, the representation of `ap` in the calling function is indeterminate and shall be passed to the `va_end` macro prior to any further reference to `ap`. and > A pointer to a `va_list` can be created and passed to another function, in which case the original function can make further use of the original list after the other function returns So `va_list` can be moved into another function, but `va_end` must still run in the frame that initialized (with `va_start` or `va_copy`) the `va_list` . #### Representation of `va_list` The representation of `va_list` is platform-specific. There are three flavors that are used by current rust targets: - `va_list` is an opaque pointer - `va_list` is a struct - `va_list` is a single-element array, containing a struct The opaque pointer approach is the simplest to implement: the pointer just points to an array of arguments on the caller's stack. The struct and single-element array variants are more complex, but potentially more efficient because the additional state makes it possible to pass c-variadic arguments via registers. #### array-to-pointer decay If the `va_list` is of the single-element array flavor, it is subject to array-to-pointer decay: in C, arrays are passed not by-value, but as pointers. Hence, from an FFI perspective, these two functions are equivalent. ```c #include <stdarg.h> extern int foo(va_list va) { return va_arg(va, int); } extern int bar(va_list *va) { return va_arg(*va, int); } ``` Indeed, they generate the same assembly, see https://godbolt.org/z/n8c4aq5hM. #### other calling conventions Both `clang` and `gcc` refuse to compile a function that uses variadic arguments and a non-default calling convention. See also rust-lang#141618, in particular rust-lang#141618 (comment). The LLVM intrinsics (`va_start`, `va_arg`, etc.) always expand based on the default C ABI on the current platform, not the ABI of the function they are used in. While rust only supports defining C-variadic functions with the `extern "C"` ABI that is fine, but relaxing that restriction would require either changing LLVM to take the calling convention of the current function into account, or implementing `va_start` ourselves for all platforms. ### `va_arg` and argument promotion With some exceptions, the return type of a `va_arg` call must match the type of the supplied argument: Section 7.16.1 > If type is not compatible with the type of the actual next argument (as promoted according to the default argument promotions), the behavior is undefined These default argument promotions are specified in section 6.5.3.3: > The arguments are implicitly converted, as if by assignment, to the types of the corresponding parameters, taking the type of each parameter to be the unqualified version of its declared type. The ellipsis notation in a function prototype declarator causes argument type conversion to stop after the last declared parameter, if present. The integer promotions are performed on each trailing argument, and trailing arguments that have type float are promoted to double. These are called the default argument promotions. No other conversions are performed implicitly There are a couple of additional conversions that are allowed, such as casting signed to/from unsigned integers. A concrete example of what is not allowed is to use `va_arg` to read (signed or unsigned) `char` or `short`, or `float` arguments. Reading such types is UB. See also rust-lang#61275 (comment). ## How c-variadics work in rust ### Rust API surface The rust API has similar capabilities to C but uses rust names and concepts. ```rust pub struct VaList<'f> { /* ... */ _marker: PhantomCovariantLifetime<'f>, } ``` The `VaList` struct has a lifetime parameter that ensures that the `VaList` cannot outlive the function that created it. Semantically `VaList` contains mutable references (to the caller's and/or callee's stack), so the lifetime is covariant. The `#[rustc_pass_indirectly_in_non_rustic_abis]` attribute is applied to the definition if `va_list` is a single-element array on the target platform. This attribute simulates the array-to-pointer decay that the C `va_list` type is subject to on that target. A goal of `c_variadic` is to be able to write portable code that uses c-variadics. When `va_list` is a pointer or struct FFI compatibility with a rust `VaList` is straightforward, the attribute to pass indirectly is needed to also make the types FFI compatible on targets where array-to-pointer decay kicks in. The `#[rustc_pass_indirectly_in_non_rustic_abis]` attribute works as desired because `VaList` is a by-move type: in rust this is enforced by the type system, in C the specification requires it. Mutations to the passed object are not observable in the caller (because the value is semantically moved and hence inaccessible). The `VaList::next_arg` method can be used to read the next argument. ```rust pub unsafe trait VaArgSafe: Copy + Sealed {} impl<'f> VaList<'f> { pub unsafe fn next_arg<T: VaArgSafe>(&mut self) -> T { /* ... */ } } ``` The implementation is equivalent to C `va_arg`, though for all targets that we propose to stabilize here the `va_arg` logic is implemented in `rustc` itself, and does not rely on LLVM (more information on that below). The return type is constrained by `VaArgSafe` so that only valid argument types can be read. In particular this mechanism prevents subtle issues around implicit numeric promotion in C. Reading an argument is unsafe because reading more arguments than were supplied is UB. Implementors of `VaArgSafe` must implement `Copy` because the `VaList` can be cloned and hence the same variable argument can be read twice, which is only safe if the type is `Copy`. The `VaArgSafe` trait is guaranteed to be implemented for: - `c_int`, `c_long` and `c_longlong` - `c_uint`, `c_ulong` and `c_ulonglong` - `c_double` - `*const T` and `*mut T` Implementations for other types are not guaranteed to be portable, so portable programs should not rely on e.g. `usize` or `f64` implementing this trait directly. C argument types are considered to have the rust type that corresponds to `core::ffi::*`, so a C `int` is mapped to `c_int` and so on. We don't consider the C `_BitInt` or `_Float32` types here, rather we (on most platforms) map `f64` to `double` etc. `_BitInt(32)` and `int` are distinct types. `_BitInt` is furthermore special because it does not participate in integer promotion. Calling `VaList::next_arg` to read an argument of type `T` is only safe if all of the following conditions are satisfied: - There is another c-variadic argument to read. - The actual type of the argument `U` is compatible with `T` (as defined below). - If `U` and `T` are both integer types, then the value passed by the caller must be representable in both types. Types `T` and `U` are compatible when: - `T` and `U` are the same type (up to free lifetimes). - `T` and `U` are integer types of the same size. - `T` and `U` are both pointers, and their target types are compatible. - `T` is a pointer to `c_void` and `U` is a pointer to `i8` or `u8`, or vice versa. ```rust // SAFETY: the caller must supply an argument that is compatible with `u64`, // optionally followed by other arguments that are ignored. unsafe extern "C" fn variadic(mut ap: ...) -> u64 { unsafe { ap.next_arg::<u64>() } } // The type is incompatible, Miri will report UB. unsafe { variadic(1u32) } // The value is not representable by u64, Miri will report UB. unsafe { variadic(-1i64) } // This is fine. unsafe { variadic(42i64) } ``` And an example of when equality up to free lifetimes is relevant. ```rust const unsafe extern "C" fn read_as<T: core::ffi::VaArgSafe>(mut ap: ...) -> T { ap.next_arg::<T>() } unsafe fn read_cast_lifetime() { // Allowed const { read_as::<*const &'static i32>(std::ptr::dangling::<&i32>()) }; // Not allowed const { read_as::<*const fn(&'static ())>(std::ptr::dangling::<for<'a> fn(&'a ())>()) }; //~^ ERROR va_arg type mismatch: requested `*const fn(&())` is incompatible with next argument of type `*const for<'a> fn(&'a ())` } ``` The `VaList` type implements `Clone` and `Drop`: ```rust impl<'f> Clone for VaList<'f> { /* ... */ } impl<'f> Drop for VaList<'f> { fn drop(&mut self) { /* no-op */ } } ``` The `Clone` implementation can be used to duplicate a `VaList`. The copy has the same position as the original, but both can be incremented independently. While all current targets could also implement `Copy` for `VaList`, a future target might not, so for now `Copy` is not implemented. LLVM now guarantee that `memcpy` may be used to duplicate a `VaList` when the operation is equivalent to `memcpy` on the platform, which is true for all current LLVM targets. The `Drop` implementation is a no-op, it does call a function named `va_end`, but that itself is a no-op that exists only for Miri to detect UB. In C,`va_end` must run in the frame where the `va_list` was initialized. Because `VaList` can be moved (like the C `va_list`), the frame in which a `VaList` is dropped may not be the frame in which it was initialized. LLVM now guarantees that `va_end` may be omitted when `va_end` is a no-op, which is the case for all current LLVM targets. The `VaList` type is available on all targets, even on targets that don't actually support c-variadic definitions. On such targets, it is impossible to get a valid `VaList` value, because attempting to define a c-variadic function (using the `...` argument) will throw an error. ### Syntax In rust, a C-variadic function looks like this: ```rust unsafe extern "C" fn foo(a: i32, b: i32, args: ...) { /* body */ } ``` The special `args: ...` argument stands in for an arbitrary number of arguments that the caller may pass. The `...` argument must be the last argument in the parameter list of a function. Like in C23 and later, `...` may be the only argument. The `...` syntax is already stable in foreign functions, `c_variadic` additionally allows it in function definitions. In function definitions, the `...` argument must have a pattern. The argument can be ignored by using `_: ...`. In foreign function declarations the pattern can be omitted. A function definition with a `...` argument must be an `unsafe` function. Passing an incorrect number of arguments, or arguments of the wrong type, is UB, and hence every call site has to satisfy the safety conditions. A special case is a function that ignores its `VaList` entirely using `_: ...`: we may decide to allow such functions to be safe. At the time of writing we see insufficient benefits relative to the additional complexity that this entails. A function with the `...` argument must be an `extern "C"` or `extern "C-unwind"` function. In the future we want to extend the set of accepted ABIs to include all ABIs for which we allow calling a c-variadic function (including e.g. `sysv64` and `win64`). The `...` argument can occur in definitions of functions, inherent methods, and trait methods. When any method on a trait uses a c-variadic argument, the trait is no longer dyn-compatible. The technical reason is that there is no sound way to generate a `ReifyShim` that passes on the c-variadic arguments. ### Desugaring In a function like this: ```rust unsafe extern "C" fn foo(args: ...) { // ... } ``` The `args: ...` is internally desugared into a call to LLVM's `va_start` that initializes `args` as a `VaList`. The `VaList` gets the lifetime of a local variable on `foo`'s stack, so that the `VaList` cannot outlive the function that created it. The desugaring will fail with an error when the current target does not support c-variadic definitions. Currently this is the case for `spriv` and `bpf`: ``` error: the `bpfel` target does not support c-variadic functions --> $DIR/not-supported.rs:23:31 | LL | unsafe extern "C" fn variadic(_: ...) {} | ^^^^^^ ``` ### A note on LLVM `va_arg` The LLVM `va_arg` intrinsic is known to silently miscompile. A [comment in the implementation](https://github.com/llvm/llvm-project/blob/72c8f98f74f2b4f9677d0d5e3dc91bc4d6cb39f4/clang/lib/CodeGen/ABIInfoImpl.cpp#L406-L411) notes: > This default implementation defers to the llvm backend's va_arg instruction. It can handle only passing arguments directly (typically only handled in the backend for primitive types), or aggregates passed indirectly by pointer (NOTE: if the "byval" flag has ABI impact in the callee, this implementation cannot work.) > > Only a few cases are covered here at the moment -- those needed by the default abi. Hence, like `clang`, `rustc` implements `va_arg` for the vast majority of targets (specifically including all tier-1 targets) in [`va_arg.rs`](https://github.com/rust-lang/rust/blob/master/compiler/rustc_codegen_llvm/src/va_arg.rs). Note that the match on the architecture is exhaustive, however the behavior on targets where we've not validated the correctness of the implementation is an unresolved question (see below). ## Future extensions ### C-variadics and `const fn` Support for c-variadic `const fn` (and by extension, support in Miri) is implemented in rust-lang#150601 and gated by `const_c_variadic`. Practical usage requires `const_destruct` too because `VaList` has a custom `Drop` implementation. ```rust #![feature(c_variadic, const_c_variadic, const_destruct)] const unsafe extern "C" fn variadic(mut ap: ...) -> i32 { ap.next_arg() } ``` ### Naked variadic functions Currently only `C` and `C-unwind` are valid ABIs for all c-variadic function definitions. With naked functions it is possible to define e.g. a `win64` c-variadic function in a program where `sysv64` is the default. This feature is tracked as [`c_variadic_naked_functions`](rust-lang#148767). ```rust #![feature(c_variadic, c_variadic_naked_functions)] #[unsafe(naked)] unsafe extern "win64" fn variadic_win64(_: u32, _: ...) -> u32 { core::arch::naked_asm!( r#" push rax mov qword ptr [rsp + 40], r9 mov qword ptr [rsp + 24], rdx mov qword ptr [rsp + 32], r8 lea rax, [rsp + 40] mov qword ptr [rsp], rax lea eax, [rdx + rcx] add eax, r8d pop rcx ret "#, ) } ``` ### C-variadics and coroutines An `async fn` or any other type of coroutine cannot be c-variadic. We see no reason to support this. ### Defining safe C-variadic functions In `extern` blocks, it is valid to mark C-variadic functions as safe, under the assumption that the function completely ignores the variable arguments list: ```rust unsafe extern "C" { safe fn foo(...); } ``` Normally, C-variadic function definitions must be unsafe, because calling the function with unexpected (in type or number) elements is UB. We could relax this constraint on C-variadic functions that ignore their C variable argument list, e.g.: ```rust // NOTE: not unsafe extern "C" fn(x: i32, _: ...) -> i32 { x } ``` At the moment we don't have a good reason to add this behavior. It is completely backwards compatible, so if a need arises in the future we can revisit this. ### Accepting more `va_arg` return types Discussed in rust-lang#44930 (comment). We only want to implement `VaArgSafe` for types that have a clear counterpart in C. That rules out types like `Option<NonNull>` or `NonZeroI32`. We might add `MaybeUninit<c_int>` and so on in the future if a use case comes up: this would map to a C `union`. The only planned extension right now is support for `i128` and `u128` where they can be mapped to (unsigned) `__int128`. However `rustc` currently does not know on what targets this type is available, and hence we leave it out of the stabilization for now. Adding 128-bit support is in progress in rust-lang#155429. ### C-variadic support on untested targets Because c-variadic is a platform-specific feature, and extremely unsafe, we're apprehensive about stabilizing it for targets where that implementation has not actually been validated. The [`#[c_variadic_experimental_arch]`](rust-lang#155973) feature gates such targets. The current list of targets which are kept unstable by this PR is: - `riscv32e-unknown-none-elf` because its ABI may change in the future - `sparc` because compilers for it are no longer distributed - `avr`, `m68k` and `msp430` because they are hard to validate - targets categorized as `Other`, e.g. through a custom `target.json` ### Multiple C-variadic ABIs in the same program rust-lang#141618 Both `clang` and `gcc` reject using `...` in functions with a non-default ABI for the target. That makes the layout of `VaList` and expansion of `va_start`, `va_arg` etc. unambiguous. For now we impose a similar restriction for the rust implementation. This restriction could be lifted in the future, but this would requite that `VaList` somehow "stores" its ABI. One approach is to add a type parameter to `VaList` that default's to the platform's default ABI. Each c-variadic argument would then desugar to use the ABI of the c-variadic function that creates it. ## History [RFC 2137](rust-lang/rfcs#2137) proposes to "support defining C-compatible variadic functions in rust" in 2017, and it is still the core of the implementation today. The text lays out a basic rust API and highlights potential issues (e.g. some solution is needed to match C's array-to-pointer decay), but does not always provide concrete solutions. In 2019 rust-lang#59625 introduces a wrapper type to simulate array-to-pointer decay. With this API the C semantics can be matched, but doing so correctly takes a great deal of care. The `VaList` type also has two lifetime arguments in this version, which is inelegant. Then, little seems to have happened for 6 years, until the recent burst of activity that resulted in the current proposal. - [#t-compiler > c_variadic API and ABI](https://rust-lang.zulipchat.com/#narrow/channel/131828-t-compiler/topic/c_variadic.20API.20and.20ABI/with/527115587) - rust-lang#141524 **implementation history** The list of PRs is long, but they have all been labled with [`F-c_variadic`](https://github.com/rust-lang/rust/pulls?q=is%3Apr+label%3AF-c_variadic+). ## Unresolved Questions ### `VaArgSafe` and function pointers rust-lang#153646 Currently `VaArgSafe` is not implemented for function pointers, and doing so would be tricky. There is the practical issue of not being able to be generic over the number of arguments, but there are also some complex constraints on the signature, see https://www.gnu.org/software/c-intro-and-ref/manual/html_node/Compatible-Types.html. ### Thanks Many people have worked on this feature over the years, and many more have provided input. I'd like to credit here the people that have been especially involved in this push for stabilization: @workingjubilee, @RalfJung, @beetrees, @joshtriplett and @tgross35. r? @tgross35

@workingjubilee

…=tgross35,traviscross Stabilize c-variadic function definitions tracking issue: Fixes rust-lang#44930 reference PR: rust-lang/reference#2177 There are some minor things still in flight, but I think we're far enough along now. # Stabilization report ## Summary In C, functions can use a variable argument list `...` to accept an arbitrary number of untyped arguments. Rust is already able to call such functions (e.g. `libc::printf`), the `c_variadic` feature adds the ability to define them. A rust c-variadic function looks like this: ```rust /// SAFETY: must be called with (at least) 2 i32 arguments. unsafe extern "C" fn sum(mut args: ...) -> i32 { let a = args.next_arg::<i32>(); let b = args.next_arg::<i32>(); a + b } fn foo() -> i32 { unsafe { sum(0i32, 2i32) } } ``` This function accepts a variable arguments list `args: ...`, from which it is able to read arguments using the `next_arg` method. The main goal of defining c-variadic functions in rust is interaction with C code. Therefore it is a design goal that the rust types map directly to their C counterparts on all targets. Additionally, we disallow interaction between c-variadic functions and certain rust features that don't make much sense in an FFI context (e.g. `extern "Rust" fn` or `async fn`). ## How variadics work in C The authoritative source for how variadics (also known as "variable arguments") work in C is the C specification. In this document we'll use [section 7.16 of the final draft of the C23 standard](https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3220.pdf#page=302). > A function may be called with a variable number of arguments of varying types if its parameter type list ends with an ellipsis Earlier versions of C furthermore required that the `...` argument is not the first argument of the parameter type list (so at least one other argument was required). Starting in C23 this requirement has been lifted. ### C API surface - `va_list`: an opaque type that stores the information needed to read variadic arguments, or copy the list of variadic arguments. Typically values of this type get the name `ap`. - `va_start`: a `va_list` must be initialized with the `va_start` macro before it can be used. - `va_copy`: the `va_copy` macro copies a `va_list`. The copy starts at the position in the argument list of the original (so **not** at the first variadic argument to the function), and both can be moved forward independently. This means the same argument can be read multiple times. - `va_arg`: reads the next argument from the `va_ist`. - `va_end`: deinitializes a `va_list`. ### Important notes #### Not calling `va_end` is UB Section 7.16.1 > Each invocation of the `va_start` and `va_copy` macros shall be matched by a corresponding invocation of the `va_end` macro in the same function. Section 7.16.1.3: > The `va_end` macro facilitates a normal return from the function whose variable argument list was referred to by the expansion of the `va_start` macro, or the function containing the expansion of the `va_copy` macro, that initialized the `va_list` ap. The `va_end` macro may modify ap so that it is no longer usable (without being reinitialized by the `va_start` or `va_copy` macro). If there is no corresponding invocation of the `va_start` or `va_copy` macro, or if the `va_end` macro is not invoked before the return, the behavior is undefined. We believe that this behavior is this strict because some early C implementations chose to implement `va_list` like so [(source)](https://softwarepreservation.computerhistory.org/c_plus_plus/cfront/release_3.0.3/source/incl-master/proto-headers/stdarg.sol): ```rust #define va_start(ap, parmN) {\ va_buf _va;\ _vastart(ap = (va_list)_va, (char *)&parmN + sizeof parmN) #define va_end(ap) } #define va_arg(ap, mode) *((mode *)_vaarg(ap, sizeof (mode))) ``` To our knowledge no remotely-modern implementation actually implements `va_end` as anything but a no-op. #### A `va_list` may be moved Section 7.16 > The object `ap` may be passed as an argument to another function; if that function invokes the `va_arg` macro with parameter `ap`, the representation of `ap` in the calling function is indeterminate and shall be passed to the `va_end` macro prior to any further reference to `ap`. and > A pointer to a `va_list` can be created and passed to another function, in which case the original function can make further use of the original list after the other function returns So `va_list` can be moved into another function, but `va_end` must still run in the frame that initialized (with `va_start` or `va_copy`) the `va_list` . #### Representation of `va_list` The representation of `va_list` is platform-specific. There are three flavors that are used by current rust targets: - `va_list` is an opaque pointer - `va_list` is a struct - `va_list` is a single-element array, containing a struct The opaque pointer approach is the simplest to implement: the pointer just points to an array of arguments on the caller's stack. The struct and single-element array variants are more complex, but potentially more efficient because the additional state makes it possible to pass c-variadic arguments via registers. #### array-to-pointer decay If the `va_list` is of the single-element array flavor, it is subject to array-to-pointer decay: in C, arrays are passed not by-value, but as pointers. Hence, from an FFI perspective, these two functions are equivalent. ```c #include <stdarg.h> extern int foo(va_list va) { return va_arg(va, int); } extern int bar(va_list *va) { return va_arg(*va, int); } ``` Indeed, they generate the same assembly, see https://godbolt.org/z/n8c4aq5hM. #### other calling conventions Both `clang` and `gcc` refuse to compile a function that uses variadic arguments and a non-default calling convention. See also rust-lang#141618, in particular rust-lang#141618 (comment). The LLVM intrinsics (`va_start`, `va_arg`, etc.) always expand based on the default C ABI on the current platform, not the ABI of the function they are used in. While rust only supports defining C-variadic functions with the `extern "C"` ABI that is fine, but relaxing that restriction would require either changing LLVM to take the calling convention of the current function into account, or implementing `va_start` ourselves for all platforms. ### `va_arg` and argument promotion With some exceptions, the return type of a `va_arg` call must match the type of the supplied argument: Section 7.16.1 > If type is not compatible with the type of the actual next argument (as promoted according to the default argument promotions), the behavior is undefined These default argument promotions are specified in section 6.5.3.3: > The arguments are implicitly converted, as if by assignment, to the types of the corresponding parameters, taking the type of each parameter to be the unqualified version of its declared type. The ellipsis notation in a function prototype declarator causes argument type conversion to stop after the last declared parameter, if present. The integer promotions are performed on each trailing argument, and trailing arguments that have type float are promoted to double. These are called the default argument promotions. No other conversions are performed implicitly There are a couple of additional conversions that are allowed, such as casting signed to/from unsigned integers. A concrete example of what is not allowed is to use `va_arg` to read (signed or unsigned) `char` or `short`, or `float` arguments. Reading such types is UB. See also rust-lang#61275 (comment). ## How c-variadics work in rust ### Rust API surface The rust API has similar capabilities to C but uses rust names and concepts. ```rust pub struct VaList<'f> { /* ... */ _marker: PhantomCovariantLifetime<'f>, } ``` The `VaList` struct has a lifetime parameter that ensures that the `VaList` cannot outlive the function that created it. Semantically `VaList` contains mutable references (to the caller's and/or callee's stack), so the lifetime is covariant. The `#[rustc_pass_indirectly_in_non_rustic_abis]` attribute is applied to the definition if `va_list` is a single-element array on the target platform. This attribute simulates the array-to-pointer decay that the C `va_list` type is subject to on that target. A goal of `c_variadic` is to be able to write portable code that uses c-variadics. When `va_list` is a pointer or struct FFI compatibility with a rust `VaList` is straightforward, the attribute to pass indirectly is needed to also make the types FFI compatible on targets where array-to-pointer decay kicks in. The `#[rustc_pass_indirectly_in_non_rustic_abis]` attribute works as desired because `VaList` is a by-move type: in rust this is enforced by the type system, in C the specification requires it. Mutations to the passed object are not observable in the caller (because the value is semantically moved and hence inaccessible). The `VaList::next_arg` method can be used to read the next argument. ```rust pub unsafe trait VaArgSafe: Copy + Sealed {} impl<'f> VaList<'f> { pub unsafe fn next_arg<T: VaArgSafe>(&mut self) -> T { /* ... */ } } ``` The implementation is equivalent to C `va_arg`, though for all targets that we propose to stabilize here the `va_arg` logic is implemented in `rustc` itself, and does not rely on LLVM (more information on that below). The return type is constrained by `VaArgSafe` so that only valid argument types can be read. In particular this mechanism prevents subtle issues around implicit numeric promotion in C. Reading an argument is unsafe because reading more arguments than were supplied is UB. Implementors of `VaArgSafe` must implement `Copy` because the `VaList` can be cloned and hence the same variable argument can be read twice, which is only safe if the type is `Copy`. The `VaArgSafe` trait is guaranteed to be implemented for: - `c_int`, `c_long` and `c_longlong` - `c_uint`, `c_ulong` and `c_ulonglong` - `c_double` - `*const T` and `*mut T` Implementations for other types are not guaranteed to be portable, so portable programs should not rely on e.g. `usize` or `f64` implementing this trait directly. C argument types are considered to have the rust type that corresponds to `core::ffi::*`, so a C `int` is mapped to `c_int` and so on. We don't consider the C `_BitInt` or `_Float32` types here, rather we (on most platforms) map `f64` to `double` etc. `_BitInt(32)` and `int` are distinct types. `_BitInt` is furthermore special because it does not participate in integer promotion. Calling `VaList::next_arg` to read an argument of type `T` is only safe if all of the following conditions are satisfied: - There is another c-variadic argument to read. - The actual type of the argument `U` is compatible with `T` (as defined below). - If `U` and `T` are both integer types, then the value passed by the caller must be representable in both types. Types `T` and `U` are compatible when: - `T` and `U` are the same type (up to free lifetimes). - `T` and `U` are integer types of the same size. - `T` and `U` are both pointers, and their target types are compatible. - `T` is a pointer to `c_void` and `U` is a pointer to `i8` or `u8`, or vice versa. ```rust // SAFETY: the caller must supply an argument that is compatible with `u64`, // optionally followed by other arguments that are ignored. unsafe extern "C" fn variadic(mut ap: ...) -> u64 { unsafe { ap.next_arg::<u64>() } } // The type is incompatible, Miri will report UB. unsafe { variadic(1u32) } // The value is not representable by u64, Miri will report UB. unsafe { variadic(-1i64) } // This is fine. unsafe { variadic(42i64) } ``` And an example of when equality up to free lifetimes is relevant. ```rust const unsafe extern "C" fn read_as<T: core::ffi::VaArgSafe>(mut ap: ...) -> T { ap.next_arg::<T>() } unsafe fn read_cast_lifetime() { // Allowed const { read_as::<*const &'static i32>(std::ptr::dangling::<&i32>()) }; // Not allowed const { read_as::<*const fn(&'static ())>(std::ptr::dangling::<for<'a> fn(&'a ())>()) }; //~^ ERROR va_arg type mismatch: requested `*const fn(&())` is incompatible with next argument of type `*const for<'a> fn(&'a ())` } ``` The `VaList` type implements `Clone` and `Drop`: ```rust impl<'f> Clone for VaList<'f> { /* ... */ } impl<'f> Drop for VaList<'f> { fn drop(&mut self) { /* no-op */ } } ``` The `Clone` implementation can be used to duplicate a `VaList`. The copy has the same position as the original, but both can be incremented independently. While all current targets could also implement `Copy` for `VaList`, a future target might not, so for now `Copy` is not implemented. LLVM now guarantee that `memcpy` may be used to duplicate a `VaList` when the operation is equivalent to `memcpy` on the platform, which is true for all current LLVM targets. The `Drop` implementation is a no-op, it does call a function named `va_end`, but that itself is a no-op that exists only for Miri to detect UB. In C,`va_end` must run in the frame where the `va_list` was initialized. Because `VaList` can be moved (like the C `va_list`), the frame in which a `VaList` is dropped may not be the frame in which it was initialized. LLVM now guarantees that `va_end` may be omitted when `va_end` is a no-op, which is the case for all current LLVM targets. The `VaList` type is available on all targets, even on targets that don't actually support c-variadic definitions. On such targets, it is impossible to get a valid `VaList` value, because attempting to define a c-variadic function (using the `...` argument) will throw an error. ### Syntax In rust, a C-variadic function looks like this: ```rust unsafe extern "C" fn foo(a: i32, b: i32, args: ...) { /* body */ } ``` The special `args: ...` argument stands in for an arbitrary number of arguments that the caller may pass. The `...` argument must be the last argument in the parameter list of a function. Like in C23 and later, `...` may be the only argument. The `...` syntax is already stable in foreign functions, `c_variadic` additionally allows it in function definitions. In function definitions, the `...` argument must have a pattern. The argument can be ignored by using `_: ...`. In foreign function declarations the pattern can be omitted. A function definition with a `...` argument must be an `unsafe` function. Passing an incorrect number of arguments, or arguments of the wrong type, is UB, and hence every call site has to satisfy the safety conditions. A special case is a function that ignores its `VaList` entirely using `_: ...`: we may decide to allow such functions to be safe. At the time of writing we see insufficient benefits relative to the additional complexity that this entails. A function with the `...` argument must be an `extern "C"` or `extern "C-unwind"` function. In the future we want to extend the set of accepted ABIs to include all ABIs for which we allow calling a c-variadic function (including e.g. `sysv64` and `win64`). The `...` argument can occur in definitions of functions, inherent methods, and trait methods. When any method on a trait uses a c-variadic argument, the trait is no longer dyn-compatible. The technical reason is that there is no sound way to generate a `ReifyShim` that passes on the c-variadic arguments. ### Desugaring In a function like this: ```rust unsafe extern "C" fn foo(args: ...) { // ... } ``` The `args: ...` is internally desugared into a call to LLVM's `va_start` that initializes `args` as a `VaList`. The `VaList` gets the lifetime of a local variable on `foo`'s stack, so that the `VaList` cannot outlive the function that created it. The desugaring will fail with an error when the current target does not support c-variadic definitions. Currently this is the case for `spriv` and `bpf`: ``` error: the `bpfel` target does not support c-variadic functions --> $DIR/not-supported.rs:23:31 | LL | unsafe extern "C" fn variadic(_: ...) {} | ^^^^^^ ``` ### A note on LLVM `va_arg` The LLVM `va_arg` intrinsic is known to silently miscompile. A [comment in the implementation](https://github.com/llvm/llvm-project/blob/72c8f98f74f2b4f9677d0d5e3dc91bc4d6cb39f4/clang/lib/CodeGen/ABIInfoImpl.cpp#L406-L411) notes: > This default implementation defers to the llvm backend's va_arg instruction. It can handle only passing arguments directly (typically only handled in the backend for primitive types), or aggregates passed indirectly by pointer (NOTE: if the "byval" flag has ABI impact in the callee, this implementation cannot work.) > > Only a few cases are covered here at the moment -- those needed by the default abi. Hence, like `clang`, `rustc` implements `va_arg` for the vast majority of targets (specifically including all tier-1 targets) in [`va_arg.rs`](https://github.com/rust-lang/rust/blob/master/compiler/rustc_codegen_llvm/src/va_arg.rs). Note that the match on the architecture is exhaustive, however the behavior on targets where we've not validated the correctness of the implementation is an unresolved question (see below). ## Future extensions ### C-variadics and `const fn` Support for c-variadic `const fn` (and by extension, support in Miri) is implemented in rust-lang#150601 and gated by `const_c_variadic`. Practical usage requires `const_destruct` too because `VaList` has a custom `Drop` implementation. ```rust #![feature(c_variadic, const_c_variadic, const_destruct)] const unsafe extern "C" fn variadic(mut ap: ...) -> i32 { ap.next_arg() } ``` ### Naked variadic functions Currently only `C` and `C-unwind` are valid ABIs for all c-variadic function definitions. With naked functions it is possible to define e.g. a `win64` c-variadic function in a program where `sysv64` is the default. This feature is tracked as [`c_variadic_naked_functions`](rust-lang#148767). ```rust #![feature(c_variadic, c_variadic_naked_functions)] #[unsafe(naked)] unsafe extern "win64" fn variadic_win64(_: u32, _: ...) -> u32 { core::arch::naked_asm!( r#" push rax mov qword ptr [rsp + 40], r9 mov qword ptr [rsp + 24], rdx mov qword ptr [rsp + 32], r8 lea rax, [rsp + 40] mov qword ptr [rsp], rax lea eax, [rdx + rcx] add eax, r8d pop rcx ret "#, ) } ``` ### C-variadics and coroutines An `async fn` or any other type of coroutine cannot be c-variadic. We see no reason to support this. ### Defining safe C-variadic functions In `extern` blocks, it is valid to mark C-variadic functions as safe, under the assumption that the function completely ignores the variable arguments list: ```rust unsafe extern "C" { safe fn foo(...); } ``` Normally, C-variadic function definitions must be unsafe, because calling the function with unexpected (in type or number) elements is UB. We could relax this constraint on C-variadic functions that ignore their C variable argument list, e.g.: ```rust // NOTE: not unsafe extern "C" fn(x: i32, _: ...) -> i32 { x } ``` At the moment we don't have a good reason to add this behavior. It is completely backwards compatible, so if a need arises in the future we can revisit this. ### Accepting more `va_arg` return types Discussed in rust-lang#44930 (comment). We only want to implement `VaArgSafe` for types that have a clear counterpart in C. That rules out types like `Option<NonNull>` or `NonZeroI32`. We might add `MaybeUninit<c_int>` and so on in the future if a use case comes up: this would map to a C `union`. The only planned extension right now is support for `i128` and `u128` where they can be mapped to (unsigned) `__int128`. However `rustc` currently does not know on what targets this type is available, and hence we leave it out of the stabilization for now. Adding 128-bit support is in progress in rust-lang#155429. ### C-variadic support on untested targets Because c-variadic is a platform-specific feature, and extremely unsafe, we're apprehensive about stabilizing it for targets where that implementation has not actually been validated. The [`#[c_variadic_experimental_arch]`](rust-lang#155973) feature gates such targets. The current list of targets which are kept unstable by this PR is: - `riscv32e-unknown-none-elf` because its ABI may change in the future - `sparc` because compilers for it are no longer distributed - `avr`, `m68k` and `msp430` because they are hard to validate - targets categorized as `Other`, e.g. through a custom `target.json` ### Multiple C-variadic ABIs in the same program rust-lang#141618 Both `clang` and `gcc` reject using `...` in functions with a non-default ABI for the target. That makes the layout of `VaList` and expansion of `va_start`, `va_arg` etc. unambiguous. For now we impose a similar restriction for the rust implementation. This restriction could be lifted in the future, but this would requite that `VaList` somehow "stores" its ABI. One approach is to add a type parameter to `VaList` that default's to the platform's default ABI. Each c-variadic argument would then desugar to use the ABI of the c-variadic function that creates it. ## History [RFC 2137](rust-lang/rfcs#2137) proposes to "support defining C-compatible variadic functions in rust" in 2017, and it is still the core of the implementation today. The text lays out a basic rust API and highlights potential issues (e.g. some solution is needed to match C's array-to-pointer decay), but does not always provide concrete solutions. In 2019 rust-lang#59625 introduces a wrapper type to simulate array-to-pointer decay. With this API the C semantics can be matched, but doing so correctly takes a great deal of care. The `VaList` type also has two lifetime arguments in this version, which is inelegant. Then, little seems to have happened for 6 years, until the recent burst of activity that resulted in the current proposal. - [#t-compiler > c_variadic API and ABI](https://rust-lang.zulipchat.com/#narrow/channel/131828-t-compiler/topic/c_variadic.20API.20and.20ABI/with/527115587) - rust-lang#141524 **implementation history** The list of PRs is long, but they have all been labled with [`F-c_variadic`](https://github.com/rust-lang/rust/pulls?q=is%3Apr+label%3AF-c_variadic+). ## Unresolved Questions ### `VaArgSafe` and function pointers rust-lang#153646 Currently `VaArgSafe` is not implemented for function pointers, and doing so would be tricky. There is the practical issue of not being able to be generic over the number of arguments, but there are also some complex constraints on the signature, see https://www.gnu.org/software/c-intro-and-ref/manual/html_node/Compatible-Types.html. ### Thanks Many people have worked on this feature over the years, and many more have provided input. I'd like to credit here the people that have been especially involved in this push for stabilization: @workingjubilee, @RalfJung, @beetrees, @joshtriplett and @tgross35. r? @tgross35

@workingjubilee

…=tgross35,traviscross Stabilize c-variadic function definitions tracking issue: Fixes rust-lang#44930 reference PR: rust-lang/reference#2177 There are some minor things still in flight, but I think we're far enough along now. # Stabilization report ## Summary In C, functions can use a variable argument list `...` to accept an arbitrary number of untyped arguments. Rust is already able to call such functions (e.g. `libc::printf`), the `c_variadic` feature adds the ability to define them. A rust c-variadic function looks like this: ```rust /// SAFETY: must be called with (at least) 2 i32 arguments. unsafe extern "C" fn sum(mut args: ...) -> i32 { let a = args.next_arg::<i32>(); let b = args.next_arg::<i32>(); a + b } fn foo() -> i32 { unsafe { sum(0i32, 2i32) } } ``` This function accepts a variable arguments list `args: ...`, from which it is able to read arguments using the `next_arg` method. The main goal of defining c-variadic functions in rust is interaction with C code. Therefore it is a design goal that the rust types map directly to their C counterparts on all targets. Additionally, we disallow interaction between c-variadic functions and certain rust features that don't make much sense in an FFI context (e.g. `extern "Rust" fn` or `async fn`). ## How variadics work in C The authoritative source for how variadics (also known as "variable arguments") work in C is the C specification. In this document we'll use [section 7.16 of the final draft of the C23 standard](https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3220.pdf#page=302). > A function may be called with a variable number of arguments of varying types if its parameter type list ends with an ellipsis Earlier versions of C furthermore required that the `...` argument is not the first argument of the parameter type list (so at least one other argument was required). Starting in C23 this requirement has been lifted. ### C API surface - `va_list`: an opaque type that stores the information needed to read variadic arguments, or copy the list of variadic arguments. Typically values of this type get the name `ap`. - `va_start`: a `va_list` must be initialized with the `va_start` macro before it can be used. - `va_copy`: the `va_copy` macro copies a `va_list`. The copy starts at the position in the argument list of the original (so **not** at the first variadic argument to the function), and both can be moved forward independently. This means the same argument can be read multiple times. - `va_arg`: reads the next argument from the `va_ist`. - `va_end`: deinitializes a `va_list`. ### Important notes #### Not calling `va_end` is UB Section 7.16.1 > Each invocation of the `va_start` and `va_copy` macros shall be matched by a corresponding invocation of the `va_end` macro in the same function. Section 7.16.1.3: > The `va_end` macro facilitates a normal return from the function whose variable argument list was referred to by the expansion of the `va_start` macro, or the function containing the expansion of the `va_copy` macro, that initialized the `va_list` ap. The `va_end` macro may modify ap so that it is no longer usable (without being reinitialized by the `va_start` or `va_copy` macro). If there is no corresponding invocation of the `va_start` or `va_copy` macro, or if the `va_end` macro is not invoked before the return, the behavior is undefined. We believe that this behavior is this strict because some early C implementations chose to implement `va_list` like so [(source)](https://softwarepreservation.computerhistory.org/c_plus_plus/cfront/release_3.0.3/source/incl-master/proto-headers/stdarg.sol): ```rust #define va_start(ap, parmN) {\ va_buf _va;\ _vastart(ap = (va_list)_va, (char *)&parmN + sizeof parmN) #define va_end(ap) } #define va_arg(ap, mode) *((mode *)_vaarg(ap, sizeof (mode))) ``` To our knowledge no remotely-modern implementation actually implements `va_end` as anything but a no-op. #### A `va_list` may be moved Section 7.16 > The object `ap` may be passed as an argument to another function; if that function invokes the `va_arg` macro with parameter `ap`, the representation of `ap` in the calling function is indeterminate and shall be passed to the `va_end` macro prior to any further reference to `ap`. and > A pointer to a `va_list` can be created and passed to another function, in which case the original function can make further use of the original list after the other function returns So `va_list` can be moved into another function, but `va_end` must still run in the frame that initialized (with `va_start` or `va_copy`) the `va_list` . #### Representation of `va_list` The representation of `va_list` is platform-specific. There are three flavors that are used by current rust targets: - `va_list` is an opaque pointer - `va_list` is a struct - `va_list` is a single-element array, containing a struct The opaque pointer approach is the simplest to implement: the pointer just points to an array of arguments on the caller's stack. The struct and single-element array variants are more complex, but potentially more efficient because the additional state makes it possible to pass c-variadic arguments via registers. #### array-to-pointer decay If the `va_list` is of the single-element array flavor, it is subject to array-to-pointer decay: in C, arrays are passed not by-value, but as pointers. Hence, from an FFI perspective, these two functions are equivalent. ```c #include <stdarg.h> extern int foo(va_list va) { return va_arg(va, int); } extern int bar(va_list *va) { return va_arg(*va, int); } ``` Indeed, they generate the same assembly, see https://godbolt.org/z/n8c4aq5hM. #### other calling conventions Both `clang` and `gcc` refuse to compile a function that uses variadic arguments and a non-default calling convention. See also rust-lang#141618, in particular rust-lang#141618 (comment). The LLVM intrinsics (`va_start`, `va_arg`, etc.) always expand based on the default C ABI on the current platform, not the ABI of the function they are used in. While rust only supports defining C-variadic functions with the `extern "C"` ABI that is fine, but relaxing that restriction would require either changing LLVM to take the calling convention of the current function into account, or implementing `va_start` ourselves for all platforms. ### `va_arg` and argument promotion With some exceptions, the return type of a `va_arg` call must match the type of the supplied argument: Section 7.16.1 > If type is not compatible with the type of the actual next argument (as promoted according to the default argument promotions), the behavior is undefined These default argument promotions are specified in section 6.5.3.3: > The arguments are implicitly converted, as if by assignment, to the types of the corresponding parameters, taking the type of each parameter to be the unqualified version of its declared type. The ellipsis notation in a function prototype declarator causes argument type conversion to stop after the last declared parameter, if present. The integer promotions are performed on each trailing argument, and trailing arguments that have type float are promoted to double. These are called the default argument promotions. No other conversions are performed implicitly There are a couple of additional conversions that are allowed, such as casting signed to/from unsigned integers. A concrete example of what is not allowed is to use `va_arg` to read (signed or unsigned) `char` or `short`, or `float` arguments. Reading such types is UB. See also rust-lang#61275 (comment). ## How c-variadics work in rust ### Rust API surface The rust API has similar capabilities to C but uses rust names and concepts. ```rust pub struct VaList<'f> { /* ... */ _marker: PhantomCovariantLifetime<'f>, } ``` The `VaList` struct has a lifetime parameter that ensures that the `VaList` cannot outlive the function that created it. Semantically `VaList` contains mutable references (to the caller's and/or callee's stack), so the lifetime is covariant. The `#[rustc_pass_indirectly_in_non_rustic_abis]` attribute is applied to the definition if `va_list` is a single-element array on the target platform. This attribute simulates the array-to-pointer decay that the C `va_list` type is subject to on that target. A goal of `c_variadic` is to be able to write portable code that uses c-variadics. When `va_list` is a pointer or struct FFI compatibility with a rust `VaList` is straightforward, the attribute to pass indirectly is needed to also make the types FFI compatible on targets where array-to-pointer decay kicks in. The `#[rustc_pass_indirectly_in_non_rustic_abis]` attribute works as desired because `VaList` is a by-move type: in rust this is enforced by the type system, in C the specification requires it. Mutations to the passed object are not observable in the caller (because the value is semantically moved and hence inaccessible). The `VaList::next_arg` method can be used to read the next argument. ```rust pub unsafe trait VaArgSafe: Copy + Sealed {} impl<'f> VaList<'f> { pub unsafe fn next_arg<T: VaArgSafe>(&mut self) -> T { /* ... */ } } ``` The implementation is equivalent to C `va_arg`, though for all targets that we propose to stabilize here the `va_arg` logic is implemented in `rustc` itself, and does not rely on LLVM (more information on that below). The return type is constrained by `VaArgSafe` so that only valid argument types can be read. In particular this mechanism prevents subtle issues around implicit numeric promotion in C. Reading an argument is unsafe because reading more arguments than were supplied is UB. Implementors of `VaArgSafe` must implement `Copy` because the `VaList` can be cloned and hence the same variable argument can be read twice, which is only safe if the type is `Copy`. The `VaArgSafe` trait is guaranteed to be implemented for: - `c_int`, `c_long` and `c_longlong` - `c_uint`, `c_ulong` and `c_ulonglong` - `c_double` - `*const T` and `*mut T` Implementations for other types are not guaranteed to be portable, so portable programs should not rely on e.g. `usize` or `f64` implementing this trait directly. C argument types are considered to have the rust type that corresponds to `core::ffi::*`, so a C `int` is mapped to `c_int` and so on. We don't consider the C `_BitInt` or `_Float32` types here, rather we (on most platforms) map `f64` to `double` etc. `_BitInt(32)` and `int` are distinct types. `_BitInt` is furthermore special because it does not participate in integer promotion. Calling `VaList::next_arg` to read an argument of type `T` is only safe if all of the following conditions are satisfied: - There is another c-variadic argument to read. - The actual type of the argument `U` is compatible with `T` (as defined below). - If `U` and `T` are both integer types, then the value passed by the caller must be representable in both types. Types `T` and `U` are compatible when: - `T` and `U` are the same type (up to free lifetimes). - `T` and `U` are integer types of the same size. - `T` and `U` are both pointers, and their target types are compatible. - `T` is a pointer to `c_void` and `U` is a pointer to `i8` or `u8`, or vice versa. ```rust // SAFETY: the caller must supply an argument that is compatible with `u64`, // optionally followed by other arguments that are ignored. unsafe extern "C" fn variadic(mut ap: ...) -> u64 { unsafe { ap.next_arg::<u64>() } } // The type is incompatible, Miri will report UB. unsafe { variadic(1u32) } // The value is not representable by u64, Miri will report UB. unsafe { variadic(-1i64) } // This is fine. unsafe { variadic(42i64) } ``` And an example of when equality up to free lifetimes is relevant. ```rust const unsafe extern "C" fn read_as<T: core::ffi::VaArgSafe>(mut ap: ...) -> T { ap.next_arg::<T>() } unsafe fn read_cast_lifetime() { // Allowed const { read_as::<*const &'static i32>(std::ptr::dangling::<&i32>()) }; // Not allowed const { read_as::<*const fn(&'static ())>(std::ptr::dangling::<for<'a> fn(&'a ())>()) }; //~^ ERROR va_arg type mismatch: requested `*const fn(&())` is incompatible with next argument of type `*const for<'a> fn(&'a ())` } ``` The `VaList` type implements `Clone` and `Drop`: ```rust impl<'f> Clone for VaList<'f> { /* ... */ } impl<'f> Drop for VaList<'f> { fn drop(&mut self) { /* no-op */ } } ``` The `Clone` implementation can be used to duplicate a `VaList`. The copy has the same position as the original, but both can be incremented independently. While all current targets could also implement `Copy` for `VaList`, a future target might not, so for now `Copy` is not implemented. LLVM now guarantee that `memcpy` may be used to duplicate a `VaList` when the operation is equivalent to `memcpy` on the platform, which is true for all current LLVM targets. The `Drop` implementation is a no-op, it does call a function named `va_end`, but that itself is a no-op that exists only for Miri to detect UB. In C,`va_end` must run in the frame where the `va_list` was initialized. Because `VaList` can be moved (like the C `va_list`), the frame in which a `VaList` is dropped may not be the frame in which it was initialized. LLVM now guarantees that `va_end` may be omitted when `va_end` is a no-op, which is the case for all current LLVM targets. The `VaList` type is available on all targets, even on targets that don't actually support c-variadic definitions. On such targets, it is impossible to get a valid `VaList` value, because attempting to define a c-variadic function (using the `...` argument) will throw an error. ### Syntax In rust, a C-variadic function looks like this: ```rust unsafe extern "C" fn foo(a: i32, b: i32, args: ...) { /* body */ } ``` The special `args: ...` argument stands in for an arbitrary number of arguments that the caller may pass. The `...` argument must be the last argument in the parameter list of a function. Like in C23 and later, `...` may be the only argument. The `...` syntax is already stable in foreign functions, `c_variadic` additionally allows it in function definitions. In function definitions, the `...` argument must have a pattern. The argument can be ignored by using `_: ...`. In foreign function declarations the pattern can be omitted. A function definition with a `...` argument must be an `unsafe` function. Passing an incorrect number of arguments, or arguments of the wrong type, is UB, and hence every call site has to satisfy the safety conditions. A special case is a function that ignores its `VaList` entirely using `_: ...`: we may decide to allow such functions to be safe. At the time of writing we see insufficient benefits relative to the additional complexity that this entails. A function with the `...` argument must be an `extern "C"` or `extern "C-unwind"` function. In the future we want to extend the set of accepted ABIs to include all ABIs for which we allow calling a c-variadic function (including e.g. `sysv64` and `win64`). The `...` argument can occur in definitions of functions, inherent methods, and trait methods. When any method on a trait uses a c-variadic argument, the trait is no longer dyn-compatible. The technical reason is that there is no sound way to generate a `ReifyShim` that passes on the c-variadic arguments. ### Desugaring In a function like this: ```rust unsafe extern "C" fn foo(args: ...) { // ... } ``` The `args: ...` is internally desugared into a call to LLVM's `va_start` that initializes `args` as a `VaList`. The `VaList` gets the lifetime of a local variable on `foo`'s stack, so that the `VaList` cannot outlive the function that created it. The desugaring will fail with an error when the current target does not support c-variadic definitions. Currently this is the case for `spriv` and `bpf`: ``` error: the `bpfel` target does not support c-variadic functions --> $DIR/not-supported.rs:23:31 | LL | unsafe extern "C" fn variadic(_: ...) {} | ^^^^^^ ``` ### A note on LLVM `va_arg` The LLVM `va_arg` intrinsic is known to silently miscompile. A [comment in the implementation](https://github.com/llvm/llvm-project/blob/72c8f98f74f2b4f9677d0d5e3dc91bc4d6cb39f4/clang/lib/CodeGen/ABIInfoImpl.cpp#L406-L411) notes: > This default implementation defers to the llvm backend's va_arg instruction. It can handle only passing arguments directly (typically only handled in the backend for primitive types), or aggregates passed indirectly by pointer (NOTE: if the "byval" flag has ABI impact in the callee, this implementation cannot work.) > > Only a few cases are covered here at the moment -- those needed by the default abi. Hence, like `clang`, `rustc` implements `va_arg` for the vast majority of targets (specifically including all tier-1 targets) in [`va_arg.rs`](https://github.com/rust-lang/rust/blob/master/compiler/rustc_codegen_llvm/src/va_arg.rs). Note that the match on the architecture is exhaustive, however the behavior on targets where we've not validated the correctness of the implementation is an unresolved question (see below). ## Future extensions ### C-variadics and `const fn` Support for c-variadic `const fn` (and by extension, support in Miri) is implemented in rust-lang#150601 and gated by `const_c_variadic`. Practical usage requires `const_destruct` too because `VaList` has a custom `Drop` implementation. ```rust #![feature(c_variadic, const_c_variadic, const_destruct)] const unsafe extern "C" fn variadic(mut ap: ...) -> i32 { ap.next_arg() } ``` ### Naked variadic functions Currently only `C` and `C-unwind` are valid ABIs for all c-variadic function definitions. With naked functions it is possible to define e.g. a `win64` c-variadic function in a program where `sysv64` is the default. This feature is tracked as [`c_variadic_naked_functions`](rust-lang#148767). ```rust #![feature(c_variadic, c_variadic_naked_functions)] #[unsafe(naked)] unsafe extern "win64" fn variadic_win64(_: u32, _: ...) -> u32 { core::arch::naked_asm!( r#" push rax mov qword ptr [rsp + 40], r9 mov qword ptr [rsp + 24], rdx mov qword ptr [rsp + 32], r8 lea rax, [rsp + 40] mov qword ptr [rsp], rax lea eax, [rdx + rcx] add eax, r8d pop rcx ret "#, ) } ``` ### C-variadics and coroutines An `async fn` or any other type of coroutine cannot be c-variadic. We see no reason to support this. ### Defining safe C-variadic functions In `extern` blocks, it is valid to mark C-variadic functions as safe, under the assumption that the function completely ignores the variable arguments list: ```rust unsafe extern "C" { safe fn foo(...); } ``` Normally, C-variadic function definitions must be unsafe, because calling the function with unexpected (in type or number) elements is UB. We could relax this constraint on C-variadic functions that ignore their C variable argument list, e.g.: ```rust // NOTE: not unsafe extern "C" fn(x: i32, _: ...) -> i32 { x } ``` At the moment we don't have a good reason to add this behavior. It is completely backwards compatible, so if a need arises in the future we can revisit this. ### Accepting more `va_arg` return types Discussed in rust-lang#44930 (comment). We only want to implement `VaArgSafe` for types that have a clear counterpart in C. That rules out types like `Option<NonNull>` or `NonZeroI32`. We might add `MaybeUninit<c_int>` and so on in the future if a use case comes up: this would map to a C `union`. The only planned extension right now is support for `i128` and `u128` where they can be mapped to (unsigned) `__int128`. However `rustc` currently does not know on what targets this type is available, and hence we leave it out of the stabilization for now. Adding 128-bit support is in progress in rust-lang#155429. ### C-variadic support on untested targets Because c-variadic is a platform-specific feature, and extremely unsafe, we're apprehensive about stabilizing it for targets where that implementation has not actually been validated. The [`#[c_variadic_experimental_arch]`](rust-lang#155973) feature gates such targets. The current list of targets which are kept unstable by this PR is: - `riscv32e-unknown-none-elf` because its ABI may change in the future - `sparc` because compilers for it are no longer distributed - `avr`, `m68k` and `msp430` because they are hard to validate - targets categorized as `Other`, e.g. through a custom `target.json` ### Multiple C-variadic ABIs in the same program rust-lang#141618 Both `clang` and `gcc` reject using `...` in functions with a non-default ABI for the target. That makes the layout of `VaList` and expansion of `va_start`, `va_arg` etc. unambiguous. For now we impose a similar restriction for the rust implementation. This restriction could be lifted in the future, but this would requite that `VaList` somehow "stores" its ABI. One approach is to add a type parameter to `VaList` that default's to the platform's default ABI. Each c-variadic argument would then desugar to use the ABI of the c-variadic function that creates it. ## History [RFC 2137](rust-lang/rfcs#2137) proposes to "support defining C-compatible variadic functions in rust" in 2017, and it is still the core of the implementation today. The text lays out a basic rust API and highlights potential issues (e.g. some solution is needed to match C's array-to-pointer decay), but does not always provide concrete solutions. In 2019 rust-lang#59625 introduces a wrapper type to simulate array-to-pointer decay. With this API the C semantics can be matched, but doing so correctly takes a great deal of care. The `VaList` type also has two lifetime arguments in this version, which is inelegant. Then, little seems to have happened for 6 years, until the recent burst of activity that resulted in the current proposal. - [#t-compiler > c_variadic API and ABI](https://rust-lang.zulipchat.com/#narrow/channel/131828-t-compiler/topic/c_variadic.20API.20and.20ABI/with/527115587) - rust-lang#141524 **implementation history** The list of PRs is long, but they have all been labled with [`F-c_variadic`](https://github.com/rust-lang/rust/pulls?q=is%3Apr+label%3AF-c_variadic+). ## Unresolved Questions ### `VaArgSafe` and function pointers rust-lang#153646 Currently `VaArgSafe` is not implemented for function pointers, and doing so would be tricky. There is the practical issue of not being able to be generic over the number of arguments, but there are also some complex constraints on the signature, see https://www.gnu.org/software/c-intro-and-ref/manual/html_node/Compatible-Types.html. ### Thanks Many people have worked on this feature over the years, and many more have provided input. I'd like to credit here the people that have been especially involved in this push for stabilization: @workingjubilee, @RalfJung, @beetrees, @joshtriplett and @tgross35. r? @tgross35

rustbot added the S-waiting-on-review Status: The marked PR is awaiting review from a maintainer label Feb 17, 2026

folkertdev commented Feb 17, 2026

View reviewed changes

ehuss reviewed Feb 27, 2026

View reviewed changes

folkertdev mentioned this pull request Mar 30, 2026

report the varargs_without_pattern lint in deps rust-lang/rust#154599

Merged

folkertdev mentioned this pull request Apr 23, 2026

Stabilize c-variadic function definitions rust-lang/rust#155697

Open

tshepang reviewed May 2, 2026

View reviewed changes