#unix #pipe #fork #exec #posix

unix-exec-output-catcher

Library to run executables in a child process and catch STDOUT and STDERR output on UNIX-systems. std::process::Command is probably the better option. Use this source code as educational source how it could be done.

8 releases

new 0.2.3 Jan 10, 2021
0.2.2 Nov 30, 2020
0.1.3 Nov 27, 2020

#89 in Unix APIs

Download history 5/week @ 2020-11-20 109/week @ 2020-11-27 42/week @ 2020-12-04 11/week @ 2020-12-11 3/week @ 2020-12-18 12/week @ 2021-01-01 30/week @ 2021-01-08

65 downloads per month
Used in mac-sys-info

MIT license

35KB
578 lines

unix-exec-output-catcher

A library written in Rust that executes an executable in a child process and catches its output (stdout and stderr).

⚠️ Difference to std::process::Command 🚨

std::process::Command does the same in the standard library but with one exception: My library gives you access to stdout, stderr, and "stdcombined". This way you get all output lines in the order they appeared. That's the unique feature of this crate. std/process/struct.Command.html#method.output

TL;DR;

The call to fork_exec_and_catch() is blocking. If the program produces infinite output to stdout or stderr, this function will never return. If the program produces 1GB of output this function will consume 1GB of memory. See examples directory for example code. Please read the warnings/information in OCatchStrategy. The strategy determines in what way "STDCOMBINED" get's collected.

Will my "STDCOMBINED" output (STDOUT + STDERR) be in right order?

  • OCatchStrategy::StdCombined: definitely
  • OCatchStrategy::StdSeparately: most probably, but there is no guarantee. If there are alternating prints to STDOUT/STDERR in a row without a few hundreds microseconds in between, it will probably happen due to scheduling and in-kernel buffering that STDOUT/STDERR is not captured in correct order. See Rust comments for more information.

Example

use unix_exec_output_catcher::{fork_exec_and_catch, OCatchStrategy};

fn main() {
    // executes "ls" with "-la" as argument.
    // this is equivalent to running "$ ls -la" in your shell.
    // The line by line output is stored inside the result.
    let res = fork_exec_and_catch(
        "ls", 
        vec!["ls", "-la"], 
        OCatchStrategy::StdSeparately
    );
    println!("{:#?}", res.unwrap());
}

Used technologies / important keywords

  • Unix (including but not limited to Linux-distributions, MacOS)
  • pipe()
  • exec()
  • fork()
  • dup2()

Dependencies

~0.5–1MB
~24K SLoC