Function mlock 

pub unsafe fn mlock(addr: *const c_void, len: usize) -> Result<()>

Available on Unix only.

Lock the pages containing the specified memory region to prevent swapping.

Returns:

• Ok(()) on success
• Err(…) with last_os_error() on failure
• Err(Unsupported) on platforms where this call is not available

Safety

The caller must ensure that (addr, len) refers to a valid, non-null memory region owned by this process for the duration of the call, and that the region is not deallocated, unmapped, or remapped concurrently.

Examples

no_run

use std::io;

fn demo() -> io::Result<()> {

let mut buf = vec![0u8; 4096]; let ptr = buf.as_ptr() as *const std::os::raw::c_void; let len = buf.len(); match unsafe { os_memlock::mlock(ptr, len) } { Ok(()) => { // do work… unsafe { os_memlock::munlock(ptr, len)?; } } Err(e) if e.kind() == std::io::ErrorKind::Unsupported => { // platform/build doesn’t support mlock; proceed without locking } Err(e) => return Err(e), }

Ok(()) }

Examples found in repository

examples/locked_vec.rs (line 32)

    pub fn new(len: usize) -> io::Result<Self> {
        // Allocate a zeroed buffer. We won't change capacity after locking.
        let buf = vec![0u8; len];

        // Attempt to lock pages. Treat Unsupported as a non-fatal condition.
        let ptr = buf.as_ptr() as *const std::os::raw::c_void;
        let locked = match unsafe { os_memlock::mlock(ptr, buf.len()) } {
            Ok(()) => true,
            Err(e) if e.kind() == io::ErrorKind::Unsupported => {
                eprintln!(
                    "os-memlock: mlock unsupported on this platform/build; continuing unlocked"
                );
                false
            }
            Err(e) => return Err(e),
        };

        // Best-effort: on Linux, advise dump exclusion.
        #[cfg(target_os = "linux")]
        {
            let mut_ptr = buf.as_mut_ptr() as *mut std::os::raw::c_void;
            match unsafe { os_memlock::madvise_dontdump(mut_ptr, buf.len()) } {
                Ok(()) => (),
                Err(e) if e.kind() == io::ErrorKind::Unsupported => {
                    // Not supported on this target; ignore gracefully.
                }
                Err(e) => {
                    // Non-fatal: just log the error.
                    eprintln!("os-memlock: madvise(MADV_DONTDUMP) failed: {e}");
                }
            }
        }

        Ok(Self { buf, locked })
    }

examples/simple.rs (line 36)

fn main() -> io::Result<()> {
    // Simple buffer representing secret data. Use a page-sized allocation for clarity.
    // On many systems a page is 4096 bytes; this example uses that common size.
    const PAGE_LEN: usize = 4096;
    let mut secret = vec![0u8; PAGE_LEN];

    // Put some dummy secret bytes (for demo only).
    secret[..16].copy_from_slice(b"super-secret-data");

    let ptr = secret.as_ptr() as *const std::os::raw::c_void;

    let len = secret.len();

    println!("Attempting to lock {} bytes at {:p}", len, ptr);

    // Try to mlock the buffer. This is unsafe and may return Unsupported on some builds/platforms.
    match unsafe { os_memlock::mlock(ptr, len) } {
        Ok(()) => println!("mlock succeeded"),
        Err(e) if e.kind() == io::ErrorKind::Unsupported => {
            println!("mlock is unsupported on this platform/build; continuing without page-lock")
        }
        Err(e) => return Err(e),
    }

    // Best-effort: on Linux and FreeBSD, advise the kernel not to include the mapping in core dumps.
    #[cfg(any(target_os = "linux", target_os = "freebsd"))]
    {
        let mut_ptr = secret.as_mut_ptr() as *mut std::os::raw::c_void;
        match unsafe { os_memlock::madvise_dontdump(mut_ptr, len) } {
            Ok(()) => println!("madvise dump-exclusion hint applied"),
            Err(e) if e.kind() == io::ErrorKind::Unsupported => {
                println!("madvise dump-exclusion hint unsupported on this platform/build")
            }
            Err(e) => eprintln!("madvise failed: {:#}", e),
        }
    }

    // Do some work while memory is (hopefully) locked.
    println!("Working with secret data (simulated)...");
    // Sleep briefly to simulate lifetime of locked secret. (In real code avoid sleeping.)
    thread::sleep(Duration::from_millis(250));

    // Before dropping or unmapping the buffer, munlock.
    match unsafe { os_memlock::munlock(ptr, len) } {
        Ok(()) => println!("munlock succeeded"),
        Err(e) if e.kind() == io::ErrorKind::Unsupported => {
            println!("munlock unsupported (no-op for this platform/build)")
        }
        Err(e) => return Err(e),
    }

    // Zeroize secret before drop as a good hygiene (example only; use a proper zeroize crate in production).
    for b in &mut secret {
        *b = 0;
    }

    println!("Secret zeroized and example complete.");
    Ok(())
}