Base: Write some initial man pages

It ain't much, but it's honest work!

8 files changed, 256 insertions, 0 deletions

diff --git a/Base/usr/share/man/man1/crash.md b/Base/usr/share/man/man1/crash.md
new file mode 100644
index 0000000000..4e55f82573
--- /dev/null
+++ b/Base/usr/share/man/man1/crash.md
@@ -0,0 +1,34 @@
+## Name
+
+crash - intentionally perform an illegal operation
+
+## Synopsis
+
+```**sh
+$ crash [options]
+```
+
+## Description
+
+This program is used to test how the Serenity kernel handles
+userspace crashes, and can be used to simulate many different
+kinds of crashes.
+
+## Options
+
+* `-s`: Perform a segmentation violation by dereferencing an invalid pointer.
+* `-d`: Perform a division by zero.
+* `-i`: Execute an illegal CPU instruction.
+* `-a`: Call `abort()`.
+* `-m`: Read a pointer from uninitialized memory, then read from it.
+* `-f`: Read a pointer from memory freed using `free()`, then read from it.
+* `-M`: Read a pointer from uninitialized memory, then write to it.
+* `-F`: Read a pointer from memory freed using `free()`, then write to it.
+* `-r`: Write to read-only memory.
+
+## Examples
+
+```sh
+$ crash -F
+Shell: crash(33) exitied due to signal "Segmentation violation"
+```
\ No newline at end of file
diff --git a/Base/usr/share/man/man1/echo.md b/Base/usr/share/man/man1/echo.md
new file mode 100644
index 0000000000..d14033b9a5
--- /dev/null
+++ b/Base/usr/share/man/man1/echo.md
@@ -0,0 +1,19 @@
+## Name
+
+echo - print the given text
+
+## Synopsis
+
+`echo text...`
+
+## Description
+
+Print the given *text*, which is passed as argv, to the standard output,
+separating arguments with a space character.
+
+## Examples
+
+```sh
+$ echo hello friends!
+hello friends!
+```
diff --git a/Base/usr/share/man/man1/man.md b/Base/usr/share/man/man1/man.md
new file mode 100644
index 0000000000..368dea7179
--- /dev/null
+++ b/Base/usr/share/man/man1/man.md
@@ -0,0 +1,46 @@
+## Name
+
+man - read manual pages
+
+## Synopsis
+
+```**sh
+$ man page
+$ man section page
+```
+
+## Description
+
+`man` finds, loads and displays the so-called manual pages,
+or man pages for short, from the Serenity manual. You're reading
+the manual page for `man` program itself right now.
+
+## Sections
+
+The Serenity manual is split into the following *sections*, or *chapters*:
+
+1. Command-line programs
+2. System calls
+
+More sections will be added in the future.
+
+## Examples
+
+To open documentation for the `echo` command:
+```sh
+$ man echo
+```
+
+To open the documentation for the `mkdir` command:
+```sh
+$ man 1 mkdir
+```
+Conversely, to open the documentation about the `mkdir()` syscall:
+```sh
+$ man 2 mkdir
+```
+
+## Files
+
+`man` looks for man pages under `/usr/share/man`. For example,
+this man page should be located at `/usr/share/man/man1/man.md`.
diff --git a/Base/usr/share/man/man1/md.md b/Base/usr/share/man/man1/md.md
new file mode 100644
index 0000000000..836dd35839
--- /dev/null
+++ b/Base/usr/share/man/man1/md.md
@@ -0,0 +1,28 @@
+## Name
+
+md - render markdown documents
+
+## Synposis
+
+```**sh
+$ md [--html] [input-file.md]
+```
+
+## Description
+
+Read a Markdown document and render it using either terminal
+escape sequences (the default) or HTML. If a file name is given,
+`md` reads the document from that file; by default it reads its
+standard input.
+
+## Options
+
+* `--html`: Render the document into HTML.
+
+## Examples
+
+Here's how you can render this man page into HTML:
+
+```sh
+$ md --html /usr/share/man/man1/md.md
+```
diff --git a/Base/usr/share/man/man1/mkdir.md b/Base/usr/share/man/man1/mkdir.md
new file mode 100644
index 0000000000..eef73cdaeb
--- /dev/null
+++ b/Base/usr/share/man/man1/mkdir.md
@@ -0,0 +1,19 @@
+## Name
+
+mkdir - create a directory
+
+## Synopsis
+
+```**sh
+$ mkdir path
+```
+
+## Description
+
+Create a new empty directory at the given *path*.
+
+## Examples
+
+```sh
+$ mkdir /tmp/foo
+```
diff --git a/Base/usr/share/man/man2/access.md b/Base/usr/share/man/man2/access.md
new file mode 100644
index 0000000000..13d7b77027
--- /dev/null
+++ b/Base/usr/share/man/man2/access.md
@@ -0,0 +1,24 @@
+## Name
+
+access - check if a file is accessible
+
+## Synopsis
+
+```**c++
+#include <unistd.h>
+
+int access(const char* path, int mode);
+```
+
+## Description
+
+Check if a file at the given *path* exists and is accessible to the current user for the given *mode*.
+Valid flags for *mode* are:
+* `F_OK` to check if the file is accessible at all,
+* `R_OK` to check if the file can be read,
+* `W_OK` to check if the file can be written to,
+* `X_OK` to check if the file can be executed as a program.
+
+## Return value
+
+If the file is indeed accessible for the specified *mode*, `access()` returns 0. Otherwise, it returns -1 and sets `errno` to describe the error.
diff --git a/Base/usr/share/man/man2/mkdir.md b/Base/usr/share/man/man2/mkdir.md
new file mode 100644
index 0000000000..6411ceac73
--- /dev/null
+++ b/Base/usr/share/man/man2/mkdir.md
@@ -0,0 +1,20 @@
+## Name
+
+mkdir - create a directory
+
+## Synopsis
+
+```**c++
+#include <sys/stat.h>
+
+int mkdir(const char* path, mode_t mode);
+```
+
+## Description
+
+Create a new empty directory at the given *path* using the given *mode*.
+
+## Return value
+
+If the directory was created successfully, `mkdir()` returns 0. Otherwise,
+it returns -1 and sets `errno` to describe the error.
diff --git a/Base/usr/share/man/man2/pipe.md b/Base/usr/share/man/man2/pipe.md
new file mode 100644
index 0000000000..e09cb463a5
--- /dev/null
+++ b/Base/usr/share/man/man2/pipe.md
@@ -0,0 +1,66 @@
+## Name
+
+pipe, pipe2 - create a pipe
+
+## Synposis
+
+```**c++
+#include <unistd.h>
+
+int pipe(int pipefd[2]);
+int pipe2(int pipefd[2], int flags);
+```
+
+## Description
+
+`pipe()` creates a new pipe, an anonymous FIFO channel. It returns two new file descriptors in `pipefd`.
+Any data written to the `pipefd[1]` can then be read from `pipefd[0]`. When `pipefd[1]` is closed, reads
+from `pipefd[0]` will return EOF.
+
+`pipe2()` behaves the same as `pipe()`, but it additionally accepts the following *flags*:
+
+* `O_CLOEXEC`: Automatically close the file descriptors created by this call, as if by `close()` call, when performing an `exec()`.
+
+## Examples
+
+The following program creates a pipe, then forks, the child then
+writes some data to the pipe which the parent reads:
+
+```c++
+#include <AK/Assertions.h>
+#include <stdio.h>
+#incldue <unistd.h>
+
+int main()
+{
+    // Create the pipe.
+    int pipefd[2];
+    int rc = pipe(pipefd);
+    ASSERT(rc == 0);
+
+    pid_t pid = fork();
+    ASSERT(pid >= 0);
+
+    if (pid == 0) {
+        // Close the reading end of the pipe.
+        close(pipefd[0]);
+        // Write a message to the writing end of the pipe.
+        static const char greeting[] = "Hello friends!";
+        int nwritten = write(pipefd[1], greeting, sizeof(greeting));
+        ASSERT(nwritten == sizeof(greeting));
+        exit(0);
+    } else {
+        // Close the writing end of the pipe.
+        // If we don't do this, we'll never
+        // get an EOF.
+        close(pipefd[1]);
+        // Read the message from the reading end of the pipe.
+        char buffer[100];
+        int nread = read(pipefd[0], buffer, sizeof(buffer));
+        ASSERT(nread > 0);
+        // Try to read again. We should get an EOF this time.
+        nread = read(pipefd[0], buffer + nread, sizeof(buffer) - nread);
+        ASSERT(nread == 0);
+    }
+}
+```