Struct memfd_exec::MemFdExecutable

pub struct MemFdExecutable {
    pub stdin: Option<Stdio>,
    pub stdout: Option<Stdio>,
    pub stderr: Option<Stdio>,
    /* private fields */
}

This is the main struct used to create an in-memory only executable. Wherever possible, it is intended to be a drop-in replacement for the standard library’s process::Command struct.

Examples

This example is the “motivating case” for this library. It shows how to execute a binary entirely from memory, without writing it to disk. This is useful for executing binaries sneakily, or (the real reason) for bundling executables that are a pain to set up and compile, but whose static versions are very portable. Here’s a “sneaky” example:

use memfd_exec::{MemFdExecutable, Stdio};

// You can include the entirety of a binary (for example, nc)
let nc_binary= include_bytes!("/usr/bin/nc-static");


// The first argument is just the name for the program, you can pick anything but
// if the program expects a specific argv[0] value, use that.
// The second argument is the binary code to execute.
let mut cmd = MemFdExecutable::new("nc", nc_binary)
    // We can pass arbitrary args just like with Command. Here, we'll execute nc
    // to listen on a port and run a shell for connections, entirely from memory.
    .arg("-l")
    .arg("1234")
    .arg("-e")
    .arg("/bin/sh")
    // And we can get piped stdin/stdout just like with Command
    .stdout(Stdio::piped())
    // Spawn starts the child process and gives us a handle back
    .spawn()
    .expect("failed to execute process");

// Then, we can wait for the program to exit.
cmd.wait();

Fields

stdin: Option<Stdio>

The program’s stdin handle

stdout: Option<Stdio>

The program’s stdout handle

stderr: Option<Stdio>

The program’s stderr handle

Implementations

impl MemFdExecutable

pub fn new<S: AsRef<OsStr>>(name: S, code: Vec<u8>) -> Self

Create a new MemFdExecutable with the given name and code. The name is the name of the program, and is used as the argv[0] argument to the program. The code is the binary code to execute (usually, the entire contents of an ELF file).

Examples

You can run code that is included directly in your executable with include_bytes!():

use memfd_exec::MemFdExecutable;

let code = include_bytes!("/usr/bin/nc-static");

let mut cmd = MemFdExecutable::new("nc", code)
    .arg("-l")
    .arg("1234")
    .arg("-e")
    .arg("/bin/sh")
    .status()
    .expect("failed to execute process");

pub fn arg<S: AsRef<OsStr>>(&mut self, arg: S) -> &mut Self

Add an argument to the program. This is equivalent to Command::arg().

pub fn args<I, S>(&mut self, args: I) -> &mut Selfwhere
    I: IntoIterator<Item = S>,
    S: AsRef<OsStr>,

Add multiple arguments to the program. This is equivalent to Command::args().

pub fn env<K, V>(&mut self, key: K, val: V) -> &mut Selfwhere
    K: AsRef<OsStr>,
    V: AsRef<OsStr>,

Add an environment variable to the program. This is equivalent to Command::env().

pub fn envs<I, K, V>(&mut self, vars: I) -> &mut Selfwhere
    I: IntoIterator<Item = (K, V)>,
    K: AsRef<OsStr>,
    V: AsRef<OsStr>,

Add multiple environment variables to the program. This is equivalent to Command::envs().

pub fn env_remove<K: AsRef<OsStr>>(&mut self, key: K) -> &mut Self

Remove an environment variable from the program. This is equivalent to Command::env_remove().

pub fn env_clear(&mut self) -> &mut Self

Clear all environment variables from the program. This is equivalent to Command::env_clear().

pub fn cwd<P: AsRef<Path>>(&mut self, dir: P) -> &mut Self

Set the current working directory for the program. This is equivalent to Command::current_dir().

pub fn stdin<T: Into<Stdio>>(&mut self, cfg: T) -> &mut Self

Set the stdin handle for the program. This is equivalent to Command::stdin(). The default is to inherit the current process’s stdin. Note that this Stdio is not the same exactly as process::Stdio, but it is feature-equivalent.

Examples

This example creates a cat process that will read in the contents passed to its stdin handle and write them to a null stdout (i.e. it will be discarded). The same methodology can be used to read from stderr/stdout.

use std::thread::spawn;
use std::io::Write;

use memfd_exec::{MemFdExecutable, Stdio};

let mut cat_cmd = MemFdExecutable::new("cat", include_bytes!("/bin/cat").to_vec())
   .stdin(Stdio::piped())
   .stdout(Stdio::null())
   .spawn()
   .expect("failed to spawn cat");

let mut cat_stdin = cat_cmd.stdin.take().expect("failed to open stdin");
spawn(move || {
   cat_stdin.write_all(b"hello world").expect("failed to write to stdin");
});

pub fn stdout<T: Into<Stdio>>(&mut self, cfg: T) -> &mut Self

pub fn stderr<T: Into<Stdio>>(&mut self, cfg: T) -> &mut Self

pub fn spawn(&mut self) -> Result<Child>

Spawn the program as a child process. This is equivalent to Command::spawn().

pub fn output(&mut self) -> Result<Output>

Spawn the program as a child process and wait for it to complete, obtaining the output and exit status. This is equivalent to Command::output().

pub fn status(&mut self) -> Result<ExitStatus>

Spawn the program as a child process and wait for it to complete, obtaining the exit status. This is equivalent to Command::status().

pub fn _new(name: &OsStr, code: Vec<u8>) -> Self

Create a new Executable from the given program name.

pub fn _saw_nul(&self) -> bool

pub fn _get_cwd(&self) -> &Option<CString>

pub fn _spawn(&mut self, default: Stdio, needs_stdin: bool) -> Result<Child>

pub fn _capture_env(&mut self) -> Option<Vec<CString>>

pub fn _exec(&mut self, default: Stdio) -> Error

pub fn _get_program_cstr(&self) -> &CStr

pub fn _get_argv(&self) -> &Vec<CString>

pub fn _env_saw_path(&self) -> bool

pub fn _program_is_path(&self) -> bool