1 files changed, 46 insertions, 0 deletions
diff --git a/src/doc/rust-by-example/src/std_misc/process/pipe.md b/src/doc/rust-by-example/src/std_misc/process/pipe.md
new file mode 100644
index 000000000..fb0be0ea1
--- /dev/null
+++ b/src/doc/rust-by-example/src/std_misc/process/pipe.md
@@ -0,0 +1,46 @@
+# Pipes
+
+The `std::Child` struct represents a running child process, and exposes the
+`stdin`, `stdout` and `stderr` handles for interaction with the underlying
+process via pipes.
+
+```rust,ignore
+use std::io::prelude::*;
+use std::process::{Command, Stdio};
+
+static PANGRAM: &'static str =
+"the quick brown fox jumped over the lazy dog\n";
+
+fn main() {
+    // Spawn the `wc` command
+    let process = match Command::new("wc")
+                                .stdin(Stdio::piped())
+                                .stdout(Stdio::piped())
+                                .spawn() {
+        Err(why) => panic!("couldn't spawn wc: {}", why),
+        Ok(process) => process,
+    };
+
+    // Write a string to the `stdin` of `wc`.
+    //
+    // `stdin` has type `Option<ChildStdin>`, but since we know this instance
+    // must have one, we can directly `unwrap` it.
+    match process.stdin.unwrap().write_all(PANGRAM.as_bytes()) {
+        Err(why) => panic!("couldn't write to wc stdin: {}", why),
+        Ok(_) => println!("sent pangram to wc"),
+    }
+
+    // Because `stdin` does not live after the above calls, it is `drop`ed,
+    // and the pipe is closed.
+    //
+    // This is very important, otherwise `wc` wouldn't start processing the
+    // input we just sent.
+
+    // The `stdout` field also has type `Option<ChildStdout>` so must be unwrapped.
+    let mut s = String::new();
+    match process.stdout.unwrap().read_to_string(&mut s) {
+        Err(why) => panic!("couldn't read wc stdout: {}", why),
+        Ok(_) => print!("wc responded with:\n{}", s),
+    }
+}
+```