Struct StackLayoutRef

pub struct StackLayoutRef<'a> { /* private fields */ }

Wraps a slice of bytes representing a Linux stack layout allowing to conveniently parse its content.

The stack layout under Linux contains argc, argv, envv/envp, and the auxiliary vector, all with the additional referenced payloads. More precisely, the structure contains data in the following order:

• argc: Amount of arguments
• argv: null-terminated array of pointers into argv data area
• NULL pointer
• envv: null-terminated array of pointers into envv data area
• NULL pointer
• auxv Array of auxiliary variables (AT variables), terminated by an AuxVarType::Null entry.
• NUL[s] for padding
• auxv data area: Possibly payload of auxiliary variables
• argv data area: Null-terminated C strings representing the arguments
• envv data area: Null-terminated C strings representing the environment
• NUL[s] for padding

The parsing code will determine at runtime how long the data actually is, therefore, it is recommended to pass in a slice that is long enough to hold the stack layout. For example, passing in a 1 MiB slice is perfectly fine.

Safety

Each function that loads data from one of the

More Info

• <See https://lwn.net/Articles/631631/>

Implementations

impl<'a> StackLayoutRef<'a>

pub fn new(bytes: &'a [u8], argc: Option<usize>) -> Self

Creates a new view into the stack layout.

The argc determines whether bytes start with the argc argument (=> None) or if bytes already point to the start of argv.

Examples found in repository

examples/minimal_builder.rs (line 36)

fn main() {
    let builder = StackLayoutBuilder::new()
        // can contain terminating zero; not mandatory in the builder
        .add_argv("foo")
        .add_argv("hello")
        .add_envv("PATH=/bin")
        .add_auxv(AuxVar::ExecFn("/usr/bin/foo".into()));

    let layout = builder.build(None /* we create the layout in our address space */);
    let layout = StackLayoutRef::new(layout.as_ref(), None);

    // SAFETY: This is safe as all pointers point into our address space.
    for (i, arg) in unsafe { layout.argv_iter() }.enumerate() {
        println!("  [{i}] {}", arg.to_str().unwrap());
    }
}

examples/linux_print_layout.rs (line 38)

fn main(argc: isize, argv: *const *const u8) -> isize {
    let buffer = unsafe {
        // 100 KiB, reasonably big.
        // On my Linux machine, the structure needs 23 KiB
        slice::from_raw_parts(argv.cast::<u8>(), 0x19000)
    };

    let parsed = StackLayoutRef::new(buffer, Some(argc as usize));

    println!("There are {} arguments.", parsed.argc());
    println!("  argv (raw)");
    for (i, arg) in parsed.argv_raw_iter().enumerate() {
        println!("    [{i}] @ {arg:?}");
    }
    println!("  argv");
    // SAFETY: The pointers are valid in the address space of this process.
    for (i, arg) in unsafe { parsed.argv_iter() }.enumerate() {
        println!("    [{i}] {arg:?}");
    }

    println!("There are {} environment variables.", parsed.envc());
    println!("  envv (raw)");
    for (i, env) in parsed.envv_raw_iter().enumerate() {
        println!("    [{i}] {env:?}");
    }
    println!("  envv");
    // SAFETY: The pointers are valid in the address space of this process.
    for (i, env) in unsafe { parsed.envv_iter() }.enumerate() {
        println!("    [{i}] {env:?}");
    }

    println!(
        "There are {} auxiliary vector entries/AT variables.",
        parsed.auxv_raw_iter().count()
    );
    println!("  aux");
    // ptr iter is safe for other address spaces; the other only because here user_addr == write_addr
    for aux in unsafe { parsed.auxv_iter() } {
        if aux.key().value_in_data_area() {
            println!("    {:?} => @ {:?}", aux.key(), aux);
        } else {
            println!("    {:?} => {:?}", aux.key(), aux);
        }
    }

    0
}

pub fn argc(&self) -> usize

Returns the number of arguments.

Examples found in repository

examples/linux_print_layout.rs (line 40)

fn main(argc: isize, argv: *const *const u8) -> isize {
    let buffer = unsafe {
        // 100 KiB, reasonably big.
        // On my Linux machine, the structure needs 23 KiB
        slice::from_raw_parts(argv.cast::<u8>(), 0x19000)
    };

    let parsed = StackLayoutRef::new(buffer, Some(argc as usize));

    println!("There are {} arguments.", parsed.argc());
    println!("  argv (raw)");
    for (i, arg) in parsed.argv_raw_iter().enumerate() {
        println!("    [{i}] @ {arg:?}");
    }
    println!("  argv");
    // SAFETY: The pointers are valid in the address space of this process.
    for (i, arg) in unsafe { parsed.argv_iter() }.enumerate() {
        println!("    [{i}] {arg:?}");
    }

    println!("There are {} environment variables.", parsed.envc());
    println!("  envv (raw)");
    for (i, env) in parsed.envv_raw_iter().enumerate() {
        println!("    [{i}] {env:?}");
    }
    println!("  envv");
    // SAFETY: The pointers are valid in the address space of this process.
    for (i, env) in unsafe { parsed.envv_iter() }.enumerate() {
        println!("    [{i}] {env:?}");
    }

    println!(
        "There are {} auxiliary vector entries/AT variables.",
        parsed.auxv_raw_iter().count()
    );
    println!("  aux");
    // ptr iter is safe for other address spaces; the other only because here user_addr == write_addr
    for aux in unsafe { parsed.auxv_iter() } {
        if aux.key().value_in_data_area() {
            println!("    {:?} => @ {:?}", aux.key(), aux);
        } else {
            println!("    {:?} => {:?}", aux.key(), aux);
        }
    }

    0
}

pub fn envc(&self) -> usize

Returns the number of environment variables.

Examples found in repository

examples/linux_print_layout.rs (line 51)

fn main(argc: isize, argv: *const *const u8) -> isize {
    let buffer = unsafe {
        // 100 KiB, reasonably big.
        // On my Linux machine, the structure needs 23 KiB
        slice::from_raw_parts(argv.cast::<u8>(), 0x19000)
    };

    let parsed = StackLayoutRef::new(buffer, Some(argc as usize));

    println!("There are {} arguments.", parsed.argc());
    println!("  argv (raw)");
    for (i, arg) in parsed.argv_raw_iter().enumerate() {
        println!("    [{i}] @ {arg:?}");
    }
    println!("  argv");
    // SAFETY: The pointers are valid in the address space of this process.
    for (i, arg) in unsafe { parsed.argv_iter() }.enumerate() {
        println!("    [{i}] {arg:?}");
    }

    println!("There are {} environment variables.", parsed.envc());
    println!("  envv (raw)");
    for (i, env) in parsed.envv_raw_iter().enumerate() {
        println!("    [{i}] {env:?}");
    }
    println!("  envv");
    // SAFETY: The pointers are valid in the address space of this process.
    for (i, env) in unsafe { parsed.envv_iter() }.enumerate() {
        println!("    [{i}] {env:?}");
    }

    println!(
        "There are {} auxiliary vector entries/AT variables.",
        parsed.auxv_raw_iter().count()
    );
    println!("  aux");
    // ptr iter is safe for other address spaces; the other only because here user_addr == write_addr
    for aux in unsafe { parsed.auxv_iter() } {
        if aux.key().value_in_data_area() {
            println!("    {:?} => @ {:?}", aux.key(), aux);
        } else {
            println!("    {:?} => {:?}", aux.key(), aux);
        }
    }

    0
}

pub fn auxvc(&self) -> usize

Returns the number of auxiliary vector entries.

pub fn argv_raw_iter(&self) -> impl Iterator<Item = *const u8>

Returns an iterator over the raw argument vector’s (argv) CStr pointers.

Safety

The pointers must point to valid memory. If dereferenced, the memory must be in the address space of the application. Otherwise, segmentation faults or UB will occur.

Examples found in repository

examples/linux_print_layout.rs (line 42)

fn main(argc: isize, argv: *const *const u8) -> isize {
    let buffer = unsafe {
        // 100 KiB, reasonably big.
        // On my Linux machine, the structure needs 23 KiB
        slice::from_raw_parts(argv.cast::<u8>(), 0x19000)
    };

    let parsed = StackLayoutRef::new(buffer, Some(argc as usize));

    println!("There are {} arguments.", parsed.argc());
    println!("  argv (raw)");
    for (i, arg) in parsed.argv_raw_iter().enumerate() {
        println!("    [{i}] @ {arg:?}");
    }
    println!("  argv");
    // SAFETY: The pointers are valid in the address space of this process.
    for (i, arg) in unsafe { parsed.argv_iter() }.enumerate() {
        println!("    [{i}] {arg:?}");
    }

    println!("There are {} environment variables.", parsed.envc());
    println!("  envv (raw)");
    for (i, env) in parsed.envv_raw_iter().enumerate() {
        println!("    [{i}] {env:?}");
    }
    println!("  envv");
    // SAFETY: The pointers are valid in the address space of this process.
    for (i, env) in unsafe { parsed.envv_iter() }.enumerate() {
        println!("    [{i}] {env:?}");
    }

    println!(
        "There are {} auxiliary vector entries/AT variables.",
        parsed.auxv_raw_iter().count()
    );
    println!("  aux");
    // ptr iter is safe for other address spaces; the other only because here user_addr == write_addr
    for aux in unsafe { parsed.auxv_iter() } {
        if aux.key().value_in_data_area() {
            println!("    {:?} => @ {:?}", aux.key(), aux);
        } else {
            println!("    {:?} => {:?}", aux.key(), aux);
        }
    }

    0
}

pub fn envv_raw_iter(&self) -> impl Iterator<Item = *const u8>

Returns an iterator over the raw environment vector’s (envv) CStr pointers.

Safety

The pointers must point to valid memory. If dereferenced, the memory must be in the address space of the application. Otherwise, segmentation faults or UB will occur.

Examples found in repository

examples/linux_print_layout.rs (line 53)

fn main(argc: isize, argv: *const *const u8) -> isize {
    let buffer = unsafe {
        // 100 KiB, reasonably big.
        // On my Linux machine, the structure needs 23 KiB
        slice::from_raw_parts(argv.cast::<u8>(), 0x19000)
    };

    let parsed = StackLayoutRef::new(buffer, Some(argc as usize));

    println!("There are {} arguments.", parsed.argc());
    println!("  argv (raw)");
    for (i, arg) in parsed.argv_raw_iter().enumerate() {
        println!("    [{i}] @ {arg:?}");
    }
    println!("  argv");
    // SAFETY: The pointers are valid in the address space of this process.
    for (i, arg) in unsafe { parsed.argv_iter() }.enumerate() {
        println!("    [{i}] {arg:?}");
    }

    println!("There are {} environment variables.", parsed.envc());
    println!("  envv (raw)");
    for (i, env) in parsed.envv_raw_iter().enumerate() {
        println!("    [{i}] {env:?}");
    }
    println!("  envv");
    // SAFETY: The pointers are valid in the address space of this process.
    for (i, env) in unsafe { parsed.envv_iter() }.enumerate() {
        println!("    [{i}] {env:?}");
    }

    println!(
        "There are {} auxiliary vector entries/AT variables.",
        parsed.auxv_raw_iter().count()
    );
    println!("  aux");
    // ptr iter is safe for other address spaces; the other only because here user_addr == write_addr
    for aux in unsafe { parsed.auxv_iter() } {
        if aux.key().value_in_data_area() {
            println!("    {:?} => @ {:?}", aux.key(), aux);
        } else {
            println!("    {:?} => {:?}", aux.key(), aux);
        }
    }

    0
}

pub fn auxv_raw_iter(&self) -> impl Iterator<Item = AuxVarRaw>

Returns an iterator over the auxiliary variables vector’s (auxv) AuxVarRaw elements.

Safety

Any pointers must point to valid memory. If dereferenced, the memory must be in the address space of the application. Otherwise, segmentation faults or UB will occur.

Examples found in repository

examples/linux_print_layout.rs (line 64)

fn main(argc: isize, argv: *const *const u8) -> isize {
    let buffer = unsafe {
        // 100 KiB, reasonably big.
        // On my Linux machine, the structure needs 23 KiB
        slice::from_raw_parts(argv.cast::<u8>(), 0x19000)
    };

    let parsed = StackLayoutRef::new(buffer, Some(argc as usize));

    println!("There are {} arguments.", parsed.argc());
    println!("  argv (raw)");
    for (i, arg) in parsed.argv_raw_iter().enumerate() {
        println!("    [{i}] @ {arg:?}");
    }
    println!("  argv");
    // SAFETY: The pointers are valid in the address space of this process.
    for (i, arg) in unsafe { parsed.argv_iter() }.enumerate() {
        println!("    [{i}] {arg:?}");
    }

    println!("There are {} environment variables.", parsed.envc());
    println!("  envv (raw)");
    for (i, env) in parsed.envv_raw_iter().enumerate() {
        println!("    [{i}] {env:?}");
    }
    println!("  envv");
    // SAFETY: The pointers are valid in the address space of this process.
    for (i, env) in unsafe { parsed.envv_iter() }.enumerate() {
        println!("    [{i}] {env:?}");
    }

    println!(
        "There are {} auxiliary vector entries/AT variables.",
        parsed.auxv_raw_iter().count()
    );
    println!("  aux");
    // ptr iter is safe for other address spaces; the other only because here user_addr == write_addr
    for aux in unsafe { parsed.auxv_iter() } {
        if aux.key().value_in_data_area() {
            println!("    {:?} => @ {:?}", aux.key(), aux);
        } else {
            println!("    {:?} => {:?}", aux.key(), aux);
        }
    }

    0
}

pub unsafe fn argv_iter(&self) -> impl Iterator<Item = &'a CStr>

Unsafe version of Self::argv_raw_iter that only works if all pointers are valid. It emits high-level items of type CStr.

This is typically safe if you parse the stack layout you’ve got from Linux but not if you parse some other’s stack layout.

Safety

The pointers must point to valid memory. If dereferenced, the memory must be in the address space of the application. Otherwise, segmentation faults or UB will occur.

Examples found in repository

examples/minimal_builder.rs (line 39)

fn main() {
    let builder = StackLayoutBuilder::new()
        // can contain terminating zero; not mandatory in the builder
        .add_argv("foo")
        .add_argv("hello")
        .add_envv("PATH=/bin")
        .add_auxv(AuxVar::ExecFn("/usr/bin/foo".into()));

    let layout = builder.build(None /* we create the layout in our address space */);
    let layout = StackLayoutRef::new(layout.as_ref(), None);

    // SAFETY: This is safe as all pointers point into our address space.
    for (i, arg) in unsafe { layout.argv_iter() }.enumerate() {
        println!("  [{i}] {}", arg.to_str().unwrap());
    }
}

examples/linux_print_layout.rs (line 47)

fn main(argc: isize, argv: *const *const u8) -> isize {
    let buffer = unsafe {
        // 100 KiB, reasonably big.
        // On my Linux machine, the structure needs 23 KiB
        slice::from_raw_parts(argv.cast::<u8>(), 0x19000)
    };

    let parsed = StackLayoutRef::new(buffer, Some(argc as usize));

    println!("There are {} arguments.", parsed.argc());
    println!("  argv (raw)");
    for (i, arg) in parsed.argv_raw_iter().enumerate() {
        println!("    [{i}] @ {arg:?}");
    }
    println!("  argv");
    // SAFETY: The pointers are valid in the address space of this process.
    for (i, arg) in unsafe { parsed.argv_iter() }.enumerate() {
        println!("    [{i}] {arg:?}");
    }

    println!("There are {} environment variables.", parsed.envc());
    println!("  envv (raw)");
    for (i, env) in parsed.envv_raw_iter().enumerate() {
        println!("    [{i}] {env:?}");
    }
    println!("  envv");
    // SAFETY: The pointers are valid in the address space of this process.
    for (i, env) in unsafe { parsed.envv_iter() }.enumerate() {
        println!("    [{i}] {env:?}");
    }

    println!(
        "There are {} auxiliary vector entries/AT variables.",
        parsed.auxv_raw_iter().count()
    );
    println!("  aux");
    // ptr iter is safe for other address spaces; the other only because here user_addr == write_addr
    for aux in unsafe { parsed.auxv_iter() } {
        if aux.key().value_in_data_area() {
            println!("    {:?} => @ {:?}", aux.key(), aux);
        } else {
            println!("    {:?} => {:?}", aux.key(), aux);
        }
    }

    0
}

pub unsafe fn envv_iter(&self) -> impl Iterator<Item = &'a CStr>

Unsafe version of Self::envv_raw_iter that only works if all pointers are valid. It emits high-level items of type CStr.

This is typically safe if you parse the stack layout you’ve got from Linux but not if you parse some other’s stack layout.

Safety

The pointers must point to valid memory. If dereferenced, the memory must be in the address space of the application. Otherwise, segmentation faults or UB will occur.

Examples found in repository

examples/linux_print_layout.rs (line 58)

fn main(argc: isize, argv: *const *const u8) -> isize {
    let buffer = unsafe {
        // 100 KiB, reasonably big.
        // On my Linux machine, the structure needs 23 KiB
        slice::from_raw_parts(argv.cast::<u8>(), 0x19000)
    };

    let parsed = StackLayoutRef::new(buffer, Some(argc as usize));

    println!("There are {} arguments.", parsed.argc());
    println!("  argv (raw)");
    for (i, arg) in parsed.argv_raw_iter().enumerate() {
        println!("    [{i}] @ {arg:?}");
    }
    println!("  argv");
    // SAFETY: The pointers are valid in the address space of this process.
    for (i, arg) in unsafe { parsed.argv_iter() }.enumerate() {
        println!("    [{i}] {arg:?}");
    }

    println!("There are {} environment variables.", parsed.envc());
    println!("  envv (raw)");
    for (i, env) in parsed.envv_raw_iter().enumerate() {
        println!("    [{i}] {env:?}");
    }
    println!("  envv");
    // SAFETY: The pointers are valid in the address space of this process.
    for (i, env) in unsafe { parsed.envv_iter() }.enumerate() {
        println!("    [{i}] {env:?}");
    }

    println!(
        "There are {} auxiliary vector entries/AT variables.",
        parsed.auxv_raw_iter().count()
    );
    println!("  aux");
    // ptr iter is safe for other address spaces; the other only because here user_addr == write_addr
    for aux in unsafe { parsed.auxv_iter() } {
        if aux.key().value_in_data_area() {
            println!("    {:?} => @ {:?}", aux.key(), aux);
        } else {
            println!("    {:?} => {:?}", aux.key(), aux);
        }
    }

    0
}

pub unsafe fn auxv_iter(&self) -> impl Iterator<Item = AuxVar<'a>>

Unsafe version of Self::argv_raw_iter that only works if all pointers are valid. It emits high-level items of type AuxVar.

This is typically safe if you parse the stack layout you’ve got from Linux but not if you parse some other’s stack layout.

Safety

Any pointers must point to valid memory. If dereferenced, the memory must be in the address space of the application. Otherwise, segmentation faults or UB will occur.

Examples found in repository

examples/linux_print_layout.rs (line 68)

fn main(argc: isize, argv: *const *const u8) -> isize {
    let buffer = unsafe {
        // 100 KiB, reasonably big.
        // On my Linux machine, the structure needs 23 KiB
        slice::from_raw_parts(argv.cast::<u8>(), 0x19000)
    };

    let parsed = StackLayoutRef::new(buffer, Some(argc as usize));

    println!("There are {} arguments.", parsed.argc());
    println!("  argv (raw)");
    for (i, arg) in parsed.argv_raw_iter().enumerate() {
        println!("    [{i}] @ {arg:?}");
    }
    println!("  argv");
    // SAFETY: The pointers are valid in the address space of this process.
    for (i, arg) in unsafe { parsed.argv_iter() }.enumerate() {
        println!("    [{i}] {arg:?}");
    }

    println!("There are {} environment variables.", parsed.envc());
    println!("  envv (raw)");
    for (i, env) in parsed.envv_raw_iter().enumerate() {
        println!("    [{i}] {env:?}");
    }
    println!("  envv");
    // SAFETY: The pointers are valid in the address space of this process.
    for (i, env) in unsafe { parsed.envv_iter() }.enumerate() {
        println!("    [{i}] {env:?}");
    }

    println!(
        "There are {} auxiliary vector entries/AT variables.",
        parsed.auxv_raw_iter().count()
    );
    println!("  aux");
    // ptr iter is safe for other address spaces; the other only because here user_addr == write_addr
    for aux in unsafe { parsed.auxv_iter() } {
        if aux.key().value_in_data_area() {
            println!("    {:?} => @ {:?}", aux.key(), aux);
        } else {
            println!("    {:?} => {:?}", aux.key(), aux);
        }
    }

    0
}

Trait Implementations

impl<'a> Debug for StackLayoutRef<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.