Base: Add more manpages for command-line utilities

Author: https://github.com/sppmacd
Commit: https://github.com/SerenityOS/serenity/commit/57340dda36b
Pull-request: https://github.com/SerenityOS/serenity/pull/7611
Reviewed-by: https://github.com/gunnarbeutner
Reviewed-by: https://github.com/idispatch
Reviewed-by: https://github.com/matusf

Base/usr/share/man/man1/allocate.md

@@ -0,0 +1,51 @@
+## Name
+
+allocate - allocate memory
+
+## Synopsis
+
+```**sh
+$ allocate [number [unit (B/KiB/MiB)]]
+```
+
+## Description
+
+`allocate` allocates a specific amount of virtual memory (specified in `number` and `unit`, by default 50 MiB), It also writes to each allocated page and then sleeps for 10 seconds. It is primarily used to test the kernel's memory management capabilities.
+
+## Arguments
+
+* `number`: A number of `units` to allocate; the default is **50**
+* `unit`: Data size unit, can be `B` (bytes), `KiB` (kibibytes) or `MiB` (mebibytes); the default is **MiB**
+
+## Examples
+
+```sh
+$ allocate 100 MiB
+allocating memory (104857600 bytes)...
+done in 13ms
+writing one byte to each page of allocated memory...
+step took 46ms (217.391304MiB/s)
+step took 32ms (312.500000MiB/s)
+step took 31ms (322.580645MiB/s)
+step took 55ms (181.818181MiB/s)
+step took 35ms (285.714285MiB/s)
+step took 40ms (250.000000MiB/s)
+step took 39ms (256.410256MiB/s)
+step took 52ms (192.307692MiB/s)
+step took 44ms (227.272727MiB/s)
+done in 426ms
+sleeping for ten seconds...
+0
+1
+2
+3
+4
+5
+6
+7
+8
+9
+done.
+freeing memory...
+done in 119ms
+```

Base/usr/share/man/man1/aplay.md

@@ -0,0 +1,28 @@
+## Name
+
+aplay - play a sound
+
+## Synopsis
+
+```**sh
+$ aplay [--loop] <path>
+```
+
+## Description
+
+This program plays a sound specified in `path` through AudioServer.
+
+## Options
+
+* `-l`, `--loop`: Loop playback
+
+## Arguments
+
+* `path`: Path to audio file
+
+## Examples
+
+```sh
+$ aplay ~/sound.wav
+$ aplay -l ~/music.wav
+```

Base/usr/share/man/man1/arp.md

@@ -0,0 +1,23 @@
+## Name
+
+arp - display ARP cache
+
+## Synopsis
+
+```**sh
+# arp
+```
+
+## Description
+
+This program run as root displays IP and MAC addresses of devices in local network.
+
+ARP stands for Address Resolution Protocol, which is used to find devices in local network.
+
+## Examples
+
+```sh
+# arp
+Address          HWaddress
+192.168.1.1      52:54:00:12:34:56
+```

Base/usr/share/man/man1/basename.md

@@ -0,0 +1,28 @@
+## Name
+
+basename - strip directory names from path
+
+## Synopsis
+
+```**sh
+$ basename <path>
+```
+
+## Description
+
+`basename` prints basename (filename, stripped of preceding directory names) of specified `path` to standard output. The path does not have to exist.
+
+## Arguments
+
+* `path`: The path which we want to get basename of
+
+## Examples
+
+```sh
+$ basename /
+/
+$ basename ~
+anon
+$ basename Source/js/array.js
+array.js
+```

Base/usr/share/man/man1/bt.md

@@ -21,6 +21,10 @@ addresses for each frame in the stack producing a backtrace.
 * If Kernel addresses are available, they will not be symbolicated unless
   the current user has access to the `/boot/Kernel` file.
 
+## Arguments
+
+* `pid`: Process ID
+
 ## Examples
 
 View all stacks of pid number 10:

Base/usr/share/man/man1/cat.md

@@ -0,0 +1,53 @@
+## Name
+
+cat - concatenate files to stdout
+
+## Synopsis
+
+```**sh
+$ cat [file...]
+```
+
+## Description
+
+This program passes contents of specified `files` to standard output, in the specified order. If no `file` is specified, or it is `-`, it defaults to standard input.
+
+## Arguments
+
+* `file`: Files to print
+
+## Examples
+
+```sh
+# Display a single file
+$ cat README.md
+# SerenityOS
+
+Graphical Unix-like operating system for x86 computers.
+...
+
+# Display standard input
+$ cat
+aaa
+aaa
+bbb
+bbb^C
+
+# Display ls output where each file is in separate line
+$ ls | cat
+Desktop
+Documents
+Downloads
+README.md
+Source
+js-tests
+tests
+web-tests
+
+# Display multiple files
+$ echo 123 > test.txt
+$ echo 456 > test2.txt
+cat test.txt test2.txt
+123
+456
+```

Base/usr/share/man/man1/checksum.md

@@ -0,0 +1,22 @@
+## Name
+
+checksum - helper program for calculating checksums
+
+## Synopsis
+
+`$ md5sum <file>`
+`$ sha1sum <file>`
+`$ sha256sum <file>`
+`$ sha512sum <file>`
+
+## Description
+
+This program calculates and print specified checksum of files. It cannot be run directly, only
+as `md5sum`, `sha1sum`, `sha256sum` or `sha512sum`.
+
+## See also
+
+* [`md5sum`(1)](md5sum.md)
+* [`sha1sum`(1)](sha1sum.md)
+* [`sha256sum`(1)](sha256sum.md)
+* [`sha512sum`(1)](sha512sum.md)

Base/usr/share/man/man1/chgrp.md

@@ -0,0 +1,29 @@
+## Name
+
+chgrp - change group ownership of file
+
+## Synopsis
+
+```**sh
+$ chgrp <gid> <path>
+$ chgrp <name> <path>
+```
+
+## Description
+
+`chgrp` called as root or as file owner changes owning group of specified `path` to `gid` or `name`.
+
+## Examples
+
+```sh
+# Change group of README.md to 111
+# chgrp 111 README.md
+
+# Change group of README.md to root
+# chgrp root README.md
+```
+
+## See also
+
+* [`chmod`(1)](chmod.md)
+* [`chown`(1)](chown.md)

Base/usr/share/man/man1/chmod.md

@@ -0,0 +1,49 @@
+## Name
+
+chmod - change file mode
+
+## Synopsis
+
+```**sh
+$ chmod <octal-mode> <path...>
+$ chmod <mode> <path...>
+```
+
+## Description
+
+`chmod` changes mode of all files specified in `path` to `octal-mode` or using symbolic representation.
+
+The symbolic representation format is `[[ugoa][+-=][rwx...],...]`. Multiple symbolic can be given, separated by commas.
+
+The letters `[ugoa]` controls which users' access will be changes: `u` means file owner, `g` file owning group, `o` others, and `a` - all users. If no letter is given, `a` is assumed.
+
+The letters `[+-=]` controls which action will be taken: `+` sets the permission, `-` removes the permission, and `=` sets the mentioned permissions and unsets the other permissions.
+
+The letters `[rwx]` controls which permission will be changes: `r` is read, `w` is write and `x` is execute.
+
+A numeric mode is combination of 1 to 4 numbers. Omitted digits are assumet to be leading zeros. The first digit select the set user ID (4), set group ID (2) and restricted deletion / sticky (1) attributes. The second, third and fourth digit controls permissions of each user group: owner, owning group and others (not owner or owning group), respectively: read (4), write (2) and execute (1).
+
+## Examples
+
+```sh
+# Allow full access for owner, read-execute for group, and no access for others, of 'README.md':
+$ chmod 750 README.md
+
+# Change '/bin/su' to be set-uid, read-write-execute for owner, only execute for others:
+# chmod 4711 /bin/su
+
+# Add read access for others to all files in 'Source' directory:
+$ chmod o+r Source/*
+
+# Deny read and write access for non-owners, and allow full access for owners of 'script.sh':
+$ chmod o-rw,g-rw,u+rwx script.sh
+
+# Set group access to only read of 'script.sh':
+$ chmod g=r script.sh
+```
+
+## See also
+
+* [`chgrp`(1)](chmod.md)
+* [`chown`(1)](chown.md)
+* [`chmod`(2)](../man2/chmod.md)

Base/usr/share/man/man1/chown.md

@@ -0,0 +1,32 @@
+## Name
+
+chown - change file owner / group
+
+## Synopsis
+
+```**sh
+$ chown [user][:group] files...
+```
+
+## Description
+
+`chown` changes the owner of specified files to `user`, and owning group to `group`. If `group` is not specified, it is left unchanged.
+
+**NOTE**: The caller must be a superuser to change user ownership. Other users can use `chown` to change the group to one of their other
+group.
+
+## Examples
+
+```sh
+# Change 'file' owner and group to 'anon':
+$ chown anon:anon file
+
+# Change 'file' owner to 'root', leave group unchanged:
+# chown root file
+```
+
+## See also
+
+* [`chgrp`(1)](chmod.md)
+* [`chown`(1)](chown.md)
+* [`chmod`(2)](../man2/chmod.md)

Base/usr/share/man/man1/chres.md

@@ -0,0 +1,24 @@
+## Name
+
+chres - change display resolution
+
+## Synopsis
+
+```**sh
+$ chres <width> <height> [scale factor]
+```
+
+## Description
+
+`chres` changes the display resolution to <width>x<height>@<scale factor>x.
+
+## Examples
+
+```sh
+# Change resolution to 1920x1080, scale 2x:
+$ chres 1920 1080 2
+```
+
+## Files
+
+* `/tmp/portal/window` to communicate with WindowServer

Base/usr/share/man/man1/clear.md

@@ -0,0 +1,13 @@
+## Name
+
+clear - clear the terminal
+
+## Synopsis
+
+```**sh
+$ clear
+```
+
+## Description
+
+`clear` clears the current terminal contents by writing `\033[3J\033[H\033[2J` to the standard output.

Base/usr/share/man/man1/copy.md

@@ -0,0 +1,28 @@
+## Name
+
+copy - copy text to the clipboard
+
+## Synopsis
+
+```**sh
+$ copy [options...] [text...]
+```
+
+## Description
+
+`copy` copies text from stdin or command-line argument (`text`) to the system clipboard. The clipboard is managed by WindowServer.
+
+## Options
+
+* `-t type`, `--type type`: MIME type of data stored in clipboard. The default type is `text/plain`.
+* `-c`, `--clear`: Clear the clipboard instead of copying.
+
+## Examples
+
+```sh
+# Copy some image to clipboard
+$ cat image.png | copy -t image/png
+
+# Place text 'foo' in clupboard
+$ copy foo
+```

Base/usr/share/man/man1/cp.md

@@ -0,0 +1,36 @@
+## Name
+
+cp - copy files
+
+## Synopsis
+
+```**sh
+$ cp [options...] <source...> <destination>
+```
+
+## Description
+
+`cp` copies files specified in `source` to `destination`.
+
+If there are several `sources`, the directory `destination` is created and all files specified in `sources` are copied into that directory. Otherwise, the `source` file is copied as `destination` file. If the file exists, it is overridden. If `destination` directory exists and there is only one `source`, the `source` file is copied into the `destination` directory.
+
+If a directory is specified in `source`, the `-R` (recursive) flag is required. Otherwise, an error occurs.
+
+## Options
+
+* `-l`, `--link`: Create hard links instead of copying
+* `-R`, `-r`, `--recursive`: Copy directories recursively
+* `-v`, `--verbose`: Display what files are copied
+
+## Examples
+
+```sh
+# Copy cpp-tests file and name it cpp-tests-backup
+$ cp cpp-tests cpp-tests-backup
+
+# Copy cpp-tests directory and name it cpp-tests-backup
+$ cp -R cpp-tests cpp-tests-backup
+
+# Copy cpp-tests file into existing root
+$ cp cpp-tests root
+```

Base/usr/share/man/man1/du.md

@@ -0,0 +1,54 @@
+## Name
+
+du - print disk usage
+
+## Synopsis
+
+```**sh
+$ du [files...]
+```
+
+## Description
+
+`du` prints disk usage data for every argument, in KiB (kibibytes).
+
+## Options
+
+* `-a`, `--all`: Write counts for all files, not just directories
+* `--apparent-size`: Print apparent sizes, rather than disk usage
+* `-d N`, `--max-depth N`: Print the total for a directory or file only if it is N or fewer levels below the command line argument
+* `-s`, `--summarize`: Display only a total for each argument
+* `-t size`, `--threshold size`: Exclude entries smaller than size if positive, or entries greater than size if negative
+* `--time time-type`: Show time of time time-type of any file in the directory, or any of its subdirectories. Available choices: mtime, modification, ctime, status, use, atime, access
+* `--exclude pattern`: Exclude files that match pattern
+* `-X file, --exclude_from`: Exclude files that match any pattern in file
+
+## Arguments
+
+* `files`: Files to print disk usage of
+
+## Examples
+
+```sh
+~ $ du -s *
+4       Desktop
+4       Documents
+4       Downloads
+6       README.md
+4       Source
+4       js-tests
+4       tests
+4       web-tests
+~ $ du -a Documents
+2       Documents/emoji.txt
+2       Documents/zip/archive.zip
+4       Documents/zip
+2       Documents/tips.txt
+4       Documents
+~ $ du --apparent-size -a Documents
+4       Documents/emoji.txt
+4       Documents/zip/archive.zip
+4       Documents/zip
+4       Documents/tips.txt
+4       Documents
+```

Base/usr/share/man/man1/id.md

@@ -0,0 +1,39 @@
+## Name
+
+id - print user/group ID
+
+## Synopsis
+
+```**sh
+$ id [options...]
+```
+
+## Description
+
+`id` outputs user and group information for the current user.
+
+## Options
+
+* `-u`: Print only real UID.
+* `-g`: Print only real GID.
+* `-G`: Print only all GIDs.
+* `-n`: If `-u`, `-g` or `-G` is specified, print full names instead of IDs.
+
+## Examples
+
+```sh
+$ id
+uid=100(anon) gid=100(users) groups=1(wheel),10(lookup),12(notify),4(audio),13(window),14(clipboard),3(phys)
+$ id -u
+100
+$ id -g
+100
+$ id -un
+anon
+$ id -G
+1 10 12 4 13 14 3
+```
+
+## See also
+
+* [`whoami`(1)](whoami.md)

Base/usr/share/man/man1/more.md

@@ -0,0 +1,21 @@
+## Name
+
+more - page through text
+
+## Synopsis
+
+```**sh
+$ more
+```
+
+## Description
+
+`more` reads data from standard input and prints it to standard output, screen by screen.
+
+## Examples
+
+```sh
+# dmesg | more
+...
+--[ more ]--
+```

Base/usr/share/man/man1/mv.md

@@ -0,0 +1,27 @@
+## Name
+
+mv - move (rename) files
+
+## Synopsis
+
+```**sh
+$ mv [options...] <old name> <new name>
+$ mv [options...] <source...> <destination>
+```
+
+## Description
+
+`mv` renames file `old name` to `new name` or moves all `source` files into `destination`.
+
+## Options
+
+* `-f`, `--force`: Do not prompt before overwriting (not implemented for now)
+* `-v`, `--verbose`: Display all moved files
+
+## Examples
+
+```sh
+$ mv bin /usr
+$ mv *.cpp /usr/src
+$ mv old.txt new.txt
+```

Base/usr/share/man/man1/notify.md

@@ -0,0 +1,25 @@
+## Name
+
+notify - create a notification
+
+## Synopsis
+
+```**sh
+$ notify <title> <message> [icon-path]
+```
+
+## Arguments
+
+* `title`: The title of notification
+* `message`: The message of notification
+* `icon-path`: Path to icon image file
+
+## Description
+
+`notify` creates a WindowServer notification with title `title` and message `message`. You can also provide an icon path; by default, no icon will be used.
+
+## Examples
+
+```sh
+$ <command> && notify "Information" "Command succeeded" /res/icons/32x32/msgbox-information.png
+```

Base/usr/share/man/man1/sleep.md

@@ -0,0 +1,23 @@
+## Name
+
+sleep - delay for a specified number of seconds
+
+## Synopsis
+
+```**sh
+$ sleep <seconds>
+```
+
+## Arguments
+
+* `seconds`: Number of seconds to sleep
+
+## Description
+
+`sleep` pauses execution for specified number of seconds.
+
+## Examples
+
+```sh
+$ sleep 5
+```

Base/usr/share/man/man1/whoami.md

@@ -0,0 +1,26 @@
+## Name
+
+whoami - print effective user name
+
+## Synopsis
+
+```**sh
+$ whoami
+```
+
+## Description
+
+`whoami` outputs the user name associated with current effective UID.
+
+## Examples
+
+```sh
+$ whoami
+anon
+# whoami
+root
+```
+
+## See also
+
+* [`id`(1)](id.md)

Base/usr/share/man/man1/yes.md

@@ -0,0 +1,41 @@
+## Name
+
+yes - output a string repeatedly until killed
+
+## Synopsis
+
+```**sh
+$ yes [string]
+```
+
+## Description
+
+`yes` outputs an endless stream of specified `string` (with trailing newline) in a loop.
+
+## Options
+
+* `string`: String to print; defaults to "yes".
+
+## Examples
+
+```sh
+$ yes
+yes
+yes
+yes
+yes
+yes
+yes
+yes^C
+$ yes t
+t
+t
+t
+t
+t
+t
+t
+t
+t
+t^C
+```

Base/usr/share/man/man8/dmesg.md

@@ -0,0 +1,19 @@
+## Name
+
+dmesg - display the kernel log
+
+## Synopsis
+
+```**sh
+# dmesg
+```
+
+## Description
+
+`dmesg` displays the kernel log (as seen on serial debug output). Only messages printed by kernel processes are displayed.
+
+## Examples
+
+```sh
+$ dmesg
+```

Base/usr/share/man/man8/hostname.md

@@ -0,0 +1,28 @@
+## Name
+
+hostname - print or set hostname
+
+## Synopsis
+
+```**sh
+$ hostname [hostname]
+```
+
+## Description
+
+`hostname` prints current host name. If the `hostname` argument is give and the user is a superuser, the utility sets the current host name to its value. The maximum hostname length is 64 characters. The hostname is not persisted after reboot.
+
+## Examples
+
+```sh
+# Print current hostname
+$ hostname
+courage
+
+# Set the new hostname
+# hostname foo
+
+# Print new hostname
+# hostname
+foo
+```

Base/usr/share/man/man8/umount.md

@@ -0,0 +1,26 @@
+## Name
+
+umount - unmount file system
+
+## Synopsis
+
+```**sh
+$ umount <mountpoint>
+```
+
+## Arguments
+* `mountpoint`: File system path to unmount
+
+## Description
+
+`umount` run as root unmounts a file system mounted at specified `mountpoint`.
+
+## Examples
+
+```sh
+# umount /
+```
+
+## See also
+
+* [`mount`(8)](../man8/mount.md)