silk.mem.va_list.
The C variadic arguments of an export "C" function, read one at a time.
When to use#
Use VaList in the body of an export "C" function whose parameters end with ..., such as
a C library entry point like uv_loop_configure(loop, option, ...) that a C program calls with
extra arguments.
Details#
The function's C entry starts its va_list before the body runs. Intrinsic.variadicArguments()
answers its address in that body only, and VaList.of wraps it. Each VaList.next reads
the next argument as the C caller passed it, under the target's C ABI: System V x86-64 and AAPCS
ARM64 read the register save area and then the stack, while Darwin ARM64, Windows and
WebAssembly read consecutive stack slots. A type implements VariadicArgument to say how C
passes it; the integer types, f64 and the raw pointers of VaList.nextPointer are covered.
C promotes a variadic char or short to int and a float to double, so read those as
i32 and f64.
Gotchas#
Nothing checks the C caller: reading more arguments than it passed, or a type other than the one it passed, reads unrelated memory. The list lives in the C entry's frame, so it is valid only until the function returns; do not keep it or its address.
Examples#
Read one int when the option asks for it#
import silk.mem.va_list { VaList }
pub unsafe export "C" fn configure(target: *mut u8, option: i32, ...) -> i32 as "example_configure" {
if option != 0 {
return 0
}
unsafe {
let mut arguments = VaList.of(Intrinsic.variadicArguments())
return arguments.next<i32>()
}
}
pub fn main() -> i32 {
return 0
}Import as VaList with import silk.mem.va_list { VaList }.
Public declarations: 3.
VaList#
pub struct VaListThe C variadic arguments of the running export "C" function, read in order.
Details#
Make one with VaList.of from Intrinsic.variadicArguments() in the body of an export "C"
function whose parameters end with .... Each VaList.next reads one argument under the
target's C ABI and moves past it. The list lives in the function's C entry frame and is valid
until the function returns.
VariadicSlot#
pub struct VariadicSlot<T>How C passes a variadic argument of type T: in an integer or a floating-point slot, and how
many bytes the value has.
Details#
VariadicArgument answers one for each type that VaList.next reads.
Field floating#
pub floating: boolWhether C passes the value in a floating-point register when one is free.
Field bytes#
pub bytes: usizeThe value's size in bytes: 4 or 8.
Implementation VariadicSlot<T>#
impl<T> VariadicSlot<T>Associated function integer#
pub fn integer(bytes: usize) -> VariadicSlot<T>The slot of an integer or pointer of bytes bytes, 4 or 8.
Associated function float#
pub fn float() -> VariadicSlot<T>The slot of a double.
VariadicArgument#
pub interface VariadicArgumentA type that a C caller can pass as a variadic argument after C's default promotions, so that
VaList.next can read it.
Details#
i32, u32, i64, u64, isize, usize and f64 implement it. A narrower C integer arrives
as int (i32), and a float arrives as double (f64).
Operation variadicSlot#
fn variadicSlot() -> VariadicSlot<Self>How C passes a value of this type.
Implementation VariadicArgument for i32#
impl VariadicArgument for i32Operation variadicSlot#
fn variadicSlot() -> VariadicSlot<i32>Implementation VariadicArgument for u32#
impl VariadicArgument for u32Operation variadicSlot#
fn variadicSlot() -> VariadicSlot<u32>Implementation VariadicArgument for i64#
impl VariadicArgument for i64Operation variadicSlot#
fn variadicSlot() -> VariadicSlot<i64>Implementation VariadicArgument for u64#
impl VariadicArgument for u64Operation variadicSlot#
fn variadicSlot() -> VariadicSlot<u64>Implementation VariadicArgument for isize#
impl VariadicArgument for isizeOperation variadicSlot#
fn variadicSlot() -> VariadicSlot<isize>Implementation VariadicArgument for usize#
impl VariadicArgument for usizeOperation variadicSlot#
fn variadicSlot() -> VariadicSlot<usize>Implementation VariadicArgument for f64#
impl VariadicArgument for f64Operation variadicSlot#
fn variadicSlot() -> VariadicSlot<f64>Implementation VaList#
impl VaListAssociated function of#
pub unsafe fn of(list: *mut u64) -> VaListWraps the va_list at list, the address Intrinsic.variadicArguments() answers in the
body of an export "C" function whose parameters end with ....
Details#
The list starts at the first variadic argument. It lives in the function's C entry frame, so the result is valid until the function returns.
Method next#
pub unsafe fn next<T: VariadicArgument + Copy>(self: &mut Self) -> TReads the next variadic argument as a T and moves past it.
Details#
It follows the target's C ABI for a value that C passed as T after the default promotions:
a char or short arrives as i32 and a float as f64. The caller must have passed an
argument of this type in this position; nothing checks it.
Method nextPointer#
pub unsafe fn nextPointer<T>(self: &mut Self) -> ?*mut TReads the next variadic argument as a raw pointer to T, which may be null, and moves past
it.
Details#
The caller must have passed a pointer in this position; nothing checks it.
Category: Memory.
Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.