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 + +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 + +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 + +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 +#include +#incldue + +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); + } +} +```