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#

silk
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#

silk
pub struct VaList

The 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#

silk
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#

silk
pub floating: bool

Whether C passes the value in a floating-point register when one is free.

Field bytes#

silk
pub bytes: usize

The value's size in bytes: 4 or 8.

Implementation VariadicSlot<T>#

silk
impl<T> VariadicSlot<T>

Associated function integer#

silk
pub fn integer(bytes: usize) -> VariadicSlot<T>

The slot of an integer or pointer of bytes bytes, 4 or 8.

Associated function float#

silk
pub fn float() -> VariadicSlot<T>

The slot of a double.

VariadicArgument#

silk
pub interface VariadicArgument

A 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#

silk
fn variadicSlot() -> VariadicSlot<Self>

How C passes a value of this type.

Implementation VariadicArgument for i32#

silk
impl VariadicArgument for i32

Operation variadicSlot#

silk
fn variadicSlot() -> VariadicSlot<i32>

Implementation VariadicArgument for u32#

silk
impl VariadicArgument for u32

Operation variadicSlot#

silk
fn variadicSlot() -> VariadicSlot<u32>

Implementation VariadicArgument for i64#

silk
impl VariadicArgument for i64

Operation variadicSlot#

silk
fn variadicSlot() -> VariadicSlot<i64>

Implementation VariadicArgument for u64#

silk
impl VariadicArgument for u64

Operation variadicSlot#

silk
fn variadicSlot() -> VariadicSlot<u64>

Implementation VariadicArgument for isize#

silk
impl VariadicArgument for isize

Operation variadicSlot#

silk
fn variadicSlot() -> VariadicSlot<isize>

Implementation VariadicArgument for usize#

silk
impl VariadicArgument for usize

Operation variadicSlot#

silk
fn variadicSlot() -> VariadicSlot<usize>

Implementation VariadicArgument for f64#

silk
impl VariadicArgument for f64

Operation variadicSlot#

silk
fn variadicSlot() -> VariadicSlot<f64>

Implementation VaList#

silk
impl VaList

Associated function of#

silk
pub unsafe fn of(list: *mut u64) -> VaList

Wraps 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#

silk
pub unsafe fn next<T: VariadicArgument + Copy>(self: &mut Self) -> T

Reads 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#

silk
pub unsafe fn nextPointer<T>(self: &mut Self) -> ?*mut T

Reads 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.

View the source of this page