Multi page manual (#5110)

1 files changed, 24 insertions, 0 deletions

diff --git a/docs/examples/unix_cat.md b/docs/examples/unix_cat.md
new file mode 100644
index 000000000..7534ef0d0
--- /dev/null
+++ b/docs/examples/unix_cat.md
@@ -0,0 +1,24 @@
+## An implementation of the unix "cat" program
+
+In this program each command-line argument is assumed to be a filename, the file
+is opened, and printed to stdout.
+
+```ts
+for (let i = 0; i < Deno.args.length; i++) {
+  let filename = Deno.args[i];
+  let file = await Deno.open(filename);
+  await Deno.copy(file, Deno.stdout);
+  file.close();
+}
+```
+
+The `copy()` function here actually makes no more than the necessary kernel ->
+userspace -> kernel copies. That is, the same memory from which data is read
+from the file, is written to stdout. This illustrates a general design goal for
+I/O streams in Deno.
+
+Try the program:
+
+```shell
+$ deno run --allow-read https://deno.land/std/examples/cat.ts /etc/passwd
+```